# encyc/novel-vibe architecture

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

- Interactive diagram: https://gitdiagram.com/encyc/novel-vibe
- Repository: https://github.com/encyc/novel-vibe

## Overview

Novel Vibe is a local-first, cloud-optional, multi-agent novel-writing system: the writer works in a project workspace, asks the Chief Editor for help, and reviews AI-proposed Markdown changes. The Agent Server coordinates specialist agents and session context; documents move through human-controlled confirmation states, with a database serving as a rebuildable index. The graph also preserves the documented community, skills, billing, and MCP capabilities. Some subsystem internals were not sampled, so their paths use the exact enclosing directories and their links are limited to documented relationships.

Main entry points: [`packages/novel-agents/server.ts`](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/server.ts) (Agent Server), [`packages/novel-agents/lib/storage.ts`](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/lib/storage.ts) (Markdown Documents), [`packages/novel-webui/src/App.tsx`](https://github.com/encyc/novel-vibe/blob/main/packages/novel-webui/src/App.tsx) (Web UI), [`packages/novel-agents/agents.ts`](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/agents.ts) (Agent Orchestrator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Writing Workspace"]
  node_webui["Web UI<br/>[App.tsx]"]
  node_api_client["API Client<br/>[client.ts]"]
  node_workspace_routes["Workspace Router"]
end

subgraph group_agent["Agent Runtime"]
  node_orchestrator["Agent Orchestrator<br/>[agents.ts]"]
  node_session_service["Session Service<br/>[service.ts]"]
  node_context_manager["Context Manager<br/>[manager.ts]"]
  node_specialists["Specialist Agents<br/>[agents.ts]"]
end

subgraph group_content["Creative Content"]
  node_documents["Markdown Documents<br/>[storage.ts]"]
  node_frontmatter["Document Metadata<br/>[frontmatter.ts]"]
  node_versioning["Document Versioning<br/>[service.ts]"]
  node_index_store[("Database Index<br/>[db.ts]")]
end

subgraph group_platform["Platform Services"]
  node_community["Community<br/>[service.ts]"]
  node_skills["Skills System<br/>[service.ts]"]
  node_billing["Credits and Billing"]
end

subgraph group_access["Access Channels"]
  node_bff["Web BFF<br/>[routes.ts]"]
  node_agent_server["Agent Server<br/>[server.ts]"]
  node_mcp["MCP Server<br/>[server.ts]"]
  node_mcp_client["MCP Agent Client<br/>[agent-client.ts]"]
end

node_writer(("Writer"))

node_writer -->|"uses"| node_webui
node_webui -->|"routes to"| node_workspace_routes
node_webui -->|"requests through"| node_api_client
node_api_client -.->|"calls API"| node_bff
node_bff -.->|"proxies requests"| node_agent_server
node_agent_server -->|"coordinates"| node_orchestrator
node_orchestrator -->|"delegates to"| node_specialists
node_orchestrator -.->|"uses sessions"| node_session_service
node_session_service -->|"builds context"| node_context_manager
node_context_manager -.->|"restores context"| node_documents
node_agent_server -->|"reads and writes"| node_documents
node_agent_server -->|"records versions"| node_versioning
node_documents -->|"stores metadata"| node_frontmatter
node_documents -->|"rebuilds index"| node_index_store
node_agent_server -->|"serves community"| node_community
node_agent_server -.->|"serves skills"| node_skills
node_agent_server -.->|"uses billing"| node_billing
node_writer -.->|"uses tools"| node_mcp
node_mcp -->|"registers tools"| node_mcp_client
node_mcp_client -.->|"calls Agent API"| node_agent_server

click node_webui "https://github.com/encyc/novel-vibe/blob/main/packages/novel-webui/src/App.tsx"
click node_api_client "https://github.com/encyc/novel-vibe/blob/main/packages/novel-webui/src/api/client.ts"
click node_workspace_routes "https://github.com/encyc/novel-vibe/blob/main/packages/novel-webui/src/workbench/WorkspaceRouter.tsx"
click node_bff "https://github.com/encyc/novel-vibe/blob/main/packages/novel-web/src/routes.ts"
click node_agent_server "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/server.ts"
click node_orchestrator "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/agents.ts"
click node_session_service "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/session/service.ts"
click node_context_manager "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/context/manager.ts"
click node_specialists "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/agents.ts"
click node_documents "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/lib/storage.ts"
click node_frontmatter "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/lib/frontmatter.ts"
click node_versioning "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/document-version/service.ts"
click node_index_store "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/lib/db.ts"
click node_community "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/community/service.ts"
click node_skills "https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/skills/service.ts"
click node_billing "https://github.com/encyc/novel-vibe/tree/main/packages/novel-agents/billing"
click node_mcp "https://github.com/encyc/novel-vibe/blob/main/packages/novel-mcp/src/server.ts"
click node_mcp_client "https://github.com/encyc/novel-vibe/blob/main/packages/novel-mcp/src/agent-client.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_webui,node_api_client,node_workspace_routes toneBlue
class node_orchestrator,node_session_service,node_context_manager,node_specialists toneAmber
class node_documents,node_frontmatter,node_versioning,node_index_store toneMint
class node_community,node_skills,node_billing toneRose
class node_bff,node_agent_server,node_mcp,node_mcp_client,node_writer toneIndigo
```

## Components

### Writing Workspace

- [Web UI](https://github.com/encyc/novel-vibe/blob/main/packages/novel-webui/src/App.tsx): `packages/novel-webui/src/App.tsx`
- [API Client](https://github.com/encyc/novel-vibe/blob/main/packages/novel-webui/src/api/client.ts): `packages/novel-webui/src/api/client.ts`
- [Workspace Router](https://github.com/encyc/novel-vibe/blob/main/packages/novel-webui/src/workbench/WorkspaceRouter.tsx): `packages/novel-webui/src/workbench/WorkspaceRouter.tsx`

### Agent Runtime

- [Agent Orchestrator](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/agents.ts): `packages/novel-agents/agents.ts`
- [Session Service](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/session/service.ts): `packages/novel-agents/session/service.ts`
- [Context Manager](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/context/manager.ts): `packages/novel-agents/context/manager.ts`
- [Specialist Agents](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/agents.ts): `packages/novel-agents/agents.ts`

### Creative Content

- [Markdown Documents](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/lib/storage.ts): `packages/novel-agents/lib/storage.ts`
- [Document Metadata](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/lib/frontmatter.ts): `packages/novel-agents/lib/frontmatter.ts`
- [Document Versioning](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/document-version/service.ts): `packages/novel-agents/document-version/service.ts`
- [Database Index](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/lib/db.ts): `packages/novel-agents/lib/db.ts`

### Platform Services

- [Community](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/community/service.ts): `packages/novel-agents/community/service.ts`
- [Skills System](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/skills/service.ts): `packages/novel-agents/skills/service.ts`
- [Credits and Billing](https://github.com/encyc/novel-vibe/tree/main/packages/novel-agents/billing): `packages/novel-agents/billing`

### Access Channels

- [Web BFF](https://github.com/encyc/novel-vibe/blob/main/packages/novel-web/src/routes.ts): `packages/novel-web/src/routes.ts`
- [Agent Server](https://github.com/encyc/novel-vibe/blob/main/packages/novel-agents/server.ts): `packages/novel-agents/server.ts`
- [MCP Server](https://github.com/encyc/novel-vibe/blob/main/packages/novel-mcp/src/server.ts): `packages/novel-mcp/src/server.ts`
- [MCP Agent Client](https://github.com/encyc/novel-vibe/blob/main/packages/novel-mcp/src/agent-client.ts): `packages/novel-mcp/src/agent-client.ts`

### Other components

- **Writer**

## Connections

- Writer → Web UI: uses (evidence: `README.md`)
- Web UI → Workspace Router: routes to (evidence: `packages/novel-webui/src/workbench/WorkspaceRouter.tsx`)
- Web UI → API Client: requests through (evidence: `packages/novel-webui/src/App.tsx`)
- API Client → Web BFF: calls API (evidence: `README.md`)
- Web BFF → Agent Server: proxies requests (evidence: `README.md`)
- Agent Server → Agent Orchestrator: coordinates (evidence: `packages/novel-agents/server.ts`)
- Agent Orchestrator → Specialist Agents: delegates to (evidence: `README.md`)
- Agent Orchestrator → Session Service: uses sessions
- Session Service → Context Manager: builds context (evidence: `packages/novel-agents/session/service.ts`)
- Context Manager → Markdown Documents: restores context
- Agent Server → Markdown Documents: reads and writes (evidence: `packages/novel-agents/server.ts`)
- Agent Server → Document Versioning: records versions (evidence: `packages/novel-agents/server.ts`)
- Markdown Documents → Document Metadata: stores metadata (evidence: `README.md`)
- Markdown Documents → Database Index: rebuilds index (evidence: `README.md`)
- Agent Server → Community: serves community (evidence: `packages/novel-agents/server.ts`)
- Agent Server → Skills System: serves skills (evidence: `packages/novel-agents/server.ts`)
- Agent Server → Credits and Billing: uses billing
- Writer → MCP Server: uses tools (evidence: `README.md`)
- MCP Server → MCP Agent Client: registers tools (evidence: `packages/novel-mcp/src/server.ts`)
- MCP Agent Client → Agent Server: calls Agent API