How arc42/status.arc42.org-site works
Project Overview
• It’s a mono‐repo comprised of three top‐level parts:
1. A static Jekyll site (/docs) deployed to GitHub Pages.
2. An arc42 documentation pipeline (/documentation) that produces the technical docs.
3. A statistic service in Go (/go-app) hosted on Fly.io.
Main Components
• Static Site (Jekyll)
• Source: /docs
• Build & Deploy: GitHub Actions → GitHub Pages
• Delivers status pages, badges, and static assets.
• Documentation Pipeline
• Source: /documentation (Asciidoctor, docToolchain)
• Generates arc42 architecture docs and ADRs.
• Statistic Service (Go-app)
• Entry point: main.go
• API Gateway: internal/api (serves HTML templates, JSON)
• Domain Layer: internal/domain
• Badge Service: internal/badge
• Database Layer: internal/database (TursoDB via Atlas HCL)
• Integrations:
– Plausible Analytics (internal/plausible)
– GitHub GraphQL (internal/github)
– Slack Notifications (internal/slack)
• Utilities & Commands: CLI under go-app/cmd (caching, badge downloads, DB migrations, etc.)
• Config & Env: internal/env, .fly.toml, environment variables for secrets.
External Services & Infrastructure
• Plausible Analytics API (fetch usage data)
• GitHub GraphQL API (fetch repo stats)
• Slack API (post alerts)
• TursoDB (cloud SQL database)
• Fly.io (hosting for Go‐app)
• GitHub Pages (hosting for the Jekyll site)
• GitHub Actions (CI/CD for both site and go‐app)
Relationships & Data Flows
• Static Site
– Pulls badge SVGs from the Go‐app API.
– Updated via CI; serves to end users (browsers).
• Go‐app Service
1. Scheduler or On‐Demand → triggers data‐collection routines.
2. Plausible & GitHub → fetch stats → processed by domain logic.
3. Database → persistent store for historical metrics and cache metadata.
4. Badge Generator → creates SVG badges on‐the‐fly.
5. API Gateway → serves HTML/JSON endpoints (templates under internal/api/*.gohtml).
6. Slack Notifier → error or milestone alerts.
Architectural Patterns & Principles
• Layered Architecture: API → Domain → Persistence → External Interfaces.
• Hexagonal / Ports & Adapters: each external service is an adapter under internal/plausible, internal/github, internal/slack.
• CI/CD Pipelines: isolated workflows for static site (pages-build-deployment) and Go service (fly.yml + linting).
Deployment Views
• GitHub Actions: show two pipelines—one for /docs → GitHub Pages, one for /go-app → Fly.io.
• GitHub Pages: static bucket / CDN for Jekyll site.
• Static Site (Jekyll)
• Documentation Pipeline (arc42 docs)
• Go‐app Service (runtime)
d. On the side, show CI/CD workflows linking to their respective hosting targets.