One monorepo. Each directory has one job; each file has one job. The INDEX.md resolver in every code dir is the authoritative map this tree is built from. Click any entry for its one job, key files and what it produces.

repo root

gamentic/

root

Self-hosted AI dungeon RPG monorepo: the game brain (orchestrator), the no-build UI (frontend), the media services (infra, voice-api), the compose stack and the setup faces, all docs.

One job: One repo; ./up.sh raises whichever world the ANNA boolean names.

Key files / dirs: docker-compose.yml; up.sh; gamentic-setup; setup.html; README.md; CHANGELOG.md; .env.example

Entry / owner: up.sh; gamentic-setup; setup.html; docker-compose.yml

Produces: the running stack (./up.sh raises whichever world ANNA names)

Key point: Writes: .env (via setup faces)

IN: none

OUT: orchestrator (orchestrator/); frontend (frontend/); infra (infra/); voice (voice-api/); docs (docs/)

JSON shape

{
  "services": [
    "orchestrator",
    "frontend",
    "comfyui",
    "image-api",
    "voice-api",
    "anna-api",
    "anna-agent"
  ],
  "config": ".env (single layer)"
}

orchestrator (brain)

orchestrator/

brain

The game brain service: FastAPI orchestrator that resolves one turn per POST, plus its Dockerfile, prompts, tests and SQLite data.

One job: The REST surface plus the turn loop; one turn = one commit.

Key files / dirs: app/; prompts/; tests/; Dockerfile; INDEX.md; requirements.txt

Entry / owner: app/main.py

Produces: one fully-resolved turn per /games/{id}/action

Key point: Writes: gamentic.db (SQLite, WAL)

IN: root (orchestrator/)

OUT: app (app/); prompts (prompts/)

JSON shape

{
  "entrypoint": "app/main.py",
  "db": "gamentic.db"
}

orchestrator/app/

brain

The Python package: every route, the turn engine, the tool registry, the SQL layer, media glue, prompts assembly and config; one file/subpackage per concern.

One job: Each file has one job; the INDEX is the resolver.

Key files / dirs: main.py; prompts.py; db.py; models.py; config.py; engine/; tools/; repo/; integrate/; providers/; constants.py; voice_design.py

Entry / owner: app/main.py; app/engine/turn.py

Produces: resolved GameState + beats

Key point: Writes: SQLite via repo/

IN: orchestrator (app/)

OUT: engine (engine/); tools (tools/); repo (repo/); integrate (integrate/); providers (providers/); fMain (main.py); fPrompts (prompts.py); fLlm (llm.py); fDb (db.py); fModels (models.py); fMedia (media.py); fConfig (config.py); fCreator (creator.py); fTransfer (transfer.py)

JSON shape

{
  "facades": [
    "engine",
    "tools",
    "repo",
    "integrate",
    "providers"
  ]
}

app/engine/

brain

The turn loop, one module per concern: player beats, deterministic adjudication, the narrator call, the bounded character cascade, whispers, the context meter, prose scrubbing, the new-item diff, background memory folds.

One job: The turn loop: run_turn does everything; folds open their own conns.

Key files / dirs: turn.py; parsing.py; folds.py; __init__.py; INDEX.md

Entry / owner: app/engine/turn.py: run_turn; app/engine/parsing.py; app/engine/folds.py

Produces: adjudicated turn, scrubbed beats, memory folds

Key point: Writes: beats, character/game summaries (via repo)

IN: app (engine/)

OUT: none

JSON shape

{
  "modules": [
    "turn.py",
    "parsing.py",
    "folds.py"
  ],
  "key": "run_turn, interpret_action"
}

app/tools/

brain

The model's ONLY way to change state: one module per domain, each tool's JSON schema beside its handler, composed by a registry. A tool the schema does not describe does not exist.

One job: The model's ONLY way to change state.

Key files / dirs: combat.py; items.py; characters.py; progression.py; scene.py; world.py; narrative.py; base.py; __init__.py; INDEX.md

