$ show newideas99/open-dungeon
Open Dungeon is a fully local AI roleplay application that generates both narrative text and inline scene images on-device. Built as a Next.js 16 application with a React 19 frontend, it provides a rich interactive fiction experience where users can write actions, dialogue, or narration, and the AI narrator responds with streaming prose. The system supports multiple text backends: local Ollama models (Gemma 4 QAT variants) or any OpenAI-compatible server (LM Studio, llama.cpp, OpenRouter, etc.). Image generation is handled by a separate Python HTTP server that wraps optimized FLUX.2-klein backends (MFLUX/MLX on Apple Silicon, PyTorch SDNQ on CUDA/CPU) or an existing ComfyUI instance. The architecture is a monolith with a Next.js server handling API routes, SQLite for persistence, and an optional sidecar image server. Key entry points include the main chat UI (src/app/page.tsx), the story API (src/app/api/story/route.ts) which handles streaming narration, and the image generation API (src/app/api/images/route.ts). The codebase demonstrates strong engineering practices: thorough streaming support with artifact filtering, robust error handling with timeouts and fallbacks, clean database abstraction, and well-structured Python image server with resident model support.
The LLM identified 5 files worth highlighting for reuse:
A standalone HTTP server that wraps multiple FLUX.2-klein image generation backends (MFLUX/MLX, PyTorch SDNQ) with a unified API. It supports resident model mode via IPC to a long-lived MLX worker, automatic backend fallback (MFLUX→SDNQ on non-macOS), reference image handling, and configurable dimensions/aspects. The server is well-structured with clean separation of concerns, proper timeout handling, and detailed health reporting. It could be extracted as a reusable image generation microservice.
A resident MLX worker process that keeps Flux2Klein and the uncensored GGUF text encoder loaded across requests. It communicates via JSON-lines over stdin/stdout, supports both text-to-image and edit (reference-based) generation, and manages memory with MLX cache limits. The worker demonstrates a clean pattern for keeping ML models warm between inference calls, with proper error handling and memory reporting.
Contains the core prompt construction logic and a streaming artifact filter that strips reasoning model artifacts (think blocks, channel markers, Harmony tags) from narration output in real-time. The `createStreamingArtifactFilter` function implements a state machine that suppresses thought content, handles partial markers split across chunks, and emits only visible story text. The `stripReasoningArtifacts` function provides a non-streaming counterpart. This is a non-obvious, reusable pattern for any application consuming streaming LLM output from reasoning models.
A clean SQLite database abstraction using better-sqlite3 with automatic schema creation and migration (ALTER TABLE for new columns). It provides typed CRUD operations for chats, messages, characters, and app settings, with proper transaction handling for multi-table updates. The module handles JSON serialization/deserialization for complex fields and includes a story summary compaction system for long context windows. It's well-structured and could be extracted as a reusable local-first storage pattern.
A clean integration module for ComfyUI that builds a standard text-to-image workflow, submits it via the ComfyUI prompt API, polls for completion, and retrieves the generated image. It handles checkpoint discovery, dimension calculation for different modes/aspects, and proper timeout management. The module demonstrates a reusable pattern for interacting with ComfyUI's HTTP API from a Node.js backend.