# forsonny/claude-code-novel-writer architecture

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

- Interactive diagram: https://gitdiagram.com/forsonny/claude-code-novel-writer
- Repository: https://github.com/forsonny/claude-code-novel-writer

## Overview

#### Purpose and entry points
This is a Claude Code–oriented autonomous novel-writing workspace, not a conventional application service. Claude is the primary runtime and executes repository instructions to plan, generate, review, and maintain a long-form manuscript. Bootstrap and validation start at `launch-novel.sh` and `verify-system.sh`; the operational contract is centered on `CLAUDE.md`. Human operators can observe state through `automation/dashboard.py`.

#### Orchestration and agent layer
`CLAUDE.md` acts as the master orchestrator: it directs workflow decisions and delegates specialized work. Agent instruction files form the functional AI pipeline:
- Story structure and adaptive pacing: `.claude/agents/plot-architect.md`, `.claude/agents/smart-planner.md`
- Prose production and continuity review: `.claude/agents/chapter-writer.md`, `.claude/agents/continuity-editor.md`
- Domain enrichment and remediation: `.claude/agents/worldbuilder.md`, `.claude/agents/character-developer.md`, `.claude/agents/error-recovery.md`

Claude configuration and injected reminders reside in `.claude/settings.json` and `.claude/context-injection.txt`.

#### Canonical story state
The system persists narrative state as repository-managed JSON rather than a database. Planning is the principal control input: `planning/novel-outline.json` defines intended structure, while `planning/chapter-status.json`, `planning/plot-progress.json`, and `planning/scene-tracker.json` record execution progress. The orchestrator and planning agents should read these before generation and update them after completed work, making them the synchronization boundary between Claude sessions.

#### Narrative knowledge domains
Character and world facts are separated from planning state to support consistency checks and targeted agent work. `characters/character-knowledge.json` is the character/arc reference; `worldbuilding/world-state.json` captures setting rules and world changes. Manuscript-level metadata belongs in `manuscript/metadata.json`. Generated chapter content is implied to live under `manuscript/`, although no chapter files are present in the supplied tree.

#### Generation and quality loop
The intended loop is: initialize/health-check, synchronize state, assess plan and quality, generate a chapter, run checks, persist progress, and repeat. Chapter formatting and prose expectations are supplied by `templates/chapter-template.md` and `output-styles/autonomous-novelist.md`. `automation/chapter-completed.sh` is the likely post-generation integration boundary, with `automation/quality-check.sh` and `automation/duplicate-checker.sh` providing content validation.

#### Automation, recovery, and observability
Shell automation implements workspace maintenance around Claude-driven generation: session lifecycle in `automation/session-init.sh` and `automation/session-summary.sh`; state synchronization in `automation/auto-sync-progress.sh`; health and performance checks in `automation/system-health-check.sh` and `automation/performance-monitor.sh`. Recovery and durability are handled through `automation/auto-backup.sh`, `automation/pre-compact-backup.sh`, and `automation/backup.sh`. These scripts operate on local files; no external database, API, or deployed infrastructure is evidenced.

#### Runtime and operational boundaries
Required runtimes are a Unix-like shell, Claude Code CLI, and Python 3 for `automation/dashboard.py`. The dashboard is an observer/reporting interface over local project artifacts, including monitor and sync-report modes. Documentation is maintained separately in `Documentation/System-Architecture.md` and `Documentation/User-Guide.md`; it describes operation but is not part of the execution path.

