# huangleijiana/novel-agent architecture

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

- Interactive diagram: https://gitdiagram.com/huangleijiana/novel-agent
- Repository: https://github.com/huangleijiana/novel-agent

## Overview

Novel Agent is a web-controlled, multi-agent novel-writing system. A user submits a project through the frontend; the API runs a LangGraph workflow that pauses for human confirmation between major phases and resumes chapter work through review and revision. The workflow delegates creative and quality tasks to specialized agents, backed by configurable LLM providers, structured project state, and workspace persistence. The README documents the pipeline and capabilities; sampled source confirms the graph/phase-executor and persistence roles, but not every agent call or integration, so uncertain links are omitted.

Main entry points: [`src/agents/orchestrator.py`](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/orchestrator.py) (Agent Orchestrator), [`src/graph/workflow.py`](https://github.com/huangleijiana/novel-agent/blob/master/src/graph/workflow.py) (LangGraph Workflow), [`src/graph/nodes.py`](https://github.com/huangleijiana/novel-agent/blob/master/src/graph/nodes.py) (Phase Nodes), [`src/llm/scheduler.py`](https://github.com/huangleijiana/novel-agent/blob/master/src/llm/scheduler.py) (Model Scheduler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_frontend["Web Control Panel<br/>[app.js]"]
  node_api["FastAPI Routes<br/>[routes.py]"]
  node_ws["Progress WebSocket<br/>[websocket.py]"]
end

subgraph group_workflow["Workflow Control"]
  node_workflow_engine["LangGraph Workflow<br/>[workflow.py]"]
  node_graph_nodes["Phase Nodes<br/>[nodes.py]"]
  node_phase_exec["Phase Executors<br/>[phase_executor.py]"]
  node_state["Workflow State<br/>[state.py]"]
end

subgraph group_creative["Planning &amp; Writing"]
  node_orchestrator["Agent Orchestrator<br/>[orchestrator.py]"]
  node_topic["Topic Research<br/>[topic_scout.py]"]
  node_world["World Building<br/>[architect.py]"]
  node_characters["Character Planning"]
  node_plot["Plot Planning<br/>[plot_planner.py]"]
  node_writer["Chapter Writing<br/>[writer.py]"]
end

subgraph group_quality["Review &amp; Memory"]
  node_editor["Editorial Review<br/>[editor.py]"]
  node_continuity["Continuity Checks"]
  node_reader["Reader Simulation"]
  node_reviewer["Adversarial Review<br/>[reviewer.py]"]
  node_refiner["Chapter Refinement<br/>[refiner.py]"]
  node_memory["Story Memory<br/>[memory_manager.py]"]
end

subgraph group_platform["Runtime Services"]
  node_storage[("Workspace Files<br/>[file_manager.py]")]
  node_scheduler["Model Scheduler<br/>[scheduler.py]"]
  node_providers["LLM Providers<br/>[providers.py]"]
  node_config["App Settings<br/>[settings.py]"]
end

node_user(("Novel Author"))

node_user -->|"submits project"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"invokes workflow"| node_workflow_engine
node_workflow_engine -->|"routes phases"| node_graph_nodes
node_workflow_engine -->|"flows state"| node_state
node_graph_nodes -->|"executes phases"| node_phase_exec
node_graph_nodes -->|"broadcasts progress"| node_ws
node_phase_exec -->|"delegates phase work"| node_orchestrator
node_orchestrator -->|"runs research"| node_topic
node_orchestrator -->|"builds world"| node_world
node_orchestrator -->|"plans characters"| node_characters
node_orchestrator -->|"plans chapters"| node_plot
node_orchestrator -.->|"writes chapters"| node_writer
node_orchestrator -.->|"reviews drafts"| node_editor
node_orchestrator -.->|"checks continuity"| node_continuity
node_orchestrator -.->|"simulates readers"| node_reader
node_orchestrator -.->|"adversarial review"| node_reviewer
node_orchestrator -.->|"applies revisions"| node_refiner
node_orchestrator -.->|"updates memory"| node_memory
node_workflow_engine -.->|"resumes artifacts"| node_storage
node_graph_nodes -->|"persists artifacts"| node_storage
node_orchestrator -->|"uses models"| node_scheduler
node_scheduler -->|"loads assignments"| node_config
node_scheduler -->|"dispatches requests"| node_providers

click node_frontend "https://github.com/huangleijiana/novel-agent/blob/master/src/frontend/js/app.js"
click node_api "https://github.com/huangleijiana/novel-agent/blob/master/src/api/routes.py"
click node_ws "https://github.com/huangleijiana/novel-agent/blob/master/src/api/websocket.py"
click node_workflow_engine "https://github.com/huangleijiana/novel-agent/blob/master/src/graph/workflow.py"
click node_graph_nodes "https://github.com/huangleijiana/novel-agent/blob/master/src/graph/nodes.py"
click node_phase_exec "https://github.com/huangleijiana/novel-agent/blob/master/src/api/phase_executor.py"
click node_state "https://github.com/huangleijiana/novel-agent/blob/master/src/models/state.py"
click node_orchestrator "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/orchestrator.py"
click node_topic "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/topic_scout.py"
click node_world "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/architect.py"
click node_characters "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/character_manager.py"
click node_plot "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/plot_planner.py"
click node_writer "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/writer.py"
click node_editor "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/editor.py"
click node_continuity "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/continuity_checker.py"
click node_reader "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/reader_simulator.py"
click node_reviewer "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/reviewer.py"
click node_refiner "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/refiner.py"
click node_memory "https://github.com/huangleijiana/novel-agent/blob/master/src/agents/memory_manager.py"
click node_storage "https://github.com/huangleijiana/novel-agent/blob/master/src/storage/file_manager.py"
click node_scheduler "https://github.com/huangleijiana/novel-agent/blob/master/src/llm/scheduler.py"
click node_providers "https://github.com/huangleijiana/novel-agent/blob/master/src/llm/providers.py"
click node_config "https://github.com/huangleijiana/novel-agent/blob/master/src/config/settings.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_frontend,node_api,node_ws toneBlue
class node_workflow_engine,node_graph_nodes,node_phase_exec,node_state toneAmber
class node_orchestrator,node_topic,node_world,node_characters,node_plot,node_writer toneMint
class node_editor,node_continuity,node_reader,node_reviewer,node_refiner,node_memory toneRose
class node_storage,node_scheduler,node_providers,node_config,node_user toneIndigo
```

## Components

### User Interface

- [Web Control Panel](https://github.com/huangleijiana/novel-agent/blob/master/src/frontend/js/app.js): `src/frontend/js/app.js`
- [FastAPI Routes](https://github.com/huangleijiana/novel-agent/blob/master/src/api/routes.py): `src/api/routes.py`
- [Progress WebSocket](https://github.com/huangleijiana/novel-agent/blob/master/src/api/websocket.py): `src/api/websocket.py`

### Workflow Control

- [LangGraph Workflow](https://github.com/huangleijiana/novel-agent/blob/master/src/graph/workflow.py): `src/graph/workflow.py`
- [Phase Nodes](https://github.com/huangleijiana/novel-agent/blob/master/src/graph/nodes.py): `src/graph/nodes.py`
- [Phase Executors](https://github.com/huangleijiana/novel-agent/blob/master/src/api/phase_executor.py): `src/api/phase_executor.py`
- [Workflow State](https://github.com/huangleijiana/novel-agent/blob/master/src/models/state.py): `src/models/state.py`

### Planning & Writing

- [Agent Orchestrator](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/orchestrator.py): `src/agents/orchestrator.py`
- [Topic Research](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/topic_scout.py): `src/agents/topic_scout.py`
- [World Building](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/architect.py): `src/agents/architect.py`
- [Character Planning](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/character_manager.py): `src/agents/character_manager.py`
- [Plot Planning](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/plot_planner.py): `src/agents/plot_planner.py`
- [Chapter Writing](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/writer.py): `src/agents/writer.py`

### Review & Memory

- [Editorial Review](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/editor.py): `src/agents/editor.py`
- [Continuity Checks](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/continuity_checker.py): `src/agents/continuity_checker.py`
- [Reader Simulation](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/reader_simulator.py): `src/agents/reader_simulator.py`
- [Adversarial Review](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/reviewer.py): `src/agents/reviewer.py`
- [Chapter Refinement](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/refiner.py): `src/agents/refiner.py`
- [Story Memory](https://github.com/huangleijiana/novel-agent/blob/master/src/agents/memory_manager.py): `src/agents/memory_manager.py`

### Runtime Services

- [Workspace Files](https://github.com/huangleijiana/novel-agent/blob/master/src/storage/file_manager.py): `src/storage/file_manager.py`
- [Model Scheduler](https://github.com/huangleijiana/novel-agent/blob/master/src/llm/scheduler.py): `src/llm/scheduler.py`
- [LLM Providers](https://github.com/huangleijiana/novel-agent/blob/master/src/llm/providers.py): `src/llm/providers.py`
- [App Settings](https://github.com/huangleijiana/novel-agent/blob/master/src/config/settings.py): `src/config/settings.py`

### Other components

- **Novel Author**

## Connections

- Novel Author → Web Control Panel: submits project (evidence: `README.md`)
- Web Control Panel → FastAPI Routes: calls API (evidence: `README.md`)
- FastAPI Routes → LangGraph Workflow: invokes workflow (evidence: `README.md`)
- LangGraph Workflow → Phase Nodes: routes phases (evidence: `src/graph/workflow.py`)
- LangGraph Workflow → Workflow State: flows state (evidence: `src/graph/workflow.py`)
- Phase Nodes → Phase Executors: executes phases (evidence: `src/graph/nodes.py`)
- Phase Nodes → Progress WebSocket: broadcasts progress (evidence: `src/graph/nodes.py`)
- Phase Executors → Agent Orchestrator: delegates phase work (evidence: `src/api/phase_executor.py`)
- Agent Orchestrator → Topic Research: runs research (evidence: `src/agents/orchestrator.py`)
- Agent Orchestrator → World Building: builds world (evidence: `src/agents/orchestrator.py`)
- Agent Orchestrator → Character Planning: plans characters (evidence: `src/agents/orchestrator.py`)
- Agent Orchestrator → Plot Planning: plans chapters (evidence: `src/agents/orchestrator.py`)
- Agent Orchestrator → Chapter Writing: writes chapters (evidence: `README.md`)
- Agent Orchestrator → Editorial Review: reviews drafts (evidence: `README.md`)
- Agent Orchestrator → Continuity Checks: checks continuity (evidence: `README.md`)
- Agent Orchestrator → Reader Simulation: simulates readers (evidence: `README.md`)
- Agent Orchestrator → Adversarial Review: adversarial review (evidence: `README.md`)
- Agent Orchestrator → Chapter Refinement: applies revisions (evidence: `README.md`)
- Agent Orchestrator → Story Memory: updates memory (evidence: `README.md`)
- LangGraph Workflow → Workspace Files: resumes artifacts (evidence: `README.md`)
- Phase Nodes → Workspace Files: persists artifacts (evidence: `src/graph/nodes.py`)
- Agent Orchestrator → Model Scheduler: uses models (evidence: `src/agents/orchestrator.py`)
- Model Scheduler → App Settings: loads assignments (evidence: `src/llm/scheduler.py`)
- Model Scheduler → LLM Providers: dispatches requests (evidence: `src/llm/scheduler.py`)
