# arc42/status.arc42.org-site architecture

> Architecture diagram of the GitHub repository arc42/status.arc42.org-site, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arc42/status.arc42.org-site
- Repository: https://github.com/arc42/status.arc42.org-site

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TB
  %% Static Site Layer
  subgraph "Static Site (Jekyll)" 
    direction TB
    SS_docs["docs/"]:::frontend
    SS_config["_config.yml"]:::frontend
    SS_layouts["_layouts/"]:::frontend
    SS_includes["_includes/"]:::frontend
    SS_pages["_pages/"]:::frontend
    SS_assets["assets/"]:::frontend
    SS_docker["Dockerfile"]:::frontend
    SS_docs --> SS_config
    SS_docs --> SS_layouts
    SS_docs --> SS_includes
    SS_docs --> SS_pages
    SS_docs --> SS_assets
    SS_docs --> SS_docker
  end

  %% Documentation Pipeline Layer
  subgraph "Documentation Pipeline (arc42)" 
    direction TB
    DP_docs["documentation/"]:::docs
    DP_adrs["adrs/"]:::docs
    DP_arc42["arc42/"]:::docs
    DP_images["images/ & 0-repo-overview.drawio"]:::docs
    DP_toolchain["docToolchainConfig.groovy"]:::docs
    DP_docs --> DP_adrs
    DP_docs --> DP_arc42
    DP_docs --> DP_images
    DP_docs --> DP_toolchain
  end

  %% Go-app Service Layer
  subgraph "Go-app Service (runtime)"
    direction TB
    GA_entry["main.go"]:::backend

    subgraph "Layers"
      direction TB
      GA_api["API Gateway"]:::backend
      GA_domain["Domain Layer"]:::backend
      GA_persistence["Database Layer"]:::backend
      GA_badge["Badge Service"]:::backend
      GA_env["Env Config"]:::backend
      GA_flyhost["Fly.io Helper"]:::backend
      GA_api --> GA_domain
      GA_domain --> GA_persistence
      GA_domain --> GA_badge
      GA_domain --> GA_env
      GA_domain --> GA_flyhost
    end

    subgraph "External Adapters"
      direction TB
      AD_plausible["Plausible Adapter"]:::external
      AD_github["GitHub Adapter"]:::external
      AD_slack["Slack Adapter"]:::external
      GA_persistence --- AD_plausible
      GA_persistence --- AD_github
      GA_persistence --- AD_slack
      AD_plausible --- DB
      AD_github --- DB
      AD_slack --- DB
    end

    subgraph "Utilities & Commands"
      direction TB
      CMD["go-app/cmd/"]:::backend
      CMD_cache["tryCaching.go"]:::backend
      CMD_download["downloadBadgeSVGs"]:::backend
      CMD_gqlcmd["githubGraphQL"]:::backend
      CMD_slackcmd["trySlackMessage.go"]:::backend
      CMD_turso["tursoDB/"]:::backend
      CMD --> CMD_cache
      CMD --> CMD_download
      CMD --> CMD_gqlcmd
      CMD --> CMD_slackcmd
      CMD --> CMD_turso
    end

    GA_entry --> GA_api
    GA_entry --> CMD
  end

  %% Database
  DB["TursoDB"]:::infra

  %% External Services
  Plausible["Plausible Analytics API"]:::external
  GitHubAPI["GitHub GraphQL API"]:::external
  SlackAPI["Slack API"]:::external

  %% Hosting & CI/CD
  GH_Actions["GitHub Actions"]:::infra
  Pages["GitHub Pages"]:::infra
  FlyIO["Fly.io"]:::infra
  EndUser["End User (Browser)"]:::external

  %% Flows
  EndUser --> Pages
  Pages -->|serves static site| EndUser
  SS_docs -->|CI build| GH_Actions
  GH_Actions -->|deploy docs| Pages
  GA_api -->|serves badges| SS_docs
  GA_api -->|HTTP/JSON| EndUser
  GH_Actions -->|deploy go-app| FlyIO
  FlyIO -->/--> GA_entry
  GA_api -->|fetch stats| AD_plausible
  GA_api -->|fetch stats| AD_github
  GA_api -->|notifications| AD_slack
  AD_plausible -->|Analytics data| Plausible
  AD_github -->|GraphQL| GitHubAPI
  AD_slack -->|Post alerts| SlackAPI
  GA_persistence -->|SQL| DB

  %% Click Events
  click SS_docs "https://github.com/arc42/status.arc42.org-site/tree/main/docs/"
  click SS_config "https://github.com/arc42/status.arc42.org-site/blob/main/docs/_config.yml"
  click SS_layouts "https://github.com/arc42/status.arc42.org-site/tree/main/docs/_layouts/"
  click SS_includes "https://github.com/arc42/status.arc42.org-site/tree/main/docs/_includes/"
  click SS_pages "https://github.com/arc42/status.arc42.org-site/tree/main/docs/_pages/"
  click SS_assets "https://github.com/arc42/status.arc42.org-site/tree/main/docs/assets/"
  click SS_docker "https://github.com/arc42/status.arc42.org-site/tree/main/docs/Dockerfile"
  click DP_docs "https://github.com/arc42/status.arc42.org-site/tree/main/documentation/"
  click DP_adrs "https://github.com/arc42/status.arc42.org-site/tree/main/documentation/adrs/"
  click DP_arc42 "https://github.com/arc42/status.arc42.org-site/tree/main/documentation/arc42/"
  click DP_images "https://github.com/arc42/status.arc42.org-site/tree/main/documentation/images/"
  click DP_toolchain "https://github.com/arc42/status.arc42.org-site/blob/main/documentation/docToolchainConfig.groovy"
  click GA_entry "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/main.go"
  click GA_api "https://github.com/arc42/status.arc42.org-site/tree/main/go-app/internal/api/"
  click GA_domain "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/internal/domain/domain.go"
  click GA_badge "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/internal/badge/badges.go"
  click GA_persistence "https://github.com/arc42/status.arc42.org-site/tree/main/go-app/internal/database/"
  click AD_plausible "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/internal/plausible/vpvStatistics.go"
  click AD_github "https://github.com/arc42/status.arc42.org-site/tree/main/go-app/internal/github/"
  click AD_slack "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/internal/slack/slack.go"
  click GA_env "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/internal/env/environment.go"
  click GA_flyhost "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/internal/fly/flyHosting.go"
  click CMD "https://github.com/arc42/status.arc42.org-site/tree/main/go-app/cmd/"
  click CMD_cache "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/cmd/cache/tryCaching.go"
  click CMD_download "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/cmd/downloadBadgeSVGs/main.go"
  click CMD_gqlcmd "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/cmd/githubGraphQL/main.go"
  click CMD_slackcmd "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/cmd/slack/trySlackMessage.go"
  click CMD_turso "https://github.com/arc42/status.arc42.org-site/tree/main/go-app/cmd/tursoDB/"
  click GH_Actions "https://github.com/arc42/status.arc42.org-site/tree/main/.github/workflows/"
  click FlyIO "https://github.com/arc42/status.arc42.org-site/blob/main/go-app/fly.toml"

  %% Styles
  classDef frontend fill:#cce5ff,stroke:#004085,color:#004085
  classDef docs fill:#d4edda,stroke:#155724,color:#155724
  classDef backend fill:#fff3cd,stroke:#856404,color:#856404
  classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
  classDef infra fill:#f8f9fa,stroke:#343a40,color:#343a40
```
