newdrive/docs/architecture.md

Architecture guide

The detailed baseline is Drive_v2_final_plan.md. This guide is a short implementation map.

Request flow

HTTP transport -> application use case -> domain rules
                                  |-> PostgreSQL repository
                                  |-> storage/external adapter

Transport code handles protocol concerns only. Application services own transactions and coordinate database-plus-storage work. Domain code contains no infrastructure dependencies.

Durable work

No authoritative state lives only in memory. Upload sessions, commit intents, jobs, leases, and cursors are persisted in PostgreSQL. Committed blobs are immutable and become visible only after storage promotion and metadata commit.

Frontend

Each feature owns its routes, API hooks, components, state, and tests. Cross-feature access goes through a small public entrypoint. Server state stays in TanStack Query and local UI state remains close to the component or feature that owns it.

Preview rendering is capability-driven and lazy-loaded. Adding a format must not require editing the file manager.