33 lines
2 KiB
Markdown
33 lines
2 KiB
Markdown
# Architecture guide
|
|
|
|
The detailed baseline is `Drive_v2_final_plan.md`. This guide is a short implementation map.
|
|
|
|
## Request flow
|
|
|
|
```text
|
|
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.
|
|
|
|
## Sync-ready server contract
|
|
|
|
The server exposes neutral file and change primitives, not client sync modes. A consumer obtains a start cursor, recursively enumerates stable node/parent IDs, then replays the durable change feed until caught up. Events carry resulting state or tombstones and are safe to process more than once. See ADR-0008.
|
|
|
|
Node revision covers all meaningful mutations; content revision and SHA-256 distinguish content changes from rename, move, favorite, or trash metadata changes. Persistent idempotency and authenticated client attribution apply to every transport.
|
|
|
|
## External protocols
|
|
|
|
REST and application services are canonical. A future WebDAV gateway translates protocol requests into those services, and a native rclone backend may consume REST directly. Neither may touch managed object storage or repository tables. Rsync server access is not planned. See ADR-0009.
|
|
|
|
## 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.
|