# up2wp/story-matrix-ai architecture

> Architecture diagram of the GitHub repository up2wp/story-matrix-ai, 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/up2wp/story-matrix-ai
- Repository: https://github.com/up2wp/story-matrix-ai

## Overview

Story Matrix AI is a full-stack AI-assisted novel-creation application. Authors move through story seeding, world building, outlining, constraints, and chapter drafting, iterating as needed; supporting workflows include imported-work backfill, proofreading/export, audiobook creation, and visual-asset generation. The React client routes users to these workflows and persists work through a REST API backed by SQLite. AI, Voicebox, image-provider, and optional Immich integrations are mediated by backend routes and services. README documents capabilities not covered by the sampled source; those are represented at their supported directory paths, without asserting unverified internal wiring.

Main entry points: [`src/core/store.ts`](https://github.com/up2wp/story-matrix-ai/blob/main/src/core/store.ts) (Work State), [`src/App.tsx`](https://github.com/up2wp/story-matrix-ai/blob/main/src/App.tsx) (Application Router), [`server/src/index.ts`](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/index.ts) (API Server), [`src/pages/seed/SeedPage.tsx`](https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/seed/SeedPage.tsx) (Story Seed)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Novel Creation"]
  node_works["Work Management<br/>[WorksPage.tsx]"]
  node_seed["Story Seed<br/>[SeedPage.tsx]"]
  node_world["World Builder<br/>[WorldPage.tsx]"]
  node_outline["Outline Editor<br/>[OutlinePage.tsx]"]
  node_constraints["Core Constraints"]
  node_chapters["Chapter Writing<br/>[ChaptersPage.tsx]"]
  node_backfill["Import Backfill"]
  node_proofread["Proofreading<br/>[useProofread.ts]"]
  node_preview["Preview &amp; Export<br/>[usePreview.ts]"]
end

subgraph group_client["Client Platform"]
  node_app["Application Router<br/>[App.tsx]"]
  node_state["Work State<br/>[store.ts]"]
  node_api["REST Client<br/>[api-client.ts]"]
  node_ai_client["AI Client<br/>[client.ts]"]
end

subgraph group_server["Backend Services"]
  node_backend["API Server<br/>[index.ts]"]
  node_work_routes["Work Routes<br/>[works.ts]"]
  node_database[("SQLite Database<br/>[db.ts]")]
  node_ai_routes["AI Routes<br/>[ai.ts]"]
  node_image_services["Image Provider Services"]
  node_immich_client["Immich Client<br/>[immich-client.ts]"]
end

subgraph group_media["Media Workflows"]
  node_audiobook["Audiobook Workflow<br/>[useAudiobook.ts]"]
  node_voice_routes["Voicebox Proxy<br/>[voicebox.ts]"]
  node_visual["Visual Assets"]
  node_image_routes["Image Generation API"]
  node_imagegen["Imagegen Workspace<br/>[imagegen.ts]"]
end

subgraph group_admin["Accounts &amp; Config"]
  node_auth["Authentication<br/>[auth.ts]"]
  node_users["User Management<br/>[users.ts]"]
  node_config["System Configuration<br/>[system-config.ts]"]
end

node_author(("Author"))
node_administrator(("Administrator"))
node_ai_provider{{"Configured AI"}}
node_voicebox{{"Voicebox Service"}}
node_image_provider{{"Image Provider"}}
node_immich{{"Immich Storage"}}

node_author -->|"uses"| node_app
node_administrator -->|"administers"| node_app
node_app -->|"routes"| node_works
node_app -->|"routes"| node_seed
node_app -->|"routes"| node_world
node_app -->|"routes"| node_outline
node_app -->|"routes"| node_constraints
node_app -->|"routes"| node_chapters
node_author -->|"starts story"| node_seed
node_seed -->|"advances creation"| node_world
node_world -->|"advances creation"| node_outline
node_outline -->|"advances creation"| node_constraints
node_constraints -->|"guides drafting"| node_chapters
node_works -->|"updates work"| node_state
node_seed -->|"updates work"| node_state
node_world -->|"updates work"| node_state
node_outline -->|"updates work"| node_state
node_constraints -->|"updates work"| node_state
node_chapters -->|"updates work"| node_state
node_backfill -->|"updates work"| node_state
node_proofread -->|"edits work"| node_state
node_preview -->|"reads work"| node_state
node_state -->|"requests data"| node_api
node_api -->|"sends REST requests"| node_backend
node_backend -->|"dispatches work requests"| node_work_routes
node_backend -->|"dispatches auth requests"| node_auth
node_backend -->|"dispatches user requests"| node_users
node_backend -->|"dispatches config requests"| node_config
node_work_routes -->|"reads/writes works"| node_database
node_users -->|"reads/writes users"| node_database
node_config -->|"reads/writes config"| node_database
node_auth -->|"reads/writes accounts"| node_database
node_backfill -->|"requests extraction"| node_ai_client
node_audiobook -->|"requests prompts"| node_ai_client
node_ai_client -->|"posts AI requests"| node_backend
node_backend -->|"dispatches AI requests"| node_ai_routes
node_ai_routes -->|"forwards prompts"| node_ai_provider
node_author -->|"creates chapter audio"| node_audiobook
node_audiobook -->|"requests Voicebox operations"| node_voice_routes
node_voice_routes -->|"proxies requests"| node_voicebox
node_author -->|"creates visual assets"| node_visual
node_visual -->|"requests generation"| node_image_routes
node_author -->|"uses workspace"| node_imagegen
node_imagegen -->|"requests image operations"| node_image_services
node_image_routes -->|"runs generation"| node_image_services
node_image_services -->|"sends image requests"| node_image_provider
node_image_services -.->|"stores/retrieves assets"| node_immich_client
node_immich_client -.->|"uses storage API"| node_immich

click node_app "https://github.com/up2wp/story-matrix-ai/blob/main/src/App.tsx"
click node_works "https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/works/WorksPage.tsx"
click node_seed "https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/seed/SeedPage.tsx"
click node_world "https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/world/WorldPage.tsx"
click node_outline "https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/outline/OutlinePage.tsx"
click node_constraints "https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/constraints/ConstraintsPage.tsx"
click node_chapters "https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/chapters/ChaptersPage.tsx"
click node_backfill "https://github.com/up2wp/story-matrix-ai/blob/main/src/features/backfill/useImportBackfill.ts"
click node_proofread "https://github.com/up2wp/story-matrix-ai/blob/main/src/features/proofread/useProofread.ts"
click node_preview "https://github.com/up2wp/story-matrix-ai/blob/main/src/features/preview/usePreview.ts"
click node_state "https://github.com/up2wp/story-matrix-ai/blob/main/src/core/store.ts"
click node_api "https://github.com/up2wp/story-matrix-ai/blob/main/src/core/api-client.ts"
click node_ai_client "https://github.com/up2wp/story-matrix-ai/blob/main/src/ai/client.ts"
click node_backend "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/index.ts"
click node_work_routes "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/works.ts"
click node_database "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/db.ts"
click node_ai_routes "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/ai.ts"
click node_auth "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/auth.ts"
click node_users "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/users.ts"
click node_config "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/system-config.ts"
click node_audiobook "https://github.com/up2wp/story-matrix-ai/blob/main/src/features/audiobook/useAudiobook.ts"
click node_voice_routes "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/voicebox.ts"
click node_visual "https://github.com/up2wp/story-matrix-ai/blob/main/src/features/image-generation/useImageGeneration.ts"
click node_image_routes "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/image-generation.ts"
click node_imagegen "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/imagegen.ts"
click node_image_services "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/services/image-generation-runner.ts"
click node_immich_client "https://github.com/up2wp/story-matrix-ai/blob/main/server/src/services/immich-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_works,node_seed,node_world,node_outline,node_constraints,node_chapters,node_backfill,node_proofread,node_preview toneBlue
class node_app,node_state,node_api,node_ai_client,node_immich toneAmber
class node_backend,node_work_routes,node_database,node_ai_routes,node_image_services,node_immich_client toneMint
class node_audiobook,node_voice_routes,node_visual,node_image_routes,node_imagegen toneRose
class node_auth,node_users,node_config,node_author,node_administrator,node_ai_provider,node_voicebox,node_image_provider toneIndigo
```

## Components

### Novel Creation

- [Work Management](https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/works/WorksPage.tsx): `src/pages/works/WorksPage.tsx`
- [Story Seed](https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/seed/SeedPage.tsx): `src/pages/seed/SeedPage.tsx`
- [World Builder](https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/world/WorldPage.tsx): `src/pages/world/WorldPage.tsx`
- [Outline Editor](https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/outline/OutlinePage.tsx): `src/pages/outline/OutlinePage.tsx`
- [Core Constraints](https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/constraints/ConstraintsPage.tsx): `src/pages/constraints/ConstraintsPage.tsx`
- [Chapter Writing](https://github.com/up2wp/story-matrix-ai/blob/main/src/pages/chapters/ChaptersPage.tsx): `src/pages/chapters/ChaptersPage.tsx`
- [Import Backfill](https://github.com/up2wp/story-matrix-ai/blob/main/src/features/backfill/useImportBackfill.ts): `src/features/backfill/useImportBackfill.ts`
- [Proofreading](https://github.com/up2wp/story-matrix-ai/blob/main/src/features/proofread/useProofread.ts): `src/features/proofread/useProofread.ts`
- [Preview & Export](https://github.com/up2wp/story-matrix-ai/blob/main/src/features/preview/usePreview.ts): `src/features/preview/usePreview.ts`

### Client Platform

- [Application Router](https://github.com/up2wp/story-matrix-ai/blob/main/src/App.tsx): `src/App.tsx`
- [Work State](https://github.com/up2wp/story-matrix-ai/blob/main/src/core/store.ts): `src/core/store.ts`
- [REST Client](https://github.com/up2wp/story-matrix-ai/blob/main/src/core/api-client.ts): `src/core/api-client.ts`
- [AI Client](https://github.com/up2wp/story-matrix-ai/blob/main/src/ai/client.ts): `src/ai/client.ts`

### Backend Services

- [API Server](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/index.ts): `server/src/index.ts`
- [Work Routes](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/works.ts): `server/src/routes/works.ts`
- [SQLite Database](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/db.ts): `server/src/db.ts`
- [AI Routes](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/ai.ts): `server/src/routes/ai.ts`
- [Image Provider Services](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/services/image-generation-runner.ts): `server/src/services/image-generation-runner.ts`
- [Immich Client](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/services/immich-client.ts): `server/src/services/immich-client.ts`

### Media Workflows

- [Audiobook Workflow](https://github.com/up2wp/story-matrix-ai/blob/main/src/features/audiobook/useAudiobook.ts): `src/features/audiobook/useAudiobook.ts`
- [Voicebox Proxy](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/voicebox.ts): `server/src/routes/voicebox.ts`
- [Visual Assets](https://github.com/up2wp/story-matrix-ai/blob/main/src/features/image-generation/useImageGeneration.ts): `src/features/image-generation/useImageGeneration.ts`
- [Image Generation API](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/image-generation.ts): `server/src/routes/image-generation.ts`
- [Imagegen Workspace](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/imagegen.ts): `server/src/routes/imagegen.ts`

### Accounts & Config

- [Authentication](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/auth.ts): `server/src/routes/auth.ts`
- [User Management](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/users.ts): `server/src/routes/users.ts`
- [System Configuration](https://github.com/up2wp/story-matrix-ai/blob/main/server/src/routes/system-config.ts): `server/src/routes/system-config.ts`

### Other components

- **Author**
- **Administrator**
- **Configured AI**
- **Voicebox Service**
- **Image Provider**
- **Immich Storage**

## Connections

- Author → Application Router: uses
- Administrator → Application Router: administers
- Application Router → Work Management: routes
- Application Router → Story Seed: routes
- Application Router → World Builder: routes
- Application Router → Outline Editor: routes
- Application Router → Core Constraints: routes
- Application Router → Chapter Writing: routes
- Author → Story Seed: starts story
- Story Seed → World Builder: advances creation
- World Builder → Outline Editor: advances creation
- Outline Editor → Core Constraints: advances creation
- Core Constraints → Chapter Writing: guides drafting
- Work Management → Work State: updates work
- Story Seed → Work State: updates work
- World Builder → Work State: updates work
- Outline Editor → Work State: updates work
- Core Constraints → Work State: updates work
- Chapter Writing → Work State: updates work
- Import Backfill → Work State: updates work
- Proofreading → Work State: edits work
- Preview & Export → Work State: reads work
- Work State → REST Client: requests data
- REST Client → API Server: sends REST requests
- API Server → Work Routes: dispatches work requests
- API Server → Authentication: dispatches auth requests
- API Server → User Management: dispatches user requests
- API Server → System Configuration: dispatches config requests
- Work Routes → SQLite Database: reads/writes works
- User Management → SQLite Database: reads/writes users
- System Configuration → SQLite Database: reads/writes config
- Authentication → SQLite Database: reads/writes accounts
- Import Backfill → AI Client: requests extraction
- Audiobook Workflow → AI Client: requests prompts
- AI Client → API Server: posts AI requests
- API Server → AI Routes: dispatches AI requests
- AI Routes → Configured AI: forwards prompts
- Author → Audiobook Workflow: creates chapter audio
- Audiobook Workflow → Voicebox Proxy: requests Voicebox operations
- Voicebox Proxy → Voicebox Service: proxies requests
- Author → Visual Assets: creates visual assets
- Visual Assets → Image Generation API: requests generation
- Author → Imagegen Workspace: uses workspace
- Imagegen Workspace → Image Provider Services: requests image operations
- Image Generation API → Image Provider Services: runs generation
- Image Provider Services → Image Provider: sends image requests
- Image Provider Services → Immich Client: stores/retrieves assets
- Immich Client → Immich Storage: uses storage API