# mikemacd/rotation architecture

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

- Interactive diagram: https://gitdiagram.com/mikemacd/rotation
- Repository: https://github.com/mikemacd/rotation

## Overview

1. **What this repository is**
   - A small desktop graphics program that loads a 3D object from a data file and renders a rotating wireframe/line drawing of it.
   - The current implementation is a Go rewrite of older Amiga Basic and C/X11 versions kept in the repo for historical reference.

2. **Primary runtime boundary**
   - The app is a single native desktop executable built with Go.
   - It depends on `github.com/andlabs/ui` for the windowing/graphics layer, so the UI is not browser-based or server-based; it is an OS-native GUI application.

3. **Main Go entrypoint**
   - `rotation.go` is the central application file.
   - It likely contains startup, argument parsing, model loading, rotation math, and orchestration of the render loop.
   - `window.go` is the UI boundary, separating window creation, control wiring, and drawing surface concerns from the core rotation/model logic.

4. **Data loading subsystem**
   - The `.dat` files (`icosahedron.dat`, `cube.dat`, `car.dat`, `boat.dat`, etc.) are model inputs.
   - `./rotation -f <file>` indicates the app selects one of these geometry files at runtime rather than embedding a single hardcoded shape.
   - These files are the main external data source and define the object being drawn.

5. **Rendering flow**
   - The data flow is: **load model file → interpret vertices/edges/faces → apply rotation transforms → draw in GUI window**.
   - The visual output is driven by the rotation math rather than by a complex scene graph or 3D engine.
   - This suggests a lightweight custom renderer focused on simple geometric transformation and line drawing.

6. **Geometry/math subsystem**
   - The code includes the core 3D math needed for rotating an object in space.
   - Based on the README, this math is implemented directly in the application rather than delegated to a modern graphics API or 3D library.
   - That makes the math layer the main computation boundary in the app.

7. **Command-line and configuration**
   - Runtime behavior is configured primarily through command-line flags, especially `-f` to choose the input model file.
   - `-h` exposes help text, implying a small CLI front end wrapped around the GUI program.

8. **Build and dependency management**
   - The project is a Go module (`go.mod`, `go.sum`) and also vendors dependencies in `vendor/`.
   - This matters architecturally because the build is self-contained and reproducible, with external UI dependencies pinned locally.
   - The README notes platform prerequisites may be required for `andlabs/ui` on Linux/Windows.

9. **Legacy implementations**
   - `rotation.C` and `rotation.AmigaBasic.BAS` are not part of the active Go runtime, but they document the program’s evolution.
   - They are useful for understanding the original architecture and behavior, but the current executable path is the Go code.

10. **Repository shape and likely diagram boundaries**
   - One clear boundary is **UI/rendering** versus **model/maths/loader**:
     - UI layer: window creation, event handling, drawing surface.
     - Core layer: file parsing, object representation, transforms, rotation.
   - Another boundary is **application code** versus **input assets**:
     - executable logic in Go
     - 3D object definitions in `.dat` files

11. **What is not present**
   - There is no evidence of a network service, database, background worker, or multi-process architecture.
   - The program appears to be a standalone interactive desktop utility with local file input and immediate graphical output.

12. **In one sentence**
   - This repo is a small, single-process Go desktop app that reads a selected 3D object file, computes simple rotation transforms, and renders the result in a native GUI window using `andlabs/ui`.

