adventure/apps/web/docs/REFACTOR-LOG.md

Refactor Log

Internal refactor of AdventureOS. Behaviour, API contracts, and schema preserved unless explicitly noted.

Phase 1: Safety baseline

• Removed debug telemetry from apps/web/src/app/api/library/books/route.ts
• Extracted pure adventure helpers: derive-state.ts, template-matching.ts, checklist-value.ts
• Added unit tests for @adventureos/shared (xp, levels, scores, chapters)
• Added characterization tests for deriveState, template matching, undo Calibre mismatch
• Replaced misnamed feature-repair.test.ts with real tests

Manual smoke checklist

• Login / logout
• Command Centre: adventure items, todos, rest day, customize
• Settings: theme, AI config, templates, action history undo
• Library: manual books and Calibre (if configured)
• Cartographer: generate, activate, complete, dismiss
• Teacher: generate, complete, deep links
• Undo toast and settings undo

Commands run each phase

npm run test
npm run lint
npm run build
npm run db:migrate   # when DB available

Phase 2: Configuration and constants

• Centralised env reads in lib/config/
• Typed constants for settings keys, action types, theme IDs

Phase 3: API and data access

• Zod input validation on teacher, templates, settings routes
• Repository layer for settings, teacher, adventure templates
• Typed errors in lib/errors/; handleApi uses mapErrorToResponse
• Teacher route uses createTeacherLesson service

Phase 4: Domain/service cleanup

• Split adventure.ts into lib/services/adventure/{materialization,daily,scoring,templates}.ts
• Unified Calibre reading log via lib/services/reading/log-pages.ts

Phase 5: Frontend cleanup

• Client API: features/adventure/api.ts, features/undo/api.ts, lib/api-client.ts
• Hooks: useAdventureMutations, useUndoMutation, useActionToastHandlers
• Split todays-adventure.tsx; extracted adventure-item-row, checklist-item
• Consolidated AI prompt editors into AiPromptEditor
• Shared UI: RetroWindow, TabToggle, LoadingState, ErrorState
• Undo toast uses query invalidation (no full page reload)

Phase 6: Type safety

• JSONB interfaces in lib/types/jsonb.ts
• Teacher types in @adventureos/shared
• Removed unused @radix-ui/* dependencies

Phase 7: Tests and CI

• Validation/error unit tests
• @adventureos/shared test script and vitest config
• Root npm run test runs web + shared
• GitHub Actions CI workflow

Phase 8: Documentation

• ARCHITECTURE.md — layers and service boundaries
• KNOWN-ISSUES.md — documented gaps