# jj-sleeps/paletteai architecture

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

## Overview

PaletteAI’s main workflow is image upload or sample selection, image normalization and palette extraction, then palette review, accessibility/visualization, and library or feedback-based ranking. Its plugin framework adds local and webhook panels; the separate cross-dev Palette Fixer receives VibeCheck events and suggests (but does not apply) palette swaps. Edges reflect shown calls and README-documented behavior; unsampled implementation details are not inferred.

Main entry points: [`paletteai/api.py`](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/api.py) (REST API), [`paletteai/service.py`](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/service.py) (Palette services), [`paletteai/main.py`](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/main.py) (App factory), [`paletteai/plugins.py`](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/plugins.py) (Plugin manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["PaletteAI app"]
  node_main["App factory<br/>[main.py]"]
  node_api["REST API<br/>[api.py]"]
  node_schemas["API models<br/>[schemas.py]"]
  node_frontend["Web interface<br/>[app.js]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_service["Palette services<br/>[service.py]"]
  node_database[("SQLite store<br/>[db.py]")]
  node_samples["Sample images<br/>[samples.py]"]
end

subgraph group_analysis["Palette analysis"]
  node_etl["Image normalization<br/>[etl.py]"]
  node_clustering["Palette clustering<br/>[clustering.py]"]
  node_color["Color science<br/>[color.py]"]
  node_ranking["Preference ranking<br/>[ranking.py]"]
end

subgraph group_extension["Plugins"]
  node_plugin_manager["Plugin manager<br/>[plugins.py]"]
  node_local_plugin["Tints and shades<br/>[plugin.py]"]
  node_webhook_plugin["Webhook plugin"]
end

subgraph group_fixer["Palette Fixer"]
  node_fixer_app["Fixer webhook app<br/>[app.py]"]
  node_fixer_engine["Swap engine<br/>[fixer.py]"]
  node_vibecheck_client["VibeCheck client<br/>[client.py]"]
end

node_user(("User"))
node_vibecheck(("VibeCheck host"))

node_user -->|"uses"| node_frontend
node_frontend -->|"calls API"| node_api
node_main -->|"loads settings"| node_config
node_main -->|"initializes"| node_database
node_main -->|"creates samples"| node_samples
node_main -->|"mounts router"| node_api
node_main -->|"loads plugins"| node_plugin_manager
node_api -->|"validates with"| node_schemas
node_api -->|"calls"| node_service
node_api -->|"lists samples"| node_samples
node_service -->|"normalizes images"| node_etl
node_service -->|"extracts clusters"| node_clustering
node_service -->|"computes color data"| node_color
node_service -->|"ranks palettes"| node_ranking
node_service -->|"reads and writes"| node_database
node_api -->|"runs color tools"| node_color
node_api -->|"queries previews"| node_database
node_plugin_manager -->|"loads plugin"| node_local_plugin
node_plugin_manager -->|"dispatches panels"| node_webhook_plugin
node_plugin_manager -->|"provides palette access"| node_service
node_vibecheck -->|"sends event"| node_fixer_app
node_fixer_app -->|"proposes swaps"| node_fixer_engine
node_fixer_app -->|"fetches and rescoring"| node_vibecheck_client
node_vibecheck_client -.->|"calls host API"| node_vibecheck
node_fixer_engine -->|"uses color science"| node_color

click node_main "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/main.py"
click node_api "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/api.py"
click node_schemas "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/schemas.py"
click node_frontend "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/static/app.js"
click node_config "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/config.py"
click node_service "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/service.py"
click node_database "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/db.py"
click node_samples "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/samples.py"
click node_etl "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/etl.py"
click node_clustering "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/clustering.py"
click node_color "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/color.py"
click node_ranking "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/ranking.py"
click node_plugin_manager "https://github.com/jj-sleeps/paletteai/blob/main/paletteai/plugins.py"
click node_local_plugin "https://github.com/jj-sleeps/paletteai/blob/main/plugins/tints_and_shades/plugin.py"
click node_fixer_app "https://github.com/jj-sleeps/paletteai/blob/main/crossdev/palette_fixer/app.py"
click node_fixer_engine "https://github.com/jj-sleeps/paletteai/blob/main/crossdev/palette_fixer/fixer.py"
click node_vibecheck_client "https://github.com/jj-sleeps/paletteai/blob/main/crossdev/palette_fixer/client.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_main,node_api,node_schemas,node_frontend,node_config,node_service,node_database,node_samples,node_user toneBlue
class node_etl,node_clustering,node_color,node_ranking toneAmber
class node_plugin_manager,node_local_plugin,node_webhook_plugin toneMint
class node_fixer_app,node_fixer_engine,node_vibecheck_client toneRose
class node_vibecheck toneIndigo
```

## Components

### PaletteAI app

- [App factory](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/main.py): `paletteai/main.py`
- [REST API](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/api.py): `paletteai/api.py`
- [API models](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/schemas.py): `paletteai/schemas.py`
- [Web interface](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/static/app.js): `paletteai/static/app.js`
- [Runtime settings](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/config.py): `paletteai/config.py`
- [Palette services](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/service.py): `paletteai/service.py`
- [SQLite store](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/db.py): `paletteai/db.py`
- [Sample images](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/samples.py): `paletteai/samples.py`

### Palette analysis

- [Image normalization](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/etl.py): `paletteai/etl.py`
- [Palette clustering](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/clustering.py): `paletteai/clustering.py`
- [Color science](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/color.py): `paletteai/color.py`
- [Preference ranking](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/ranking.py): `paletteai/ranking.py`

### Plugins

- [Plugin manager](https://github.com/jj-sleeps/paletteai/blob/main/paletteai/plugins.py): `paletteai/plugins.py`
- [Tints and shades](https://github.com/jj-sleeps/paletteai/blob/main/plugins/tints_and_shades/plugin.py): `plugins/tints_and_shades/plugin.py`
- **Webhook plugin**

### Palette Fixer

- [Fixer webhook app](https://github.com/jj-sleeps/paletteai/blob/main/crossdev/palette_fixer/app.py): `crossdev/palette_fixer/app.py`
- [Swap engine](https://github.com/jj-sleeps/paletteai/blob/main/crossdev/palette_fixer/fixer.py): `crossdev/palette_fixer/fixer.py`
- [VibeCheck client](https://github.com/jj-sleeps/paletteai/blob/main/crossdev/palette_fixer/client.py): `crossdev/palette_fixer/client.py`

### Other components

- **User**
- **VibeCheck host**

## Connections

- User → Web interface: uses (evidence: `README.md`)
- Web interface → REST API: calls API (evidence: `README.md`)
- App factory → Runtime settings: loads settings (evidence: `paletteai/main.py`)
- App factory → SQLite store: initializes (evidence: `paletteai/main.py`)
- App factory → Sample images: creates samples (evidence: `paletteai/main.py`)
- App factory → REST API: mounts router (evidence: `paletteai/main.py`)
- App factory → Plugin manager: loads plugins (evidence: `paletteai/main.py`)
- REST API → API models: validates with (evidence: `paletteai/api.py`)
- REST API → Palette services: calls (evidence: `paletteai/api.py`)
- REST API → Sample images: lists samples (evidence: `paletteai/api.py`)
- Palette services → Image normalization: normalizes images (evidence: `paletteai/service.py`)
- Palette services → Palette clustering: extracts clusters (evidence: `paletteai/service.py`)
- Palette services → Color science: computes color data (evidence: `paletteai/service.py`)
- Palette services → Preference ranking: ranks palettes (evidence: `paletteai/service.py`)
- Palette services → SQLite store: reads and writes (evidence: `paletteai/service.py`)
- REST API → Color science: runs color tools (evidence: `paletteai/api.py`)
- REST API → SQLite store: queries previews (evidence: `paletteai/api.py`)
- Plugin manager → Tints and shades: loads plugin (evidence: `paletteai/plugins.py`)
- Plugin manager → Webhook plugin: dispatches panels (evidence: `paletteai/plugins.py`)
- Plugin manager → Palette services: provides palette access (evidence: `paletteai/plugins.py`)
- VibeCheck host → Fixer webhook app: sends event (evidence: `crossdev/palette_fixer/app.py`)
- Fixer webhook app → Swap engine: proposes swaps (evidence: `crossdev/palette_fixer/app.py`)
- Fixer webhook app → VibeCheck client: fetches and rescoring (evidence: `crossdev/palette_fixer/app.py`)
- VibeCheck client → VibeCheck host: calls host API
- Swap engine → Color science: uses color science (evidence: `crossdev/palette_fixer/fixer.py`)
