# mbadolato/iterm2-color-schemes architecture

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

- Interactive diagram: https://gitdiagram.com/mbadolato/iterm2-color-schemes
- Repository: https://github.com/mbadolato/iterm2-color-schemes

## Overview

This repository is a catalog of terminal color schemes, with conversion into terminal/editor formats and tools for previewing schemes. The main workflow is to supply an iTerm color file or YAML scheme, then generate output from templates; users can also preview schemes interactively. README documents many format ports, while the excerpts chiefly show the generator and preview implementation, so format-specific internals are represented only at the directory level. The license and screenshot utilities are supporting catalog capabilities, not the main runtime path.

Main entry points: [`tools/gen.py`](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/gen.py) (Theme generator), [`tools/preview_theme/cli.py`](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/cli.py) (Preview command), [`tools/screenshot_gen/__main__.py`](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/screenshot_gen/__main__.py) (Screenshot generator), [`schemes`](https://github.com/mbadolato/iterm2-color-schemes/tree/master/schemes) (Theme sources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_catalog["Scheme catalog"]
  node_source_themes["Theme sources"]
  node_yaml_themes["YAML themes"]
end

subgraph group_conversion["Theme conversion"]
  node_generator["Theme generator<br/>[gen.py]"]
  node_templates["Format templates"]
  node_format_ports["Terminal format ports"]
end

subgraph group_preview["Theme preview"]
  node_preview_cli["Preview command<br/>[cli.py]"]
  node_preview_loader["Theme loader<br/>[loader.py]"]
  node_preview_renderer["ANSI preview renderer<br/>[render.py]"]
  node_preview_colors["Color formatting<br/>[colors.py]"]
  node_preview_terminal["Terminal controls<br/>[terminal.py]"]
end

subgraph group_support["Catalog support"]
  node_license_check["License validation<br/>[check_licenses.py]"]
  node_screenshots["Theme screenshots"]
  node_screenshot_tool["Screenshot generator<br/>[__main__.py]"]
  node_screenshot_renderer["Image renderer<br/>[renderer.py]"]
  node_screenshot_helpers["Screenshot helpers<br/>[helpers.py]"]
end

node_user(("Theme user"))

node_user -->|"selects scheme"| node_source_themes
node_user -->|"authors scheme"| node_yaml_themes
node_source_themes -->|"converts schemes"| node_generator
node_yaml_themes -->|"converts themes"| node_generator
node_generator -->|"renders templates"| node_templates
node_generator -->|"generates formats"| node_format_ports
node_generator -->|"checks licenses"| node_license_check
node_user -->|"previews themes"| node_preview_cli
node_preview_cli -->|"resolves themes"| node_preview_loader
node_preview_cli -->|"renders preview"| node_preview_renderer
node_preview_cli -->|"reads controls"| node_preview_terminal
node_preview_loader -->|"loads theme data"| node_generator
node_preview_renderer -->|"formats colors"| node_preview_colors
node_screenshot_tool -->|"renders images"| node_screenshot_renderer
node_screenshot_tool -->|"reads scheme data"| node_screenshot_helpers
node_screenshot_renderer -->|"uses font charset"| node_screenshot_helpers
node_screenshot_tool -.->|"writes screenshots"| node_screenshots

click node_source_themes "https://github.com/mbadolato/iterm2-color-schemes/tree/master/schemes"
click node_yaml_themes "https://github.com/mbadolato/iterm2-color-schemes/tree/master/yaml"
click node_generator "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/gen.py"
click node_templates "https://github.com/mbadolato/iterm2-color-schemes/tree/master/tools/templates"
click node_format_ports "https://github.com/mbadolato/iterm2-color-schemes/tree/master/alacritty"
click node_license_check "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/check_licenses.py"
click node_preview_cli "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/cli.py"
click node_preview_loader "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/loader.py"
click node_preview_renderer "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/render.py"
click node_preview_colors "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/colors.py"
click node_preview_terminal "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/terminal.py"
click node_screenshots "https://github.com/mbadolato/iterm2-color-schemes/tree/master/screenshots"
click node_screenshot_tool "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/screenshot_gen/__main__.py"
click node_screenshot_renderer "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/screenshot_gen/renderer.py"
click node_screenshot_helpers "https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/screenshot_gen/helpers.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_source_themes,node_yaml_themes,node_user toneBlue
class node_generator,node_templates,node_format_ports toneAmber
class node_preview_cli,node_preview_loader,node_preview_renderer,node_preview_colors,node_preview_terminal toneMint
class node_license_check,node_screenshots,node_screenshot_tool,node_screenshot_renderer,node_screenshot_helpers toneRose
```

## Components

### Scheme catalog

- [Theme sources](https://github.com/mbadolato/iterm2-color-schemes/tree/master/schemes): `schemes`
- [YAML themes](https://github.com/mbadolato/iterm2-color-schemes/tree/master/yaml): `yaml`

### Theme conversion

- [Theme generator](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/gen.py): `tools/gen.py`
- [Format templates](https://github.com/mbadolato/iterm2-color-schemes/tree/master/tools/templates): `tools/templates`
- [Terminal format ports](https://github.com/mbadolato/iterm2-color-schemes/tree/master/alacritty): `alacritty`

### Theme preview

- [Preview command](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/cli.py): `tools/preview_theme/cli.py`
- [Theme loader](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/loader.py): `tools/preview_theme/loader.py`
- [ANSI preview renderer](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/render.py): `tools/preview_theme/render.py`
- [Color formatting](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/colors.py): `tools/preview_theme/colors.py`
- [Terminal controls](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/preview_theme/terminal.py): `tools/preview_theme/terminal.py`

### Catalog support

- [License validation](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/check_licenses.py): `tools/check_licenses.py`
- [Theme screenshots](https://github.com/mbadolato/iterm2-color-schemes/tree/master/screenshots): `screenshots`
- [Screenshot generator](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/screenshot_gen/__main__.py): `tools/screenshot_gen/__main__.py`
- [Image renderer](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/screenshot_gen/renderer.py): `tools/screenshot_gen/renderer.py`
- [Screenshot helpers](https://github.com/mbadolato/iterm2-color-schemes/blob/master/tools/screenshot_gen/helpers.py): `tools/screenshot_gen/helpers.py`

### Other components

- **Theme user**

## Connections

- Theme user → Theme sources: selects scheme (evidence: `README.md`)
- Theme user → YAML themes: authors scheme (evidence: `README.md`)
- Theme sources → Theme generator: converts schemes (evidence: `README.md`)
- YAML themes → Theme generator: converts themes (evidence: `README.md`)
- Theme generator → Format templates: renders templates (evidence: `README.md`)
- Theme generator → Terminal format ports: generates formats (evidence: `README.md`)
- Theme generator → License validation: checks licenses (evidence: `tools/gen.py`)
- Theme user → Preview command: previews themes (evidence: `README.md`)
- Preview command → Theme loader: resolves themes (evidence: `tools/preview_theme/cli.py`)
- Preview command → ANSI preview renderer: renders preview (evidence: `tools/preview_theme/cli.py`)
- Preview command → Terminal controls: reads controls (evidence: `tools/preview_theme/cli.py`)
- Theme loader → Theme generator: loads theme data (evidence: `tools/preview_theme/loader.py`)
- ANSI preview renderer → Color formatting: formats colors (evidence: `tools/preview_theme/render.py`)
- Screenshot generator → Image renderer: renders images (evidence: `tools/screenshot_gen/__main__.py`)
- Screenshot generator → Screenshot helpers: reads scheme data (evidence: `tools/screenshot_gen/__main__.py`)
- Image renderer → Screenshot helpers: uses font charset (evidence: `tools/screenshot_gen/renderer.py`)
- Screenshot generator → Theme screenshots: writes screenshots