# fogleman/primitive architecture

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

- Interactive diagram: https://gitdiagram.com/fogleman/primitive
- Repository: https://github.com/fogleman/primitive

## Overview

Primitive Pictures is a Go image-reconstruction tool: the CLI loads and scales a target, then repeatedly searches for a shape that improves the image and writes raster, vector, or animated output. Its optimization uses parallel workers, shape mutation, and pixel-difference scoring. A Python bot also generates pictures from Flickr photos and processes tweeted images before posting results to Twitter. The core CLI and worker flow are visible in excerpts; some additional shape modes and bot polling details are documented or indexed but not fully sampled.

Main entry points: [`main.go`](https://github.com/fogleman/primitive/blob/master/main.go) (CLI orchestration), [`bot/main.py`](https://github.com/fogleman/primitive/blob/master/bot/main.py) (Bot orchestration), [`primitive/worker.go`](https://github.com/fogleman/primitive/blob/master/primitive/worker.go) (Search workers), [`primitive/model.go`](https://github.com/fogleman/primitive/blob/master/primitive/model.go) (Image model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflow"]
  node_main["CLI orchestration<br/>[main.go]"]
  node_imageio["Image I/O<br/>[util.go]"]
end

subgraph group_search["Shape search"]
  node_model["Image model<br/>[model.go]"]
  node_worker["Search workers<br/>[worker.go]"]
  node_state["Candidate state<br/>[state.go]"]
  node_optimizer["Hill climbing<br/>[optimize.go]"]
  node_shapes["Shape generators"]
end

subgraph group_render["Raster and output"]
  node_scoring["Pixel scoring<br/>[core.go]"]
  node_raster["Scanline rasterization<br/>[raster.go]"]
  node_canvas["Canvas rendering<br/>[model.go]"]
end

subgraph group_bot["Social bot"]
  node_botrunner["Bot orchestration<br/>[main.py]"]
end

node_user(("CLI user"))
node_flickr["Flickr service"]
node_twitter["Twitter service"]
node_artifact["Generated image"]

node_user -->|"supplies options"| node_main
node_main -->|"loads input"| node_imageio
node_main -->|"creates and steps"| node_model
node_model -->|"runs searches"| node_worker
node_worker -->|"creates candidates"| node_state
node_worker -->|"hill climbs"| node_optimizer
node_worker -->|"generates shapes"| node_shapes
node_worker -->|"scores candidates"| node_scoring
node_model -->|"scores additions"| node_scoring
node_shapes -.->|"rasterizes shapes"| node_raster
node_model -->|"renders frames"| node_canvas
node_main -->|"encodes output"| node_imageio
node_main -->|"writes images"| node_artifact
node_botrunner -->|"fetches photos"| node_flickr
node_botrunner -->|"runs CLI"| node_main
node_botrunner -->|"posts results"| node_twitter
node_botrunner -->|"checks generated file"| node_artifact
node_flickr -->|"returns photos"| node_botrunner
node_twitter -.->|"delivers mentions"| node_botrunner

click node_main "https://github.com/fogleman/primitive/blob/master/main.go"
click node_imageio "https://github.com/fogleman/primitive/blob/master/primitive/util.go"
click node_model "https://github.com/fogleman/primitive/blob/master/primitive/model.go"
click node_worker "https://github.com/fogleman/primitive/blob/master/primitive/worker.go"
click node_state "https://github.com/fogleman/primitive/blob/master/primitive/state.go"
click node_optimizer "https://github.com/fogleman/primitive/blob/master/primitive/optimize.go"
click node_shapes "https://github.com/fogleman/primitive/tree/master/primitive"
click node_scoring "https://github.com/fogleman/primitive/blob/master/primitive/core.go"
click node_raster "https://github.com/fogleman/primitive/blob/master/primitive/raster.go"
click node_canvas "https://github.com/fogleman/primitive/blob/master/primitive/model.go"
click node_botrunner "https://github.com/fogleman/primitive/blob/master/bot/main.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_imageio,node_user toneBlue
class node_model,node_worker,node_state,node_optimizer,node_shapes toneAmber
class node_scoring,node_raster,node_canvas toneMint
class node_botrunner toneRose
class node_flickr,node_twitter,node_artifact toneIndigo
```

## Components

### CLI workflow

- [CLI orchestration](https://github.com/fogleman/primitive/blob/master/main.go): `main.go`
- [Image I/O](https://github.com/fogleman/primitive/blob/master/primitive/util.go): `primitive/util.go`

### Shape search

- [Image model](https://github.com/fogleman/primitive/blob/master/primitive/model.go): `primitive/model.go`
- [Search workers](https://github.com/fogleman/primitive/blob/master/primitive/worker.go): `primitive/worker.go`
- [Candidate state](https://github.com/fogleman/primitive/blob/master/primitive/state.go): `primitive/state.go`
- [Hill climbing](https://github.com/fogleman/primitive/blob/master/primitive/optimize.go): `primitive/optimize.go`
- [Shape generators](https://github.com/fogleman/primitive/tree/master/primitive): `primitive`

### Raster and output

- [Pixel scoring](https://github.com/fogleman/primitive/blob/master/primitive/core.go): `primitive/core.go`
- [Scanline rasterization](https://github.com/fogleman/primitive/blob/master/primitive/raster.go): `primitive/raster.go`
- [Canvas rendering](https://github.com/fogleman/primitive/blob/master/primitive/model.go): `primitive/model.go`

### Social bot

- [Bot orchestration](https://github.com/fogleman/primitive/blob/master/bot/main.py): `bot/main.py`

### Other components

- **CLI user**
- **Flickr service**
- **Twitter service**
- **Generated image**

## Connections

- CLI user → CLI orchestration: supplies options (evidence: `README.md`)
- CLI orchestration → Image I/O: loads input (evidence: `main.go`)
- CLI orchestration → Image model: creates and steps (evidence: `main.go`)
- Image model → Search workers: runs searches (evidence: `primitive/model.go`)
- Search workers → Candidate state: creates candidates (evidence: `primitive/worker.go`)
- Search workers → Hill climbing: hill climbs (evidence: `primitive/worker.go`)
- Search workers → Shape generators: generates shapes (evidence: `primitive/worker.go`)
- Search workers → Pixel scoring: scores candidates (evidence: `primitive/worker.go`)
- Image model → Pixel scoring: scores additions (evidence: `primitive/model.go`)
- Shape generators → Scanline rasterization: rasterizes shapes
- Image model → Canvas rendering: renders frames (evidence: `primitive/model.go`)
- CLI orchestration → Image I/O: encodes output (evidence: `main.go`)
- CLI orchestration → Generated image: writes images (evidence: `main.go`)
- Bot orchestration → Flickr service: fetches photos (evidence: `bot/main.py`)
- Bot orchestration → CLI orchestration: runs CLI (evidence: `bot/main.py`)
- Bot orchestration → Twitter service: posts results (evidence: `bot/main.py`)
- Bot orchestration → Generated image: checks generated file (evidence: `bot/main.py`)
- Flickr service → Bot orchestration: returns photos (evidence: `bot/main.py`)
- Twitter service → Bot orchestration: delivers mentions
