Slice 1 (Module 02): Document upload & list — foundation

[mGasiorek998]

What to build

Lay the full foundation for patient document management as a single end-to-end slice. This covers both new database tables, the storage service, the upload and list endpoints, the typed contract, and the patient-facing /patient/documents page.

Specifically:

• Add documents and document_shares tables to the Drizzle schema (both needed now so FK constraints are in place from the start).
• Add DOCUMENT_STORAGE_PATH env var to the Zod config (defaults to apps/api/storage/documents/); auto-create the directory recursively at API startup; add apps/api/storage/ to .gitignore.
• Implement the document storage service (deep module): write(stream) → uuid, read(uuid) → ReadStream, delete(uuid) → void. No DB knowledge.
• Implement uploadDocument use case: MIME allowlist check (application/pdf, image/png, image/jpeg, image/webp), write to disk, insert documents row, return metadata.
• Implement listDocuments use case: fetch patient's own documents ordered by uploadedAt descending.
• Apply Hono bodyLimit middleware at 10 MiB + 1 byte on the upload route — oversized requests rejected before parseBody() runs, no partial file ever touches disk.
• POST /documents (201 + metadata | 413 | 415 | 422 | 500) and GET /documents (200 + array) routes, both behind requireAuth() + requireRole(['patient']).
• Fill in packages/contracts/src/documents.ts with Zod schemas for these two endpoints.
• /patient/documents page in the web app: file input that calls the upload endpoint, document list showing filename / size / uploadedAt for each entry.

Acceptance criteria

• POST /documents with a valid PDF ≤ 10 MiB returns 201 with { id, filename, mimeType, size, uploadedAt } and a UUID-named file (no extension, no original filename) appears in the storage directory.
• POST /documents with a file > 10 MiB returns 413 { error: "FILE_TOO_LARGE", ... } and no file is written to disk.
• POST /documents with a disallowed MIME type returns 415 { error: "UNSUPPORTED_MEDIA_TYPE", ... }.
• POST /documents with no file part returns 422 { error: "MISSING_FILE", ... }.
• GET /documents returns 200 with documents ordered by uploadedAt descending; returns [] when the patient has no documents.
• Both endpoints return 401 without a valid JWT and 403 when called with a doctor JWT.
• A fresh clone: after cp .env.example .env && pnpm dev, the storage directory exists and uploads work without any manual mkdir.
• Storage service unit tests pass against a real temp directory (cleaned up in afterAll).
• Repository integration tests pass against real Postgres.
• HTTP integration tests cover all status codes above.
• pnpm verify exits 0.

User stories covered

• US Slice 1: Monorepo scaffold + /health tracer bullet #1: As a patient, I want to upload a medical document so that I can make it available for sharing with my doctors.
• US Slice 2: Login + role-aware dashboard happy path #2: As a patient, I want to see a list of all my uploaded documents ordered from newest to oldest.
• US fix: api-client doubles base URL in fetch call #8: As a patient, I want to upload a file up to 10 MiB.
• US Slice 1 (Module 02): Document upload & list — foundation #9: As a patient, I want an oversized upload to be rejected before any data is written.
• US Slice 2 (Module 02): Delete document with atomic cascade #10: As a patient, I want unsupported file types to be rejected immediately.
• US Slice 1 (Module 03): Doctor profile read/update + specialization column #19: As a developer, I want pnpm verify to pass at every commit.
• US Slice 2a (Module 03): Slot table + list-own + read-only slot management page #20: As a developer, I want the document storage directory created automatically at API startup.
• US Slice 2b (Module 03): Slot creation with overlap detection + add slot form #21: As a developer, I want the storage path configurable via env var.

Blocked by

None — can start immediately (requires auth slice to be merged first).

[mGasiorek998]

Plan for Slice 1 (Module 02): Document upload & list — foundation

Modules touched:

• apps/api/src/db/schema.ts — add documents + document_shares tables
• apps/api/src/config.ts — add DOCUMENT_STORAGE_PATH env var (default apps/api/storage/documents/)
• apps/api/src/infrastructure/document-storage.ts — storage service: write, read, delete
• apps/api/src/infrastructure/document-repository.ts — Drizzle-backed insert + list
• apps/api/src/use-cases/documents/upload-document.ts — MIME check, disk write, DB insert
• apps/api/src/use-cases/documents/list-documents.ts — fetch patient docs ordered by uploadedAt
• apps/api/src/routes/documents/documents-router.ts — POST + GET with bodyLimit + requireAuth + requireRole
• packages/contracts/src/documents.ts — Zod schemas for upload and list endpoints
• apps/web/src/features/documents/ — query hook + component
• apps/web/src/routes/patient/documents.tsx — patient documents page

Tests planned (TDD):

1. Storage service unit tests (temp dir, write→read→delete)
2. Document repository integration tests (real Postgres)
3. HTTP integration tests for all ACs (POST, GET, 401, 403, 413, 415, 422)
4. Web component test for document list

Order: schema → config → storage service → repository → use-cases → routes → contract → web

[mGasiorek998]

Implementation PR opened: #15. 4 red→green cycles, 16 tests added (12 HTTP integration + 4 storage unit). pnpm verify exits 0 (68 tests total).