# codelovingcat/github-snake-remix architecture

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

- Interactive diagram: https://gitdiagram.com/codelovingcat/github-snake-remix
- Repository: https://github.com/codelovingcat/github-snake-remix

## Overview

GitHub Snake Remix fetches a contribution calendar, normalizes it into a grid, plans and simulates a deterministic snake animation, renders SVG frames, and encodes them as a GIF artifact. The graph includes the core domain, color, animation, rendering, and quality responsibilities. The README documents the overall workflow and product features; source excerpts establish several internal calls. Some orchestration details are not excerpted, so only documented or directly evidenced relationships are shown.

Main entry points: [`src/animation-timeline.ts`](https://github.com/codelovingcat/github-snake-remix/blob/main/src/animation-timeline.ts) (Animation Timeline), [`src/generate.ts`](https://github.com/codelovingcat/github-snake-remix/blob/main/src/generate.ts) (Generation Orchestrator), [`src/gif-output.ts`](https://github.com/codelovingcat/github-snake-remix/blob/main/src/gif-output.ts) (GIF Encoder), [`src/contribution-grid.ts`](https://github.com/codelovingcat/github-snake-remix/blob/main/src/contribution-grid.ts) (Grid Normalizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Contribution Data"]
  node_provider["GraphQL Provider<br/>[github-graphql.ts]"]
  node_calendar["Calendar Contract"]
  node_grid["Grid Normalizer"]
end

subgraph group_simulation["Snake Simulation"]
  node_path["Snake Path Planner<br/>[snake-path.ts]"]
  node_engine["Snake Engine<br/>[snake-engine.ts]"]
  node_timeline["Animation Timeline"]
end

subgraph group_rendering["Rendering and Output"]
  node_generator["Generation Orchestrator<br/>[generate.ts]"]
  node_svg["SVG Frame Renderer<br/>[svg-renderer.ts]"]
  node_gif["GIF Encoder<br/>[gif-output.ts]"]
  node_quality["Artifact Quality Guards<br/>[quality.ts]"]
  node_artifact["GIF Artifact"]
end

subgraph group_domain["Shared Domain"]
  node_domain["Grid and Point Types<br/>[domain.ts]"]
  node_colors["Contribution Colors<br/>[colors.ts]"]
end

node_operator(("Generator Operator"))
node_github{{"GitHub GraphQL API"}}

node_operator -->|"runs generation"| node_generator
node_generator -->|"requests calendar"| node_provider
node_provider -->|"queries calendar"| node_github
node_provider -->|"returns calendar"| node_calendar
node_generator -->|"normalizes calendar"| node_grid
node_grid -->|"reads calendar"| node_calendar
node_grid -->|"uses empty-cell color"| node_colors
node_generator -->|"creates animation"| node_timeline
node_timeline -->|"plans route"| node_path
node_timeline -->|"simulates movement"| node_engine
node_timeline -->|"reads cells"| node_grid
node_generator -->|"encodes animation"| node_gif
node_gif -->|"reads frames"| node_timeline
node_gif -->|"renders frames"| node_svg
node_svg -->|"reads snake state"| node_engine
node_svg -->|"colors cells"| node_colors
node_svg -->|"reads heart particles"| node_timeline
node_gif -->|"validates output"| node_quality
node_gif -->|"writes GIF"| node_artifact
node_grid -->|"uses cell types"| node_domain
node_path -->|"uses point helpers"| node_domain
node_engine -->|"uses cell helpers"| node_domain
node_colors -->|"uses contribution levels"| node_domain

click node_generator "https://github.com/codelovingcat/github-snake-remix/blob/main/src/generate.ts"
click node_provider "https://github.com/codelovingcat/github-snake-remix/blob/main/src/github-graphql.ts"
click node_calendar "https://github.com/codelovingcat/github-snake-remix/blob/main/src/github-contributions.ts"
click node_grid "https://github.com/codelovingcat/github-snake-remix/blob/main/src/contribution-grid.ts"
click node_path "https://github.com/codelovingcat/github-snake-remix/blob/main/src/snake-path.ts"
click node_engine "https://github.com/codelovingcat/github-snake-remix/blob/main/src/snake-engine.ts"
click node_timeline "https://github.com/codelovingcat/github-snake-remix/blob/main/src/animation-timeline.ts"
click node_svg "https://github.com/codelovingcat/github-snake-remix/blob/main/src/svg-renderer.ts"
click node_gif "https://github.com/codelovingcat/github-snake-remix/blob/main/src/gif-output.ts"
click node_quality "https://github.com/codelovingcat/github-snake-remix/blob/main/src/quality.ts"
click node_domain "https://github.com/codelovingcat/github-snake-remix/blob/main/src/domain.ts"
click node_colors "https://github.com/codelovingcat/github-snake-remix/blob/main/src/colors.ts"

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_provider,node_calendar,node_grid toneBlue
class node_path,node_engine,node_timeline toneAmber
class node_generator,node_svg,node_gif,node_quality,node_artifact,node_github toneMint
class node_domain,node_colors toneRose
class node_operator toneIndigo
```

## Components

### Contribution Data

- [GraphQL Provider](https://github.com/codelovingcat/github-snake-remix/blob/main/src/github-graphql.ts): `src/github-graphql.ts`
- [Calendar Contract](https://github.com/codelovingcat/github-snake-remix/blob/main/src/github-contributions.ts): `src/github-contributions.ts`
- [Grid Normalizer](https://github.com/codelovingcat/github-snake-remix/blob/main/src/contribution-grid.ts): `src/contribution-grid.ts`

### Snake Simulation

- [Snake Path Planner](https://github.com/codelovingcat/github-snake-remix/blob/main/src/snake-path.ts): `src/snake-path.ts`
- [Snake Engine](https://github.com/codelovingcat/github-snake-remix/blob/main/src/snake-engine.ts): `src/snake-engine.ts`
- [Animation Timeline](https://github.com/codelovingcat/github-snake-remix/blob/main/src/animation-timeline.ts): `src/animation-timeline.ts`

### Rendering and Output

- [Generation Orchestrator](https://github.com/codelovingcat/github-snake-remix/blob/main/src/generate.ts): `src/generate.ts`
- [SVG Frame Renderer](https://github.com/codelovingcat/github-snake-remix/blob/main/src/svg-renderer.ts): `src/svg-renderer.ts`
- [GIF Encoder](https://github.com/codelovingcat/github-snake-remix/blob/main/src/gif-output.ts): `src/gif-output.ts`
- [Artifact Quality Guards](https://github.com/codelovingcat/github-snake-remix/blob/main/src/quality.ts): `src/quality.ts`
- **GIF Artifact**

### Shared Domain

- [Grid and Point Types](https://github.com/codelovingcat/github-snake-remix/blob/main/src/domain.ts): `src/domain.ts`
- [Contribution Colors](https://github.com/codelovingcat/github-snake-remix/blob/main/src/colors.ts): `src/colors.ts`

### Other components

- **Generator Operator**
- **GitHub GraphQL API**

## Connections

- Generator Operator → Generation Orchestrator: runs generation (evidence: `README.md`)
- Generation Orchestrator → GraphQL Provider: requests calendar (evidence: `README.md`)
- GraphQL Provider → GitHub GraphQL API: queries calendar (evidence: `src/github-graphql.ts`)
- GraphQL Provider → Calendar Contract: returns calendar (evidence: `src/github-graphql.ts`)
- Generation Orchestrator → Grid Normalizer: normalizes calendar (evidence: `README.md`)
- Grid Normalizer → Calendar Contract: reads calendar (evidence: `src/contribution-grid.ts`)
- Grid Normalizer → Contribution Colors: uses empty-cell color (evidence: `src/contribution-grid.ts`)
- Generation Orchestrator → Animation Timeline: creates animation (evidence: `README.md`)
- Animation Timeline → Snake Path Planner: plans route (evidence: `src/animation-timeline.ts`)
- Animation Timeline → Snake Engine: simulates movement (evidence: `src/animation-timeline.ts`)
- Animation Timeline → Grid Normalizer: reads cells (evidence: `src/animation-timeline.ts`)
- Generation Orchestrator → GIF Encoder: encodes animation (evidence: `README.md`)
- GIF Encoder → Animation Timeline: reads frames (evidence: `src/gif-output.ts`)
- GIF Encoder → SVG Frame Renderer: renders frames (evidence: `src/gif-output.ts`)
- SVG Frame Renderer → Snake Engine: reads snake state (evidence: `src/svg-renderer.ts`)
- SVG Frame Renderer → Contribution Colors: colors cells (evidence: `src/svg-renderer.ts`)
- SVG Frame Renderer → Animation Timeline: reads heart particles (evidence: `src/svg-renderer.ts`)
- GIF Encoder → Artifact Quality Guards: validates output (evidence: `src/gif-output.ts`)
- GIF Encoder → GIF Artifact: writes GIF (evidence: `src/gif-output.ts`)
- Grid Normalizer → Grid and Point Types: uses cell types (evidence: `src/contribution-grid.ts`)
- Snake Path Planner → Grid and Point Types: uses point helpers (evidence: `src/snake-path.ts`)
- Snake Engine → Grid and Point Types: uses cell helpers (evidence: `src/snake-engine.ts`)
- Contribution Colors → Grid and Point Types: uses contribution levels (evidence: `src/colors.ts`)
