Technical Overview
Architecture, data and model routing.
Architecture
Bardo is a Turborepo with pnpm workspaces.
| Path | Role |
|---|---|
apps/web | The Next.js app: routes, Clerk sign-in, the UI, and the Convex backend. |
apps/docs | This documentation, built with Fumadocs. |
packages/markdown | The workspace core: paths, files and rules, with no Storyteller code. |
packages/storyteller | Pure Storyteller logic: world, turns, time, capabilities. |
packages/shared | Small shared utilities. |
The core does not import Storyteller modules. The Storyteller reaches the workspace only through a defined contract. Convex functions and authentication sit at the edge of the app, not inside the packages.
Data
- One file store for notes, world and campaign files, with revisions.
- World events and checkpoints, and a rebuildable index of entities, facts and names.
- Chat entries, usage records and bookkeeping tables.
- Every query and mutation derives the owner from the sign-in token.
Model Routing
The model is chosen by configuration:
- The default for the story writer, answerer and interpreter is a DeepSeek model, pinned to one provider through the AI Gateway.
- A stronger model is the escalation tier, and a small model acts as the decision gate.
- Each call goes through a spend guard that admits only allowed models and effort levels.
Story creation and slash commands do not call a model. Plain moves and approved waiting have deterministic resolution; optional interpretation or narration can use the gated model path.
Live model calls require explicit operator enablement, owner scope and spend admission. A bounded development evaluation was recorded on 2026-11-03; it is historical evidence, not a fresh certification of this checkout or support for a published RPG system. Current hosted settings and live quality were not reverified during Phase 0 or Phase 1. The local candidate passed mock-backed tests and builds; those do not certify live behavior.
Privacy
Provider keys stay on the server. File contents are kept out of telemetry.