How scadoshi/heron works
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: stats/services.rs Stats Service · routes.rs HTTP Routes · stats Stats Handlers · calendar/services.rs Calendar Service
Components 23
HTTP API
- HTTP Routes
src/lib/inbound/http/routes.rs - Stats Handlers
src/lib/inbound/http/handlers/stats - Health Handlers
src/lib/inbound/http/handlers/health.rs - JSON Contracts
src/lib/inbound/http/contracts - HTTP Middleware
src/lib/inbound/http/middleware.rs - HTTP Server
src/lib/inbound/http/mod.rs
Domain Services
- Stats Service
src/lib/domain/stats/services.rs - Stats Models
src/lib/domain/stats/models - Calendar Service
src/lib/domain/calendar/services.rs - Calendar Models
src/lib/domain/calendar/models.rs - Counts Sweep
src/lib/domain/counts/services.rs - Counts Models
src/lib/domain/counts/models.rs - Cache Health
src/lib/domain/health/services.rs
Outbound Adapters
- GitHub API
src/lib/outbound/github/mod.rs - Tarball Source
src/lib/outbound/tarball/mod.rs - Source Measurement
measure/src/lib.rs - Memory Cache
src/lib/outbound/cache/memory.rs - Layered Cache
src/lib/outbound/cache/layered.rs - Steller Cache
src/lib/outbound/cache/steller/mod.rs - RESP Codec
src/lib/outbound/cache/steller/resp.rs
Runtime Setup
- Configuration
src/lib/config.rs - Server Bootstrap
src/bin/heron.rs
Other components
- API Client
Connections 21
- API Client → HTTP Routes: requests
README.md - HTTP Routes → Stats Handlers: dispatches
src/lib/inbound/http/routes.rs - HTTP Routes → Health Handlers: dispatches
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
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
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
src/lib/inbound/http/mod.rs