Architecture
Containers
Browser / Claude
│ HTTPS (your reverse proxy)
▼
web (Caddy) ── / → built web app (static files)
│ /api /mcp /ical → server:3000
│ /auth/v1, /.well-known/* → auth:9999
▼
server (Node.js) ──► db (PostgreSQL 17) ◄── auth (GoTrue)
webis Caddy with the built web app and the fileinfra/caddy/Caddyfile: it is the one address to the outside.serveris Fastify: REST API under/api, the MCP server under/mcp, the calendar subscription feed under/icaland pg-boss background jobs (calendar subscriptions, search index, backups, trash).authis Supabase Auth (GoTrue): sign-in, passkeys, TOTP and an OAuth 2.1 server through which MCP clients such as Claude sign in. The server checks the tokens against the JWKS.dbis PostgreSQL 17 (Supabase image withpgvectorfor the search).
Server (apps/server/src)
| Folder | Role |
|---|---|
domain/ | The domain logic, one file per area (courses, files, planning, calendar, notes, flashcards, programs, recordings, inbox …). Plain functions on the database; this is where permissions belong (access.ts: roles) |
http/ | Fastify routes that point thinly to domain/ |
mcp/ | The MCP server: tools that call the same domain/ logic with the user's permissions |
jobs/ | Scheduled jobs (scheduler.ts, backup.ts) |
search/ | Search by meaning (embeddings, local) and wording (PostgreSQL full text with the simple configuration, the same for every language), fused by rank |
db/ | Drizzle schema (schema.ts) and migrations (drizzle/) |
One rule runs through everything: permissions are checked in domain/, not in the routes. Then they apply to the web app and to MCP alike.
Web app (apps/web/src)
views/ are the pages (CourseView, PlanningView …), components/ reusable parts, lib/ helpers (API client, session, zoom, stored settings), i18n/ all texts (en.ts the source, de.ts the German one; index.ts picks the language and formats dates and numbers). The interface only uses building blocks from @study/ui.
Data
- Documents live as plain folders under
FILES_DIR/courses/<course>/<folder>/; the database knows them with metadata. - Users (
profiles) hang off the GoTrue accounts. Roles apply per course (course_members). - Deadlines are shared (with a course) or private (without). Ticking off is per user (
deadline_done).
Decisions
Important decisions are under Decisions: