# scadoshi/heron architecture

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

- Interactive diagram: https://gitdiagram.com/scadoshi/heron
- Repository: https://github.com/scadoshi/heron

## Overview

Heron is a personal JSON API for allowlisted GitHub repositories. A client requests portfolio or repository stats; HTTP routes dispatch to domain services, which obtain GitHub data, use cache ports, and return JSON contracts. A separate recurring counts sweep downloads repository tarballs and measures source; portfolio output can also include a contribution calendar. Health endpoints report server and cache status. The README documents these capabilities, but several wiring details are not visible in the sampled source, so those relationships are shown as unverified where needed.

Main entry points: [`src/lib/domain/stats/services.rs`](https://github.com/scadoshi/heron/blob/main/src/lib/domain/stats/services.rs) (Stats Service), [`src/lib/inbound/http/routes.rs`](https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/routes.rs) (HTTP Routes), [`src/lib/inbound/http/handlers/stats`](https://github.com/scadoshi/heron/tree/main/src/lib/inbound/http/handlers/stats) (Stats Handlers), [`src/lib/domain/calendar/services.rs`](https://github.com/scadoshi/heron/blob/main/src/lib/domain/calendar/services.rs) (Calendar Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_http["HTTP API"]
  node_routes["HTTP Routes<br/>[routes.rs]"]
  node_stats_handlers["Stats Handlers"]
  node_health_handlers["Health Handlers<br/>[health.rs]"]
  node_json_contracts["JSON Contracts"]
  node_middleware["HTTP Middleware<br/>[middleware.rs]"]
  node_http_server["HTTP Server<br/>[mod.rs]"]
end

subgraph group_domain["Domain Services"]
  node_stats_service["Stats Service<br/>[services.rs]"]
  node_stats_models["Stats Models"]
  node_calendar_service["Calendar Service<br/>[services.rs]"]
  node_calendar_models["Calendar Models<br/>[models.rs]"]
  node_counts_service["Counts Sweep<br/>[services.rs]"]
  node_counts_models["Counts Models<br/>[models.rs]"]
  node_health_service["Cache Health<br/>[services.rs]"]
end

subgraph group_adapters["Outbound Adapters"]
  node_github["GitHub API<br/>[mod.rs]"]
  node_tarball["Tarball Source<br/>[mod.rs]"]
  node_measure["Source Measurement<br/>[lib.rs]"]
  node_memory_cache[("Memory Cache<br/>[memory.rs]")]
  node_layered_cache[("Layered Cache<br/>[layered.rs]")]
  node_steller_cache[("Steller Cache<br/>[mod.rs]")]
  node_resp["RESP Codec<br/>[resp.rs]"]
end

subgraph group_runtime["Runtime Setup"]
  node_config["Configuration<br/>[config.rs]"]
  node_server["Server Bootstrap<br/>[heron.rs]"]
end

node_client(("API Client"))

node_client -->|"requests"| node_routes
node_routes -->|"dispatches"| node_stats_handlers
node_routes -->|"dispatches"| node_health_handlers
node_stats_handlers -.->|"calls"| node_stats_service
node_health_handlers -.->|"calls"| node_health_service
node_stats_handlers -.->|"serializes"| node_json_contracts
node_stats_service -.->|"uses"| node_stats_models
node_stats_service -.->|"fetches stats"| node_github
node_stats_service -.->|"caches results"| node_memory_cache
node_stats_service -.->|"caches results"| node_layered_cache
node_layered_cache -.->|"falls back"| node_steller_cache
node_steller_cache -->|"encodes commands"| node_resp
node_stats_service -.->|"includes calendar"| node_calendar_service
node_calendar_service -.->|"fetches calendar"| node_github
node_calendar_service -.->|"produces"| node_calendar_models
node_counts_service -.->|"requests counts"| node_tarball
node_tarball -->|"measures archive"| node_measure
node_counts_service -.->|"produces"| node_counts_models
node_server -.->|"loads settings"| node_config
node_server -.->|"starts"| node_http_server
node_http_server -->|"serves"| node_routes

click node_routes "https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/routes.rs"
click node_stats_handlers "https://github.com/scadoshi/heron/tree/main/src/lib/inbound/http/handlers/stats"
click node_health_handlers "https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/handlers/health.rs"
click node_json_contracts "https://github.com/scadoshi/heron/tree/main/src/lib/inbound/http/contracts"
click node_middleware "https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/middleware.rs"
click node_stats_service "https://github.com/scadoshi/heron/blob/main/src/lib/domain/stats/services.rs"
click node_stats_models "https://github.com/scadoshi/heron/tree/main/src/lib/domain/stats/models"
click node_calendar_service "https://github.com/scadoshi/heron/blob/main/src/lib/domain/calendar/services.rs"
click node_calendar_models "https://github.com/scadoshi/heron/blob/main/src/lib/domain/calendar/models.rs"
click node_counts_service "https://github.com/scadoshi/heron/blob/main/src/lib/domain/counts/services.rs"
click node_counts_models "https://github.com/scadoshi/heron/blob/main/src/lib/domain/counts/models.rs"
click node_health_service "https://github.com/scadoshi/heron/blob/main/src/lib/domain/health/services.rs"
click node_github "https://github.com/scadoshi/heron/blob/main/src/lib/outbound/github/mod.rs"
click node_tarball "https://github.com/scadoshi/heron/blob/main/src/lib/outbound/tarball/mod.rs"
click node_measure "https://github.com/scadoshi/heron/blob/main/measure/src/lib.rs"
click node_memory_cache "https://github.com/scadoshi/heron/blob/main/src/lib/outbound/cache/memory.rs"
click node_layered_cache "https://github.com/scadoshi/heron/blob/main/src/lib/outbound/cache/layered.rs"
click node_steller_cache "https://github.com/scadoshi/heron/blob/main/src/lib/outbound/cache/steller/mod.rs"
click node_resp "https://github.com/scadoshi/heron/blob/main/src/lib/outbound/cache/steller/resp.rs"
click node_config "https://github.com/scadoshi/heron/blob/main/src/lib/config.rs"
click node_server "https://github.com/scadoshi/heron/blob/main/src/bin/heron.rs"
click node_http_server "https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/mod.rs"

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_routes,node_stats_handlers,node_health_handlers,node_json_contracts,node_middleware,node_http_server,node_client toneBlue
class node_stats_service,node_stats_models,node_calendar_service,node_calendar_models,node_counts_service,node_counts_models,node_health_service toneAmber
class node_github,node_tarball,node_measure,node_memory_cache,node_layered_cache,node_steller_cache,node_resp toneMint
class node_config,node_server toneRose
```

## Components

### HTTP API

- [HTTP Routes](https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/routes.rs): `src/lib/inbound/http/routes.rs`
- [Stats Handlers](https://github.com/scadoshi/heron/tree/main/src/lib/inbound/http/handlers/stats): `src/lib/inbound/http/handlers/stats`
- [Health Handlers](https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/handlers/health.rs): `src/lib/inbound/http/handlers/health.rs`
- [JSON Contracts](https://github.com/scadoshi/heron/tree/main/src/lib/inbound/http/contracts): `src/lib/inbound/http/contracts`
- [HTTP Middleware](https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/middleware.rs): `src/lib/inbound/http/middleware.rs`
- [HTTP Server](https://github.com/scadoshi/heron/blob/main/src/lib/inbound/http/mod.rs): `src/lib/inbound/http/mod.rs`

### Domain Services

- [Stats Service](https://github.com/scadoshi/heron/blob/main/src/lib/domain/stats/services.rs): `src/lib/domain/stats/services.rs`
- [Stats Models](https://github.com/scadoshi/heron/tree/main/src/lib/domain/stats/models): `src/lib/domain/stats/models`
- [Calendar Service](https://github.com/scadoshi/heron/blob/main/src/lib/domain/calendar/services.rs): `src/lib/domain/calendar/services.rs`
- [Calendar Models](https://github.com/scadoshi/heron/blob/main/src/lib/domain/calendar/models.rs): `src/lib/domain/calendar/models.rs`
- [Counts Sweep](https://github.com/scadoshi/heron/blob/main/src/lib/domain/counts/services.rs): `src/lib/domain/counts/services.rs`
- [Counts Models](https://github.com/scadoshi/heron/blob/main/src/lib/domain/counts/models.rs): `src/lib/domain/counts/models.rs`
- [Cache Health](https://github.com/scadoshi/heron/blob/main/src/lib/domain/health/services.rs): `src/lib/domain/health/services.rs`

### Outbound Adapters

- [GitHub API](https://github.com/scadoshi/heron/blob/main/src/lib/outbound/github/mod.rs): `src/lib/outbound/github/mod.rs`
- [Tarball Source](https://github.com/scadoshi/heron/blob/main/src/lib/outbound/tarball/mod.rs): `src/lib/outbound/tarball/mod.rs`
- [Source Measurement](https://github.com/scadoshi/heron/blob/main/measure/src/lib.rs): `measure/src/lib.rs`
- [Memory Cache](https://github.com/scadoshi/heron/blob/main/src/lib/outbound/cache/memory.rs): `src/lib/outbound/cache/memory.rs`
- [Layered Cache](https://github.com/scadoshi/heron/blob/main/src/lib/outbound/cache/layered.rs): `src/lib/outbound/cache/layered.rs`
- [Steller Cache](https://github.com/scadoshi/heron/blob/main/src/lib/outbound/cache/steller/mod.rs): `src/lib/outbound/cache/steller/mod.rs`
- [RESP Codec](https://github.com/scadoshi/heron/blob/main/src/lib/outbound/cache/steller/resp.rs): `src/lib/outbound/cache/steller/resp.rs`

### Runtime Setup

- [Configuration](https://github.com/scadoshi/heron/blob/main/src/lib/config.rs): `src/lib/config.rs`
- [Server Bootstrap](https://github.com/scadoshi/heron/blob/main/src/bin/heron.rs): `src/bin/heron.rs`

### Other components

- **API Client**

## Connections

- API Client → HTTP Routes: requests (evidence: `README.md`)
- HTTP Routes → Stats Handlers: dispatches (evidence: `src/lib/inbound/http/routes.rs`)
- HTTP Routes → Health Handlers: dispatches (evidence: `src/lib/inbound/http/routes.rs`)
- Stats Handlers → Stats Service: calls
- Health Handlers → Cache Health: calls
- Stats Handlers → JSON Contracts: serializes
- Stats Service → Stats Models: uses
- Stats Service → GitHub API: fetches stats
- Stats Service → Memory Cache: caches results
- Stats Service → Layered Cache: caches results
- Layered Cache → Steller Cache: falls back
- Steller Cache → RESP Codec: encodes commands (evidence: `src/lib/outbound/cache/steller/mod.rs`)
- Stats Service → Calendar Service: includes calendar
- Calendar Service → GitHub API: fetches calendar
- Calendar Service → Calendar Models: produces
- Counts Sweep → Tarball Source: requests counts
- Tarball Source → Source Measurement: measures archive (evidence: `src/lib/outbound/tarball/mod.rs`)
- Counts Sweep → Counts Models: produces
- Server Bootstrap → Configuration: loads settings
- Server Bootstrap → HTTP Server: starts
- HTTP Server → HTTP Routes: serves (evidence: `src/lib/inbound/http/mod.rs`)
