# kojix2/orbits architecture

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

- Interactive diagram: https://gitdiagram.com/kojix2/orbits
- Repository: https://github.com/kojix2/orbits

## Overview

#### Purpose and Entry Points
`orbits` is a Crystal CLI that generates strange-attractor density images and renders them directly in terminals, as PNG, SIXEL, terminal graphics protocols, or ANSI Unicode text. Library loading begins at `src/orbits.cr`; the executable entry point is `src/orbits_cli.cr`. Command parsing and invocation orchestration live in `src/orbits/cli.cr`.

#### CLI Configuration and Reproducibility
The CLI selects an attractor (or randomizes one), accepts attractor-specific coefficients, image/raster controls, transforms, colormaps, output destinations, and rendering protocols. Seeded random parameter selection makes the full generated configuration reproducible. Presentation of resolved settings and persistence/display output are separated into `src/orbits/cli/config_presenter.cr` and `src/orbits/cli/output_writer.cr`, with randomization in `src/orbits/random_params.cr`.

#### Attractor Model Layer
Attractor implementations provide the iterative mathematical systems that generate orbit points. The shared attractor surface is organized under `src/orbits/attractors.cr`; concrete Clifford, De Jong, Hopalong, and Ikeda implementations are in `src/orbits/attractors/clifford.cr`, `src/orbits/attractors/de_jong.cr`, and `src/orbits/attractors/ikeda.cr`. Common domain data types are centralized in `src/orbits/types.cr`.

#### Orbit Generation and Rasterization
Generation converts selected attractor parameters into one or more independent orbit trajectories, including nearby starts. `src/orbits/generator.cr` is the computational generation boundary. Generated points are mapped into a bounded density raster according to configured size/window in `src/orbits/raster.cr`; this separates mathematical coordinates from pixel-space accumulation.

#### Image Transformation and Color Rendering
Post-generation transforms modify raster density before colorization, supporting modes such as linear, logarithmic, cubic, and equalized. This stage is implemented in `src/orbits/xforms.cr`. `src/orbits/colormap.cr` maps transformed values to named palettes, while `src/orbits/renderer.cr` coordinates raster-to-image rendering for the chosen output path.

#### Terminal Image Abstraction
`src/term_image.cr` provides a terminal-output subsystem independent of attractor generation. `src/term_image/protocol.cr` defines the protocol-facing abstraction, and `src/term_image/detector.cr` selects an available graphics protocol from environment/terminal capabilities. Concrete binary terminal graphics backends include `src/term_image/iterm2.cr`, `src/term_image/kitty.cr`, and `src/term_image/sixel.cr`; tmux-specific wrapping is handled by `src/term_image/tmux.cr`.

#### File and Text Output Boundaries
The image representation and PNG encoding are isolated from terminal protocol emission in `src/term_image/image.cr` and `src/term_image/png.cr`. When graphics protocols are unavailable or explicitly requested, ANSI truecolor Unicode renderers produce Braille or shaded text via `src/term_image/text.cr`. The CLI output writer decides whether the rendered result is emitted to the terminal or saved as formats such as PNG/SIXEL.

#### Runtime and Delivery
The project targets the Crystal runtime and uses Shards for dependency/build management (`shard.yml`). Build and test/release automation are defined in `.github/workflows/test.yml` and `.github/workflows/release.yml`. It relies on local terminal capabilities and environment signals rather than a network service or persistent backend.

