# malcolmkhong/novara architecture

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

- Interactive diagram: https://gitdiagram.com/malcolmkhong/novara
- Repository: https://github.com/malcolmkhong/novara

## Overview

Novara is an AI novel-writing studio: authors create and structure a novel, direct a role-based agent run, review gated chapter changes, and finalize work into canon and searchable memory before exporting. The workbench also supports direct drafting, document browsing, import/export, and usage visibility. The README documents the principal run lifecycle and finalization guarantees; several route and UI internals are represented at their exact tree paths because their source was not sampled.

Main entry points: [`src/lib/agent/runtime.ts`](https://github.com/malcolmkhong/novara/blob/main/src/lib/agent/runtime.ts) (Agent runtime), [`src/lib/db.ts`](https://github.com/malcolmkhong/novara/blob/main/src/lib/db.ts) (Novel database), [`src/components/novara/writer/workbench-shell.tsx`](https://github.com/malcolmkhong/novara/blob/main/src/components/novara/writer/workbench-shell.tsx) (Writer workbench), [`src/app/api/ai/draft/route.ts`](https://github.com/malcolmkhong/novara/blob/main/src/app/api/ai/draft/route.ts) (Direct drafting)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Writer workbench"]
  node_studio["Studio shell<br/>[novara-app.tsx]"]
  node_workbench_ui["Writer workbench"]
  node_conversation["Run conversation"]
  node_documents["Document tree<br/>[doc-tree.ts]"]
  node_chapter_editor["Chapter editor<br/>[chapter-editor.tsx]"]
end

subgraph group_agent["Agent and AI"]
  node_run_api["Run API<br/>[route.ts]"]
  node_agent_runtime["Agent runtime<br/>[runtime.ts]"]
  node_tool_protocol["Agent tools<br/>[tool-protocol.ts]"]
  node_ai_router["AI router<br/>[router.ts]"]
  node_providers["Provider adapters<br/>[registry.ts]"]
  node_draft_api["Direct drafting<br/>[route.ts]"]
end

subgraph group_canon["Novel canon"]
  node_novel_api["Novel API<br/>[route.ts]"]
  node_chapter_api["Chapter API<br/>[route.ts]"]
  node_lifecycle["Canon lifecycle<br/>[lifecycle.ts]"]
  node_memory["Memory projection<br/>[sediment.ts]"]
  node_review["Review and QC<br/>[review.ts]"]
  node_export_import["Import and export<br/>[route.ts]"]
end

subgraph group_platform["Identity and data"]
  node_database[("Novel database<br/>[db.ts]")]
  node_auth["Google sign-in<br/>[client.ts]"]
  node_middleware["Request identity<br/>[middleware.ts]"]
end

subgraph group_usage["Usage and billing"]
  node_credits["Credit charging<br/>[charge.ts]"]
  node_usage_store["Usage records<br/>[usage-store.ts]"]
end

node_author(("Author"))
node_external_ai{{"AI providers"}}
node_neon[("Neon Postgres")]

node_author -->|"opens"| node_studio
node_studio -->|"renders"| node_workbench_ui
node_workbench_ui -->|"presents"| node_conversation
node_workbench_ui -->|"browses"| node_documents
node_workbench_ui -->|"edits chapters"| node_chapter_editor
node_conversation -.->|"starts runs"| node_run_api
node_run_api -->|"dispatches"| node_agent_runtime
node_agent_runtime -->|"executes tools"| node_tool_protocol
node_agent_runtime -.->|"requests completions"| node_ai_router
node_ai_router -->|"resolves adapter"| node_providers
node_providers -.->|"calls"| node_external_ai
node_author -->|"requests draft"| node_draft_api
node_draft_api -->|"reads chapter"| node_database
node_draft_api -->|"retrieves memory"| node_memory
node_draft_api -.->|"requests completion"| node_ai_router
node_author -->|"manages novel"| node_novel_api
node_author -->|"updates chapter"| node_chapter_api
node_chapter_api -->|"moves canon state"| node_lifecycle
node_lifecycle -->|"writes projection"| node_memory
node_lifecycle -->|"commits transaction"| node_database
node_agent_runtime -->|"reviews chapters"| node_review
node_agent_runtime -->|"finalizes chapters"| node_lifecycle
node_export_import -->|"restores records"| node_database
node_middleware -->|"provides identity"| node_database
node_auth -.->|"authenticates"| node_author
node_agent_runtime -.->|"checks balance"| node_credits
node_credits -->|"records usage"| node_usage_store
node_usage_store -->|"persists usage"| node_database
node_database -->|"stores records"| node_neon

click node_studio "https://github.com/malcolmkhong/novara/blob/main/src/components/novara/novara-app.tsx"
click node_workbench_ui "https://github.com/malcolmkhong/novara/blob/main/src/components/novara/writer/workbench-shell.tsx"
click node_conversation "https://github.com/malcolmkhong/novara/blob/main/src/components/novara/writer/conversation-pane.tsx"
click node_documents "https://github.com/malcolmkhong/novara/blob/main/src/lib/novara/doc-tree.ts"
click node_chapter_editor "https://github.com/malcolmkhong/novara/blob/main/src/components/novara/writer/chapter-editor.tsx"
click node_run_api "https://github.com/malcolmkhong/novara/blob/main/src/app/api/agent/runs/route.ts"
click node_agent_runtime "https://github.com/malcolmkhong/novara/blob/main/src/lib/agent/runtime.ts"
click node_tool_protocol "https://github.com/malcolmkhong/novara/blob/main/src/lib/agent/tool-protocol.ts"
click node_ai_router "https://github.com/malcolmkhong/novara/blob/main/src/lib/ai/router.ts"
click node_providers "https://github.com/malcolmkhong/novara/blob/main/src/lib/ai/providers/registry.ts"
click node_draft_api "https://github.com/malcolmkhong/novara/blob/main/src/app/api/ai/draft/route.ts"
click node_novel_api "https://github.com/malcolmkhong/novara/blob/main/src/app/api/novels/%5Bid%5D/route.ts"
click node_chapter_api "https://github.com/malcolmkhong/novara/blob/main/src/app/api/chapters/%5Bid%5D/route.ts"
click node_lifecycle "https://github.com/malcolmkhong/novara/blob/main/src/lib/novara/lifecycle.ts"
click node_memory "https://github.com/malcolmkhong/novara/blob/main/src/lib/novara/sediment.ts"
click node_review "https://github.com/malcolmkhong/novara/blob/main/src/lib/novara/review.ts"
click node_export_import "https://github.com/malcolmkhong/novara/blob/main/src/app/api/import/route.ts"
click node_database "https://github.com/malcolmkhong/novara/blob/main/src/lib/db.ts"
click node_auth "https://github.com/malcolmkhong/novara/blob/main/src/lib/firebase/client.ts"
click node_middleware "https://github.com/malcolmkhong/novara/blob/main/src/middleware.ts"
click node_credits "https://github.com/malcolmkhong/novara/blob/main/src/lib/credits/charge.ts"
click node_usage_store "https://github.com/malcolmkhong/novara/blob/main/src/lib/usage/usage-store.ts"

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_studio,node_workbench_ui,node_conversation,node_documents,node_chapter_editor toneBlue
class node_run_api,node_agent_runtime,node_tool_protocol,node_ai_router,node_providers,node_draft_api,node_neon toneAmber
class node_novel_api,node_chapter_api,node_lifecycle,node_memory,node_review,node_export_import toneMint
class node_database,node_auth,node_middleware toneRose
class node_credits,node_usage_store,node_author,node_external_ai toneIndigo
```

## Components

### Writer workbench

- [Studio shell](https://github.com/malcolmkhong/novara/blob/main/src/components/novara/novara-app.tsx): `src/components/novara/novara-app.tsx`
- [Writer workbench](https://github.com/malcolmkhong/novara/blob/main/src/components/novara/writer/workbench-shell.tsx): `src/components/novara/writer/workbench-shell.tsx`
- [Run conversation](https://github.com/malcolmkhong/novara/blob/main/src/components/novara/writer/conversation-pane.tsx): `src/components/novara/writer/conversation-pane.tsx`
- [Document tree](https://github.com/malcolmkhong/novara/blob/main/src/lib/novara/doc-tree.ts): `src/lib/novara/doc-tree.ts`
- [Chapter editor](https://github.com/malcolmkhong/novara/blob/main/src/components/novara/writer/chapter-editor.tsx): `src/components/novara/writer/chapter-editor.tsx`

### Agent and AI

- [Run API](https://github.com/malcolmkhong/novara/blob/main/src/app/api/agent/runs/route.ts): `src/app/api/agent/runs/route.ts`
- [Agent runtime](https://github.com/malcolmkhong/novara/blob/main/src/lib/agent/runtime.ts): `src/lib/agent/runtime.ts`
- [Agent tools](https://github.com/malcolmkhong/novara/blob/main/src/lib/agent/tool-protocol.ts): `src/lib/agent/tool-protocol.ts`
- [AI router](https://github.com/malcolmkhong/novara/blob/main/src/lib/ai/router.ts): `src/lib/ai/router.ts`
- [Provider adapters](https://github.com/malcolmkhong/novara/blob/main/src/lib/ai/providers/registry.ts): `src/lib/ai/providers/registry.ts`
- [Direct drafting](https://github.com/malcolmkhong/novara/blob/main/src/app/api/ai/draft/route.ts): `src/app/api/ai/draft/route.ts`

### Novel canon

- [Novel API](https://github.com/malcolmkhong/novara/blob/main/src/app/api/novels/%5Bid%5D/route.ts): `src/app/api/novels/[id]/route.ts`
- [Chapter API](https://github.com/malcolmkhong/novara/blob/main/src/app/api/chapters/%5Bid%5D/route.ts): `src/app/api/chapters/[id]/route.ts`
- [Canon lifecycle](https://github.com/malcolmkhong/novara/blob/main/src/lib/novara/lifecycle.ts): `src/lib/novara/lifecycle.ts`
- [Memory projection](https://github.com/malcolmkhong/novara/blob/main/src/lib/novara/sediment.ts): `src/lib/novara/sediment.ts`
- [Review and QC](https://github.com/malcolmkhong/novara/blob/main/src/lib/novara/review.ts): `src/lib/novara/review.ts`
- [Import and export](https://github.com/malcolmkhong/novara/blob/main/src/app/api/import/route.ts): `src/app/api/import/route.ts`

### Identity and data

- [Novel database](https://github.com/malcolmkhong/novara/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [Google sign-in](https://github.com/malcolmkhong/novara/blob/main/src/lib/firebase/client.ts): `src/lib/firebase/client.ts`
- [Request identity](https://github.com/malcolmkhong/novara/blob/main/src/middleware.ts): `src/middleware.ts`

### Usage and billing

- [Credit charging](https://github.com/malcolmkhong/novara/blob/main/src/lib/credits/charge.ts): `src/lib/credits/charge.ts`
- [Usage records](https://github.com/malcolmkhong/novara/blob/main/src/lib/usage/usage-store.ts): `src/lib/usage/usage-store.ts`

### Other components

- **Author**
- **AI providers**
- **Neon Postgres**

## Connections

- Author → Studio shell: opens
- Studio shell → Writer workbench: renders
- Writer workbench → Run conversation: presents
- Writer workbench → Document tree: browses
- Writer workbench → Chapter editor: edits chapters
- Run conversation → Run API: starts runs
- Run API → Agent runtime: dispatches
- Agent runtime → Agent tools: executes tools
- Agent runtime → AI router: requests completions
- AI router → Provider adapters: resolves adapter (evidence: `src/lib/ai/router.ts`)
- Provider adapters → AI providers: calls
- Author → Direct drafting: requests draft (evidence: `src/app/api/ai/draft/route.ts`)
- Direct drafting → Novel database: reads chapter (evidence: `src/app/api/ai/draft/route.ts`)
- Direct drafting → Memory projection: retrieves memory (evidence: `src/app/api/ai/draft/route.ts`)
- Direct drafting → AI router: requests completion
- Author → Novel API: manages novel (evidence: `src/app/api/novels/[id]/route.ts`)
- Author → Chapter API: updates chapter (evidence: `src/app/api/chapters/[id]/route.ts`)
- Chapter API → Canon lifecycle: moves canon state (evidence: `src/app/api/chapters/[id]/route.ts`)
- Canon lifecycle → Memory projection: writes projection (evidence: `src/lib/novara/lifecycle.ts`)
- Canon lifecycle → Novel database: commits transaction (evidence: `src/lib/novara/lifecycle.ts`)
- Agent runtime → Review and QC: reviews chapters
- Agent runtime → Canon lifecycle: finalizes chapters
- Import and export → Novel database: restores records (evidence: `src/app/api/import/route.ts`)
- Request identity → Novel database: provides identity (evidence: `src/lib/db.ts`)
- Google sign-in → Author: authenticates
- Agent runtime → Credit charging: checks balance
- Credit charging → Usage records: records usage (evidence: `src/lib/credits/charge.ts`)
- Usage records → Novel database: persists usage (evidence: `src/lib/usage/usage-store.ts`)
- Novel database → Neon Postgres: stores records
