# github/gh-skyline architecture

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

- Interactive diagram: https://gitdiagram.com/github/gh-skyline
- Repository: https://github.com/github/gh-skyline

## Overview

#### Purpose and entry points
`gh-skyline` is a Go GitHub CLI extension that converts a GitHub user’s contribution calendar into a 3D-printable binary STL, with an optional terminal ASCII preview. Process startup is `main.go`; command wiring and flag handling are rooted in `cmd/root.go` and `cmd/skyline/skyline.go`.

#### CLI orchestration
The skyline command resolves flags for user, year/range, full history, output, web-only, art-only, and debug behavior. It is the application coordinator: validate/select the requested time span, obtain contribution data, render preview, and conditionally write STL output. Paths: `cmd/skyline/skyline.go`, `cmd/root.go`, `internal/types/types.go`.

#### GitHub boundary and authentication
GitHub access is isolated behind the internal client layer. It relies on the installed/authenticated `gh` CLI rather than implementing independent credential management. This boundary fetches the authenticated or explicitly requested user and contribution graph data, likely including join-date information needed by `--full`; it also supports profile-opening behavior. Paths: `internal/github/client.go`, `internal/github/init.go`, `internal/types/types.go`.

#### Shared contribution model
A common type layer carries contribution-calendar data between API retrieval and both renderers, keeping GitHub transport logic separate from visualization and geometry. Domain-specific failures are centralized for command-level reporting. Paths: `internal/types/types.go`, `internal/errors/errors.go`.

#### ASCII loading-preview pipeline
The ASCII generator maps contribution levels and future/empty dates into terminal blocks, rearranging each week vertically into the skyline/building effect. This is a presentation-only path for loading feedback and becomes the terminal result when `--art-only` is selected. Paths: `internal/ascii/generator.go`, `internal/ascii/block.go`, `internal/ascii/text.go`.

#### STL model-generation pipeline
The STL generator transforms the same calendar into a 3D model: contribution cells become geometric structures, with geometry utilities defining shapes, transforms, vectors, and text. Bundled geometry assets support model lettering/branding. The STL layer serializes the assembled mesh as binary STL to the selected or default output file. Paths: `internal/stl/generator.go`, `internal/stl/stl.go`, `internal/stl/geometry/geometry.go`, `internal/stl/geometry/shapes.go`, `internal/stl/geometry/assets.go`.

#### Runtime, dependencies, and delivery
The runtime is a compiled Go executable invoked by GitHub CLI as `gh skyline`. Material external dependencies are GitHub CLI/authentication, GitHub’s user/contribution APIs, and `golang/freetype` plus bundled Mona Sans assets for 3D text. GitHub Actions provides build, lint, and release automation. Paths: `go.mod`, `internal/stl/geometry/text.go`, `internal/stl/geometry/assets`, `.github/workflows/release.yml`.

