How sortedcord/ada works
Ada is a self-hosted, single-player narrative simulation. A player submits an action through the web client; the API accepts a turn and queues durable work, and the worker runs resumable intent, perception, NPC cognition, resolution, narration, and memory/card stages. Validated canonical state is persisted in PostgreSQL, while the client reads run and journal views. Separate authoring paths manage versioned scenarios and story cards, and an MCP bridge exposes scenario tools. The README documents these capabilities; sampled excerpts show only parts of their wiring, so uncertain calls are omitted.
Main entry points: turn-worker.ts Turn worker · schema.ts Canonical database · app.ts REST and SSE API · scenario-service.ts Scenario service
Components 22
Player client
- Web app
apps/web/src/main.tsx
Application services
- REST and SSE API
apps/api/src/app.ts - Run service
apps/api/src/run-service.ts - Scenario MCP server
apps/scenario-mcp/src/server.ts
Turn runtime
- Turn worker
apps/worker/src/turn-worker.ts - Turn engine
packages/engine/src/orchestrator.ts - NPC context
packages/engine/src/npc-context-service.ts - AI gateway
packages/ai/src/index.ts - Prompt builders
packages/prompts/src/builders.ts
World data
- Domain policies
packages/domain/src/policies.ts - API contracts
packages/contracts/src/api.ts - Run and scenario services
packages/db/src/run-services.ts - NPC context repository
packages/db/src/npc-context.ts - Canonical database
packages/db/src/schema.ts
Authoring and context
- Scenario service
apps/api/src/scenario-service.ts - Narrative architect
packages/architect/src/index.ts - Context retrieval
packages/retrieval/src/sql-service.ts - Scenario tools
packages/scenario-tools/src/index.ts - Retrieval indexing
packages/retrieval/src/indexer.ts
Other components
- Player
- Turn queue
- PostgreSQL
Connections 25
- Player → Web app: submits actions
- Web app → REST and SSE API: requests views and turns
- REST and SSE API → API contracts: validates API data
- REST and SSE API → Run service: delegates run operations
- REST and SSE API → Scenario service: delegates scenario edits
- Run service → Turn queue: enqueues turns
- Turn queue → Turn worker: delivers jobs
- Turn worker → Turn engine: orchestrates stages
- Turn worker → AI gateway: requests generation
- Turn worker → Prompt builders: builds role prompts
- Turn worker → Narrative architect: advances story guidance
- Turn worker → Run and scenario services: persists turn state
- Turn engine → Domain policies: applies policies
- Turn engine → NPC context: builds NPC context
- NPC context → NPC context repository: loads scoped context
- NPC context → Domain policies: checks query scope
- Run and scenario services → Canonical database: reads and writes
- NPC context repository → Canonical database: reads context records
- Context retrieval → Canonical database: searches and audits
- Retrieval indexing → Canonical database: indexes context
- Canonical database → PostgreSQL: stores canonical state
- Scenario service → Scenario tools: validates operations
- Scenario service → Narrative architect: critiques card changes
- Scenario service → Canonical database: versions scenario data
- Scenario MCP server → REST and SSE API: calls scenario API