# andrea-ragalzi/koma-studio architecture

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

- Interactive diagram: https://gitdiagram.com/andrea-ragalzi/koma-studio
- Repository: https://github.com/andrea-ragalzi/koma-studio

## Overview

Koma Studio is a local-first Qt desktop app for manga project authoring. Users create or open a project, edit Story and Universe content, compose pages, optionally generate and review panel-image candidates, then export PNG pages. The graph preserves those distinct stages and the project persistence layer. Some capabilities are documented but their UI or implementation was not sampled; those links use README evidence or are omitted rather than inferred from folder structure.

Main entry points: [`src/app/AppController.cpp`](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/AppController.cpp) (App controller), [`src/app/PageController.cpp`](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/PageController.cpp) (Page composition), [`src/app/PanelGeneration.cpp`](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/PanelGeneration.cpp) (Panel generation), [`src/storage/AssetImporter.cpp`](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/AssetImporter.cpp) (Reference assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_appcontroller["App controller<br/>[AppController.cpp]"]
  node_settings["Settings<br/>[Settings.cpp]"]
  node_library["Project library"]
end

subgraph group_authoring["Story and Universe"]
  node_story["Story editing"]
  node_universe["Universe editing"]
  node_references["Reference assets<br/>[AssetImporter.cpp]"]
end

subgraph group_production["Pages and Production"]
  node_composition["Page composition<br/>[PageController.cpp]"]
  node_panelmodel["Panel layout model<br/>[PanelLayout.cpp]"]
  node_generation["Panel generation"]
  node_provider["Generation providers"]
  node_codexjob["Codex job"]
  node_candidate["Candidate review"]
  node_export["PNG page export<br/>[PageExport.cpp]"]
end

subgraph group_persistence["Project Persistence"]
  node_projectstore[("Project store<br/>[ProjectStore.cpp]")]
  node_workspacestore[("Workspace store<br/>[WorkspaceStore.cpp]")]
  node_pagestore[("Page store<br/>[PageStore.cpp]")]
  node_generationstore[("Generation store")]
  node_assetfiles["Project asset files<br/>[AssetFiles.cpp]"]
end

node_user(("Studio user"))

node_user -->|"uses"| node_appcontroller
node_appcontroller -->|"manages"| node_library
node_appcontroller -->|"configures"| node_settings
node_appcontroller -->|"exposes"| node_story
node_appcontroller -->|"exposes"| node_universe
node_appcontroller -->|"exposes"| node_composition
node_appcontroller -->|"opens projects"| node_projectstore
node_story -->|"reads and saves"| node_workspacestore
node_universe -->|"reads and saves"| node_workspacestore
node_story -->|"imports images"| node_references
node_universe -->|"imports images"| node_references
node_workspacestore -->|"uses database"| node_projectstore
node_composition -->|"loads and saves"| node_pagestore
node_composition -->|"reads references"| node_workspacestore
node_composition -->|"uses layout"| node_panelmodel
node_composition -->|"starts generation"| node_generation
node_generation -->|"selects provider"| node_provider
node_generation -->|"dispatches Codex"| node_codexjob
node_generation -->|"records candidates"| node_generationstore
node_generation -->|"imports results"| node_references
node_candidate -->|"reviews candidates"| node_generationstore
node_composition -->|"exports pages"| node_export
node_export -->|"reads images"| node_assetfiles
node_generationstore -->|"uses database"| node_projectstore
node_pagestore -->|"uses database"| node_projectstore
node_references -->|"resolves files"| node_assetfiles

click node_appcontroller "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/AppController.cpp"
click node_settings "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/core/Settings.cpp"
click node_library "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/ProjectListModel.cpp"
click node_story "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/WorkspaceController.cpp"
click node_universe "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/WorkspaceController.cpp"
click node_references "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/AssetImporter.cpp"
click node_composition "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/PageController.cpp"
click node_panelmodel "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/domain/PanelLayout.cpp"
click node_generation "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/PanelGeneration.cpp"
click node_provider "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/GenerationProvider.cpp"
click node_codexjob "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/CodexGenerationJob.cpp"
click node_candidate "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/GenerationStore.cpp"
click node_export "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/PageExport.cpp"
click node_projectstore "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/ProjectStore.cpp"
click node_workspacestore "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/WorkspaceStore.cpp"
click node_pagestore "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/PageStore.cpp"
click node_generationstore "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/GenerationStore.cpp"
click node_assetfiles "https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/AssetFiles.cpp"

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_appcontroller,node_settings,node_library,node_user toneBlue
class node_story,node_universe,node_references toneAmber
class node_composition,node_panelmodel,node_generation,node_provider,node_codexjob,node_candidate,node_export toneMint
class node_projectstore,node_workspacestore,node_pagestore,node_generationstore,node_assetfiles toneRose
```

## Components

### Application

- [App controller](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/AppController.cpp): `src/app/AppController.cpp`
- [Settings](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/core/Settings.cpp): `src/core/Settings.cpp`
- [Project library](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/ProjectListModel.cpp): `src/app/ProjectListModel.cpp`

### Story and Universe

- [Story editing](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/WorkspaceController.cpp): `src/app/WorkspaceController.cpp`
- [Universe editing](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/WorkspaceController.cpp): `src/app/WorkspaceController.cpp`
- [Reference assets](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/AssetImporter.cpp): `src/storage/AssetImporter.cpp`

### Pages and Production

- [Page composition](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/PageController.cpp): `src/app/PageController.cpp`
- [Panel layout model](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/domain/PanelLayout.cpp): `src/domain/PanelLayout.cpp`
- [Panel generation](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/PanelGeneration.cpp): `src/app/PanelGeneration.cpp`
- [Generation providers](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/GenerationProvider.cpp): `src/app/GenerationProvider.cpp`
- [Codex job](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/CodexGenerationJob.cpp): `src/app/CodexGenerationJob.cpp`
- [Candidate review](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/GenerationStore.cpp): `src/storage/GenerationStore.cpp`
- [PNG page export](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/app/PageExport.cpp): `src/app/PageExport.cpp`

### Project Persistence

- [Project store](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/ProjectStore.cpp): `src/storage/ProjectStore.cpp`
- [Workspace store](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/WorkspaceStore.cpp): `src/storage/WorkspaceStore.cpp`
- [Page store](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/PageStore.cpp): `src/storage/PageStore.cpp`
- [Generation store](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/GenerationStore.cpp): `src/storage/GenerationStore.cpp`
- [Project asset files](https://github.com/andrea-ragalzi/koma-studio/blob/main/src/storage/AssetFiles.cpp): `src/storage/AssetFiles.cpp`

### Other components

- **Studio user**

## Connections

- Studio user → App controller: uses (evidence: `README.md`)
- App controller → Project library: manages
- App controller → Settings: configures
- App controller → Story editing: exposes
- App controller → Universe editing: exposes
- App controller → Page composition: exposes
- App controller → Project store: opens projects
- Story editing → Workspace store: reads and saves
- Universe editing → Workspace store: reads and saves
- Story editing → Reference assets: imports images (evidence: `src/app/WorkspaceController.cpp`)
- Universe editing → Reference assets: imports images (evidence: `src/app/WorkspaceController.cpp`)
- Workspace store → Project store: uses database
- Page composition → Page store: loads and saves
- Page composition → Workspace store: reads references
- Page composition → Panel layout model: uses layout (evidence: `src/app/PageController.cpp`)
- Page composition → Panel generation: starts generation (evidence: `src/app/PanelGeneration.cpp`)
- Panel generation → Generation providers: selects provider (evidence: `src/app/PanelGeneration.cpp`)
- Panel generation → Codex job: dispatches Codex (evidence: `src/app/PanelGeneration.cpp`)
- Panel generation → Generation store: records candidates (evidence: `src/app/PanelGeneration.cpp`)
- Panel generation → Reference assets: imports results (evidence: `src/app/PanelGeneration.cpp`)
- Candidate review → Generation store: reviews candidates (evidence: `src/storage/GenerationStore.cpp`)
- Page composition → PNG page export: exports pages (evidence: `src/app/PageExport.cpp`)
- PNG page export → Project asset files: reads images (evidence: `src/app/PageExport.cpp`)
- Generation store → Project store: uses database
- Page store → Project store: uses database
- Reference assets → Project asset files: resolves files
