adventure/docs/ARCHITECTURE.md

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. 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

npm run test        # domain + application + web + shared
npm run lint        # ESLint (web)
npm run typecheck   # tsc --noEmit
npm run build       # Next.js production build