# yosrikhiari/versatile architecture

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

- Interactive diagram: https://gitdiagram.com/yosrikhiari/versatile
- Repository: https://github.com/yosrikhiari/versatile

## Overview

Versatile is an offline-first fiction-writing environment with local persistence and optional server sync. A writer edits and organizes a manuscript and story bible, queries story data, or starts an AI run that plans and drafts a novel. The documented pipeline proceeds from bible and network through structure, spine, prose, and consistency; generated scenes can be committed to the manuscript. The README documents additional writing, research, export, and collaboration capabilities. Some frontend subsystems are represented by documented enclosing directories because their individual source files were not in the supplied tree.

Main entry points: [`src/services/db-core.ts`](https://github.com/yosrikhiari/versatile/blob/master/src/services/db-core.ts) (Local database), [`src/components`](https://github.com/yosrikhiari/versatile/tree/master/src/components) (Writing workspace), [`src/stores/useStoryQueryStore.ts`](https://github.com/yosrikhiari/versatile/blob/master/src/stores/useStoryQueryStore.ts) (Story Query), [`src/composables/generation`](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation) (Generation engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_writing["Writing workspace"]
  node_workspace["Writing workspace"]
  node_manuscript["Manuscript tools"]
  node_flow["Flow sessions<br/>[FlowController.cs]"]
end

subgraph group_generation["AI generation"]
  node_pipeline["Novel pipeline"]
  node_engine["Generation engine"]
  node_bible_stage["Bible stage"]
  node_network_stage["Network stage"]
  node_structure_stage["Structure stage"]
  node_spine_stage["Spine stage"]
  node_prose_stage["Prose stage"]
  node_consistency_stage["Consistency stage"]
  node_run_controller["Run controller"]
  node_commit["Generation commit"]
end

subgraph group_storydata["Story knowledge"]
  node_query["Story Query"]
  node_bible["Story Bible"]
  node_network["Story Network"]
  node_research["Research retrieval"]
end

subgraph group_persistence["Persistence and sync"]
  node_localdb[("Local database<br/>[db-core.ts]")]
  node_sync["Sync engine<br/>[sync-engine.ts]"]
  node_backend["Optional API<br/>[Program.cs]"]
end

subgraph group_services["External services"]
  node_ai["AI provider service<br/>[aiService.ts]"]
  node_localmodel{{"Local model"}}
  node_cloudmodel{{"Cloud AI provider"}}
end

node_writer(("Writer"))

node_writer -->|"edits and runs"| node_workspace
node_workspace -->|"opens tools"| node_manuscript
node_workspace -->|"starts sessions"| node_flow
node_workspace -->|"queries story"| node_query
node_query -->|"reads and updates"| node_bible
node_query -->|"reads and updates"| node_manuscript
node_writer -->|"starts generation"| node_pipeline
node_pipeline -->|"starts or resumes"| node_engine
node_engine -->|"runs"| node_bible_stage
node_bible_stage -->|"feeds"| node_network_stage
node_network_stage -->|"feeds"| node_structure_stage
node_structure_stage -->|"feeds"| node_spine_stage
node_spine_stage -->|"feeds"| node_prose_stage
node_prose_stage -->|"feeds"| node_consistency_stage
node_engine -->|"requests generation"| node_ai
node_ai -->|"sends prompts"| node_localmodel
node_ai -.->|"routes by opt-in"| node_cloudmodel
node_run_controller -->|"controls run"| node_engine
node_run_controller -->|"saves scenes"| node_commit
node_commit -->|"persists"| node_localdb
node_query -->|"reads story data"| node_localdb
node_bible -->|"stores entities"| node_localdb
node_network -->|"stores graph data"| node_localdb
node_research -->|"rewrites queries"| node_ai
node_sync -->|"reads and writes"| node_localdb
node_sync -.->|"syncs opted-in data"| node_backend
node_backend -.->|"requests embeddings"| node_cloudmodel

click node_workspace "https://github.com/yosrikhiari/versatile/tree/master/src/components"
click node_manuscript "https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Controllers/ManuscriptController.cs"
click node_flow "https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Controllers/FlowController.cs"
click node_query "https://github.com/yosrikhiari/versatile/blob/master/src/stores/useStoryQueryStore.ts"
click node_bible "https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Controllers/EntityController.cs"
click node_network "https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Controllers/GraphEdgeController.cs"
click node_research "https://github.com/yosrikhiari/versatile/tree/master/src/composables/rag"
click node_pipeline "https://github.com/yosrikhiari/versatile/blob/master/src/composables/useNovelPipeline.ts"
click node_engine "https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation"
click node_bible_stage "https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation"
click node_network_stage "https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation"
click node_structure_stage "https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation"
click node_spine_stage "https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation"
click node_prose_stage "https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation"
click node_consistency_stage "https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation"
click node_run_controller "https://github.com/yosrikhiari/versatile/blob/master/src/composables/generation/useGenerationRunController.ts"
click node_commit "https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation/commit"
click node_localdb "https://github.com/yosrikhiari/versatile/blob/master/src/services/db-core.ts"
click node_sync "https://github.com/yosrikhiari/versatile/blob/master/src/services/sync-engine.ts"
click node_backend "https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Program.cs"
click node_ai "https://github.com/yosrikhiari/versatile/blob/master/src/services/aiService.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_workspace,node_manuscript,node_flow toneBlue
class node_pipeline,node_engine,node_bible_stage,node_network_stage,node_structure_stage,node_spine_stage,node_prose_stage,node_consistency_stage,node_run_controller,node_commit toneAmber
class node_query,node_bible,node_network,node_research toneMint
class node_localdb,node_sync,node_backend toneRose
class node_ai,node_localmodel,node_cloudmodel,node_writer toneIndigo
```

## Components

### Writing workspace

- [Writing workspace](https://github.com/yosrikhiari/versatile/tree/master/src/components): `src/components`
- [Manuscript tools](https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Controllers/ManuscriptController.cs): `backend/Versatile.Api/Controllers/ManuscriptController.cs`
- [Flow sessions](https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Controllers/FlowController.cs): `backend/Versatile.Api/Controllers/FlowController.cs`

### AI generation

- [Novel pipeline](https://github.com/yosrikhiari/versatile/blob/master/src/composables/useNovelPipeline.ts): `src/composables/useNovelPipeline.ts`
- [Generation engine](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation): `src/composables/generation`
- [Bible stage](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation): `src/composables/generation`
- [Network stage](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation): `src/composables/generation`
- [Structure stage](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation): `src/composables/generation`
- [Spine stage](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation): `src/composables/generation`
- [Prose stage](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation): `src/composables/generation`
- [Consistency stage](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation): `src/composables/generation`
- [Run controller](https://github.com/yosrikhiari/versatile/blob/master/src/composables/generation/useGenerationRunController.ts): `src/composables/generation/useGenerationRunController.ts`
- [Generation commit](https://github.com/yosrikhiari/versatile/tree/master/src/composables/generation/commit): `src/composables/generation/commit`

### Story knowledge

- [Story Query](https://github.com/yosrikhiari/versatile/blob/master/src/stores/useStoryQueryStore.ts): `src/stores/useStoryQueryStore.ts`
- [Story Bible](https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Controllers/EntityController.cs): `backend/Versatile.Api/Controllers/EntityController.cs`
- [Story Network](https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Controllers/GraphEdgeController.cs): `backend/Versatile.Api/Controllers/GraphEdgeController.cs`
- [Research retrieval](https://github.com/yosrikhiari/versatile/tree/master/src/composables/rag): `src/composables/rag`

### Persistence and sync

- [Local database](https://github.com/yosrikhiari/versatile/blob/master/src/services/db-core.ts): `src/services/db-core.ts`
- [Sync engine](https://github.com/yosrikhiari/versatile/blob/master/src/services/sync-engine.ts): `src/services/sync-engine.ts`
- [Optional API](https://github.com/yosrikhiari/versatile/blob/master/backend/Versatile.Api/Program.cs): `backend/Versatile.Api/Program.cs`

### External services

- [AI provider service](https://github.com/yosrikhiari/versatile/blob/master/src/services/aiService.ts): `src/services/aiService.ts`
- **Local model**
- **Cloud AI provider**

### Other components

- **Writer**

## Connections

- Writer → Writing workspace: edits and runs
- Writing workspace → Manuscript tools: opens tools
- Writing workspace → Flow sessions: starts sessions
- Writing workspace → Story Query: queries story
- Story Query → Story Bible: reads and updates
- Story Query → Manuscript tools: reads and updates
- Writer → Novel pipeline: starts generation
- Novel pipeline → Generation engine: starts or resumes
- Generation engine → Bible stage: runs
- Bible stage → Network stage: feeds
- Network stage → Structure stage: feeds
- Structure stage → Spine stage: feeds
- Spine stage → Prose stage: feeds
- Prose stage → Consistency stage: feeds
- Generation engine → AI provider service: requests generation
- AI provider service → Local model: sends prompts
- AI provider service → Cloud AI provider: routes by opt-in
- Run controller → Generation engine: controls run
- Run controller → Generation commit: saves scenes
- Generation commit → Local database: persists
- Story Query → Local database: reads story data
- Story Bible → Local database: stores entities
- Story Network → Local database: stores graph data
- Research retrieval → AI provider service: rewrites queries
- Sync engine → Local database: reads and writes
- Sync engine → Optional API: syncs opted-in data
- Optional API → Cloud AI provider: requests embeddings