Main entry points: [`src/orbits/attractors.cr`](https://github.com/kojix2/orbits/blob/main/src/orbits/attractors.cr) (Attractor model surface), [`src/orbits/cli.cr`](https://github.com/kojix2/orbits/blob/main/src/orbits/cli.cr) (Command orchestration), [`src/orbits/cli/output_writer.cr`](https://github.com/kojix2/orbits/blob/main/src/orbits/cli/output_writer.cr) (Output writer), [`src/term_image.cr`](https://github.com/kojix2/orbits/blob/main/src/term_image.cr) (Terminal image subsystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and configuration"]
  node_entry["CLI entry point<br/>Crystal executable<br/>[orbits_cli.cr]"]
  node_cli_orchestrator["Command orchestration<br/>CLI parser<br/>[cli.cr]"]
  node_config_presenter["Resolved settings<br/>configuration display"]
  node_random_params["Seeded random parameters<br/>parameter selection<br/>[random_params.cr]"]
  node_output_writer["Output writer<br/>output routing<br/>[output_writer.cr]"]
end

subgraph group_core["Generation pipeline"]
  node_library["Library loader<br/>Crystal library<br/>[orbits.cr]"]
  node_attractors["Attractor model surface<br/>math interface<br/>[attractors.cr]"]
  node_clifford["Clifford attractor<br/>attractor implementation<br/>[clifford.cr]"]
  node_de_jong["De Jong attractor<br/>attractor implementation<br/>[de_jong.cr]"]
  node_ikeda["Ikeda attractor<br/>attractor implementation<br/>[ikeda.cr]"]
  node_types["Domain types<br/>shared data<br/>[types.cr]"]
  node_generator["Orbit generator<br/>trajectory generation<br/>[generator.cr]"]
  node_raster["Density rasterizer<br/>pixel accumulation<br/>[raster.cr]"]
  node_xforms["Density transforms<br/>raster transform<br/>[xforms.cr]"]
  node_colormap["Palette mapping<br/>colorization<br/>[colormap.cr]"]
  node_renderer["Image renderer<br/>render coordinator<br/>[renderer.cr]"]
end

subgraph group_terminal["Terminal output"]
  node_term_image["Terminal image subsystem<br/>terminal output API<br/>[term_image.cr]"]
  node_protocol["Graphics protocol abstraction<br/>protocol interface<br/>[protocol.cr]"]
  node_detector["Protocol detector<br/>capability detection<br/>[detector.cr]"]
  node_graphics_backends["Binary graphics backends<br/>iTerm2, Kitty, SIXEL"]
  node_tmux["tmux wrapper<br/>terminal wrapper<br/>[tmux.cr]"]
  node_image["Image representation<br/>image model<br/>[image.cr]"]
  node_png["PNG encoder<br/>image encoding<br/>[png.cr]"]
  node_text["ANSI Unicode renderer<br/>text fallback<br/>[text.cr]"]
end

subgraph group_delivery["Runtime and delivery"]
  node_runtime["Crystal and Shards<br/>build runtime<br/>[shard.yml]"]
  node_automation["CI and release automation<br/>GitHub Actions<br/>[test.yml]"]
end

node_entry -->|"starts"| node_cli_orchestrator
node_library -->|"loads"| node_attractors
node_cli_orchestrator -->|"randomizes"| node_random_params
node_cli_orchestrator -->|"presents config"| node_config_presenter
node_cli_orchestrator -->|"selects"| node_attractors
node_attractors -->|"implements"| node_clifford
node_attractors -->|"implements"| node_de_jong
node_attractors -->|"implements"| node_ikeda
node_attractors -->|"iterates"| node_generator
node_types -->|"defines domain data"| node_attractors
node_generator -->|"orbit points"| node_raster
node_raster -->|"density raster"| node_xforms
node_xforms -->|"transformed values"| node_colormap
node_colormap -->|"colored pixels"| node_renderer
node_renderer -->|"builds image"| node_image
node_cli_orchestrator -->|"routes result"| node_output_writer
node_output_writer -->|"emits terminal output"| node_term_image
node_output_writer -->|"saves PNG"| node_png
node_term_image -->|"detects capabilities"| node_detector
node_detector -->|"selects"| node_protocol
node_protocol -->|"uses"| node_graphics_backends
node_graphics_backends -.->|"wraps when needed"| node_tmux
node_term_image -->|"falls back to"| node_text
node_image -->|"encodes"| node_png
node_runtime -.->|"builds"| node_entry
node_automation -->|"tests and releases"| node_runtime

click node_entry "https://github.com/kojix2/orbits/blob/main/src/orbits_cli.cr"
click node_cli_orchestrator "https://github.com/kojix2/orbits/blob/main/src/orbits/cli.cr"
click node_config_presenter "https://github.com/kojix2/orbits/blob/main/src/orbits/cli/config_presenter.cr"
click node_random_params "https://github.com/kojix2/orbits/blob/main/src/orbits/random_params.cr"
click node_output_writer "https://github.com/kojix2/orbits/blob/main/src/orbits/cli/output_writer.cr"
click node_library "https://github.com/kojix2/orbits/blob/main/src/orbits.cr"
click node_attractors "https://github.com/kojix2/orbits/blob/main/src/orbits/attractors.cr"
click node_clifford "https://github.com/kojix2/orbits/blob/main/src/orbits/attractors/clifford.cr"
click node_de_jong "https://github.com/kojix2/orbits/blob/main/src/orbits/attractors/de_jong.cr"
click node_ikeda "https://github.com/kojix2/orbits/blob/main/src/orbits/attractors/ikeda.cr"
click node_types "https://github.com/kojix2/orbits/blob/main/src/orbits/types.cr"
click node_generator "https://github.com/kojix2/orbits/blob/main/src/orbits/generator.cr"
click node_raster "https://github.com/kojix2/orbits/blob/main/src/orbits/raster.cr"
click node_xforms "https://github.com/kojix2/orbits/blob/main/src/orbits/xforms.cr"
click node_colormap "https://github.com/kojix2/orbits/blob/main/src/orbits/colormap.cr"
click node_renderer "https://github.com/kojix2/orbits/blob/main/src/orbits/renderer.cr"
click node_term_image "https://github.com/kojix2/orbits/blob/main/src/term_image.cr"
click node_protocol "https://github.com/kojix2/orbits/blob/main/src/term_image/protocol.cr"
click node_detector "https://github.com/kojix2/orbits/blob/main/src/term_image/detector.cr"
click node_tmux "https://github.com/kojix2/orbits/blob/main/src/term_image/tmux.cr"
click node_image "https://github.com/kojix2/orbits/blob/main/src/term_image/image.cr"
click node_png "https://github.com/kojix2/orbits/blob/main/src/term_image/png.cr"
click node_text "https://github.com/kojix2/orbits/blob/main/src/term_image/text.cr"
click node_runtime "https://github.com/kojix2/orbits/blob/main/shard.yml"
click node_automation "https://github.com/kojix2/orbits/blob/main/.github/workflows/test.yml"

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_entry,node_cli_orchestrator,node_config_presenter,node_random_params,node_output_writer toneBlue
class node_library,node_attractors,node_clifford,node_de_jong,node_ikeda,node_types,node_generator,node_raster,node_xforms,node_colormap,node_renderer toneAmber
class node_term_image,node_protocol,node_detector,node_graphics_backends,node_tmux,node_image,node_png,node_text toneMint
class node_runtime,node_automation toneRose
```

## Components

### CLI and configuration

- [CLI entry point](https://github.com/kojix2/orbits/blob/main/src/orbits_cli.cr): Crystal executable · `src/orbits_cli.cr`
- [Command orchestration](https://github.com/kojix2/orbits/blob/main/src/orbits/cli.cr): CLI parser · `src/orbits/cli.cr`
- [Resolved settings](https://github.com/kojix2/orbits/blob/main/src/orbits/cli/config_presenter.cr): configuration display · `src/orbits/cli/config_presenter.cr`
- [Seeded random parameters](https://github.com/kojix2/orbits/blob/main/src/orbits/random_params.cr): parameter selection · Makes randomized configurations reproducible. · `src/orbits/random_params.cr`
- [Output writer](https://github.com/kojix2/orbits/blob/main/src/orbits/cli/output_writer.cr): output routing · `src/orbits/cli/output_writer.cr`

### Generation pipeline

- [Library loader](https://github.com/kojix2/orbits/blob/main/src/orbits.cr): Crystal library · `src/orbits.cr`
- [Attractor model surface](https://github.com/kojix2/orbits/blob/main/src/orbits/attractors.cr): math interface · Unifies Clifford, De Jong, Hopalong, and Ikeda systems. · `src/orbits/attractors.cr`
- [Clifford attractor](https://github.com/kojix2/orbits/blob/main/src/orbits/attractors/clifford.cr): attractor implementation · `src/orbits/attractors/clifford.cr`
- [De Jong attractor](https://github.com/kojix2/orbits/blob/main/src/orbits/attractors/de_jong.cr): attractor implementation · `src/orbits/attractors/de_jong.cr`
- [Ikeda attractor](https://github.com/kojix2/orbits/blob/main/src/orbits/attractors/ikeda.cr): attractor implementation · `src/orbits/attractors/ikeda.cr`
- [Domain types](https://github.com/kojix2/orbits/blob/main/src/orbits/types.cr): shared data · `src/orbits/types.cr`
- [Orbit generator](https://github.com/kojix2/orbits/blob/main/src/orbits/generator.cr): trajectory generation · Generates independent trajectories including nearby starts. · `src/orbits/generator.cr`
- [Density rasterizer](https://github.com/kojix2/orbits/blob/main/src/orbits/raster.cr): pixel accumulation · `src/orbits/raster.cr`
- [Density transforms](https://github.com/kojix2/orbits/blob/main/src/orbits/xforms.cr): raster transform · `src/orbits/xforms.cr`
- [Palette mapping](https://github.com/kojix2/orbits/blob/main/src/orbits/colormap.cr): colorization · `src/orbits/colormap.cr`
- [Image renderer](https://github.com/kojix2/orbits/blob/main/src/orbits/renderer.cr): render coordinator · `src/orbits/renderer.cr`

### Terminal output

- [Terminal image subsystem](https://github.com/kojix2/orbits/blob/main/src/term_image.cr): terminal output API · Independent of attractor generation. · `src/term_image.cr`
- [Graphics protocol abstraction](https://github.com/kojix2/orbits/blob/main/src/term_image/protocol.cr): protocol interface · `src/term_image/protocol.cr`
- [Protocol detector](https://github.com/kojix2/orbits/blob/main/src/term_image/detector.cr): capability detection · Selects a protocol from terminal and environment signals. · `src/term_image/detector.cr`
- **Binary graphics backends**: iTerm2, Kitty, SIXEL
- [tmux wrapper](https://github.com/kojix2/orbits/blob/main/src/term_image/tmux.cr): terminal wrapper · `src/term_image/tmux.cr`
- [Image representation](https://github.com/kojix2/orbits/blob/main/src/term_image/image.cr): image model · `src/term_image/image.cr`
- [PNG encoder](https://github.com/kojix2/orbits/blob/main/src/term_image/png.cr): image encoding · `src/term_image/png.cr`
- [ANSI Unicode renderer](https://github.com/kojix2/orbits/blob/main/src/term_image/text.cr): text fallback · Renders Braille or shaded truecolor text. · `src/term_image/text.cr`

### Runtime and delivery

- [Crystal and Shards](https://github.com/kojix2/orbits/blob/main/shard.yml): build runtime · `shard.yml`
- [CI and release automation](https://github.com/kojix2/orbits/blob/main/.github/workflows/test.yml): GitHub Actions · `.github/workflows/test.yml`

## Connections

- CLI entry point → Command orchestration: starts
- Library loader → Attractor model surface: loads
- Command orchestration → Seeded random parameters: randomizes
- Command orchestration → Resolved settings: presents config
- Command orchestration → Attractor model surface: selects
- Attractor model surface → Clifford attractor: implements
- Attractor model surface → De Jong attractor: implements
- Attractor model surface → Ikeda attractor: implements
- Attractor model surface → Orbit generator: iterates
- Domain types → Attractor model surface: defines domain data
- Orbit generator → Density rasterizer: orbit points
- Density rasterizer → Density transforms: density raster
- Density transforms → Palette mapping: transformed values
- Palette mapping → Image renderer: colored pixels
- Image renderer → Image representation: builds image
- Command orchestration → Output writer: routes result
- Output writer → Terminal image subsystem: emits terminal output
- Output writer → PNG encoder: saves PNG
- Terminal image subsystem → Protocol detector: detects capabilities
- Protocol detector → Graphics protocol abstraction: selects
- Graphics protocol abstraction → Binary graphics backends: uses
- Binary graphics backends → tmux wrapper: wraps when needed
- Terminal image subsystem → ANSI Unicode renderer: falls back to
- Image representation → PNG encoder: encodes
- Crystal and Shards → CLI entry point: builds
- CI and release automation → Crystal and Shards: tests and releases