Entry / owner: app/tools/base.py: @tool registry; app/tools/__init__.py: apply_tool

Produces: state-change receipts {kind,text,cue,reactions}

Key point: Writes: game state via repo (the only writers)

IN: app (tools/)

OUT: none

JSON shape

{
  "handler": "(conn,gid,args,actor) -> {kind,text,cue,reactions}",
  "kind": "state|cue|memory|invalid|spawn|kill|reject|image"
}

app/repo/

brain

All SQL, one module per domain (games, players, characters, items, scenes, quests, lore, beats, clock, state). Callers just use repo.<fn>; the engine owns the transaction.

One job: Data access; one turn = one commit; names normalized on every write.

Key files / dirs: games.py; players.py; characters.py; items.py; scenes.py; quests.py; lore.py; beats.py; clock.py; state.py; base.py; INDEX.md

Entry / owner: app/repo/state.py: game_state; app/repo/items.py (item-blob rules)

Produces: the assembled GameState the API serves (state.py: game_state)

Key point: Writes: every SQLite table

IN: app (repo/)

OUT: none

JSON shape

{
  "assembled_by": "state.py: game_state",
  "items": "JSON lists on owner rows"
}

app/integrate/

brain

Glue to the media services: image prompt composition (gender net, no-text guard, identity references), voice assignment, media persistence, all background generation jobs. Best-effort: media down never breaks the game.

One job: Never hold a DB conn across a render; re-check the game exists before writing.

Key files / dirs: voice.py; image_prompts.py; storage.py; jobs.py; events.py; __init__.py; INDEX.md

Entry / owner: app/integrate/jobs.py; app/integrate/storage.py: _persist; app/integrate/image_prompts.py

Produces: background art/voice jobs, persisted /media files

Key point: Writes: per-game /media folder, scene/item/character image urls

IN: app (integrate/)

OUT: none

JSON shape

{
  "modules": [
    "voice.py",
    "image_prompts.py",
    "storage.py",
    "jobs.py"
  ]
}

app/providers/

brain

The inference-providers layer: one interface per modality, dialect classes for pure JSON shaping (httpx only, no SDKs), the config spine, and the Anna preset. Config resolves at call time (env -> default).

One job: .env is the single config layer; defaults reproduce the local stack byte-for-byte.

Key files / dirs: base.py; image.py; audio.py; __init__.py; INDEX.md

Entry / owner: app/providers/base.py: resolve, anna_config; app/providers/image.py; app/providers/audio.py

Produces: resolved ProviderConfig per call (text/image/audio)

Key point: Writes: nothing (stateless dialects)

IN: app (providers/)

OUT: none

JSON shape

{
  "modalities": [
    "text",
    "image",
    "audio"
  ],
  "dialects": [
    "comfy",
    "openai",
    "gemini",
    "fal",
    "local",
    "elevenlabs"
  ],
  "anna_preset": "base.py"
}

orchestrator/prompts/

brain

The actual prose of every prompt (narrator core + protocol blocks, character, interpreter, explainer, image-prompt writer, creator/finalize, summaries), editable without touching code, reloaded per call.

One job: Protocol blocks inject ONLY when state triggers them (the resolver).

Key files / dirs: narrator.system.md; narrator.easy.md/.hard.md/.newplace.md/.returning.md/.looking.md/.attempts.md/.resolve.md; character.system.md; interpret.system.md; imageprompt.system.md; explain.system.md; creator.system.md; finalize.system.md; summary/charsummary/origin/artdirector .md

Entry / owner: edit the .md prose directly

Produces: the system/user messages each agent receives

Key point: Writes: nothing (read at call time)

IN: orchestrator (prompts/)

OUT: none

JSON shape

{
  "always": "narrator.system.md",
  "conditional": [
    "narrator.easy/hard/newplace/returning/looking/attempts/resolve"
  ]
}

orchestrator files

app/main.py

file

The REST surface: every route, request gating, background-task scheduling. Nothing else.

