initial 2

apps/web/docs/ARCHITECTURE.md

@@ -0,0 +1,66 @@
+# AdventureOS Architecture
+
+AdventureOS is a Next.js 16 full-stack monolith with npm workspaces.
+
+## Layers
+
+```
+Browser (React + TanStack Query + Zustand)
+    ↓ fetch /api/*
+Next.js Route Handlers (app/api/**)
+    ↓ validation (lib/validation) + handleApi (lib/api)
+Domain Services (lib/services/**)
+    ↓
+Repositories (lib/repositories/**) — Drizzle queries
+Packages: @adventureos/db, @adventureos/shared
+```
+
+## Frontend boundaries
+
+| Path | Responsibility |
+|------|----------------|
+| `app/*/page.tsx` | Route pages, data fetching via React Query |
+| `components/features/` | Domain UI components |
+| `components/ui/` | Reusable retro UI primitives |
+| `features/*/api.ts` | Typed client fetch wrappers |
+| `hooks/` | Shared React hooks (mutations, toasts) |
+| `stores/ui.ts` | Ephemeral UI state (toasts, modals) |
+| `themes/` | CSS token registry and runtime theme switching |
+
+## Backend boundaries
+
+| Path | Responsibility |
+|------|----------------|
+| `app/api/**/route.ts` | HTTP entry; parse/validate; call services |
+| `lib/services/adventure/` | Daily adventures, materialization, scoring, templates |
+| `lib/services/reading/` | Shared reading log + action recording |
+| `lib/services/ai*.ts` | AI generation, config, memory, chat, context |
+| `lib/services/ai-memory.ts` | User-controlled personal AI memories |
+| `lib/services/ai-context.ts` | Layered context builder for local models |
+| `lib/services/ai-chat.ts` | Mentor chat sessions and messages |
+| `lib/services/day-boundary.ts` | Configurable day rollover (after-midnight logging) |
+| `lib/repositories/` | Drizzle data access only |
+| `lib/config/` | Environment variables and domain constants |
+| `lib/errors/` | Typed errors and response mapping |
+| `lib/validation/` | Zod request schemas |
+
+## Data stores
+
+- **PostgreSQL** — primary app data via Drizzle (`packages/db`)
+- **Calibre metadata.db** — read-only SQLite via `better-sqlite3` when configured
+
+## Service boundaries (rules)
+
+1. Route handlers must not import Drizzle directly (use services/repositories).
+2. Repositories contain no business rules.
+3. Services orchestrate repositories, shared math, XP, and action events.
+4. Client components use `features/*/api.ts`, not raw fetch scattered in UI.
+5. `@adventureos/shared` holds pure domain types and formulas — no I/O.
+
+## Known gaps
+
+See [KNOWN-ISSUES.md](./KNOWN-ISSUES.md).
+
+## Refactor history
+
+See [REFACTOR-LOG.md](./REFACTOR-LOG.md).