# gandholi-kumar/curiokraft-coloring-book architecture

> Architecture diagram of the GitHub repository gandholi-kumar/curiokraft-coloring-book, 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/gandholi-kumar/curiokraft-coloring-book
- Repository: https://github.com/gandholi-kumar/curiokraft-coloring-book

## Overview

CurioKraft is a multi-agent coloring-book production and Amazon KDP publishing engine, with CLI and Publishing Studio API entry points. Its documented workflow runs manifest-driven prompt design and image generation, rescues and validates artwork, composes cover and interior PDFs, then performs KDP preflight and metadata/publishing support. Storage and synchronization provide persistent local/cloud asset management. The README documents these capabilities; only selected source excerpts were available, so links among unsampled stages are limited to documented workflow relationships.

Main entry points: [`src/curiokraft_book/cli.py`](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/cli.py) (Production CLI), [`src/curiokraft_book/orchestrator/batch_runner.py`](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/batch_runner.py) (Batch Runner), [`src/curiokraft_book/api/routes.py`](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/api/routes.py) (Studio Routes), [`src/curiokraft_book/data/hybrid_store.py`](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/hybrid_store.py) (Hybrid Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_cli["Production CLI<br/>[cli.py]"]
  node_studio["Studio API<br/>[app.py]"]
  node_routes["Studio Routes<br/>[routes.py]"]
  node_ws["Live Events"]
end

subgraph group_production["Book Production"]
  node_manifest["Book Manifest"]
  node_debate["Agent Debate<br/>[debate_engine.py]"]
  node_llm["Text Models<br/>[llm_client.py]"]
  node_providers["Model Providers<br/>[providers.py]"]
  node_images["Image Generation<br/>[image_generator.py]"]
  node_batch["Batch Runner<br/>[batch_runner.py]"]
  node_state_mgr["Pipeline State<br/>[state_manager.py]"]
end

subgraph group_quality["Artwork Quality"]
  node_rescue["Image Rescue"]
  node_validators["Artwork Validators"]
  node_qa["Book QA<br/>[book_qa.py]"]
end

subgraph group_publishing["KDP Publishing"]
  node_cover["Cover Composer<br/>[cover.py]"]
  node_interior["Interior PDF<br/>[interior_pdf.py]"]
  node_preflight["KDP Preflight<br/>[kdp_preflight.py]"]
  node_kdp_agent["KDP Metadata<br/>[kdp_publisher.py]"]
  node_kdp_parse["KDP Form Parser<br/>[kdp_parser.py]"]
end

subgraph group_state["Data and Operations"]
  node_hybrid["Hybrid Store<br/>[hybrid_store.py]"]
  node_postgres[("Relational Store<br/>[postgres_store.py]")]
  node_objects[("Asset Storage<br/>[object_storage.py]")]
  node_sync["Cloud Sync<br/>[sync_engine.py]"]
end

node_author(("Book Producer"))
node_cloud[("S3/R2 Storage")]
node_kdp(("Amazon KDP"))
node_model_services(("LLM Services"))

node_author -->|"runs"| node_cli
node_author -->|"uses"| node_studio
node_studio -->|"mounts"| node_routes
node_routes -->|"broadcasts events"| node_ws
node_cli -->|"starts batches"| node_batch
node_batch -->|"reads pages"| node_manifest
node_batch -->|"requests prompts"| node_debate
node_debate -->|"calls model"| node_llm
node_llm -->|"dispatches"| node_providers
node_providers -.->|"calls"| node_model_services
node_batch -->|"generates artwork"| node_images
node_batch -->|"tracks progress"| node_state_mgr
node_routes -->|"reads/writes books"| node_hybrid
node_state_mgr -->|"persists state"| node_hybrid
node_images -->|"rescues artwork"| node_rescue
node_rescue -->|"checks output"| node_validators
node_routes -->|"rescues ingested images"| node_rescue
node_cli -->|"builds cover"| node_cover
node_cli -->|"assembles PDF"| node_interior
node_cli -->|"runs checks"| node_preflight
node_cli -->|"generates metadata"| node_kdp_agent
node_kdp_agent -->|"uses form parsing"| node_kdp_parse
node_qa -->|"checks book"| node_validators
node_hybrid -->|"persists records"| node_postgres
node_hybrid -->|"stores assets"| node_objects
node_cli -->|"requests sync"| node_sync
node_sync -->|"syncs records"| node_postgres
node_sync -.->|"syncs assets"| node_cloud
node_objects -.->|"stores objects"| node_cloud
node_author -->|"publishes files"| node_kdp

click node_cli "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/cli.py"
click node_studio "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/api/app.py"
click node_routes "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/api/routes.py"
click node_ws "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/api/websocket_manager.py"
click node_manifest "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/blueprint_reader.py"
click node_debate "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/debate_engine.py"
click node_llm "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/llm_client.py"
click node_providers "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/providers.py"
click node_images "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/image_generator.py"
click node_batch "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/batch_runner.py"
click node_state_mgr "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/state_manager.py"
click node_rescue "https://github.com/gandholi-kumar/curiokraft-coloring-book/tree/main/src/curiokraft_book/rescue"
click node_validators "https://github.com/gandholi-kumar/curiokraft-coloring-book/tree/main/src/curiokraft_book/validators"
click node_cover "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/compositor/cover.py"
click node_interior "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/compositor/interior_pdf.py"
click node_preflight "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/validators/kdp_preflight.py"
click node_kdp_agent "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/agents/kdp_publisher.py"
click node_kdp_parse "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/agents/kdp_parser.py"
click node_qa "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/agents/book_qa.py"
click node_hybrid "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/hybrid_store.py"
click node_postgres "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/postgres_store.py"
click node_objects "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/object_storage.py"
click node_sync "https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/sync_engine.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_studio,node_routes,node_ws toneBlue
class node_manifest,node_debate,node_llm,node_providers,node_images,node_batch,node_state_mgr,node_cloud toneAmber
class node_rescue,node_validators,node_qa toneMint
class node_cover,node_interior,node_preflight,node_kdp_agent,node_kdp_parse toneRose
class node_hybrid,node_postgres,node_objects,node_sync,node_author,node_kdp,node_model_services toneIndigo
```

## Components

### User Interfaces

- [Production CLI](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/cli.py): `src/curiokraft_book/cli.py`
- [Studio API](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/api/app.py): `src/curiokraft_book/api/app.py`
- [Studio Routes](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/api/routes.py): `src/curiokraft_book/api/routes.py`
- [Live Events](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/api/websocket_manager.py): `src/curiokraft_book/api/websocket_manager.py`

### Book Production

- [Book Manifest](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/blueprint_reader.py): `src/curiokraft_book/orchestrator/blueprint_reader.py`
- [Agent Debate](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/debate_engine.py): `src/curiokraft_book/orchestrator/debate_engine.py`
- [Text Models](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/llm_client.py): `src/curiokraft_book/orchestrator/llm_client.py`
- [Model Providers](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/providers.py): `src/curiokraft_book/orchestrator/providers.py`
- [Image Generation](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/image_generator.py): `src/curiokraft_book/orchestrator/image_generator.py`
- [Batch Runner](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/batch_runner.py): `src/curiokraft_book/orchestrator/batch_runner.py`
- [Pipeline State](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/orchestrator/state_manager.py): `src/curiokraft_book/orchestrator/state_manager.py`

### Artwork Quality

- [Image Rescue](https://github.com/gandholi-kumar/curiokraft-coloring-book/tree/main/src/curiokraft_book/rescue): `src/curiokraft_book/rescue`
- [Artwork Validators](https://github.com/gandholi-kumar/curiokraft-coloring-book/tree/main/src/curiokraft_book/validators): `src/curiokraft_book/validators`
- [Book QA](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/agents/book_qa.py): `src/curiokraft_book/agents/book_qa.py`

### KDP Publishing

- [Cover Composer](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/compositor/cover.py): `src/curiokraft_book/compositor/cover.py`
- [Interior PDF](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/compositor/interior_pdf.py): `src/curiokraft_book/compositor/interior_pdf.py`
- [KDP Preflight](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/validators/kdp_preflight.py): `src/curiokraft_book/validators/kdp_preflight.py`
- [KDP Metadata](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/agents/kdp_publisher.py): `src/curiokraft_book/agents/kdp_publisher.py`
- [KDP Form Parser](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/agents/kdp_parser.py): `src/curiokraft_book/agents/kdp_parser.py`

### Data and Operations

- [Hybrid Store](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/hybrid_store.py): `src/curiokraft_book/data/hybrid_store.py`
- [Relational Store](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/postgres_store.py): `src/curiokraft_book/data/postgres_store.py`
- [Asset Storage](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/object_storage.py): `src/curiokraft_book/data/object_storage.py`
- [Cloud Sync](https://github.com/gandholi-kumar/curiokraft-coloring-book/blob/main/src/curiokraft_book/data/sync_engine.py): `src/curiokraft_book/data/sync_engine.py`

### Other components

- **Book Producer**
- **S3/R2 Storage**
- **Amazon KDP**
- **LLM Services**

## Connections

- Book Producer → Production CLI: runs
- Book Producer → Studio API: uses
- Studio API → Studio Routes: mounts
- Studio Routes → Live Events: broadcasts events
- Production CLI → Batch Runner: starts batches
- Batch Runner → Book Manifest: reads pages
- Batch Runner → Agent Debate: requests prompts
- Agent Debate → Text Models: calls model
- Text Models → Model Providers: dispatches
- Model Providers → LLM Services: calls
- Batch Runner → Image Generation: generates artwork
- Batch Runner → Pipeline State: tracks progress
- Studio Routes → Hybrid Store: reads/writes books
- Pipeline State → Hybrid Store: persists state
- Image Generation → Image Rescue: rescues artwork
- Image Rescue → Artwork Validators: checks output
- Studio Routes → Image Rescue: rescues ingested images
- Production CLI → Cover Composer: builds cover
- Production CLI → Interior PDF: assembles PDF
- Production CLI → KDP Preflight: runs checks
- Production CLI → KDP Metadata: generates metadata
- KDP Metadata → KDP Form Parser: uses form parsing
- Book QA → Artwork Validators: checks book
- Hybrid Store → Relational Store: persists records
- Hybrid Store → Asset Storage: stores assets
- Production CLI → Cloud Sync: requests sync
- Cloud Sync → Relational Store: syncs records
- Cloud Sync → S3/R2 Storage: syncs assets
- Asset Storage → S3/R2 Storage: stores objects
- Book Producer → Amazon KDP: publishes files