139 lines
5.6 KiB
Markdown
139 lines
5.6 KiB
Markdown
# Open Dungeon — Static Architecture Analysis
|
|
|
|
**Repository:** https://github.com/newideas99/open-dungeon
|
|
**Date reviewed:** 2026-09-01
|
|
**Disposition:** Finalist #2; strongest product/UI/media fit, but branch persistence requires material redesign.
|
|
|
|
## What maps well to the specification
|
|
|
|
Open Dungeon already provides a product very close to the desired interaction model:
|
|
|
|
- browser-first UI,
|
|
- local Ollama text generation,
|
|
- streaming narration,
|
|
- Do / Say / Story-style interaction,
|
|
- Continue / Retry / Erase / Edit controls,
|
|
- SQLite persistence,
|
|
- rolling story summary for long conversations,
|
|
- persistent character records,
|
|
- local inline image generation,
|
|
- character portraits/visual continuity feeding image generation,
|
|
- optional ComfyUI path.
|
|
|
|
The future-media requirement is therefore not hypothetical in this codebase. It already has a concept of the narrator requesting an image after prose and a local image backend producing it.
|
|
|
|
## Current stack
|
|
|
|
From the current package/config:
|
|
|
|
- Next.js 16
|
|
- React 19
|
|
- TypeScript
|
|
- `better-sqlite3`
|
|
- Node.js 22+
|
|
- Ollama default endpoint at `127.0.0.1:11434`
|
|
- local image worker defaults to loopback
|
|
- optional remote OpenAI-compatible/OpenRouter configuration
|
|
|
|
## Persistence finding: the major issue
|
|
|
|
The current database is fundamentally a linear chat model.
|
|
|
|
The reviewed schema contains:
|
|
|
|
- chats,
|
|
- messages,
|
|
- characters,
|
|
- app settings,
|
|
- rolling story summary fields.
|
|
|
|
Messages do not expose a parent-turn/branch-lineage model equivalent to AI-DnD or ai-adventure.
|
|
|
|
More importantly, the data layer includes an operation named `deleteMessageAndAfter()`. Its own comment says it is used by retry/erase to discard the tail of the story. Prior text can also be updated in place.
|
|
|
|
That is directly contrary to the target requirement:
|
|
|
|
> Going backward should preserve the abandoned future as an alternate branch.
|
|
|
|
This means adding robust branching is not simply a UI feature. It requires changing the persistence semantics and all features that assume a single mutable message sequence, including retry/erase/edit and summary lineage.
|
|
|
|
## Memory/context model
|
|
|
|
The prompt builder contains a history-packing mechanism with block eviction. Old story material is compressed into a rolling story summary, while recent history stays direct.
|
|
|
|
This is a reasonable lightweight storyteller strategy but is below the target design:
|
|
|
|
- no established semantic retrieval of old story events,
|
|
- no explicit Canon / Reference / Inspiration document library,
|
|
- no branch-aware memory lineage,
|
|
- no rich authoritative generic story-state graph.
|
|
|
|
Those systems would need to be added.
|
|
|
|
## Media design
|
|
|
|
Open Dungeon is the strongest finalist for immediate media UX.
|
|
|
|
The current narrator prompt exposes a `generate_image` tool after a passage and passes selected character IDs so the image path can preserve visual identity. The app can use local FLUX tooling and supports ComfyUI in recent releases.
|
|
|
|
Useful ideas to retain even if Open Dungeon is not the base:
|
|
|
|
1. media is optional; text play does not depend on it,
|
|
2. image generation is scene/turn-associated,
|
|
3. character visual identity is stored rather than reinvented each image,
|
|
4. local backend is behind a service boundary,
|
|
5. generated media appears inline in the story.
|
|
|
|
For our architecture, image generation should eventually move behind a generic media-provider interface rather than remain hard-coded to one model/workflow.
|
|
|
|
## Privacy/static network assessment
|
|
|
|
Positive:
|
|
- local Ollama is the default,
|
|
- local SQLite is the default,
|
|
- local image generation is supported,
|
|
- no telemetry requirement was apparent in the inspected package/config.
|
|
|
|
Hardening needed:
|
|
- remove or disable OpenRouter and arbitrary remote OpenAI-compatible provider options in v1,
|
|
- review Tailscale/LAN exposure separately from loopback-only default,
|
|
- verify built frontend has no remote runtime assets,
|
|
- verify image setup does not make unexpected runtime downloads after installation,
|
|
- runtime network capture still required.
|
|
|
|
## Testing concern
|
|
|
|
The inspected `package.json` exposes build/lint/image checks but no obvious comprehensive automated test command comparable to AI-DnD or Gamentic. This must be verified after clone; if accurate, a branch/persistence rewrite would need a new test foundation before implementation.
|
|
|
|
## Best reuse case
|
|
|
|
If Open Dungeon becomes the base:
|
|
- preserve the browser experience,
|
|
- preserve Ollama integration,
|
|
- preserve image/visual-continuity concepts,
|
|
- replace/extend linear message persistence with a parent-linked turn graph,
|
|
- make summary/memory branch-aware,
|
|
- add authoritative generic narrative state,
|
|
- add local document ingestion and retrieval,
|
|
- add prompt/provenance inspection.
|
|
|
|
If AI-DnD becomes the base:
|
|
- use Open Dungeon primarily as a UX and media-generation reference.
|
|
|
|
## Phase 0B questions for Codex
|
|
|
|
1. How many routes/components assume messages are a single ordered list?
|
|
2. Can a parent-linked turn/branch layer be introduced without replacing most chat APIs?
|
|
3. What happens to `story_summary` when retry/erase edits earlier history?
|
|
4. Can current image records attach cleanly to immutable turn IDs/scene IDs?
|
|
5. Is there an automated test suite not visible from the package manifest?
|
|
6. With Internet blocked, does ordinary text + local image play produce only loopback traffic?
|
|
|
|
## Primary source links
|
|
|
|
- Repository: https://github.com/newideas99/open-dungeon
|
|
- DB: https://github.com/newideas99/open-dungeon/blob/main/src/lib/db.ts
|
|
- Prompt builder: https://github.com/newideas99/open-dungeon/blob/main/src/lib/story-prompt.ts
|
|
- Environment: https://github.com/newideas99/open-dungeon/blob/main/.env.example
|
|
- Package: https://github.com/newideas99/open-dungeon/blob/main/package.json
|