# cryptopunksnotdead/cryptopunks architecture

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

## Overview

This repository is a collection of Ruby pixel-art products and libraries, not one unified runtime. The main workflow is selecting punk artwork and attributes, generating or composing an image, and saving or presenting it; the GUI adds collection and style controls. Separate branches provide synthetic-punk generation, coin treatments, and a lightweight GraphQL API. The graph preserves the README’s major capabilities and the indexed punk series. Some subsystem links are documented rather than source-verified; unsampled implementation details are omitted.

Main entry points: [`cryptopunks-gui/app/cryptopunks_gui.rb`](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/cryptopunks_gui.rb) (GUI launcher), [`cryptopunks/lib/cryptopunks/tool.rb`](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/tool.rb) (Punk tools), [`cryptopunks-gui/app/model/image.rb`](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/model/image.rb) (Image model), [`punks/lib/punks/punks.rb`](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/punks.rb) (Punk series)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_punk["Punk artwork"]
  node_punk_tool["Punk tools<br/>[tool.rb]"]
  node_punk_attrs["Attributes and colors<br/>[attributes.rb]"]
  node_punk_contract["Punk data contract"]
  node_punk_assets["Punk assets"]
  node_punk_meta["Punk metadata<br/>[punksdata-meta.rb]"]
  node_spritesheet["Spritesheet lookup<br/>[spritesheet.rb]"]
  node_generator["Image generator<br/>[generator.rb]"]
  node_punk_series["Punk series<br/>[punks.rb]"]
  node_punk_12["12px series<br/>[punks_12.rb]"]
  node_punk_32["32px bodies<br/>[bodies_32.rb]"]
  node_punk_40["40px bodies<br/>[bodies_40.rb]"]
  node_punk_saudi["Saudi series<br/>[saudis.rb]"]
  node_punk_2017["2017 series"]
  node_dataset["Metadata dataset<br/>[dataset.rb]"]
end

subgraph group_gui["Desktop GUI"]
  node_gui["GUI launcher<br/>[cryptopunks_gui.rb]"]
  node_image_model["Image model<br/>[image.rb]"]
  node_image_frame["Image display<br/>[image_frame.rb]"]
  node_menu["Menu bar<br/>[menu_bar.rb]"]
  node_preferences["Collection preferences"]
  node_style_view["Style controls"]
end

subgraph group_extras["Related libraries"]
  node_coin_api["Coin treatments<br/>[dollar.rb]"]
  node_coin_entry["Punkart extensions<br/>[punkart.rb]"]
  node_graphql["GraphQL query<br/>[query.rb]"]
end

subgraph group_synth["Synthetic punks"]
  node_synth_contract["Synthetic attributes<br/>[contract.rb]"]
  node_synth_image["Synthetic image<br/>[image.rb]"]
end

node_user(("Image creator"))
node_collections_service["Collections YAML"]
node_ethereum_user(("Ethereum account"))

node_user -.->|"requests image"| node_punk_tool
node_punk_tool -.->|"uses attributes"| node_punk_attrs
node_punk_tool -.->|"uses assets"| node_punk_assets
node_punk_tool -.->|"uses metadata"| node_punk_meta
node_punk_contract -.->|"defines assets"| node_punk_assets
node_punk_contract -.->|"defines metadata"| node_punk_meta
node_punk_series -->|"calls generator"| node_generator
node_punk_series -->|"looks up sprites"| node_spritesheet
node_punk_12 -.->|"offers small images"| node_user
node_punk_32 -.->|"offers larger images"| node_user
node_punk_40 -.->|"offers larger images"| node_user
node_punk_saudi -.->|"offers series"| node_user
node_punk_2017 -.->|"offers series"| node_user
node_user -.->|"reads metadata"| node_dataset
node_user -->|"launches"| node_gui
node_gui -->|"creates model"| node_image_model
node_gui -->|"builds menu"| node_menu
node_gui -->|"builds display"| node_image_frame
node_gui -->|"includes controls"| node_style_view
node_menu -->|"opens preferences"| node_preferences
node_image_model -->|"fetches config"| node_collections_service
node_image_model -.->|"loads composite"| node_punk_series
node_user -.->|"applies treatment"| node_coin_entry
node_coin_entry -->|"exposes treatments"| node_coin_api
node_user -.->|"queries API"| node_graphql
node_ethereum_user -.->|"supplies address"| node_synth_contract
node_synth_contract -.->|"provides attributes"| node_synth_image
node_synth_image -.->|"generates punk"| node_ethereum_user

