# spicyhek/mybuilds architecture

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

- Interactive diagram: https://gitdiagram.com/spicyhek/mybuilds
- Repository: https://github.com/spicyhek/mybuilds

## Overview

mybuilds tracks delivery evidence across Source, Build, Publish, GitOps, Reconcile, Rollout and Verify, then presents each release live or as a replay. Ingestion, Kubernetes observation and public checks provide distinct evidence to a projector backed by SQLite. The React UI exposes history, shareable release details and replay. Edges are limited to relationships stated in the README or visible in excerpts and SOURCE INDEX references; several runtime details are unsampled, so uncertain links are omitted.

Main entry points: [`internal/ingest/ingest.go`](https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/ingest.go) (Event ingester), [`internal/httpapi/releases.go`](https://github.com/spicyhek/mybuilds/blob/main/internal/httpapi/releases.go) (Release API), [`internal/releases/project.go`](https://github.com/spicyhek/mybuilds/blob/main/internal/releases/project.go) (Release projector), [`cmd/server/main.go`](https://github.com/spicyhek/mybuilds/blob/main/cmd/server/main.go) (Server runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Release tracking"]
  node_server["Server runtime<br/>[main.go]"]
  node_watcher["Workload watcher<br/>[watcher.go]"]
  node_normalizer["Runtime normalizer<br/>[normalize.go]"]
  node_verifier["Public verifier<br/>[verifier.go]"]
  node_checks["URL checks<br/>[check.go]"]
end

subgraph group_ingest["Event ingestion"]
  node_ingester["Event ingester<br/>[ingest.go]"]
  node_githubmap["GitHub translator<br/>[github.go]"]
  node_cimap["CI translator<br/>[ci.go]"]
  node_argomap["Argo translator<br/>[argocd.go]"]
end

subgraph group_store["Projection and storage"]
  node_projector["Release projector<br/>[project.go]"]
  node_releases["Release queries<br/>[releases.go]"]
  node_database[("SQLite store<br/>[storage.go]")]
  node_timeline["Replay timeline<br/>[timeline.go]"]
end

subgraph group_web["Release interface"]
  node_api["HTTP API<br/>[server.go]"]
  node_apiqueries["Release API<br/>[releases.go]"]
  node_hub["SSE stream<br/>[stream.go]"]
  node_frontend["React application<br/>[App.tsx]"]
  node_live["Live releases<br/>[useLiveReleases.ts]"]
  node_history["Release history<br/>[History.tsx]"]
  node_releasepage["Release details<br/>[ReleasePage.tsx]"]
  node_replay["Replay controls<br/>[ReplayPlayer.tsx]"]
  node_player["Pipeline player<br/>[Player.tsx]"]
  node_pipeline["Stage pipeline<br/>[Pipeline.tsx]"]
  node_stagepanel["Stage details<br/>[StagePanel.tsx]"]
end

subgraph group_buffer["Ingestion buffer"]
  node_worker["Buffer receiver<br/>[index.ts]"]
  node_queue["SQS queue"]
  node_consumer["Queue consumer<br/>[queue.go]"]
end

node_operator(("Operator"))
node_github{{"GitHub deliveries"}}
node_ci{{"CI deliveries"}}
node_argocd{{"Argo CD events"}}
node_kubernetes{{"Kubernetes workloads"}}
node_public{{"Public service URLs"}}

node_github -->|"delivers events"| node_ingester
node_ci -->|"delivers events"| node_ingester
node_argocd -->|"delivers events"| node_ingester
node_ingester -->|"translates"| node_githubmap
node_ingester -->|"translates"| node_cimap
node_ingester -->|"translates"| node_argomap
node_ingester -->|"re-projects"| node_projector
node_ingester -->|"stores events"| node_database
node_kubernetes -->|"observed by"| node_watcher
node_watcher -->|"normalizes"| node_normalizer
node_watcher -->|"supplies observations"| node_projector
node_verifier -->|"runs checks"| node_checks
node_verifier -->|"checks URL"| node_public
node_verifier -->|"supplies check evidence"| node_projector
node_projector -->|"projects releases"| node_database
node_releases -->|"queries"| node_database
node_server -->|"initializes"| node_ingester
node_server -->|"starts"| node_watcher
node_server -->|"starts"| node_verifier
node_server -->|"starts"| node_consumer
node_worker -->|"buffers events"| node_queue
node_queue -->|"feeds requests"| node_consumer
node_consumer -->|"reuses ingestion"| node_ingester
node_operator -->|"views releases"| node_frontend
node_frontend -->|"renders"| node_history
node_frontend -->|"renders"| node_releasepage
node_live -->|"fetches releases"| node_apiqueries
node_live -->|"subscribes"| node_hub
node_history -->|"loads history"| node_apiqueries
node_releasepage -->|"loads release"| node_apiqueries
node_releasepage -->|"offers replay"| node_replay
node_replay -->|"drives playback"| node_player
node_player -->|"renders stages"| node_pipeline
node_player -->|"renders details"| node_stagepanel
node_api -->|"routes requests"| node_apiqueries
node_apiqueries -->|"reads releases"| node_releases
node_apiqueries -->|"serves timeline"| node_timeline
node_timeline -->|"projects frames"| node_projector

click node_worker "https://github.com/spicyhek/mybuilds/blob/main/worker/src/index.ts"
click node_consumer "https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/queue/queue.go"
click node_server "https://github.com/spicyhek/mybuilds/blob/main/cmd/server/main.go"
click node_watcher "https://github.com/spicyhek/mybuilds/blob/main/internal/kube/watcher.go"
click node_normalizer "https://github.com/spicyhek/mybuilds/blob/main/internal/kube/normalize.go"
click node_verifier "https://github.com/spicyhek/mybuilds/blob/main/internal/verifier/verifier.go"
click node_checks "https://github.com/spicyhek/mybuilds/blob/main/internal/verifier/check.go"
click node_ingester "https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/ingest.go"
click node_githubmap "https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/github/github.go"
click node_cimap "https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/ci/ci.go"
click node_argomap "https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/argocd/argocd.go"
click node_projector "https://github.com/spicyhek/mybuilds/blob/main/internal/releases/project.go"
click node_releases "https://github.com/spicyhek/mybuilds/blob/main/internal/storage/releases.go"
click node_database "https://github.com/spicyhek/mybuilds/blob/main/internal/storage/storage.go"
click node_api "https://github.com/spicyhek/mybuilds/blob/main/internal/httpapi/server.go"
click node_apiqueries "https://github.com/spicyhek/mybuilds/blob/main/internal/httpapi/releases.go"
click node_hub "https://github.com/spicyhek/mybuilds/blob/main/internal/httpapi/stream.go"
click node_frontend "https://github.com/spicyhek/mybuilds/blob/main/web/src/App.tsx"
click node_live "https://github.com/spicyhek/mybuilds/blob/main/web/src/useLiveReleases.ts"
click node_history "https://github.com/spicyhek/mybuilds/blob/main/web/src/pages/History.tsx"
click node_releasepage "https://github.com/spicyhek/mybuilds/blob/main/web/src/pages/ReleasePage.tsx"
click node_replay "https://github.com/spicyhek/mybuilds/blob/main/web/src/components/ReplayPlayer.tsx"
click node_player "https://github.com/spicyhek/mybuilds/blob/main/web/src/components/Player.tsx"
click node_pipeline "https://github.com/spicyhek/mybuilds/blob/main/web/src/components/Pipeline.tsx"
click node_stagepanel "https://github.com/spicyhek/mybuilds/blob/main/web/src/components/StagePanel.tsx"
click node_timeline "https://github.com/spicyhek/mybuilds/blob/main/internal/releases/timeline.go"

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_server,node_watcher,node_normalizer,node_verifier,node_checks toneBlue
class node_ingester,node_githubmap,node_cimap,node_argomap toneAmber
class node_projector,node_releases,node_database,node_timeline toneMint
class node_api,node_apiqueries,node_hub,node_frontend,node_live,node_history,node_releasepage,node_replay,node_player,node_pipeline,node_stagepanel toneRose
class node_worker,node_queue,node_consumer,node_operator,node_github,node_ci,node_argocd,node_kubernetes,node_public toneIndigo
```

## Components

### Release tracking

- [Server runtime](https://github.com/spicyhek/mybuilds/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Workload watcher](https://github.com/spicyhek/mybuilds/blob/main/internal/kube/watcher.go): `internal/kube/watcher.go`
- [Runtime normalizer](https://github.com/spicyhek/mybuilds/blob/main/internal/kube/normalize.go): `internal/kube/normalize.go`
- [Public verifier](https://github.com/spicyhek/mybuilds/blob/main/internal/verifier/verifier.go): `internal/verifier/verifier.go`
- [URL checks](https://github.com/spicyhek/mybuilds/blob/main/internal/verifier/check.go): `internal/verifier/check.go`

### Event ingestion

- [Event ingester](https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/ingest.go): `internal/ingest/ingest.go`
- [GitHub translator](https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/github/github.go): `internal/ingest/github/github.go`
- [CI translator](https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/ci/ci.go): `internal/ingest/ci/ci.go`
- [Argo translator](https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/argocd/argocd.go): `internal/ingest/argocd/argocd.go`

### Projection and storage

- [Release projector](https://github.com/spicyhek/mybuilds/blob/main/internal/releases/project.go): `internal/releases/project.go`
- [Release queries](https://github.com/spicyhek/mybuilds/blob/main/internal/storage/releases.go): `internal/storage/releases.go`
- [SQLite store](https://github.com/spicyhek/mybuilds/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Replay timeline](https://github.com/spicyhek/mybuilds/blob/main/internal/releases/timeline.go): `internal/releases/timeline.go`

### Release interface

- [HTTP API](https://github.com/spicyhek/mybuilds/blob/main/internal/httpapi/server.go): `internal/httpapi/server.go`
- [Release API](https://github.com/spicyhek/mybuilds/blob/main/internal/httpapi/releases.go): `internal/httpapi/releases.go`
- [SSE stream](https://github.com/spicyhek/mybuilds/blob/main/internal/httpapi/stream.go): `internal/httpapi/stream.go`
- [React application](https://github.com/spicyhek/mybuilds/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Live releases](https://github.com/spicyhek/mybuilds/blob/main/web/src/useLiveReleases.ts): `web/src/useLiveReleases.ts`
- [Release history](https://github.com/spicyhek/mybuilds/blob/main/web/src/pages/History.tsx): `web/src/pages/History.tsx`
- [Release details](https://github.com/spicyhek/mybuilds/blob/main/web/src/pages/ReleasePage.tsx): `web/src/pages/ReleasePage.tsx`
- [Replay controls](https://github.com/spicyhek/mybuilds/blob/main/web/src/components/ReplayPlayer.tsx): `web/src/components/ReplayPlayer.tsx`
- [Pipeline player](https://github.com/spicyhek/mybuilds/blob/main/web/src/components/Player.tsx): `web/src/components/Player.tsx`
- [Stage pipeline](https://github.com/spicyhek/mybuilds/blob/main/web/src/components/Pipeline.tsx): `web/src/components/Pipeline.tsx`
- [Stage details](https://github.com/spicyhek/mybuilds/blob/main/web/src/components/StagePanel.tsx): `web/src/components/StagePanel.tsx`

### Ingestion buffer

- [Buffer receiver](https://github.com/spicyhek/mybuilds/blob/main/worker/src/index.ts): `worker/src/index.ts`
- **SQS queue**
- [Queue consumer](https://github.com/spicyhek/mybuilds/blob/main/internal/ingest/queue/queue.go): `internal/ingest/queue/queue.go`

### Other components

- **Operator**
- **GitHub deliveries**
- **CI deliveries**
- **Argo CD events**
- **Kubernetes workloads**
- **Public service URLs**

## Connections

- GitHub deliveries → Event ingester: delivers events
- CI deliveries → Event ingester: delivers events
- Argo CD events → Event ingester: delivers events
- Event ingester → GitHub translator: translates (evidence: `internal/ingest/ingest.go`)
- Event ingester → CI translator: translates (evidence: `internal/ingest/ingest.go`)
- Event ingester → Argo translator: translates (evidence: `internal/ingest/ingest.go`)
- Event ingester → Release projector: re-projects (evidence: `internal/ingest/ingest.go`)
- Event ingester → SQLite store: stores events
- Kubernetes workloads → Workload watcher: observed by
- Workload watcher → Runtime normalizer: normalizes (evidence: `internal/kube/watcher.go`)
- Workload watcher → Release projector: supplies observations
- Public verifier → URL checks: runs checks (evidence: `internal/verifier/verifier.go`)
- Public verifier → Public service URLs: checks URL
- Public verifier → Release projector: supplies check evidence
- Release projector → SQLite store: projects releases (evidence: `internal/releases/project.go`)
- Release queries → SQLite store: queries (evidence: `internal/storage/releases.go`)
- Server runtime → Event ingester: initializes (evidence: `cmd/server/main.go`)
- Server runtime → Workload watcher: starts (evidence: `cmd/server/main.go`)
- Server runtime → Public verifier: starts (evidence: `cmd/server/main.go`)
- Server runtime → Queue consumer: starts (evidence: `cmd/server/main.go`)
- Buffer receiver → SQS queue: buffers events
- SQS queue → Queue consumer: feeds requests
- Queue consumer → Event ingester: reuses ingestion (evidence: `internal/ingest/queue/queue.go`)
- Operator → React application: views releases
- React application → Release history: renders (evidence: `web/src/App.tsx`)
- React application → Release details: renders (evidence: `web/src/App.tsx`)
- Live releases → Release API: fetches releases (evidence: `web/src/useLiveReleases.ts`)
- Live releases → SSE stream: subscribes (evidence: `web/src/useLiveReleases.ts`)
- Release history → Release API: loads history (evidence: `web/src/pages/History.tsx`)
- Release details → Release API: loads release (evidence: `web/src/pages/ReleasePage.tsx`)
- Release details → Replay controls: offers replay (evidence: `web/src/pages/ReleasePage.tsx`)
- Replay controls → Pipeline player: drives playback (evidence: `web/src/components/ReplayPlayer.tsx`)
- Pipeline player → Stage pipeline: renders stages (evidence: `web/src/components/Player.tsx`)
- Pipeline player → Stage details: renders details (evidence: `web/src/components/Player.tsx`)
- HTTP API → Release API: routes requests (evidence: `internal/httpapi/server.go`)
- Release API → Release queries: reads releases (evidence: `internal/httpapi/releases.go`)
- Release API → Replay timeline: serves timeline (evidence: `internal/httpapi/releases.go`)
- Replay timeline → Release projector: projects frames
