Kagura

An AI-powered visual novel creation suite — a self-hosted content-management and creation system for multiple VN projects, built around a deeply connected knowledge base (characters, lore, locations, chapters, timelines) that grounds user–AI collaboration: from AI-assisted sprite and background generation, through scene-by-scene writing, to previewing the result — all in one Blazor app.

At a glance

• Self-hosted, single user on a home server, behind a shared-secret access gate.
• ASP.NET Core + Blazor Server on .NET 10, structured as a modular monolith in clean ports-and-adapters.
• One SQLite knowledge graph (records are nodes, relationships are links) plus on-disk assets; every change is auto-applied, journaled, and reversible (undo + Wikipedia-style per-document history).
• Image generation via NovelAI (Diffusion 5, with 4.5 for reference-driven generations); LLM collaboration via OpenRouter; a bundled booru tag database for spelling-safe tag authoring.
• A built-in C#-native player for previewing; shipped as a Docker image.
• An AI collaborator that reads and edits the same project data you do, through the same validated use cases — every change reversible.

Architecture in brief

• Ports & adapters — Server / BlazorAdapter / UseCases / Domain / Infrastructure / Kernel (ADR 0003), with the design system vendored as the Kagaku.UI submodule (ADR 0044), organized as bounded-context modules over one graph DB (ADR 0017).
• Knowledge graph — Entry nodes + generic Link edges + backlink navigation (ADR 0019).
• Reversible by design — a persistent change journal, soft delete, and per-document revision history (ADR 0020, 0022).
• Fluxor UI state with per-circuit event bridges + cross-session sync (ADR 0016); Material Symbols icons + CSS-variable design tokens (ADR 0023).
• DB-native scenes (ordered steps) and a C#-native player engine (ADR 0007, 0008).

Built on / informed by

Reused as dependencies:

• NovelAI.ImageGen — NovelAI Diffusion 4.5 / 5 client
• OpenRouter.Net — LLM client + agent loop
• booru_tag_db_dart — the danbooru tag database (bundled, read-only reference data)

Designed fresh, informed by (references, not dependencies): VNovelPlayer (scene format + player design), NovelAI.VisualNovelCreator (generation pipeline), novel-crafter / NovelArtist (knowledge base + agent tooling), story-forge (timeline / routes / biography).

Documentation

A good reading order:

• Agent notes — the short map for anyone (human or agent) changing the code: where things live, the boundaries, how work is verified and landed
• Developing Kagura — build, run with sample data, browser verification, the pre-PR checks, review rounds
• Requirements (SRS) — actors, epics, and a checkable requirement list; detailed per-feature stories under docs/stories/, with a Status paragraph where the work has shipped
• Project plan — goal, MVP scope, the phased roadmap, risks
• Architecture overview — system shape and runtime flows
• Architecture Decision Records — the planning-phase decisions (0001–0024) and the ones made during implementation (0025 onward)
• Design system — tokens, theming, icons, component inventory; the components themselves live in Kagaku.UI

Status

In use. The plan's phases 0–4 are built — the knowledge base with journaled, reversible edits and document history; sprite, background and event-CG generation through the queue; chapters, the kinetic scene editor and the debug player; the AI assistant with its tool catalog, memory and skills — plus text-to-speech, the stage in centimeters, and character and outfit sheets. The stories under docs/stories/ say what of each feature is built, box by box and in their Status paragraphs; the requirements checklist tracks the rest. The app ships as a Docker image from the Forgejo registry (deploy/).