One job: The REST surface. Every route, request gating, background-task scheduling. Nothing else.

Key files / dirs: models.py; engine/; integrate/; repo/

Entry / owner: app/main.py

Produces: one resolved turn per POST /games/{id}/action; SSE media events

Key point: Writes: schedules background art/folds; opens the per-turn connection

IN: app (main.py)

OUT: none

JSON shape

{
  "flagship": "POST /games/{id}/action",
  "events": "GET /games/{gid}/events (SSE)"
}

app/prompts.py

file

Message assembly for every agent (narrator, characters, interpreter, explainer, image-prompt writer, creator). Computes the state block and decides WHICH protocol blocks inject this turn.

One job: Message assembly; computes the state block and which protocol blocks inject.

Key files / dirs: prompts/*.md; constants.py; repo state

Entry / owner: app/prompts.py

Produces: the assembled message arrays each agent receives

Key point: Writes: nothing

IN: app (prompts.py)

OUT: none

JSON shape

{
  "output": "messages[] per agent",
  "decides": "which prompts/*.md blocks to inject"
}

app/llm.py

file

The one llama.cpp client function, chat(): no framework, returns the assistant message with parsed tool calls; the same server + model backs every agent, only the messages differ.

One job: The one llama.cpp client function, chat().

Key files / dirs: providers/base.py: resolve('text')

Entry / owner: app/llm.py: chat

Produces: assistant message + parsed tool calls

Key point: Writes: nothing

IN: app (llm.py)

OUT: none

JSON shape

{
  "fn": "chat()",
  "returns": "{content, tool_calls}"
}

app/db.py

file

Schema, migrations, WAL connection settings.

One job: Schema, migrations, WAL connection settings.

Key files / dirs: nothing (owns the schema)

Entry / owner: app/db.py

Produces: the SQLite schema + connections

Key point: Writes: gamentic.db structure (DDL, migrations, PRAGMAs)

IN: app (db.py)

OUT: none

JSON shape

{
  "db": "gamentic.db",
  "mode": "WAL"
}

app/models.py

file

Pydantic request/response shapes (the wire contract).

One job: Pydantic request/response shapes (the wire contract).

Key files / dirs: nothing

Entry / owner: app/models.py

Produces: validated request/response objects

Key point: Writes: nothing

IN: app (models.py)

OUT: none

JSON shape

{
  "defines": "the orchestrator wire contract"
}

app/media.py

file

Thin HTTP clients for image-api and voice-api; keep historical signatures but dispatch to the ACTIVE provider from app/providers/, resolved at call time.

One job: Thin HTTP clients for image-api and voice-api (provider-agnostic facade).

Key files / dirs: providers/image.py; providers/audio.py

Entry / owner: app/media.py

Produces: image/voice bytes or urls

Key point: Writes: nothing

IN: app (media.py)

OUT: none

JSON shape

{
  "targets": [
    "image-api",
    "voice-api"
  ],
  "dispatch": "active provider per call"
}

app/config.py

file

Every knob, env-overridable, with defaults.

One job: Every knob, env-overridable, with defaults.

Key files / dirs: .env / environment

Entry / owner: app/config.py

Produces: resolved config values

Key point: Writes: nothing

IN: app (config.py)

OUT: none

JSON shape

{
  "source": "env -> default"
}

app/creator.py

file

The story-creator chat sessions (persisted in SQLite) and world finalization: interview the user, then emit a structured WorldSheet.

One job: Story-creator chat sessions (SQLite-persisted) and world finalization.

Key files / dirs: prompts/creator.system.md; prompts/finalize.system.md; db.py

Entry / owner: app/creator.py

Produces: a structured WorldSheet from the creation chat

Key point: Writes: creator sessions in SQLite

IN: app (creator.py)

OUT: none

JSON shape

{
  "output": "WorldSheet",
  "sessions": "persisted in SQLite"
}

app/transfer.py

file

Export/import: adventure templates and checkpoint saves, id remapping, media scrubbing (one versioned JSON format family).

One job: Export/import: adventure templates and checkpoint saves, id remapping, media scrubbing.

Key files / dirs: repo state, media folder

Entry / owner: app/transfer.py

Produces: template JSON (world as designed) or checkpoint save (with progress)

Key point: Writes: imported games (remapped ids, scrubbed media)

IN: app (transfer.py)

OUT: none

JSON shape

{
  "kinds": [
    "adventure template",
    "checkpoint save"
  ],
  "format": "versioned JSON"
}

frontend (UI)

frontend/

frontend

The UI layer: vanilla ES modules, no build step; one in-memory state, one render() that MORPHS the DOM (vendored idiomorph), delegated handlers that mutate state and re-render. Served by nginx.

One job: No build step; one state, one morphing render().

Key files / dirs: index.html; styles.css; themes/; vendor/idiomorph.esm.js; src/; test/; nginx.conf; Dockerfile; INDEX.md

Entry / owner: src/app.js; src/app/ui.js: render

Produces: the played game screen

Key point: Writes: FE-local settings (localStorage), per-game PATCH

IN: root (frontend/)

OUT: src (src/); themes (themes/); feTest (test/)

JSON shape

{
  "entry": "src/app.js",
  "render": "src/render.js + src/render/",
  "state": "src/app/ctx.js"
}

frontend/src/

frontend

The ES module source: the boot facade (app.js), the controller package (app/), the REST client (api.js), wire->view adapters, the tagged composer, the diff engine, the voice client, and the render facade + builders.

One job: Raw wire JSON -> view model -> morphed DOM.

Key files / dirs: app.js; api.js; adapters.js; composer.js; transitions.js; voice.js; icons.js; render.js; app/; render/

Entry / owner: src/app.js; src/adapters.js; src/api.js

Produces: view models, DOM, voice synth requests

Key point: Writes: in-memory state (ctx.js)

IN: frontend (src/)

OUT: srcApp (app/); srcRender (render/)

JSON shape

{
  "client": "api.js",
  "adapters": "mapGameState/mapBeats/mapProfile",
  "diff": "transitions.js: diffState"
}

frontend/src/app/

frontend

The controller package: the one in-memory state + voice engine + api client (ctx.js), render/delegate/action-dispatch (ui.js), the turn loop, staged reveal, library, media SSE stream, play controls, profile, composer, creator, speech, settings, cues, lightbox.

One job: The controller; ctx.js holds the ONE state shared as live bindings.

Key files / dirs: ctx.js; ui.js; turns.js; reveal.js; game.js; mediastream.js; playctl.js; profilectl.js; composerctl.js; creatorctl.js; speech.js; settingsctl.js; cues.js; media.js

Entry / owner: src/app/turns.js; src/app/ui.js; src/app/mediastream.js

Produces: the action/continue loop, the staged reveal, SSE-driven media refresh

Key point: Writes: ctx state, localStorage, per-game settings PATCH

IN: src (app/)

OUT: none

JSON shape

{
  "state": "ctx.js",
  "loop": "turns.js",
  "reveal": "reveal.js",
  "sse": "mediastream.js"
}

frontend/src/render/

frontend

The render builders, one module per concern: common helpers, widgets, screens (library/creator/settings), the play deck, the story stream, the character profile, the inspect modal.

One job: One module per screen concern, behind the render facade.

Key files / dirs: common.js; widgets.js; screens.js; play.js; story.js; profile.js; inspect.js

Entry / owner: src/render/play.js; src/render/story.js; src/render/profile.js

Produces: HTML strings the facade morphs in

Key point: Writes: nothing (pure builders)

IN: src (render/)

OUT: none

JSON shape

{
  "modules": [
    "common",
    "widgets",
    "screens",
    "play",
    "story",
    "profile",
    "inspect"
  ]
}

frontend/themes/

frontend

The design tokens: colors, fonts, chamfer factor, eases. A new theme = one file like hightech.css. styles.css carries STRUCTURE only (no color literals, lint-enforced).

One job: A new theme = one file like this; no color literals outside tokens.

Key files / dirs: hightech.css

Entry / owner: themes/hightech.css

Produces: the resolved visual theme (CSS custom properties)

Key point: Writes: nothing

IN: frontend (themes/)

OUT: none

JSON shape

{
  "tokens": [
    "colors",
    "fonts",
    "chamfer",
    "eases"
  ]
}

frontend/test/

frontend

Vitest + jsdom suite: component tests mount the real app.js via init(), drive it with @testing-library/user-event, intercept the orchestrator with MSW at the network layer; plus the theme/mobile lint contracts and the setup-page test.

One job: Mount real app.js, drive with user-event, mock HTTP at the network layer (MSW).

Key files / dirs: play.component.test.js; render.test.js; composer.test.js; interaction.test.js; creator.component.test.js; transitions.test.js; voice.test.js; api.test.js; adapters.test.js; theme.lint.test.js; mobile.lint.test.js; setuppage.test.js; setup.js; fixtures.js

Entry / owner: test/setup.js (MSW default handlers); test/fixtures.js (wire builders)

Produces: pass/fail signal

Key point: Writes: nothing

IN: frontend (test/)

OUT: none

JSON shape

{
  "runner": "vitest (jsdom)",
  "mock": "MSW",
  "setup": "test/setup.js + test/fixtures.js"
}

infra (services)

infra/

infra

The accessory build context: the setup faces over one schema, the ComfyUI image, the image-api adapter, the anna-api OpenAI face + anna-agent container.

One job: One build context per accessory service.

Key files / dirs: setup/; comfyui/; image-api/; anna-api/; anna-agent/; README.md

Entry / owner: docker-compose.yml references these contexts

Produces: the media + setup + anna service images

Key point: Writes: nothing directly (compose builds from here)

IN: root (infra/)

OUT: infraSetup (setup/); infraComfy (comfyui/); infraImageApi (image-api/); infraAnnaApi (anna-api/); infraAnnaAgent (anna-agent/)

JSON shape

{
  "subdirs": [
    "setup",
    "comfyui",
    "image-api",
    "anna-api",
    "anna-agent"
  ]
}

infra/setup/

infra

The two setup faces over one schema: cli.py (terminal wizard, agent flags, host doctor) and setup.js/setup.css (the setup.html page), both rendering from schema.js so the faces can never drift; the schema also generates .env.example.

One job: Both faces render from schema.js so they can never drift apart.

Key files / dirs: schema.js; cli.py; setup.js; setup.css; tests/

Entry / owner: infra/setup/schema.js; infra/setup/cli.py

Produces: .env (saved/downloaded by either face); .env.example

Key point: Writes: .env at repo root

IN: infra (setup/)

OUT: none

JSON shape

{
  "schema": "schema.js",
  "faces": [
    "cli.py",
    "setup.js/setup.html"
  ],
  "tests": [
    "test_cli.py",
    "test_doctor.py"
  ]
}

infra/comfyui/

infra

The ComfyUI container: Dockerfile, entrypoint, the FLUX.2 Klein model fetch script, and its data dir; the GPU image backend on Strix Halo.

One job: The local GPU image backend (FLUX.2 Klein on ComfyUI).

Key files / dirs: Dockerfile; entrypoint.sh; fetch-models.sh; data/

Entry / owner: infra/comfyui/Dockerfile; infra/comfyui/fetch-models.sh

Produces: the ComfyUI GPU service image

Key point: Writes: model weights into data/

IN: infra (comfyui/)

OUT: none

JSON shape

{
  "files": [
    "Dockerfile",
    "entrypoint.sh",
    "fetch-models.sh"
  ]
}

infra/image-api/

infra

The image-api REST adapter in front of ComfyUI: app (main.py, comfy_client.py, workflow.py, config.py), the workflow JSONs, tests and Dockerfile.

One job: REST face over ComfyUI; the orchestrator's media.py talks to it.

Key files / dirs: app/main.py; app/comfy_client.py; app/workflow.py; app/config.py; workflows/; tests/; Dockerfile; README.md

Entry / owner: infra/image-api/app/main.py; infra/image-api/app/comfy_client.py

Produces: generated image bytes/urls (~4s/img)

Key point: Writes: staging image copies (freed once the orchestrator persists)

IN: infra (image-api/)

OUT: none

JSON shape

{
  "app": [
    "main.py",
    "comfy_client.py",
    "workflow.py",
    "config.py"
  ]
}

infra/anna-api/

infra

The anna-api: an OpenAI-shaped face over the vendor Anna CLI (agent.py, wire.py, main.py, config.py) so the game can drive the cloud agent text-only; flattens the stack into one ask and parses tool calls back out.

One job: Gives the vendor CLI an OpenAI face; no password ever touches .env.

Key files / dirs: app/main.py; app/agent.py; app/wire.py; app/config.py; tests/; Dockerfile

Entry / owner: infra/anna-api/app/agent.py; infra/anna-api/app/wire.py

Produces: OpenAI-compatible chat responses (text); images answer 501

Key point: Writes: nothing (signs in via the refresh token on the shared volume)

IN: infra (anna-api/)

OUT: none

JSON shape

{
  "app": [
    "main.py",
    "agent.py",
    "wire.py",
    "config.py"
  ],
  "images": "501"
}

infra/anna-agent/

infra

The anna-agent container: the vendor Anna CLI running in its own container (Dockerfile + its docker-compose.yml), raised when ANNA mode is on.

One job: The vendor CLI runs in its own container.

Key files / dirs: Dockerfile; docker-compose.yml

Entry / owner: infra/anna-agent/Dockerfile

Produces: the running vendor CLI process

Key point: Writes: the refresh token on the shared volume

IN: infra (anna-agent/)

OUT: none

JSON shape

{
  "files": [
    "Dockerfile",
    "docker-compose.yml"
  ]
}

voice-api

voice-api/

voice

The Maya1-3B TTS service on llama.cpp Vulkan: app.py (routes), synth.py, voices.py, characters.py (registry), emotion.py, manifest.py (per-game ownership), config.py, bench + samples + tests.

One job: Maya1 on llama.cpp Vulkan; speak-not-stream, per-game ownership manifest.

Key files / dirs: app.py; synth.py; voices.py; characters.py; emotion.py; manifest.py; config.py; bench.py; tests/; README.md; CHANGELOG.md

Entry / owner: voice-api/app.py; voice-api/synth.py; voice-api/manifest.py

Produces: character speech wavs (RTF ~1.1-1.2, first audio ~0.3s)

Key point: Writes: per-game wav files (the ownership manifest; delete the game, its wavs die)

IN: root (voice-api/)

OUT: none

JSON shape

{
  "route": "POST /voice/speak",
  "manifest": "per-game game_id ownership"
}

docs

docs/

docs

The documentation. The PUBLIC site is ONE page (index.html) whose section views (overview, agents, engine, state, state-json, context, infra, folders) render as a node graph, an indented tree or grouped cards, each paired with an agent-ready guide/ twin. Everything else under docs/ stays private/gitignored.

One job: Where the docs live; read HANDOFF and the atlases first.

Key files / dirs: index.html (single-page docs site); guide/ (agent-ready markdown twins); .nojekyll; HANDOFF.md (private); shared/ anna/ frontend/ image/ voice/ feedback/ (private); README.md (private)

Entry / owner: docs/*.html; docs/shared/inference-providers.md

Produces: the read-first developer docs + interactive atlases

Key point: Writes: nothing

IN: root (docs/)

OUT: none

JSON shape

{
  "public": [
    "index.html (single page: all section views)",
    "guide/<section>/index.md (twins)",
    ".nojekyll"
  ],
  "private": [
    "HANDOFF.md",
    "shared/",
    "anna/",
    "frontend/",
    "image/",
    "voice/",
    "feedback/"
  ]
}

Overview