click node_punk_tool "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/tool.rb"
click node_punk_attrs "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/attributes.rb"
click node_punk_contract "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/contract/punksdata-contract.rb"
click node_punk_assets "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/contract/punksdata-assets.rb"
click node_punk_meta "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/contract/punksdata-meta.rb"
click node_spritesheet "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/pixelart/spritesheet.rb"
click node_generator "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/pixelart/generator.rb"
click node_punk_series "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/punks.rb"
click node_punk_12 "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/punks_12.rb"
click node_punk_32 "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/bodies_32.rb"
click node_punk_40 "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/bodies_40.rb"
click node_punk_saudi "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/saudis.rb"
click node_punk_2017 "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/ye_olde_punks_2017.rb"
click node_dataset "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/dataset/dataset.rb"
click node_gui "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/cryptopunks_gui.rb"
click node_image_model "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/model/image.rb"
click node_image_frame "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/view/image_frame.rb"
click node_menu "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/view/menu_bar.rb"
click node_preferences "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/view/preferences_dialog.rb"
click node_style_view "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/view/style_options_frame.rb"
click node_coin_api "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punkart/lib/punkart/dollar.rb"
click node_coin_entry "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punkart/lib/punkart.rb"
click node_graphql "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-graphql/lib/cryptopunks/graphql/query.rb"
click node_synth_contract "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/synthpunks/lib/synthpunks/contract.rb"
click node_synth_image "https://github.com/cryptopunksnotdead/cryptopunks/blob/master/synthpunks/lib/synthpunks/image.rb"

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_punk_tool,node_punk_attrs,node_punk_contract,node_punk_assets,node_punk_meta,node_spritesheet,node_generator,node_punk_series,node_punk_12,node_punk_32,node_punk_40,node_punk_saudi,node_punk_2017,node_dataset toneBlue
class node_gui,node_image_model,node_image_frame,node_menu,node_preferences,node_style_view toneAmber
class node_coin_api,node_coin_entry,node_graphql toneMint
class node_synth_contract,node_synth_image toneRose
class node_user,node_collections_service,node_ethereum_user toneIndigo
```

## Components

### Punk artwork

- [Punk tools](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/tool.rb): `cryptopunks/lib/cryptopunks/tool.rb`
- [Attributes and colors](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/attributes.rb): `cryptopunks/lib/cryptopunks/attributes.rb`
- [Punk data contract](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/contract/punksdata-contract.rb): `cryptopunks/lib/cryptopunks/contract/punksdata-contract.rb`
- [Punk assets](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/contract/punksdata-assets.rb): `cryptopunks/lib/cryptopunks/contract/punksdata-assets.rb`
- [Punk metadata](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks/lib/cryptopunks/contract/punksdata-meta.rb): `cryptopunks/lib/cryptopunks/contract/punksdata-meta.rb`
- [Spritesheet lookup](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/pixelart/spritesheet.rb): `punks/lib/punks/pixelart/spritesheet.rb`
- [Image generator](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/pixelart/generator.rb): `punks/lib/punks/pixelart/generator.rb`
- [Punk series](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/punks.rb): `punks/lib/punks/punks.rb`
- [12px series](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/punks_12.rb): `punks/lib/punks/punks_12.rb`
- [32px bodies](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/bodies_32.rb): `punks/lib/punks/bodies_32.rb`
- [40px bodies](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/bodies_40.rb): `punks/lib/punks/bodies_40.rb`
- [Saudi series](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/saudis.rb): `punks/lib/punks/saudis.rb`
- [2017 series](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/ye_olde_punks_2017.rb): `punks/lib/punks/ye_olde_punks_2017.rb`
- [Metadata dataset](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punks/lib/punks/dataset/dataset.rb): `punks/lib/punks/dataset/dataset.rb`

### Desktop GUI

- [GUI launcher](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/cryptopunks_gui.rb): `cryptopunks-gui/app/cryptopunks_gui.rb`
- [Image model](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/model/image.rb): `cryptopunks-gui/app/model/image.rb`
- [Image display](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/view/image_frame.rb): `cryptopunks-gui/app/view/image_frame.rb`
- [Menu bar](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/view/menu_bar.rb): `cryptopunks-gui/app/view/menu_bar.rb`
- [Collection preferences](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/view/preferences_dialog.rb): `cryptopunks-gui/app/view/preferences_dialog.rb`
- [Style controls](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-gui/app/view/style_options_frame.rb): `cryptopunks-gui/app/view/style_options_frame.rb`

### Related libraries

- [Coin treatments](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punkart/lib/punkart/dollar.rb): `punkart/lib/punkart/dollar.rb`
- [Punkart extensions](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/punkart/lib/punkart.rb): `punkart/lib/punkart.rb`
- [GraphQL query](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/cryptopunks-graphql/lib/cryptopunks/graphql/query.rb): `cryptopunks-graphql/lib/cryptopunks/graphql/query.rb`

### Synthetic punks

- [Synthetic attributes](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/synthpunks/lib/synthpunks/contract.rb): `synthpunks/lib/synthpunks/contract.rb`
- [Synthetic image](https://github.com/cryptopunksnotdead/cryptopunks/blob/master/synthpunks/lib/synthpunks/image.rb): `synthpunks/lib/synthpunks/image.rb`

### Other components

- **Image creator**
- **Collections YAML**
- **Ethereum account**

## Connections

- Image creator → Punk tools: requests image
- Punk tools → Attributes and colors: uses attributes
- Punk tools → Punk assets: uses assets
- Punk tools → Punk metadata: uses metadata
- Punk data contract → Punk assets: defines assets
- Punk data contract → Punk metadata: defines metadata
- Punk series → Image generator: calls generator (evidence: `punks/lib/punks/punks.rb`)
- Punk series → Spritesheet lookup: looks up sprites (evidence: `punks/lib/punks/punks.rb`)
- 12px series → Image creator: offers small images
- 32px bodies → Image creator: offers larger images
- 40px bodies → Image creator: offers larger images
- Saudi series → Image creator: offers series
- 2017 series → Image creator: offers series
- Image creator → Metadata dataset: reads metadata
- Image creator → GUI launcher: launches (evidence: `cryptopunks-gui/app/cryptopunks_gui.rb`)
- GUI launcher → Image model: creates model (evidence: `cryptopunks-gui/app/cryptopunks_gui.rb`)
- GUI launcher → Menu bar: builds menu (evidence: `cryptopunks-gui/app/cryptopunks_gui.rb`)
- GUI launcher → Image display: builds display (evidence: `cryptopunks-gui/app/cryptopunks_gui.rb`)
- GUI launcher → Style controls: includes controls (evidence: `cryptopunks-gui/app/cryptopunks_gui.rb`)
- Menu bar → Collection preferences: opens preferences (evidence: `cryptopunks-gui/app/view/menu_bar.rb`)
- Image model → Collections YAML: fetches config (evidence: `cryptopunks-gui/app/model/image.rb`)
- Image model → Punk series: loads composite
- Image creator → Punkart extensions: applies treatment
- Punkart extensions → Coin treatments: exposes treatments (evidence: `punkart/lib/punkart.rb`)
- Image creator → GraphQL query: queries API
- Ethereum account → Synthetic attributes: supplies address
- Synthetic attributes → Synthetic image: provides attributes
- Synthetic image → Ethereum account: generates punk