Main entry points: [`rotation.go`](https://github.com/mikemacd/rotation/blob/master/rotation.go) (rotation.go), [`window.go`](https://github.com/mikemacd/rotation/blob/master/window.go) (window.go), [`go.mod`](https://github.com/mikemacd/rotation/blob/master/go.mod) (go.mod), [`vendor`](https://github.com/mikemacd/rotation/tree/master/vendor) (vendor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Go runtime"]
  node_rotation_go["rotation.go<br/>app entry<br/>[rotation.go]"]
  node_window_go["window.go<br/>ui shell<br/>[window.go]"]
end

subgraph group_assets["Model assets"]
  node_model_loader["Model files<br/>dat assets"]
  node_icosahedron_dat["icosahedron.dat<br/>geometry input<br/>[icosahedron.dat]"]
  node_cube_dat["cube.dat<br/>geometry input<br/>[cube.dat]"]
  node_car_dat["car.dat<br/>geometry input<br/>[car.dat]"]
  node_boat_dat["boat.dat<br/>geometry input<br/>[boat.dat]"]
  node_tetra_dat["tetra.dat<br/>geometry input<br/>[tetra.dat]"]
  node_oct_dat["oct.dat<br/>geometry input<br/>[oct.dat]"]
  node_pncl_dat["pncl.dat<br/>geometry input<br/>[pncl.dat]"]
  node_try_dat["try.dat<br/>geometry input<br/>[try.dat]"]
end

subgraph group_legacy["Legacy refs"]
  node_rotation_c["rotation.C<br/>legacy C<br/>[rotation.C]"]
  node_rotation_basic["rotation.AmigaBasic.BAS<br/>legacy basic"]
end

subgraph group_build["Build deps"]
  node_go_mod["go.mod<br/>module file<br/>[go.mod]"]
  node_vendor["vendor"]
end

node_rotation_go -->|"creates UI"| node_window_go
node_rotation_go -->|"loads"| node_model_loader
node_rotation_go -->|"built by"| node_go_mod
node_window_go -->|"uses UI lib"| node_vendor
node_go_mod -->|"pins deps"| node_vendor
node_model_loader -->|"example"| node_icosahedron_dat
node_model_loader -->|"example"| node_cube_dat
node_model_loader -->|"example"| node_car_dat
node_model_loader -->|"example"| node_boat_dat
node_model_loader -->|"example"| node_tetra_dat
node_model_loader -->|"example"| node_oct_dat
node_model_loader -->|"example"| node_pncl_dat
node_model_loader -->|"example"| node_try_dat
node_rotation_c -.->|"precedent"| node_rotation_go
node_rotation_basic -.->|"precedent"| node_rotation_go

click node_rotation_go "https://github.com/mikemacd/rotation/blob/master/rotation.go"
click node_window_go "https://github.com/mikemacd/rotation/blob/master/window.go"
click node_icosahedron_dat "https://github.com/mikemacd/rotation/blob/master/icosahedron.dat"
click node_cube_dat "https://github.com/mikemacd/rotation/blob/master/cube.dat"
click node_car_dat "https://github.com/mikemacd/rotation/blob/master/car.dat"
click node_boat_dat "https://github.com/mikemacd/rotation/blob/master/boat.dat"
click node_tetra_dat "https://github.com/mikemacd/rotation/blob/master/tetra.dat"
click node_oct_dat "https://github.com/mikemacd/rotation/blob/master/oct.dat"
click node_pncl_dat "https://github.com/mikemacd/rotation/blob/master/pncl.dat"
click node_try_dat "https://github.com/mikemacd/rotation/blob/master/try.dat"
click node_rotation_c "https://github.com/mikemacd/rotation/blob/master/rotation.C"
click node_rotation_basic "https://github.com/mikemacd/rotation/blob/master/rotation.AmigaBasic.BAS"
click node_go_mod "https://github.com/mikemacd/rotation/blob/master/go.mod"
click node_vendor "https://github.com/mikemacd/rotation/tree/master/vendor"

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_rotation_go,node_window_go toneBlue
class node_model_loader,node_icosahedron_dat,node_cube_dat,node_car_dat,node_boat_dat,node_tetra_dat,node_oct_dat,node_pncl_dat,node_try_dat toneAmber
class node_rotation_c,node_rotation_basic toneMint
class node_go_mod,node_vendor toneRose
```

## Components

### Go runtime

Active desktop application code and its native UI boundary.

- [rotation.go](https://github.com/mikemacd/rotation/blob/master/rotation.go): app entry · Main executable flow: startup, argument handling, model loading, rotation math, and render orchestration. · `rotation.go`
- [window.go](https://github.com/mikemacd/rotation/blob/master/window.go): ui shell · Native window creation, event wiring, and drawing surface boundary. · `window.go`

### Model assets

Runtime-selected geometry data files drawn by the app.

- **Model files**: dat assets · Selectable 3D geometry inputs consumed at runtime via the -f flag.
- [icosahedron.dat](https://github.com/mikemacd/rotation/blob/master/icosahedron.dat): geometry input · Sample object definition used as runtime input. · `icosahedron.dat`
- [cube.dat](https://github.com/mikemacd/rotation/blob/master/cube.dat): geometry input · Sample object definition used as runtime input. · `cube.dat`
- [car.dat](https://github.com/mikemacd/rotation/blob/master/car.dat): geometry input · Sample object definition used as runtime input. · `car.dat`
- [boat.dat](https://github.com/mikemacd/rotation/blob/master/boat.dat): geometry input · Sample object definition used as runtime input. · `boat.dat`
- [tetra.dat](https://github.com/mikemacd/rotation/blob/master/tetra.dat): geometry input · Sample object definition used as runtime input. · `tetra.dat`
- [oct.dat](https://github.com/mikemacd/rotation/blob/master/oct.dat): geometry input · Sample object definition used as runtime input. · `oct.dat`
- [pncl.dat](https://github.com/mikemacd/rotation/blob/master/pncl.dat): geometry input · Sample object definition used as runtime input. · `pncl.dat`
- [try.dat](https://github.com/mikemacd/rotation/blob/master/try.dat): geometry input · Sample object definition used as runtime input. · `try.dat`

### Legacy refs

Historical implementations kept for comparison and context.

- [rotation.C](https://github.com/mikemacd/rotation/blob/master/rotation.C): legacy C · Older C/X11 implementation retained as historical reference. · `rotation.C`
- [rotation.AmigaBasic.BAS](https://github.com/mikemacd/rotation/blob/master/rotation.AmigaBasic.BAS): legacy basic · Original Amiga Basic version retained as historical reference. · `rotation.AmigaBasic.BAS`

### Build deps

Module metadata and vendored dependencies.

- [go.mod](https://github.com/mikemacd/rotation/blob/master/go.mod): module file · Go module definition for the current rewrite and external dependency pinning. · `go.mod`
- [vendor](https://github.com/mikemacd/rotation/tree/master/vendor): vendored deps · Checked-in third-party dependencies used to make builds reproducible. · `vendor`

## Connections

- rotation.go → window.go: creates UI · The main program delegates native windowing and drawing setup to the UI layer.
- rotation.go → Model files: loads · The app selects and parses a geometry file at runtime.
- rotation.go → go.mod: built by · The executable is defined as a Go module.
- window.go → vendor: uses UI lib · Windowing and graphics are implemented through vendored native UI dependencies.
- go.mod → vendor: pins deps · Module metadata works with the vendored tree for reproducible builds.
- Model files → icosahedron.dat: example · Representative geometry input.
- Model files → cube.dat: example · Representative geometry input.
- Model files → car.dat: example · Representative geometry input.
- Model files → boat.dat: example · Representative geometry input.
- Model files → tetra.dat: example · Representative geometry input.
- Model files → oct.dat: example · Representative geometry input.
- Model files → pncl.dat: example · Representative geometry input.
- Model files → try.dat: example · Representative geometry input.
- rotation.C → rotation.go: precedent · Historical implementation that the Go rewrite supersedes.
- rotation.AmigaBasic.BAS → rotation.go: precedent · Original implementation that the Go rewrite supersedes.