Main entry points: [`.claude/agents/chapter-writer.md`](https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/chapter-writer.md) (Chapter writer), [`CLAUDE.md`](https://github.com/forsonny/claude-code-novel-writer/blob/main/CLAUDE.md) (Master orchestrator), [`.claude/agents/continuity-editor.md`](https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/continuity-editor.md) (Continuity editor), [`planning/chapter-status.json`](https://github.com/forsonny/claude-code-novel-writer/blob/main/planning/chapter-status.json) (Progress trackers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Claude Runtime"]
  node_claude{{"Master orchestrator<br/>Claude instructions<br/>[CLAUDE.md]"}}
  node_planner["Plot architect<br/>planning agent<br/>[plot-architect.md]"]
  node_adaptive_planner["Adaptive planner<br/>planning agent<br/>[smart-planner.md]"]
  node_writer["Chapter writer<br/>generation agent<br/>[chapter-writer.md]"]
  node_editor["Continuity editor<br/>review agent"]
  node_knowledge_agents["World, character &amp; recovery agents<br/>specialist agents<br/>[worldbuilder.md]"]
end

subgraph group_state["Local Story State"]
  node_outline["Novel outline<br/>plan JSON<br/>[novel-outline.json]"]
  node_progress["Progress trackers<br/>state JSON"]
  node_character_knowledge["Character knowledge<br/>reference JSON"]
  node_world_state["World state<br/>reference JSON<br/>[world-state.json]"]
  node_manuscript["Manuscript<br/>generated chapters"]
end

subgraph group_automation["Automation &amp; Quality"]
  node_bootstrap["Bootstrap &amp; validation<br/>shell entry points<br/>[launch-novel.sh]"]
  node_completion["Chapter completion<br/>integration script"]
  node_quality["Content quality checks<br/>validation scripts<br/>[quality-check.sh]"]
  node_sync["Progress synchronization<br/>state sync script"]
  node_recovery["Backup &amp; recovery<br/>durability scripts<br/>[auto-backup.sh]"]
  node_dashboard["Operations dashboard<br/>Python observer<br/>[dashboard.py]"]
end

node_operator(("Human operator<br/>actor"))
node_chapter_template["Chapter template<br/>writing template"]
node_output_style["Novel output style<br/>prose specification"]

node_operator -->|"starts"| node_bootstrap
node_bootstrap -->|"initializes"| node_claude
node_claude -->|"delegates planning"| node_planner
node_claude -->|"delegates pacing"| node_adaptive_planner
node_claude -->|"delegates generation"| node_writer
node_claude -->|"delegates review"| node_editor
node_claude -->|"delegates enrichment"| node_knowledge_agents
node_planner -->|"reads and updates"| node_outline
node_adaptive_planner -->|"assesses status"| node_progress
node_writer -->|"follows"| node_outline
node_writer -->|"reads"| node_progress
node_writer -->|"uses"| node_character_knowledge
node_writer -->|"uses"| node_world_state
node_chapter_template -->|"formats"| node_writer
node_output_style -->|"guides prose"| node_writer
node_writer -->|"generates chapters"| node_manuscript
node_editor -->|"reviews"| node_manuscript
node_editor -->|"checks continuity"| node_character_knowledge
node_editor -->|"checks continuity"| node_world_state
node_manuscript -->|"validates"| node_quality
node_quality -->|"passes to"| node_completion
node_completion -->|"triggers"| node_sync
node_sync -->|"persists"| node_progress
node_recovery -.->|"backs up"| node_manuscript
node_dashboard -.->|"observes"| node_progress
node_dashboard -.->|"reports on"| node_manuscript

click node_bootstrap "https://github.com/forsonny/claude-code-novel-writer/blob/main/launch-novel.sh"
click node_claude "https://github.com/forsonny/claude-code-novel-writer/blob/main/CLAUDE.md"
click node_planner "https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/plot-architect.md"
click node_adaptive_planner "https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/smart-planner.md"
click node_writer "https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/chapter-writer.md"
click node_editor "https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/continuity-editor.md"
click node_knowledge_agents "https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/worldbuilder.md"
click node_outline "https://github.com/forsonny/claude-code-novel-writer/blob/main/planning/novel-outline.json"
click node_progress "https://github.com/forsonny/claude-code-novel-writer/blob/main/planning/chapter-status.json"
click node_character_knowledge "https://github.com/forsonny/claude-code-novel-writer/blob/main/characters/character-knowledge.json"
click node_world_state "https://github.com/forsonny/claude-code-novel-writer/blob/main/worldbuilding/world-state.json"
click node_chapter_template "https://github.com/forsonny/claude-code-novel-writer/blob/main/templates/chapter-template.md"
click node_output_style "https://github.com/forsonny/claude-code-novel-writer/blob/main/output-styles/autonomous-novelist.md"
click node_completion "https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/chapter-completed.sh"
click node_quality "https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/quality-check.sh"
click node_sync "https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/auto-sync-progress.sh"
click node_recovery "https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/auto-backup.sh"
click node_dashboard "https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/dashboard.py"

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_claude,node_planner,node_adaptive_planner,node_writer,node_editor,node_knowledge_agents toneBlue
class node_outline,node_progress,node_character_knowledge,node_world_state,node_manuscript toneAmber
class node_bootstrap,node_completion,node_quality,node_sync,node_recovery,node_dashboard toneMint
class node_operator,node_chapter_template,node_output_style toneNeutral
```

## Components

### Claude Runtime

Claude Code follows repository instructions and agent roles.

- [Master orchestrator](https://github.com/forsonny/claude-code-novel-writer/blob/main/CLAUDE.md): Claude instructions · Directs the autonomous novel-writing workflow. · `CLAUDE.md`
- [Plot architect](https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/plot-architect.md): planning agent · `.claude/agents/plot-architect.md`
- [Adaptive planner](https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/smart-planner.md): planning agent · `.claude/agents/smart-planner.md`
- [Chapter writer](https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/chapter-writer.md): generation agent · `.claude/agents/chapter-writer.md`
- [Continuity editor](https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/continuity-editor.md): review agent · `.claude/agents/continuity-editor.md`
- [World, character & recovery agents](https://github.com/forsonny/claude-code-novel-writer/blob/main/.claude/agents/worldbuilder.md): specialist agents · Enrich narrative domains and remediate failures. · `.claude/agents/worldbuilder.md`

### Local Story State

JSON files synchronize narrative work across sessions.

- [Novel outline](https://github.com/forsonny/claude-code-novel-writer/blob/main/planning/novel-outline.json): plan JSON · Canonical intended story structure. · `planning/novel-outline.json`
- [Progress trackers](https://github.com/forsonny/claude-code-novel-writer/blob/main/planning/chapter-status.json): state JSON · Chapter, plot, and scene execution status. · `planning/chapter-status.json`
- [Character knowledge](https://github.com/forsonny/claude-code-novel-writer/blob/main/characters/character-knowledge.json): reference JSON · `characters/character-knowledge.json`
- [World state](https://github.com/forsonny/claude-code-novel-writer/blob/main/worldbuilding/world-state.json): reference JSON · `worldbuilding/world-state.json`
- **Manuscript**: generated chapters · Generated chapter content and manuscript metadata.

### Automation & Quality

Local shell and Python tools maintain and observe the workspace.

- [Bootstrap & validation](https://github.com/forsonny/claude-code-novel-writer/blob/main/launch-novel.sh): shell entry points · `launch-novel.sh`
- [Chapter completion](https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/chapter-completed.sh): integration script · `automation/chapter-completed.sh`
- [Content quality checks](https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/quality-check.sh): validation scripts · Checks prose quality and duplicate content. · `automation/quality-check.sh`
- [Progress synchronization](https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/auto-sync-progress.sh): state sync script · `automation/auto-sync-progress.sh`
- [Backup & recovery](https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/auto-backup.sh): durability scripts · Creates local backups before recovery-sensitive operations. · `automation/auto-backup.sh`
- [Operations dashboard](https://github.com/forsonny/claude-code-novel-writer/blob/main/automation/dashboard.py): Python observer · Reports local artifact, monitor, and sync state. · `automation/dashboard.py`

### Other components

- **Human operator**: actor
- [Chapter template](https://github.com/forsonny/claude-code-novel-writer/blob/main/templates/chapter-template.md): writing template · `templates/chapter-template.md`
- [Novel output style](https://github.com/forsonny/claude-code-novel-writer/blob/main/output-styles/autonomous-novelist.md): prose specification · `output-styles/autonomous-novelist.md`

## Connections

- Human operator → Bootstrap & validation: starts
- Bootstrap & validation → Master orchestrator: initializes
- Master orchestrator → Plot architect: delegates planning
- Master orchestrator → Adaptive planner: delegates pacing
- Master orchestrator → Chapter writer: delegates generation
- Master orchestrator → Continuity editor: delegates review
- Master orchestrator → World, character & recovery agents: delegates enrichment
- Plot architect → Novel outline: reads and updates
- Adaptive planner → Progress trackers: assesses status
- Chapter writer → Novel outline: follows
- Chapter writer → Progress trackers: reads
- Chapter writer → Character knowledge: uses
- Chapter writer → World state: uses
- Chapter template → Chapter writer: formats
- Novel output style → Chapter writer: guides prose
- Chapter writer → Manuscript: generates chapters
- Continuity editor → Manuscript: reviews
- Continuity editor → Character knowledge: checks continuity
- Continuity editor → World state: checks continuity
- Manuscript → Content quality checks: validates
- Content quality checks → Chapter completion: passes to
- Chapter completion → Progress synchronization: triggers
- Progress synchronization → Progress trackers: persists
- Backup & recovery → Manuscript: backs up
- Operations dashboard → Progress trackers: observes
- Operations dashboard → Manuscript: reports on