# wizhill05/typesafe-image-diffusion architecture

> Architecture diagram of the GitHub repository wizhill05/typesafe-image-diffusion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wizhill05/typesafe-image-diffusion
- Repository: https://github.com/wizhill05/typesafe-image-diffusion

## Overview

This is a FastAPI pixel-art generator: a user submits a prompt and refinement count, the service asks Jev one color-choice question per pixel, then optionally repeats using each pixel’s prior color and local neighborhood. The API returns the grid, confidence, usage, and pass history for the browser to display and animate. The README also documents a health endpoint and static UI. The graph focuses on the documented runtime; unsampled UI details are represented at their exact tree path, and edges are limited to relationships shown in main.py or the README.

Main entry points: [`main.py`](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py) (Pass orchestrator), [`static/index.html`](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/static/index.html) (Prompt and animation UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Web API"]
  node_generate_endpoint["Generate endpoint<br/>[main.py]"]
  node_health_endpoint["Health endpoint<br/>[main.py]"]
  node_static_endpoint["Static UI route<br/>[main.py]"]
  node_request_validation["Request validation<br/>[main.py]"]
  node_response_payload["Generation response<br/>[main.py]"]
end

subgraph group_generation["Pixel Generation"]
  node_initial_questions["Initial pixel questions<br/>[main.py]"]
  node_refinement_questions["Refinement questions<br/>[main.py]"]
  node_image_state["Prompt image state<br/>[main.py]"]
  node_pixel_encoding["Compact pixel rows<br/>[main.py]"]
  node_answer_extraction["Grid and confidence<br/>[main.py]"]
  node_usage_tracking["Token usage tracking<br/>[main.py]"]
  node_generation_orchestrator["Pass orchestrator<br/>[main.py]"]
end

subgraph group_jev["Jev Model"]
  node_typesafe_client["TypeSafe client<br/>[main.py]"]
  node_jev_service["Jev System One"]
end

subgraph group_ui["Browser UI"]
  node_web_ui["Prompt and animation UI<br/>[index.html]"]
end

node_user(("User"))
node_browser(("Browser"))

node_user -->|"enters prompt"| node_web_ui
node_web_ui -->|"requests generation"| node_generate_endpoint
node_generate_endpoint -->|"validates input"| node_request_validation
node_generate_endpoint -->|"calls generation"| node_generation_orchestrator
node_generation_orchestrator -->|"builds state"| node_image_state
node_generation_orchestrator -->|"builds first pass"| node_initial_questions
node_generation_orchestrator -->|"submits questions"| node_typesafe_client
node_typesafe_client -->|"calls System One"| node_jev_service
node_jev_service -->|"returns answers"| node_typesafe_client
node_generation_orchestrator -->|"extracts answers"| node_answer_extraction
node_generation_orchestrator -->|"accumulates usage"| node_usage_tracking
node_generation_orchestrator -->|"encodes grid"| node_pixel_encoding
node_generation_orchestrator -->|"builds next pass"| node_refinement_questions
node_pixel_encoding -->|"provides neighborhoods"| node_refinement_questions
node_generation_orchestrator -->|"assembles result"| node_response_payload
node_generate_endpoint -->|"returns JSON"| node_response_payload
node_response_payload -->|"supplies grid and history"| node_web_ui
node_browser -->|"opens application"| node_static_endpoint
node_static_endpoint -->|"serves page"| node_web_ui
node_user -.->|"checks service"| node_health_endpoint

click node_generate_endpoint "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_health_endpoint "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_static_endpoint "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_request_validation "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_initial_questions "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_refinement_questions "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_image_state "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_pixel_encoding "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_answer_extraction "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_usage_tracking "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_generation_orchestrator "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_typesafe_client "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_response_payload "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py"
click node_web_ui "https://github.com/wizhill05/typesafe-image-diffusion/blob/main/static/index.html"

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_generate_endpoint,node_health_endpoint,node_static_endpoint,node_request_validation,node_response_payload,node_user,node_browser toneBlue
class node_initial_questions,node_refinement_questions,node_image_state,node_pixel_encoding,node_answer_extraction,node_usage_tracking,node_generation_orchestrator toneAmber
class node_typesafe_client,node_jev_service toneMint
class node_web_ui toneRose
```

## Components

### Web API

- [Generate endpoint](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Health endpoint](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Static UI route](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Request validation](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Generation response](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`

### Pixel Generation

- [Initial pixel questions](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Refinement questions](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Prompt image state](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Compact pixel rows](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Grid and confidence](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Token usage tracking](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- [Pass orchestrator](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`

### Jev Model

- [TypeSafe client](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/main.py): `main.py`
- **Jev System One**

### Browser UI

- [Prompt and animation UI](https://github.com/wizhill05/typesafe-image-diffusion/blob/main/static/index.html): `static/index.html`

### Other components

- **User**
- **Browser**

## Connections

- User → Prompt and animation UI: enters prompt (evidence: `README.md`)
- Prompt and animation UI → Generate endpoint: requests generation (evidence: `README.md`)
- Generate endpoint → Request validation: validates input (evidence: `main.py`)
- Generate endpoint → Pass orchestrator: calls generation (evidence: `main.py`)
- Pass orchestrator → Prompt image state: builds state (evidence: `main.py`)
- Pass orchestrator → Initial pixel questions: builds first pass (evidence: `main.py`)
- Pass orchestrator → TypeSafe client: submits questions (evidence: `main.py`)
- TypeSafe client → Jev System One: calls System One (evidence: `main.py`)
- Jev System One → TypeSafe client: returns answers (evidence: `main.py`)
- Pass orchestrator → Grid and confidence: extracts answers (evidence: `main.py`)
- Pass orchestrator → Token usage tracking: accumulates usage (evidence: `main.py`)
- Pass orchestrator → Compact pixel rows: encodes grid (evidence: `main.py`)
- Pass orchestrator → Refinement questions: builds next pass (evidence: `main.py`)
- Compact pixel rows → Refinement questions: provides neighborhoods (evidence: `main.py`)
- Pass orchestrator → Generation response: assembles result (evidence: `main.py`)
- Generate endpoint → Generation response: returns JSON (evidence: `main.py`)
- Generation response → Prompt and animation UI: supplies grid and history (evidence: `README.md`)
- Browser → Static UI route: opens application (evidence: `README.md`)
- Static UI route → Prompt and animation UI: serves page (evidence: `main.py`)
- User → Health endpoint: checks service
