# lingfengqaq/webnovel-writer architecture

> Architecture diagram of the GitHub repository lingfengqaq/webnovel-writer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lingfengqaq/webnovel-writer
- Repository: https://github.com/lingfengqaq/webnovel-writer

## Overview

1. **What this repo is**
   - `webnovel-writer` is a Claude Code plugin that turns a novel-writing project into a managed system with commands, agents, reference packs, and a read-only dashboard.
   - The runtime is mostly Python 3.10+, with a separate built React/Vite frontend for visualization.

2. **Top-level boundaries**
   - The plugin boundary is defined by `.claude-plugin/` and `webnovel-writer/.claude-plugin/`, which package the Marketplace install metadata.
   - The main project boundary is the user’s novel workspace, where the system reads and writes project-local state rather than relying on a central server.

3. **User interaction layer**
   - Claude Code skills in `skills/webnovel-*` provide the primary UX: init, plan, query, write, review, and dashboard.
   - Agent prompts in `agents/` add specialized roles such as context, data, and reviewer, so the model can split planning, retrieval, and quality checks.

4. **Core orchestration layer**
   - `scripts/webnovel.py`, `story_system.py`, `review_pipeline.py`, `memory_cli.py`, `update_state.py`, and related utilities act as the command-line entry points.
   - Most business logic is concentrated in `scripts/data_modules/`, which is a domain-services layer rather than a single monolith.

5. **Story System as the primary source of truth**
   - The README makes the key architectural rule explicit: `.story-system/` is the canonical write-time source of truth.
   - After a chapter is accepted, `chapter_commit_service`, `event_log_store`, and `event_projection_router` convert the commit into derived project state.

6. **Derived read models and projections**
   - `.webnovel/` is the read-model layer: `state.json`, `index.db`, `summaries/`, and `memory_scratchpad.json` are regenerated projections.
   - Projection writers such as `state_projection_writer`, `summary_projection_writer`, `index_projection_writer`, `memory_projection_writer`, and `vector_projection_writer` keep those views synchronized.

7. **Retrieval and context assembly**
   - `context_manager`, `context_ranker`, `query_router`, `knowledge_query`, `rag_adapter`, and `reference_search` form the retrieval path used before writing or reviewing.
   - The system combines project content, chapter history, reference corpus, and genre guidance, with external embedding/rerank APIs configured through `.env` for RAG.
   - `references/` and `genres/` are the knowledge bases; they feed genre profiles, writing rules, and fallback guidance when contracts are incomplete.

8. **Long-term memory subsystem**
   - `scripts/data_modules/memory/` implements a separate memory pipeline with bootstrap, store, writer, budget, compactor, and orchestrator pieces.
   - This subsystem is used to retain durable narrative facts and writing context across chapters, then surfaces them back into the write-time flow through memory projections.

9. **Dashboard subsystem**
   - `webnovel-writer/dashboard/` is a standalone read-only app: a Python backend (`app.py`, `server.py`, `watcher.py`, `path_guard.py`) serves data, while `frontend/` is a prebuilt React/Vite bundle.
   - The dashboard consumes the same project projections and shows system status, files, characters, pacing, foreshadowing, and overview data; it does not own authoring state.

10. **Templates, validations, and operational guardrails**
   - `templates/` and `skills/*/references/` provide structured prompts and output schemas for common novel genres and writing tasks.
   - `agents/evals/` and `scripts/data_modules/tests/` form the validation layer, covering runtime behavior, projection integrity, and plugin workflows.
   - CI and release automation in `.github/workflows/` plus plugin-release scripts support packaging, versioning, and Marketplace distribution.

