Skip to main content

Codex and Recaps

The Codex turns played-session recaps into reviewed campaign state: locations, quests, plot threads, NPC appearances, and relationships.

Backend​

Primary files:

  • server/app/routers/campaign_entities.py
  • server/app/routers/recap_extractions.py
  • server/app/lib/entities.py
  • server/app/lib/rag/recap_extraction.py
  • server/app/models.py (CampaignEntity, CampaignEntitySession, RecapExtraction)

Codex endpoints are DM-only and AI-gated. Manual entity CRUD and extraction review use the same validated status rules.

Frontend​

Primary files:

  • web/src/screens/CampaignCodex.tsx
  • web/src/components/ExtractionReviewModal.tsx

The Codex screen groups locations, quests, plot threads, recent NPCs, and pending recap reviews. The review modal lets the DM accept, edit, dismiss, or apply proposed operations.

Extraction Lifecycle​

  1. A session is marked played with notes.
  2. A background task creates or updates a RecapExtraction.
  3. Status moves through PROCESSING, PENDING_REVIEW, FAILED, or APPLIED.
  4. Campaign SSE events notify the frontend as processing changes.
  5. The DM reviews proposed operations.
  6. Applying accepted operations mutates campaign Codex state.

Entity Rules​

Supported entity kinds include locations, quests, and plot threads. Status values are validated per kind. The current-location invariant keeps at most one location marked current by demoting the prior current location when needed.

Change Checklist​

  • Keep proposed-op schema, extraction output, and review UI aligned.
  • Treat extraction as advisory; campaign state changes only after DM apply.
  • Maintain ordering in apply logic: entities, then NPCs, then relationships.
  • Broadcast processing events when UI should update live.
  • Add regression tests for status validation and apply edge cases.