change

docs/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# AdventureOS Architecture
+
+This document describes the system architecture and behavioural invariants that must be preserved during refactoring.
+
+## Package Structure
+
+```
+packages/
+  domain/         Pure domain rules, entities, value objects — no external deps
+  application/    Use cases and port interfaces — depends on domain only
+  shared/         Deprecated re-export shim → @adventureos/domain
+  db/             Drizzle schema, migrations, connection
+
+apps/web/
+  src/
+    adapters/       Persistence, AI, Calibre implementations of ports
+    infrastructure/ Composition root, env wiring
+    app/api/        HTTP adapters (Next.js route handlers)
+    components/     UI adapters
+    lib/services/   Legacy service layer (migrating to application use cases)
+```
+
+### Dependency Rule
+
+- `domain` → nothing external
+- `application` → `domain`
+- `adapters` / `infrastructure` / `app/api` → `application`, `domain`, `db`
+- Domain must not import controllers, ORM, HTTP, or config
+
+## Behavioural Invariants
+
+Derived from [PRODUCT.md](./PRODUCT.md). These must not change without explicit approval.
+
+### XP and Progression
+
+- **No XP loss** under normal operation. Undo revokes XP via compensating negative events, not deletion.
+- **Soft caps** apply diminishing returns per source (`adventure_item`, `spiritual`, `reading`) — see `DAILY_SOFT_CAPS` in domain.
+- **Level curve** is defined by `levelFromXp` / `xpForLevel` — cap at level 150.
+- **Rest days** award `XP_AWARDS.rest_day` without requiring item completion.
+- **Daily visit** XP is awarded once per logical day.
+
+### Adventure Items
+
+- Item states: `blank` → `started` → `partial` → `done` (derived by type-specific rules).
+- Partial credit is always awarded for non-blank state transitions.
+- **Semantic keys** (`exercise`, `prayer`, `litanies`, etc.) identify items for scoring/XP. Label-string fallback remains for backward compatibility until all templates use `config.semanticKey`.
+
+### Day Boundary
+
+- Logical "today" respects configurable day-boundary hour and grace window (`getLogicalToday`, `isWithinGraceWindow`).
+- Week starts on Monday (`startOfWeek` with `weekStartsOn: 1`).
+
+### Undo
+
+- Actions recorded via `recordAction` with `beforeState` / `afterState`.
+- Undo creates compensating XP events and marks originals as revoked.
+- Each `actionType` has a dedicated undo handler — handlers must stay synchronized with record sites.
+
+### Anti-Burnout
+
+- No streak destruction, no failure screens.
+- Grace days and welcome-back flows preserve progress.
+- Forgiving day modes do not penalize the user.
+
+### Auth
+
+- Single-tenant: one user per installation (`requireUser` uses `limit(1)`).
+- Use cases receive explicit `userId` — auth resolution happens in HTTP/cron adapters only.
+
+## Migration Status
+
+| Slice | Status |
+|-------|--------|
+| UpdateAdventureItem use case | Migrated via composition root |
+| Remaining adventure operations | Legacy services |
+| Reading, dashboard, AI | Legacy services |
+| Admin CMS (Drizzle schema) | Persistence adapter |
+
+## Running Checks
+
+```bash
+npm run test        # domain + application + web + shared
+npm run lint        # ESLint (web)
+npm run typecheck   # tsc --noEmit
+npm run build       # Next.js production build
+```