Main entry points: [`webnovel-writer/scripts/data_modules`](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules) (Data modules), [`webnovel-writer/scripts/data_modules/context_manager.py`](https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/context_manager.py) (Retrieval core), [`webnovel-writer/.claude-plugin/plugin.json`](https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/.claude-plugin/plugin.json) (Plugin bundle), [`webnovel-writer/scripts/data_modules/chapter_commit_service.py`](https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/chapter_commit_service.py) (Commit chain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["Plugin boundary"]
  node_plugin_meta["Plugin metadata<br/>plugin manifest<br/>[marketplace.json]"]
  node_plugin_bundle["Plugin bundle<br/>plugin package<br/>[plugin.json]"]
end

subgraph group_ux["User UX"]
  node_skills["Skills"]
  node_agents["Agents<br/>prompt roles"]
end

subgraph group_orchestration["Runtime orchestration"]
  node_cli["CLI entrypoints<br/>python cli"]
  node_data_modules["Data modules<br/>domain services"]
end

subgraph group_story["Story system"]
  node_story_engine{{"Story engine<br/>runtime core"}}
  node_commit_chain["Commit chain<br/>event pipeline"]
  node_event_store[("Event store<br/>event log<br/>[event_log_store.py]")]
end

subgraph group_readmodel["Read models"]
  node_projections["Projections<br/>read model writers"]
  node_workspace_state[("Workspace state<br/>project state")]
end

subgraph group_memory["Memory pipeline"]
  node_memory_system["Memory system<br/>memory pipeline"]
end

subgraph group_retrieval["Retrieval"]
  node_retrieval_core["Retrieval core<br/>context assembly<br/>[context_manager.py]"]
end

subgraph group_knowledge["Knowledge bases"]
  node_knowledge_bases["Knowledge bases<br/>reference corpus"]
  node_genre_packs["Genre packs<br/>genre library"]
  node_templates["Templates<br/>prompt schemas"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_app["Dashboard app<br/>read-only app"]
  node_dashboard_ui["Dashboard UI<br/>react frontend"]
end

subgraph group_release["Validation & release"]
  node_ci_release["CI & release<br/>automation<br/>[workflows]"]
  node_validation["Validation layer<br/>tests"]
end

node_plugin_meta -->|"packages"| node_plugin_bundle
node_plugin_bundle -->|"installs"| node_skills
node_plugin_bundle -->|"ships"| node_agents
node_skills -->|"invoke"| node_cli
node_agents -->|"assist"| node_data_modules
node_cli -->|"calls"| node_data_modules
node_data_modules -->|"orchestrates"| node_story_engine
node_story_engine -->|"emits"| node_commit_chain
node_commit_chain -->|"records"| node_event_store
node_commit_chain -->|"updates"| node_projections
node_projections -->|"materializes"| node_workspace_state
node_data_modules -->|"queries"| node_retrieval_core
node_retrieval_core -->|"reads"| node_knowledge_bases
node_retrieval_core -->|"adapts"| node_genre_packs
node_retrieval_core -->|"formats"| node_templates
node_data_modules -->|"uses"| node_memory_system
node_memory_system -->|"surfaces"| node_projections
node_dashboard_app -->|"serves"| node_workspace_state
node_dashboard_app -->|"hosts"| node_dashboard_ui
node_data_modules -.->|"tested by"| node_validation
node_ci_release -->|"packages"| node_plugin_meta
node_ci_release -->|"runs"| node_validation

click node_plugin_meta "https://github.com/lingfengqaq/webnovel-writer/blob/master/.claude-plugin/marketplace.json"
click node_plugin_bundle "https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/.claude-plugin/plugin.json"
click node_skills "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/skills"
click node_agents "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/agents"
click node_cli "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts"
click node_data_modules "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules"
click node_story_engine "https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/story_system_engine.py"
click node_commit_chain "https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/chapter_commit_service.py"
click node_event_store "https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/event_log_store.py"
click node_projections "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules"
click node_memory_system "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules/memory"
click node_retrieval_core "https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/context_manager.py"
click node_knowledge_bases "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/references"
click node_genre_packs "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/genres"
click node_templates "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/templates"
click node_dashboard_app "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/dashboard"
click node_dashboard_ui "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/dashboard/frontend"
click node_ci_release "https://github.com/lingfengqaq/webnovel-writer/blob/master/.github/workflows"
click node_validation "https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_plugin_meta,node_plugin_bundle,node_retrieval_core toneBlue
class node_skills,node_agents,node_knowledge_bases,node_genre_packs,node_templates toneAmber
class node_cli,node_data_modules,node_dashboard_app,node_dashboard_ui toneMint
class node_story_engine,node_commit_chain,node_event_store,node_ci_release,node_validation toneRose
class node_projections,node_workspace_state toneIndigo
class node_memory_system toneTeal
```

## Components

### Plugin boundary

Claude Code plugin packaging and install metadata.

- [Plugin metadata](https://github.com/lingfengqaq/webnovel-writer/blob/master/.claude-plugin/marketplace.json): plugin manifest · Marketplace/plugin install descriptors for Claude Code. · `.claude-plugin/marketplace.json`
- [Plugin bundle](https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/.claude-plugin/plugin.json): plugin package · Packaged plugin metadata inside the repo mirror. · `webnovel-writer/.claude-plugin/plugin.json`

### User UX

Skills and agents that mediate authoring workflows.

- [Skills](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/skills): claude skills · Primary UX surface for init, plan, query, write, review, and dashboard workflows. · `webnovel-writer/skills`
- [Agents](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/agents): prompt roles · Specialized model roles for context, data, reviewer, and evals. · `webnovel-writer/agents`

### Runtime orchestration

CLI entrypoints and the main Python runtime.

- [CLI entrypoints](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts): python cli · User-facing commands and wrappers such as webnovel, story system, review, and memory. · `webnovel-writer/scripts`
- [Data modules](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules): domain services · Core business logic layer coordinating state, context, retrieval, projections, and validation. · `webnovel-writer/scripts/data_modules`

### Story system

Canonical write-time source of truth and event processing.

- [Story engine](https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/story_system_engine.py): runtime core · Contract-first runtime that drives chapter commit and state evolution. · `webnovel-writer/scripts/data_modules/story_system_engine.py`
- [Commit chain](https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/chapter_commit_service.py): event pipeline · Chapter commit, event log storage, and projection routing for accepted writing. · `webnovel-writer/scripts/data_modules/chapter_commit_service.py`
- [Event store](https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/event_log_store.py): event log · Persistent event log backing the story system state transitions. · `webnovel-writer/scripts/data_modules/event_log_store.py`

### Read models

Derived project state and projections for consumers.

- [Projections](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules): read model writers · State, summary, index, memory, and vector projection writers. · `webnovel-writer/scripts/data_modules`
- **Workspace state**: project state · Project-local canonical and derived files such as .story-system and .webnovel.

### Memory pipeline

Long-term memory subsystem for durable narrative context.

- [Memory system](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules/memory): memory pipeline · Bootstrap, store, writer, budget, compactor, and orchestrator for durable narrative memory. · `webnovel-writer/scripts/data_modules/memory`

### Retrieval

Context assembly and knowledge lookup before generation or review.

- [Retrieval core](https://github.com/lingfengqaq/webnovel-writer/blob/master/webnovel-writer/scripts/data_modules/context_manager.py): context assembly · Context manager, ranker, query router, RAG adapter, and knowledge query path. · `webnovel-writer/scripts/data_modules/context_manager.py`

### Knowledge bases

Genre guidance, references, and templates.

- [Knowledge bases](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/references): reference corpus · Genre profiles, shared reference packs, and domain guidance. · `webnovel-writer/references`
- [Genre packs](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/genres): genre library · Genre-specific guidance and templates for planning, writing, and review. · `webnovel-writer/genres`
- [Templates](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/templates): prompt schemas · Structured output and genre templates used by skills and runtime flows. · `webnovel-writer/templates`

### Dashboard

Read-only visualization app and its backend/frontend.

- [Dashboard app](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/dashboard): read-only app · Standalone backend that serves project projections to the UI. · `webnovel-writer/dashboard`
- [Dashboard UI](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/dashboard/frontend): react frontend · Built React/Vite bundle for system status, files, pacing, foreshadowing, and overview views. · `webnovel-writer/dashboard/frontend`

### Validation & release

Tests, CI, and release automation.

- [CI & release](https://github.com/lingfengqaq/webnovel-writer/blob/master/.github/workflows): automation · Workflow and release automation for tests, versioning, and Marketplace distribution. · `.github/workflows`
- [Validation layer](https://github.com/lingfengqaq/webnovel-writer/tree/master/webnovel-writer/scripts/data_modules/tests): tests · Runtime, projection, and plugin workflow validation coverage. · `webnovel-writer/scripts/data_modules/tests`

## Connections

- Plugin metadata → Plugin bundle: packages · Top-level and mirrored plugin metadata define install packaging.
- Plugin bundle → Skills: installs · Plugin surfaces skills as the primary user workflow.
- Plugin bundle → Agents: ships · Plugin includes specialized agent prompts.
- Skills → CLI entrypoints: invoke · Skills drive command execution and workflow entrypoints.
- Agents → Data modules: assist · Agents rely on shared runtime services for retrieval and quality checks.
- CLI entrypoints → Data modules: calls · CLI wrappers dispatch into the core runtime layer.
- Data modules → Story engine: orchestrates · Domain services coordinate the story system runtime.
- Story engine → Commit chain: emits · Accepted writing flows into the chapter commit chain.
- Commit chain → Event store: records · Commit chain persists story events and history.
- Commit chain → Projections: updates · Events are projected into read models.
- Projections → Workspace state: materializes · Projections regenerate project-local state for writers and readers.
- Data modules → Retrieval core: queries · Runtime assembles context before writing or review.
- Retrieval core → Knowledge bases: reads · Retrieval pulls shared references and guidance.
- Retrieval core → Genre packs: adapts · Genre-specific packs shape context and recommendations.
- Retrieval core → Templates: formats · Templates provide structured prompts and output schemas.
- Data modules → Memory system: uses · Runtime uses the dedicated long-term memory pipeline.
- Memory system → Projections: surfaces · Memory state is fed back through projection writers.
- Dashboard app → Workspace state: serves · Dashboard backend reads the same derived project projections.
- Dashboard app → Dashboard UI: hosts · Backend serves the prebuilt frontend bundle.
- Data modules → Validation layer: tested by · Core services are covered by runtime and projection tests.
- CI & release → Plugin metadata: packages · Automation supports release and versioning of plugin metadata.
- CI & release → Validation layer: runs · CI validates runtime and packaging workflows.
