# phaethix/inkstone architecture

> Architecture diagram of the GitHub repository phaethix/inkstone, 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/phaethix/inkstone
- Repository: https://github.com/phaethix/inkstone

## Overview

Inkstone turns a local novel into comic pages and exports them as PDF or webtoon PNG. Users start generation through the CLI or local web backend; the pipeline segments text, extracts story assets, plans pages, generates artwork, applies character-consistency prompts and lettering, then exports results. Project checkpoints support resume, while the web supervisor retries transient failures and reports progress. The README documents optional legacy panel composition, alias review, and provider alternatives; these are included, but unsampled implementation details are not expanded.

Main entry points: [`core/pipelines/creative_comic.py`](https://github.com/phaethix/inkstone/blob/main/core/pipelines/creative_comic.py) (Comic Orchestrator), [`core/api/chat_provider.py`](https://github.com/phaethix/inkstone/blob/main/core/api/chat_provider.py) (Chat Provider), [`core/api/image_provider.py`](https://github.com/phaethix/inkstone/blob/main/core/api/image_provider.py) (Image Provider), [`web/server.py`](https://github.com/phaethix/inkstone/blob/main/web/server.py) (Web Backend)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Web Backend<br/>[server.py]"]
end

subgraph group_pipeline["Generation Pipeline"]
  node_supervisor["Run Supervisor"]
  node_generator["Comic Orchestrator<br/>[creative_comic.py]"]
end

subgraph group_story["Story and Identity"]
  node_segments["Text Segmentation<br/>[segmentation.py]"]
  node_screenwriter["Story Planning<br/>[screenwriter.py]"]
  node_visualbible["Visual Bible<br/>[visual_bible.py]"]
  node_identity["Identity Consistency<br/>[identity.py]"]
  node_consistency["Consistency Prompts<br/>[consistency.py]"]
end

subgraph group_art["Artwork and Rendering"]
  node_lettering["Page Lettering<br/>[page_lettering.py]"]
  node_fonts["Font Handling<br/>[fonts.py]"]
  node_layout["Panel Layout<br/>[layout.py]"]
  node_export["PDF / PNG Export<br/>[export.py]"]
end

subgraph group_services["Providers and State"]
  node_schemas["Project Models<br/>[schemas.py]"]
  node_chatprovider["Chat Provider<br/>[chat_provider.py]"]
  node_imageprovider["Image Provider<br/>[image_provider.py]"]
  node_checkpoint[("Project Checkpoint<br/>[schemas.py]")]
  node_reliability["API Reliability<br/>[retry.py]"]
end

node_user(("User"))
node_agneschat{{"Agnes Chat API"}}
node_agnesimage{{"Agnes Image API"}}
node_compat{{"OpenAI-Compatible API"}}
node_artifacts["Comic Artifacts"]

node_user -->|"runs"| node_cli
node_user -->|"submits novel"| node_web
node_cli -->|"starts generation"| node_generator
node_web -->|"starts supervised run"| node_supervisor
node_supervisor -->|"retries run"| node_generator
node_generator -->|"splits text"| node_segments
node_generator -->|"requests extraction and plans"| node_screenwriter
node_screenwriter -->|"requests structured results"| node_chatprovider
node_chatprovider -->|"calls chat API"| node_agneschat
node_chatprovider -.->|"calls compatible chat API"| node_compat
node_generator -->|"reconciles identities"| node_visualbible
node_generator -->|"applies identity rules"| node_identity
node_generator -->|"builds consistency prompts"| node_consistency
node_generator -->|"requests artwork"| node_imageprovider
node_imageprovider -->|"generates images"| node_agnesimage
node_imageprovider -.->|"generates images"| node_compat
node_generator -->|"letters finished pages"| node_lettering
node_lettering -->|"uses fonts"| node_fonts
node_generator -->|"lays out legacy panels"| node_layout
node_generator -->|"binds pages or strip"| node_export
node_generator -->|"saves and resumes state"| node_checkpoint
node_web -->|"reads project progress"| node_checkpoint
node_export -->|"writes PDF or PNG"| node_artifacts
node_chatprovider -->|"uses retries"| node_reliability
node_imageprovider -->|"uses retries"| node_reliability

click node_cli "https://github.com/phaethix/inkstone/blob/main/core/cli.py"
click node_web "https://github.com/phaethix/inkstone/blob/main/web/server.py"
click node_supervisor "https://github.com/phaethix/inkstone/blob/main/core/pipelines/run_until_complete.py"
click node_generator "https://github.com/phaethix/inkstone/blob/main/core/pipelines/creative_comic.py"
click node_segments "https://github.com/phaethix/inkstone/blob/main/core/comic/segmentation.py"
click node_screenwriter "https://github.com/phaethix/inkstone/blob/main/core/screenwriter.py"
click node_schemas "https://github.com/phaethix/inkstone/blob/main/core/schemas.py"
click node_visualbible "https://github.com/phaethix/inkstone/blob/main/core/comic/visual_bible.py"
click node_identity "https://github.com/phaethix/inkstone/blob/main/core/comic/identity.py"
click node_consistency "https://github.com/phaethix/inkstone/blob/main/core/comic/consistency.py"
click node_chatprovider "https://github.com/phaethix/inkstone/blob/main/core/api/chat_provider.py"
click node_imageprovider "https://github.com/phaethix/inkstone/blob/main/core/api/image_provider.py"
click node_lettering "https://github.com/phaethix/inkstone/blob/main/core/comic/page_lettering.py"
click node_fonts "https://github.com/phaethix/inkstone/blob/main/core/comic/fonts.py"
click node_layout "https://github.com/phaethix/inkstone/blob/main/core/comic/layout.py"
click node_export "https://github.com/phaethix/inkstone/blob/main/core/comic/export.py"
click node_checkpoint "https://github.com/phaethix/inkstone/blob/main/core/schemas.py"
click node_reliability "https://github.com/phaethix/inkstone/blob/main/core/api/retry.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_web,node_user toneBlue
class node_supervisor,node_generator toneAmber
class node_segments,node_screenwriter,node_visualbible,node_identity,node_consistency,node_agneschat,node_agnesimage,node_compat toneMint
class node_lettering,node_fonts,node_layout,node_export toneRose
class node_schemas,node_chatprovider,node_imageprovider,node_checkpoint,node_reliability,node_artifacts toneIndigo
```

## Components

### User Interfaces

- [CLI](https://github.com/phaethix/inkstone/blob/main/core/cli.py): `core/cli.py`
- [Web Backend](https://github.com/phaethix/inkstone/blob/main/web/server.py): `web/server.py`

### Generation Pipeline

- [Run Supervisor](https://github.com/phaethix/inkstone/blob/main/core/pipelines/run_until_complete.py): `core/pipelines/run_until_complete.py`
- [Comic Orchestrator](https://github.com/phaethix/inkstone/blob/main/core/pipelines/creative_comic.py): `core/pipelines/creative_comic.py`

### Story and Identity

- [Text Segmentation](https://github.com/phaethix/inkstone/blob/main/core/comic/segmentation.py): `core/comic/segmentation.py`
- [Story Planning](https://github.com/phaethix/inkstone/blob/main/core/screenwriter.py): `core/screenwriter.py`
- [Visual Bible](https://github.com/phaethix/inkstone/blob/main/core/comic/visual_bible.py): `core/comic/visual_bible.py`
- [Identity Consistency](https://github.com/phaethix/inkstone/blob/main/core/comic/identity.py): `core/comic/identity.py`
- [Consistency Prompts](https://github.com/phaethix/inkstone/blob/main/core/comic/consistency.py): `core/comic/consistency.py`

### Artwork and Rendering

- [Page Lettering](https://github.com/phaethix/inkstone/blob/main/core/comic/page_lettering.py): `core/comic/page_lettering.py`
- [Font Handling](https://github.com/phaethix/inkstone/blob/main/core/comic/fonts.py): `core/comic/fonts.py`
- [Panel Layout](https://github.com/phaethix/inkstone/blob/main/core/comic/layout.py): `core/comic/layout.py`
- [PDF / PNG Export](https://github.com/phaethix/inkstone/blob/main/core/comic/export.py): `core/comic/export.py`

### Providers and State

- [Project Models](https://github.com/phaethix/inkstone/blob/main/core/schemas.py): `core/schemas.py`
- [Chat Provider](https://github.com/phaethix/inkstone/blob/main/core/api/chat_provider.py): `core/api/chat_provider.py`
- [Image Provider](https://github.com/phaethix/inkstone/blob/main/core/api/image_provider.py): `core/api/image_provider.py`
- [Project Checkpoint](https://github.com/phaethix/inkstone/blob/main/core/schemas.py): `core/schemas.py`
- [API Reliability](https://github.com/phaethix/inkstone/blob/main/core/api/retry.py): `core/api/retry.py`

### Other components

- **User**
- **Agnes Chat API**
- **Agnes Image API**
- **OpenAI-Compatible API**
- **Comic Artifacts**

## Connections

- User → CLI: runs
- User → Web Backend: submits novel
- CLI → Comic Orchestrator: starts generation
- Web Backend → Run Supervisor: starts supervised run
- Run Supervisor → Comic Orchestrator: retries run
- Comic Orchestrator → Text Segmentation: splits text
- Comic Orchestrator → Story Planning: requests extraction and plans
- Story Planning → Chat Provider: requests structured results
- Chat Provider → Agnes Chat API: calls chat API
- Chat Provider → OpenAI-Compatible API: calls compatible chat API
- Comic Orchestrator → Visual Bible: reconciles identities
- Comic Orchestrator → Identity Consistency: applies identity rules
- Comic Orchestrator → Consistency Prompts: builds consistency prompts
- Comic Orchestrator → Image Provider: requests artwork
- Image Provider → Agnes Image API: generates images
- Image Provider → OpenAI-Compatible API: generates images
- Comic Orchestrator → Page Lettering: letters finished pages
- Page Lettering → Font Handling: uses fonts
- Comic Orchestrator → Panel Layout: lays out legacy panels
- Comic Orchestrator → PDF / PNG Export: binds pages or strip
- Comic Orchestrator → Project Checkpoint: saves and resumes state
- Web Backend → Project Checkpoint: reads project progress
- PDF / PNG Export → Comic Artifacts: writes PDF or PNG
- Chat Provider → API Reliability: uses retries
- Image Provider → API Reliability: uses retries