# voocel/ainovel-cli architecture

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

- Interactive diagram: https://gitdiagram.com/voocel/ainovel-cli
- Repository: https://github.com/voocel/ainovel-cli

## Overview

1. **What this repository is**
   - `ainovel-cli` is a Go-based command-line/TUI engine for long-form novel generation.
   - The architecture is intentionally split between a thin host and an LLM-driven coordinator: the host starts runs, restores state, and observes events; the coordinator decides the creative workflow.

2. **Process entry points**
   - `cmd/ainovel-cli/main.go` is the executable entry.
   - Runtime can start through the TUI (`internal/entry/tui`), a headless mode (`internal/entry/headless`), or startup flows that gather the initial writing brief (`internal/entry/startup`).
   - This makes the repo both interactive and automation-friendly, but all modes converge into the same host/coordinator pipeline.

3. **Core orchestration boundary: Host vs. LLM**
   - `internal/host` contains the orchestration layer that does not decide story logic.
   - It manages run lifecycle, checkpoint recovery, event dispatch, usage tracking, and reminder injection.
   - The coordinator and subagents are responsible for decisions; the host only enforces boundaries such as stop conditions and state transitions.

4. **Agent model**
   - `internal/agents` defines the higher-level agent runtime and context management.
   - The documented roles are Coordinator, Architect, Writer, and Editor.
   - The important architectural idea is that each role has its own context and tool access, but they collaborate through persisted artifacts in the store rather than direct shared memory.

5. **Tool-driven workflow**
   - `internal/tools` is the main action surface for the agents.
   - Tools cover planning, drafting, consistency checking, committing chapters, saving foundations/reviews/arc summaries, and reading chapter context.
   - The tools are designed to return facts and write checkpoints, not to embed policy decisions, which keeps control flow in the agent layer.

6. **Persistence and state model**
   - `internal/store` is the durable system-of-record for the novel.
   - It stores the evolving manuscript and metadata: chapters, drafts, summaries, reviews, outline, characters, world rules, progress, timeline, foreshadowing, state changes, checkpoints, and runtime/session data.
   - The output directory described in the README is the primary persistence boundary: the system can crash and resume from these files.

7. **Workflow and recovery mechanics**
   - `internal/host/flow` and `internal/domain` model the run state, phase/flow transitions, simulation state, commits, checkpoints, and usage.
   - `internal/host/reminder` generates per-turn system reminders from current persisted facts, rather than relying on long-lived prompt state.
   - Recovery is step-granular: the host reads progress plus checkpoints and reconstructs the next required action.

8. **Long-context management**
   - `internal/agents/ctxpack` and `internal/tools/novel_context*` implement context packing for long novels.
   - The system uses layered summaries, sliding windows, and compacted store-derived context to keep LLM prompts within window limits.
   - This is a core architectural boundary: narrative memory is externalized into the store and selectively rehydrated into prompts.

9. **Content generation pipeline**
   - The canonical writing loop is: load novel context → read relevant chapter history → plan chapter → draft → consistency check → commit.
   - Architect-generated assets such as premise, outline, characters, world rules, compass, and layered outline are stored under `output/<novel>/meta`.
   - Editor outputs reviews and summaries that feed back into the next writing cycle, while `internal/host/budget`, `usage`, and reminder logic keep the loop constrained.

10. **Import, simulation, export, and diagnostics**
   - `internal/host/imp` handles imported source novels: it splits source text, analyzes foundations, and reconstructs story structure.
   - `internal/host/sim` and `internal/stylestat` support style imitation by building a simulation profile from sample texts.
   - `internal/host/exp` exports finished content to TXT or EPUB.
   - `internal/diag` analyzes output artifacts and emits exportable diagnostic reports, which is a separate observability/quality subsystem rather than part of the writing loop.

11. **Configuration and model/provider abstraction**
   - `internal/bootstrap` loads and merges configuration from global, project, and CLI sources.
   - `internal/models` abstracts provider/model registry and pricing/lookup, which is how the repo supports OpenRouter, Anthropic, Gemini, OpenAI, Ollama, and others.
   - This provider abstraction is a key integration boundary: the novel engine is model-agnostic.

12. **Prompt, rule, and style assets**
   - `assets/` holds embedded prompts, reference docs, style presets, and rule baselines.
   - `internal/rules` loads and merges rule files, while the README describes a layered rule system: built-in defaults plus user/project overrides.
   - These assets are not just static text; they are part of the architecture because they directly shape agent behavior and quality checks.

