CLAUDE.md

@@ -38,9 +38,13 @@ Pick libraries consistent with this stack. If you introduce a significant depend
 ```
 /                  # docs and project meta (this file, README, LICENSE, COC, CONTRIBUTING)
 /docs              # PRD.md, ARCHITECTURE.md
+/backend           # FastAPI service (uv-managed). app/ = api / core (config, db); more layers land with the data model
+/deploy            # docker-compose.yml, Caddyfile, .env.example — the self-host stack
+/.gitea/workflows  # Gitea Actions CI (build images → Gitea registry)
+/frontend          # Next.js app — not yet scaffolded (Phase 0, after the deploy story)
 ```
 
-Code does not exist yet — Phase 0 has not landed. When you scaffold it, propose a layout (e.g. `/backend`, `/frontend`, `/deploy` for compose/Caddy) and record it here and in ARCHITECTURE.md. Keep this section current as the tree grows.
+Phase 0 is landing **deploy-first**: the compose stack (Postgres + MinIO + Caddy + a minimal FastAPI backend exposing `/health` and `/health/ready`) and CI come before the real data model and the frontend. Backend dependencies are managed with **uv**; migrations will use **Alembic**. Keep this section current as the tree grows.
 
 ## Where to start
 

docs/ARCHITECTURE.md

@@ -175,6 +175,17 @@ Jobs are idempotent and retryable; an external failure degrades gracefully rathe
 - **Migrations** run on backend start (or via an explicit job) so an image pull + restart is a complete upgrade.
 - **Backups:** documented procedure for Postgres dump + object-store sync; restore is the inverse.
 
+**Repository layout (as scaffolded):**
+
+```
+/backend           # FastAPI service, uv-managed (app/ = api, core; service/repository/domain land with the data model)
+/deploy            # docker-compose.yml, Caddyfile, .env.example
+/.gitea/workflows  # Gitea Actions: build images → Gitea registry
+/frontend          # Next.js (pending)
+```
+
+The compose stack runs `postgres` (pgvector image — includes `pgvector`; `pg_trgm` ships in contrib), `minio`, `backend`, and `caddy`. The **worker** container (same image as backend, worker mode) joins once queue-driven jobs exist. Phase 0 ships a minimal backend with `/health` (liveness) and `/health/ready` (Postgres reachability) to validate the deploy wiring before the data model lands.
+
 ## 13. Observability
 
 - Structured (JSON) logs from backend and worker.