v3: api/ gets one layout rule and keeps to it, and whatever crosses the wire is defined once, in shared/ — api/model/interfaces.ts and src/model.ts declared the same 40 types by hand and had drifted: the error envelope, email required on one side and optional on the other, Invitee/InviteTreeEntry and LinkPreview/UrlPreviewResponse for one shape each. The validation limits, the role permissions, the chat length cap, the @mention pattern and the Bandcamp and YouTube player responses were copied too, behind "keep in sync" comments. shared/ now holds them once, one file per domain (api, category, chat, comment, dump, follow, mention, notification, permissions, player, playlist, search, user, validation, ws), and imports nothing from either half. The server sends Dates; the client reads Wire<T>, the same type with every Date an ISO string, and turns it back with src/utils/shared/deserialize.ts. APIErrorCode becomes a const object, since the frontend's erasableSyntaxOnly rejects an enum. The shared types showed two real gaps: the avatar upload and GET /api/users/me return the full self user and the frontend read them as public users, and a stored session may predate media tokens, so the client keeps it as its own Session type. The backend rule: each folder holds one kind of module, each file is named after its domain. routes/ parse and answer; services/ hold the logic and every SQL query (lib/auth.ts's token check moves to user-service); remote/ is the only place that fetches from other sites — the guarded fetch and the HTML scraping out of rich-content-service, public-address, the Bandcamp and YouTube resolvers, the link providers, the image proxy (fetch, checks and cache, out of routes/preview.ts) and the Twemoji glyphs (out of lib/site-icons.ts). model/ holds per table a row type, its guard and its mappers; validators/ the request guards; db/connection.ts the handle and transaction(), db/startup.ts the purges and default admin that db.ts ran on import, called at the same moment. Tests mirror the source one file per module, test/<layer>/<module>.test.ts, with shared/'s under shared/test/ (deno task test runs both); the test that covered the bandcamp and soundcloud providers together is two now, and the backend can() has its own, so 202 tests. deno lint src/ is clean too: window.* becomes globalThis.*, and test bodies and act() callbacks that never awaited lose their async. The README states the rule. No behaviour changes; the catalogues only move their source references.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -105,25 +105,32 @@ example.com {
 ## Project structure
 
 ```
+shared/            # Imported by both halves: API and socket types, limits, permissions
+  test/            # Tests of shared/ (Deno): test/<module>.test.ts
 api/
   main.ts          # Entry point — Oak application, middleware, routes
   config.ts        # Environment variables
-  middleware/      # errorMiddleware, authMiddleware
-  routes/          # HTTP routes + WebSocket
-  services/        # Business logic
+  middleware/      # Oak middleware: errors, auth, OG tags
+  routes/          # One router per URL prefix: HTTP + WebSocket, no SQL
+  services/        # Business logic and every SQL query
+  remote/          # Everything that fetches from other sites
     providers/     # Link metadata providers (YouTube, SoundCloud, Bandcamp, …)
-  model/           # Row types, type guards
-  lib/             # JWT, pagination, slugify, upload, static helpers, …
+  model/           # Per table: row type, row guard, row ↔ API mappers
+  validators/      # Per domain: request body guards
+  lib/             # Helpers with no SQL and no outbound fetch: JWT, slugs, files, …
   db/
+    connection.ts  # The database handle and transaction()
+    startup.ts     # Housekeeping run when the database opens
     schema.sql     # Database schema
     init.ts        # First-run database initialisation
     migrate.ts     # Migration runner
     migrations/    # Versioned schema migrations
+  test/            # Backend tests (Deno): test/<layer>/<module>.test.ts
   sql/
     gerbeur.db     # SQLite database (not committed)
   uploads/         # User-uploaded files — avatars, dumps, thumbnails, … (not committed)
 src/               # React frontend (Vite)
-  config/          # API base URL, validation constants, feed tabs, upload limits
+  config/          # API base URL, feed tabs, player mode
   pages/           # One component per route, nothing else
   components/      # React components only (.tsx)
   contexts/        # FooContext.ts + FooProvider.tsx pairs
@@ -132,15 +139,29 @@ src/               # React frontend (Vite)
   test/            # Frontend tests (Vitest): test/<layer>/<domain>/<Module>.test.tsx
   locales/         # Lingui message catalogues (en, fr)
   themes/          # Per-theme CSS files
-  model.ts         # Shared frontend types
   i18n.ts          # Lingui runtime setup
 public/            # Static assets (favicon, manifest, service worker)
 ```
 
-Each of `components/`, `contexts/`, `hooks/` and `utils/` is split into the
-same domain folders — `auth`, `category`, `chat`, `comment`, `dump`, `editor`,
-`feed`, `form`, `layout`, `player`, `playlist`, `profile`, `social`, `theme`,
-`ws` — plus `shared/` for what belongs to no single domain. So the chat lives in
-`components/chat/`, `contexts/chat/`, `hooks/chat/` and `utils/chat/`, and its
-tests in `test/<same path>`. Files are imported directly (no `index.ts`
-barrels), and everything uses named exports.
+Whatever crosses the wire is defined once, in `shared/`: the API envelope
+(`shared/api.ts`), each domain's types and request bodies (`shared/dump.ts`,
+`shared/user.ts`, …), the socket protocol (`shared/ws.ts`), the validation
+limits and the role permissions. The server sends Dates; the client reads
+`Wire<T>`, the same type with every Date an ISO string, and turns it back with
+`src/utils/shared/deserialize.ts`. `shared/` imports nothing from either half.
+
+The backend is split by layer, one kind of module per folder, and each file is
+named after its domain: the dumps are `routes/dumps.ts`,
+`services/dump-service.ts`, `model/dump.ts` and `validators/dump.ts`. Routes
+parse and answer, services hold the logic and the SQL, `remote/` is the only
+place that fetches from other sites. Tests mirror the source one file per
+module, so the tests of `services/chat-service.ts` are in
+`test/services/chat-service.test.ts`.
+
+Each of the frontend's `components/`, `contexts/`, `hooks/` and `utils/` is
+split into the same domain folders — `auth`, `category`, `chat`, `comment`,
+`dump`, `editor`, `feed`, `form`, `layout`, `player`, `playlist`, `profile`,
+`social`, `theme`, `ws` — plus `shared/` for what belongs to no single domain.
+So the chat lives in `components/chat/`, `contexts/chat/`, `hooks/chat/` and
+`utils/chat/`, and its tests in `test/<same path>`. Files are imported directly
+(no `index.ts` barrels), and everything uses named exports.