13. **User interaction surface**
   - `internal/entry/tui` is the primary human interface, with panels for progress, commands, import/export, simulation, and real-time steering.
   - `internal/notify` and `internal/logger` support feedback and logging around the run.
   - The TUI is an observer/control plane, not the creative engine itself.

14. **Operational and release tooling**
   - `.github/workflows/release.yml`, `.goreleaser.yml`, and `scripts/install.sh` indicate this is shipped as a cross-platform CLI binary.
   - Tests are extensive across host, store, rules, diagnostics, and simulation, which reinforces that the main risk is state-machine correctness and persistence integrity rather than HTTP/API wiring.

Main entry points: [`internal/host`](https://github.com/voocel/ainovel-cli/tree/main/internal/host) (Host), [`internal/entry/tui`](https://github.com/voocel/ainovel-cli/tree/main/internal/entry/tui) (TUI), [`internal/agents`](https://github.com/voocel/ainovel-cli/tree/main/internal/agents) (Agents runtime), [`internal/tools`](https://github.com/voocel/ainovel-cli/tree/main/internal/tools) (Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & UI"]
  node_cmd_main["CLI entry<br/>binary<br/>[main.go]"]
  node_tui["TUI<br/>interactive ui"]
  node_headless["Headless mode<br/>automation entry"]
  node_startup["Startup flow<br/>brief intake"]
end

subgraph group_core["Core Orchestration"]
  node_host["Host<br/>run orchestrator"]
  node_flow["Flow router<br/>state machine"]
  node_reminder["Reminders<br/>prompt guards"]
  node_budget["Budget<br/>usage limits<br/>[budget.go]"]
end

subgraph group_agents["Agents & Context"]
  node_agents_rt["Agents runtime<br/>role runtime"]
  node_ctxpack["Context packer<br/>context management"]
end

subgraph group_state["Domain & Store"]
  node_store[("Store<br/>durable state")]
  node_domain["Domain model<br/>run state model"]
end

subgraph group_pipeline["Writing Pipeline"]
  node_tools["Tools<br/>action surface"]
  node_novel_ctx["Novel context<br/>context builder<br/>[novel_context.go]"]
end

subgraph group_support["Support Systems"]
  node_bootstrap["Bootstrap<br/>config loader"]
  node_models["Model registry<br/>provider abstraction"]
  node_diag["Diagnostics<br/>quality reports"]
  node_importer["Import flow<br/>source ingest"]
  node_simulation["Simulation<br/>style profile"]
  node_exporter["Export flow<br/>content export"]
  node_rules["Rules engine<br/>rule loader"]
end

subgraph group_assets["Prompt Assets"]
  node_assets["Prompts & rules<br/>embedded assets"]
end

node_cmd_main -->|"loads config"| node_bootstrap
node_cmd_main -->|"launches UI"| node_tui
node_cmd_main -->|"launches headless"| node_headless
node_cmd_main -->|"gathers brief"| node_startup
node_tui -->|"controls run"| node_host
node_headless -->|"runs pipeline"| node_host
node_startup -->|"starts session"| node_host
node_host -->|"routes phases"| node_flow
node_host -->|"injects reminders"| node_reminder
node_host -->|"enforces limits"| node_budget
node_host -->|"delegates decisions"| node_agents_rt
node_agents_rt -->|"packs context"| node_ctxpack
node_ctxpack -->|"rehydrates facts"| node_store
node_agents_rt -->|"uses tools"| node_tools
node_tools -->|"builds context"| node_novel_ctx
node_tools -->|"writes checkpoints"| node_store
node_tools -->|"reads model"| node_domain
node_host -->|"tracks state"| node_domain
node_store -->|"persists state"| node_domain
node_bootstrap -->|"selects provider"| node_models
node_agents_rt -->|"calls LLMs"| node_models
node_host -->|"imports source"| node_importer
node_host -->|"simulates style"| node_simulation
node_host -->|"exports output"| node_exporter
node_diag -->|"analyzes artifacts"| node_store
node_rules -->|"loads baselines"| node_assets
node_tui -->|"shows reports"| node_diag
node_tui -->|"imports novels"| node_importer
node_tui -->|"exports novels"| node_exporter
node_tui -->|"runs simulation"| node_simulation
node_tools -->|"checks rules"| node_rules
node_agents_rt -->|"reads prompts"| node_assets

click node_cmd_main "https://github.com/voocel/ainovel-cli/blob/main/cmd/ainovel-cli/main.go"
click node_tui "https://github.com/voocel/ainovel-cli/tree/main/internal/entry/tui"
click node_headless "https://github.com/voocel/ainovel-cli/tree/main/internal/entry/headless"
click node_startup "https://github.com/voocel/ainovel-cli/tree/main/internal/entry/startup"
click node_host "https://github.com/voocel/ainovel-cli/tree/main/internal/host"
click node_flow "https://github.com/voocel/ainovel-cli/tree/main/internal/host/flow"
click node_reminder "https://github.com/voocel/ainovel-cli/tree/main/internal/host/reminder"
click node_budget "https://github.com/voocel/ainovel-cli/blob/main/internal/host/budget.go"
click node_agents_rt "https://github.com/voocel/ainovel-cli/tree/main/internal/agents"
click node_ctxpack "https://github.com/voocel/ainovel-cli/tree/main/internal/agents/ctxpack"
click node_tools "https://github.com/voocel/ainovel-cli/tree/main/internal/tools"
click node_novel_ctx "https://github.com/voocel/ainovel-cli/blob/main/internal/tools/novel_context.go"
click node_store "https://github.com/voocel/ainovel-cli/tree/main/internal/store"
click node_domain "https://github.com/voocel/ainovel-cli/tree/main/internal/domain"
click node_bootstrap "https://github.com/voocel/ainovel-cli/tree/main/internal/bootstrap"
click node_models "https://github.com/voocel/ainovel-cli/tree/main/internal/models"
click node_diag "https://github.com/voocel/ainovel-cli/tree/main/internal/diag"
click node_importer "https://github.com/voocel/ainovel-cli/tree/main/internal/host/imp"
click node_simulation "https://github.com/voocel/ainovel-cli/tree/main/internal/host/sim"
click node_exporter "https://github.com/voocel/ainovel-cli/tree/main/internal/host/exp"
click node_assets "https://github.com/voocel/ainovel-cli/tree/main/assets"
click node_rules "https://github.com/voocel/ainovel-cli/tree/main/internal/rules"

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_cmd_main,node_tui,node_headless,node_startup,node_assets toneBlue
class node_host,node_flow,node_reminder,node_budget toneAmber
class node_agents_rt,node_ctxpack toneMint
class node_store,node_domain toneRose
class node_tools,node_novel_ctx toneIndigo
class node_bootstrap,node_models,node_diag,node_importer,node_simulation,node_exporter,node_rules toneTeal
```

## Components

### Entry & UI

Executable entrypoints and user interaction surfaces.

- [CLI entry](https://github.com/voocel/ainovel-cli/blob/main/cmd/ainovel-cli/main.go): binary · Program entrypoint. · `cmd/ainovel-cli/main.go`
- [TUI](https://github.com/voocel/ainovel-cli/tree/main/internal/entry/tui): interactive ui · Primary human control and observation surface. · `internal/entry/tui`
- [Headless mode](https://github.com/voocel/ainovel-cli/tree/main/internal/entry/headless): automation entry · Non-interactive execution path. · `internal/entry/headless`
- [Startup flow](https://github.com/voocel/ainovel-cli/tree/main/internal/entry/startup): brief intake · Initial mode selection and writing-brief capture. · `internal/entry/startup`

### Core Orchestration

Host control loop, flow routing, reminders, and run lifecycle.

- [Host](https://github.com/voocel/ainovel-cli/tree/main/internal/host): run orchestrator · Lifecycle control, boundaries, and event dispatch. · `internal/host`
- [Flow router](https://github.com/voocel/ainovel-cli/tree/main/internal/host/flow): state machine · Routes run phases and transitions. · `internal/host/flow`
- [Reminders](https://github.com/voocel/ainovel-cli/tree/main/internal/host/reminder): prompt guards · Builds per-turn system reminders and stop guards. · `internal/host/reminder`
- [Budget](https://github.com/voocel/ainovel-cli/blob/main/internal/host/budget.go): usage limits · Tracks and constrains model usage. · `internal/host/budget.go`

### Agents & Context

LLM roles, context management, and prompt packing.

- [Agents runtime](https://github.com/voocel/ainovel-cli/tree/main/internal/agents): role runtime · Coordinator and subagent execution model. · `internal/agents`
- [Context packer](https://github.com/voocel/ainovel-cli/tree/main/internal/agents/ctxpack): context management · Builds compact long-context prompts from persisted facts. · `internal/agents/ctxpack`

### Domain & Store

Run state model and durable novel persistence.

- [Store](https://github.com/voocel/ainovel-cli/tree/main/internal/store): durable state · System of record for manuscript, metadata, checkpoints, and runtime state. · `internal/store`
- [Domain model](https://github.com/voocel/ainovel-cli/tree/main/internal/domain): run state model · Phases, chapters, commits, reviews, simulation, usage, and transitions. · `internal/domain`

### Writing Pipeline

Tooling that plans, drafts, checks, and commits chapters.

- [Tools](https://github.com/voocel/ainovel-cli/tree/main/internal/tools): action surface · Planning, drafting, checking, and persistence actions for agents. · `internal/tools`
- [Novel context](https://github.com/voocel/ainovel-cli/blob/main/internal/tools/novel_context.go): context builder · Selective rehydration of chapter and story context. · `internal/tools/novel_context.go`

### Support Systems

Configuration, model abstraction, diagnostics, and output/import utilities.

- [Bootstrap](https://github.com/voocel/ainovel-cli/tree/main/internal/bootstrap): config loader · Merges global, project, and CLI configuration. · `internal/bootstrap`
- [Model registry](https://github.com/voocel/ainovel-cli/tree/main/internal/models): provider abstraction · LLM provider lookup and pricing abstraction. · `internal/models`
- [Diagnostics](https://github.com/voocel/ainovel-cli/tree/main/internal/diag): quality reports · Analyzes output artifacts and emits diagnostic reports. · `internal/diag`
- [Import flow](https://github.com/voocel/ainovel-cli/tree/main/internal/host/imp): source ingest · Splits and reconstructs imported novels into structured foundations. · `internal/host/imp`
- [Simulation](https://github.com/voocel/ainovel-cli/tree/main/internal/host/sim): style profile · Builds style imitation profiles from sample texts. · `internal/host/sim`
- [Export flow](https://github.com/voocel/ainovel-cli/tree/main/internal/host/exp): content export · Exports finished content to TXT or EPUB. · `internal/host/exp`
- [Rules engine](https://github.com/voocel/ainovel-cli/tree/main/internal/rules): rule loader · Loads, merges, and checks rule files. · `internal/rules`

### Prompt Assets

Embedded prompts, rules, references, and style baselines.

- [Prompts & rules](https://github.com/voocel/ainovel-cli/tree/main/assets): embedded assets · Prompt templates, references, rules, and style presets. · `assets`

## Connections

- CLI entry → Bootstrap: loads config · Initializes runtime configuration before execution.
- CLI entry → TUI: launches UI · Starts the interactive control plane.
- CLI entry → Headless mode: launches headless · Starts non-interactive execution.
- CLI entry → Startup flow: gathers brief · Begins startup and mode selection flows.
- TUI → Host: controls run · Sends user actions into the orchestration layer.
- Headless mode → Host: runs pipeline · Delegates automated execution to the host.
- Startup flow → Host: starts session · Creates the initial run context for orchestration.
- Host → Flow router: routes phases · Advances state transitions and run stages.
- Host → Reminders: injects reminders · Builds turn-specific system guidance from persisted facts.
- Host → Budget: enforces limits · Tracks usage and stop conditions.
- Host → Agents runtime: delegates decisions · Hands creative decisions to agent roles.
- Agents runtime → Context packer: packs context · Prepares compact prompt state for each role.
- Context packer → Store: rehydrates facts · Pulls layered summaries and history from durable storage.
- Agents runtime → Tools: uses tools · Performs planning and writing actions through tools.
- Tools → Novel context: builds context · Constructs chapter-aware prompts for generation and review.
- Tools → Store: writes checkpoints · Persists drafts, summaries, reviews, and runtime artifacts.
- Tools → Domain model: reads model · Uses the run and story state model for decisions and payloads.
- Host → Domain model: tracks state · Reads and updates lifecycle, checkpoint, and usage state.
- Store → Domain model: persists state · Durable repository of novel, session, and progress data.
- Bootstrap → Model registry: selects provider · Configures model/provider registry and pricing lookup.
- Agents runtime → Model registry: calls LLMs · Uses provider-agnostic model resolution.
- Host → Import flow: imports source · Reconstructs imported novels and foundations.
- Host → Simulation: simulates style · Builds or runs style imitation support flows.
- Host → Export flow: exports output · Writes finished content to release formats.
- Diagnostics → Store: analyzes artifacts · Reads persisted outputs to produce diagnostics.
- Rules engine → Prompts & rules: loads baselines · Consumes embedded rule files and reference material.
- TUI → Diagnostics: shows reports · Surfaces diagnostics and progress to the user.
- TUI → Import flow: imports novels · Offers interactive import and recovery operations.
- TUI → Export flow: exports novels · Provides export actions from the UI.
- TUI → Simulation: runs simulation · Exposes simulation controls in the UI.
- Tools → Rules engine: checks rules · Validates writing against loaded rule sets.
- Agents runtime → Prompts & rules: reads prompts · Uses embedded prompts, references, and styles.