# ai-team-team/ai-novel architecture

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

- Interactive diagram: https://gitdiagram.com/ai-team-team/ai-novel
- Repository: https://github.com/ai-team-team/ai-novel

## Overview

AI Novel Writer turns a user’s novel blueprint into chapter prose while maintaining a continuity model: initialize the story world, plan and write chapters, review and scan the results, resolve fact conflicts, then commit approved state for later retrieval. The README also documents ATT agent committees, interruption recovery, and a live dashboard. The graph reflects those documented capabilities; unsampled implementation details are represented at their documented subsystem paths, and uncertain internal wiring is omitted.

Main entry points: [`src/workflow.py`](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow.py) (Workflow manager), [`src/memory.py`](https://github.com/ai-team-team/ai-novel/blob/main/src/memory.py) (Memory manager), [`src/state_manager.py`](https://github.com/ai-team-team/ai-novel/blob/main/src/state_manager.py) (Context retrieval), [`src/llm_client.py`](https://github.com/ai-team-team/ai-novel/blob/main/src/llm_client.py) (LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Novel Workflow"]
  node_cli["CLI<br/>[main.py]"]
  node_workflow["Workflow manager<br/>[workflow.py]"]
  node_project["Project bootstrap<br/>[project_mixin.py]"]
  node_planning["Chapter planning<br/>[planning_mixin.py]"]
  node_writing["Chapter writing<br/>[writing_mixin.py]"]
  node_review["Review and revision<br/>[discussion.py]"]
  node_scanning["Fact scanning<br/>[scanning_mixin.py]"]
end

subgraph group_agents["Agent Orchestration"]
  node_att["ATT committees<br/>[autonomy_mixin.py]"]
  node_db_committee["Database governance<br/>[db_committee.py]"]
  node_conflict["Conflict resolution"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

subgraph group_memory["Continuity Memory"]
  node_state["Context retrieval<br/>[state_manager.py]"]
  node_memory_manager["Memory manager<br/>[memory.py]"]
  node_sqlite[("Story database<br/>[schema_mixin.py]")]
  node_vectors[("Vector index<br/>[memory.py]")]
  node_conflict_commit["Conflict and commits"]
end

subgraph group_operations["Runtime Operations"]
  node_resume["Recovery checks<br/>[resume_mixin.py]"]
  node_dashboard["Live dashboard<br/>[dashboard.py]"]
end

node_writer(("Novel writer"))
node_model_api{{"Model providers"}}
node_embedding_api{{"Embedding service"}}

node_writer -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_workflow
node_workflow -->|"initializes"| node_project
node_workflow -->|"plans chapters"| node_planning
node_workflow -->|"generates prose"| node_writing
node_workflow -->|"reviews prose"| node_review
node_workflow -->|"scans facts"| node_scanning
node_workflow -->|"resolves conflicts"| node_conflict
node_workflow -->|"retrieves context"| node_state
node_workflow -->|"commits facts"| node_memory_manager
node_planning -->|"requests context"| node_state
node_writing -->|"requests context"| node_state
node_scanning -->|"extracts facts"| node_llm
node_planning -->|"generates guide"| node_llm
node_writing -->|"generates prose"| node_llm
node_review -->|"reviews and revises"| node_llm
node_conflict -->|"convenes debate"| node_att
node_db_committee -->|"uses ATT manager"| node_att
node_memory_manager -.->|"audits writes"| node_db_committee
node_memory_manager -->|"reads and writes"| node_sqlite
node_memory_manager -->|"indexes facts"| node_vectors
node_state -->|"queries memory"| node_memory_manager
node_state -->|"reads structured facts"| node_sqlite
node_state -->|"searches details"| node_vectors
node_memory_manager -->|"records commits"| node_conflict_commit
node_conflict_commit -->|"updates commit state"| node_sqlite
node_llm -->|"sends prompts"| node_model_api
node_llm -.->|"requests embeddings"| node_embedding_api
node_workflow -->|"validates on recovery"| node_resume
node_resume -->|"checks memory state"| node_memory_manager
node_workflow -->|"updates status"| node_dashboard
node_att -.->|"reports activity"| node_dashboard

click node_cli "https://github.com/ai-team-team/ai-novel/blob/main/src/main.py"
click node_workflow "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow.py"
click node_project "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/project_mixin.py"
click node_planning "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/planning_mixin.py"
click node_writing "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/writing_mixin.py"
click node_review "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/discussion.py"
click node_scanning "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/scanning_mixin.py"
click node_att "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/autonomy_mixin.py"
click node_db_committee "https://github.com/ai-team-team/ai-novel/blob/main/src/att/db_committee.py"
click node_conflict "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/conflict_resolver.py"
click node_state "https://github.com/ai-team-team/ai-novel/blob/main/src/state_manager.py"
click node_memory_manager "https://github.com/ai-team-team/ai-novel/blob/main/src/memory.py"
click node_sqlite "https://github.com/ai-team-team/ai-novel/blob/main/src/memory_components/schema_mixin.py"
click node_vectors "https://github.com/ai-team-team/ai-novel/blob/main/src/memory.py"
click node_conflict_commit "https://github.com/ai-team-team/ai-novel/blob/main/src/memory_components/conflict_commit_mixin.py"
click node_llm "https://github.com/ai-team-team/ai-novel/blob/main/src/llm_client.py"
click node_resume "https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/resume_mixin.py"
click node_dashboard "https://github.com/ai-team-team/ai-novel/blob/main/src/utils/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_cli,node_workflow,node_project,node_planning,node_writing,node_review,node_scanning toneBlue
class node_att,node_db_committee,node_conflict,node_llm toneAmber
class node_state,node_memory_manager,node_sqlite,node_vectors,node_conflict_commit toneMint
class node_resume,node_dashboard toneRose
class node_writer,node_model_api,node_embedding_api toneIndigo
```

## Components

### Novel Workflow

- [CLI](https://github.com/ai-team-team/ai-novel/blob/main/src/main.py): `src/main.py`
- [Workflow manager](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow.py): `src/workflow.py`
- [Project bootstrap](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/project_mixin.py): `src/workflow_components/project_mixin.py`
- [Chapter planning](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/planning_mixin.py): `src/workflow_components/planning_mixin.py`
- [Chapter writing](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/writing_mixin.py): `src/workflow_components/writing_mixin.py`
- [Review and revision](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/discussion.py): `src/workflow_components/discussion.py`
- [Fact scanning](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/scanning_mixin.py): `src/workflow_components/scanning_mixin.py`

### Agent Orchestration

- [ATT committees](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/autonomy_mixin.py): `src/workflow_components/autonomy_mixin.py`
- [Database governance](https://github.com/ai-team-team/ai-novel/blob/main/src/att/db_committee.py): `src/att/db_committee.py`
- [Conflict resolution](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/conflict_resolver.py): `src/workflow_components/conflict_resolver.py`
- [LLM client](https://github.com/ai-team-team/ai-novel/blob/main/src/llm_client.py): `src/llm_client.py`

### Continuity Memory

- [Context retrieval](https://github.com/ai-team-team/ai-novel/blob/main/src/state_manager.py): `src/state_manager.py`
- [Memory manager](https://github.com/ai-team-team/ai-novel/blob/main/src/memory.py): `src/memory.py`
- [Story database](https://github.com/ai-team-team/ai-novel/blob/main/src/memory_components/schema_mixin.py): `src/memory_components/schema_mixin.py`
- [Vector index](https://github.com/ai-team-team/ai-novel/blob/main/src/memory.py): `src/memory.py`
- [Conflict and commits](https://github.com/ai-team-team/ai-novel/blob/main/src/memory_components/conflict_commit_mixin.py): `src/memory_components/conflict_commit_mixin.py`

### Runtime Operations

- [Recovery checks](https://github.com/ai-team-team/ai-novel/blob/main/src/workflow_components/resume_mixin.py): `src/workflow_components/resume_mixin.py`
- [Live dashboard](https://github.com/ai-team-team/ai-novel/blob/main/src/utils/dashboard.py): `src/utils/dashboard.py`

### Other components

- **Novel writer**
- **Model providers**
- **Embedding service**

## Connections

- Novel writer → CLI: invokes
- CLI → Workflow manager: dispatches
- Workflow manager → Project bootstrap: initializes
- Workflow manager → Chapter planning: plans chapters
- Workflow manager → Chapter writing: generates prose
- Workflow manager → Review and revision: reviews prose
- Workflow manager → Fact scanning: scans facts
- Workflow manager → Conflict resolution: resolves conflicts
- Workflow manager → Context retrieval: retrieves context
- Workflow manager → Memory manager: commits facts
- Chapter planning → Context retrieval: requests context
- Chapter writing → Context retrieval: requests context
- Fact scanning → LLM client: extracts facts
- Chapter planning → LLM client: generates guide
- Chapter writing → LLM client: generates prose
- Review and revision → LLM client: reviews and revises
- Conflict resolution → ATT committees: convenes debate
- Database governance → ATT committees: uses ATT manager
- Memory manager → Database governance: audits writes
- Memory manager → Story database: reads and writes
- Memory manager → Vector index: indexes facts
- Context retrieval → Memory manager: queries memory
- Context retrieval → Story database: reads structured facts
- Context retrieval → Vector index: searches details
- Memory manager → Conflict and commits: records commits
- Conflict and commits → Story database: updates commit state
- LLM client → Model providers: sends prompts
- LLM client → Embedding service: requests embeddings
- Workflow manager → Recovery checks: validates on recovery
- Recovery checks → Memory manager: checks memory state
- Workflow manager → Live dashboard: updates status
- ATT committees → Live dashboard: reports activity