Main entry points: [`cmd/skyline/skyline.go`](https://github.com/github/gh-skyline/blob/main/cmd/skyline/skyline.go) (Skyline command), [`internal/github/client.go`](https://github.com/github/gh-skyline/blob/main/internal/github/client.go) (GitHub client), [`internal/stl/generator.go`](https://github.com/github/gh-skyline/blob/main/internal/stl/generator.go) (STL generator), [`internal/types/types.go`](https://github.com/github/gh-skyline/blob/main/internal/types/types.go) (Contribution model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_main["Process entry<br/>Go entrypoint<br/>[main.go]"]
  node_root["Root command<br/>command wiring<br/>[root.go]"]
  node_skyline["Skyline command<br/>application coordinator<br/>[skyline.go]"]
end

subgraph group_github["GitHub access"]
  node_gh{{"GitHub CLI<br/>external runtime"}}
  node_github_client["GitHub client<br/>API adapter<br/>[client.go]"]
  node_github_init["GitHub client setup<br/>client initialization<br/>[init.go]"]
  node_github_api{{"GitHub user APIs<br/>external API"}}
end

subgraph group_rendering["Rendering"]
  node_ascii["ASCII generator<br/>terminal renderer<br/>[generator.go]"]
  node_ascii_blocks["ASCII blocks and text<br/>terminal primitives<br/>[block.go]"]
  node_stl_generator["STL generator<br/>model assembler<br/>[generator.go]"]
  node_geometry["Geometry toolkit<br/>mesh geometry<br/>[geometry.go]"]
  node_text_geometry["3D text and assets<br/>geometry assets<br/>[text.go]"]
  node_stl_writer["Binary STL writer<br/>mesh serializer<br/>[stl.go]"]
end

subgraph group_delivery["Build &amp; delivery"]
  node_go_module["Go module<br/>dependency manifest<br/>[go.mod]"]
  node_release["Release workflow<br/>GitHub Actions<br/>[release.yml]"]
end

node_types["Contribution model<br/>shared domain types<br/>[types.go]"]
node_errors["Domain errors<br/>error layer<br/>[errors.go]"]
node_output["STL output file<br/>artifact"]

node_gh -->|"runs gh skyline"| node_main
node_main -->|"starts"| node_root
node_root -->|"registers"| node_skyline
node_skyline -->|"initializes"| node_github_init
node_github_init -->|"configures"| node_github_client
node_github_client -->|"uses auth"| node_gh
node_github_client -->|"queries"| node_github_api
node_github_client -->|"returns calendar"| node_types
node_github_client -->|"reports failures"| node_errors
node_skyline -->|"selects range"| node_types
node_skyline -->|"renders preview"| node_ascii
node_types -->|"calendar data"| node_ascii
node_ascii -->|"uses"| node_ascii_blocks
node_skyline -->|"when not art-only"| node_stl_generator
node_types -->|"calendar data"| node_stl_generator
node_stl_generator -->|"builds mesh"| node_geometry
node_stl_generator -->|"adds lettering"| node_text_geometry
node_stl_generator -->|"serializes"| node_stl_writer
node_stl_writer -->|"writes binary STL"| node_output
node_go_module -.->|"builds executable"| node_main
node_release -->|"builds and releases"| node_go_module

click node_main "https://github.com/github/gh-skyline/blob/main/main.go"
click node_root "https://github.com/github/gh-skyline/blob/main/cmd/root.go"
click node_skyline "https://github.com/github/gh-skyline/blob/main/cmd/skyline/skyline.go"
click node_types "https://github.com/github/gh-skyline/blob/main/internal/types/types.go"
click node_errors "https://github.com/github/gh-skyline/blob/main/internal/errors/errors.go"
click node_github_client "https://github.com/github/gh-skyline/blob/main/internal/github/client.go"
click node_github_init "https://github.com/github/gh-skyline/blob/main/internal/github/init.go"
click node_ascii "https://github.com/github/gh-skyline/blob/main/internal/ascii/generator.go"
click node_ascii_blocks "https://github.com/github/gh-skyline/blob/main/internal/ascii/block.go"
click node_stl_generator "https://github.com/github/gh-skyline/blob/main/internal/stl/generator.go"
click node_geometry "https://github.com/github/gh-skyline/blob/main/internal/stl/geometry/geometry.go"
click node_text_geometry "https://github.com/github/gh-skyline/blob/main/internal/stl/geometry/text.go"
click node_stl_writer "https://github.com/github/gh-skyline/blob/main/internal/stl/stl.go"
click node_go_module "https://github.com/github/gh-skyline/blob/main/go.mod"
click node_release "https://github.com/github/gh-skyline/blob/main/.github/workflows/release.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_main,node_root,node_skyline toneBlue
class node_gh,node_github_client,node_github_init,node_github_api toneAmber
class node_ascii,node_ascii_blocks,node_stl_generator,node_geometry,node_text_geometry,node_stl_writer toneMint
class node_go_module,node_release toneRose
class node_types,node_errors,node_output toneNeutral
```

## Components

### CLI

- [Process entry](https://github.com/github/gh-skyline/blob/main/main.go): Go entrypoint · `main.go`
- [Root command](https://github.com/github/gh-skyline/blob/main/cmd/root.go): command wiring · `cmd/root.go`
- [Skyline command](https://github.com/github/gh-skyline/blob/main/cmd/skyline/skyline.go): application coordinator · Resolves flags, selects time spans, and chooses preview or STL output. · `cmd/skyline/skyline.go`

### GitHub access

- **GitHub CLI**: external runtime · Invokes the extension and supplies authentication.
- [GitHub client](https://github.com/github/gh-skyline/blob/main/internal/github/client.go): API adapter · Retrieves users, contribution graphs, and join-date data through gh authentication. · `internal/github/client.go`
- [GitHub client setup](https://github.com/github/gh-skyline/blob/main/internal/github/init.go): client initialization · `internal/github/init.go`
- **GitHub user APIs**: external API

### Rendering

- [ASCII generator](https://github.com/github/gh-skyline/blob/main/internal/ascii/generator.go): terminal renderer · Rearranges weekly contribution levels into a skyline preview. · `internal/ascii/generator.go`
- [ASCII blocks and text](https://github.com/github/gh-skyline/blob/main/internal/ascii/block.go): terminal primitives · `internal/ascii/block.go`
- [STL generator](https://github.com/github/gh-skyline/blob/main/internal/stl/generator.go): model assembler · Converts contribution cells into a printable mesh. · `internal/stl/generator.go`
- [Geometry toolkit](https://github.com/github/gh-skyline/blob/main/internal/stl/geometry/geometry.go): mesh geometry · Defines shapes, transforms, vectors, and model assets. · `internal/stl/geometry/geometry.go`
- [3D text and assets](https://github.com/github/gh-skyline/blob/main/internal/stl/geometry/text.go): geometry assets · Uses Freetype and bundled Mona Sans assets for model lettering. · `internal/stl/geometry/text.go`
- [Binary STL writer](https://github.com/github/gh-skyline/blob/main/internal/stl/stl.go): mesh serializer · Writes the selected or default STL file. · `internal/stl/stl.go`

### Build & delivery

- [Go module](https://github.com/github/gh-skyline/blob/main/go.mod): dependency manifest · `go.mod`
- [Release workflow](https://github.com/github/gh-skyline/blob/main/.github/workflows/release.yml): GitHub Actions · Builds, lints, and releases the extension. · `.github/workflows/release.yml`

### Other components

- [Contribution model](https://github.com/github/gh-skyline/blob/main/internal/types/types.go): shared domain types · Carries calendar data between retrieval and renderers. · `internal/types/types.go`
- [Domain errors](https://github.com/github/gh-skyline/blob/main/internal/errors/errors.go): error layer · `internal/errors/errors.go`
- **STL output file**: artifact

## Connections

- GitHub CLI → Process entry: runs gh skyline
- Process entry → Root command: starts
- Root command → Skyline command: registers
- Skyline command → GitHub client setup: initializes
- GitHub client setup → GitHub client: configures
- GitHub client → GitHub CLI: uses auth
- GitHub client → GitHub user APIs: queries
- GitHub client → Contribution model: returns calendar
- GitHub client → Domain errors: reports failures
- Skyline command → Contribution model: selects range
- Skyline command → ASCII generator: renders preview
- Contribution model → ASCII generator: calendar data
- ASCII generator → ASCII blocks and text: uses
- Skyline command → STL generator: when not art-only
- Contribution model → STL generator: calendar data
- STL generator → Geometry toolkit: builds mesh
- STL generator → 3D text and assets: adds lettering
- STL generator → Binary STL writer: serializes
- Binary STL writer → STL output file: writes binary STL
- Go module → Process entry: builds executable
- Release workflow → Go module: builds and releases
