How lingfengqaq/webnovel-writer works
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: data_modules Data modules · context_manager.py Retrieval core · plugin.json Plugin bundle · chapter_commit_service.py Commit chain
Components 20
Plugin boundary
Claude Code plugin packaging and install metadata.
- Plugin metadata · Marketplace/plugin install descriptors for Claude Code.
.claude-plugin/marketplace.json - Plugin bundle · Packaged plugin metadata inside the repo mirror.
webnovel-writer/.claude-plugin/plugin.json
User UX
Skills and agents that mediate authoring workflows.
Runtime orchestration
CLI entrypoints and the main Python runtime.
- CLI entrypoints · User-facing commands and wrappers such as webnovel, story system, review, and memory.
webnovel-writer/scripts - Data modules · 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 · Contract-first runtime that drives chapter commit and state evolution.
webnovel-writer/scripts/data_modules/story_system_engine.py - Commit chain · Chapter commit, event log storage, and projection routing for accepted writing.
webnovel-writer/scripts/data_modules/chapter_commit_service.py - Event store · 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 · State, summary, index, memory, and vector projection writers.
webnovel-writer/scripts/data_modules - Workspace 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 · 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 · 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 · Genre profiles, shared reference packs, and domain guidance.
webnovel-writer/references - Genre packs · Genre-specific guidance and templates for planning, writing, and review.
webnovel-writer/genres - Templates · 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 · Standalone backend that serves project projections to the UI.
webnovel-writer/dashboard - Dashboard UI · 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 · Workflow and release automation for tests, versioning, and Marketplace distribution.
.github/workflows - Validation layer · Runtime, projection, and plugin workflow validation coverage.
webnovel-writer/scripts/data_modules/tests
Connections 22
- 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.