# Architecture — git-pages

> Komponentit, datavirrat ja rajapinnat. Miksi näin on rakennettu: [design-rationale.md](design-rationale.md).
> Secretit: [secrets.md](secrets.md). Teknologiat: [tech-stack.md](tech-stack.md).

Tämä dokumentti koskee vain `git-pages/`-palvelua — ei juuren `gitea-ci-library`-kirjastoa.

---

## Yleiskuvaus

git-pages on jaettu **HTML-raporttiarkisto**: yksi apex-host, monta Gitea-repoa, commit-kohtaiset
raporttipolut. Julkaisija (esim. CI) puskaa sisällön tar-arkistona; lukija avaa raportin
selaimella commit-linkistä.

Codeberg git-pages ajaa `PAGES_INSECURE=1` — sovellus ei tee forge-authia. Julkaisu- ja
TLS-rajaukset ovat Kubernetes-kerroksessa (Traefik, cert-manager, Secretit).

---

## Komponentit

| Komponentti | Rooli |
|-------------|-------|
| **git-pages Pod** | Codeberg git-pages `0.9.1`, filesystem-storage `/app/data` |
| **PVC** | Raporttisisältö (`{owner}/{repo}/reports/{sha8}/…`) |
| **Service** | ClusterIP :3000 git-pagesille |
| **Traefik IngressRoute** | Julkaisu (PATCH/PUT + BasicAuth) ja luku (GET/HEAD) eri säännöillä |
| **Traefik Middleware** | `git-pages-publish-auth` (BasicAuth), HTTPS-redirect |
| **cert-manager Certificate** | TLS → Secret `git-pages-tls` |
| **CronJob `git-pages-retention`** | Päivittäinen siivous (PVC + Gitea branch-lista) |

| Secret | Rooli |
|--------|-------|
| `git-pages-publish-auth` | htpasswd julkaisuun (Traefik) |
| `git-pages-retention-gitea` | Gitea PAT branch-listaan (CronJob) |

---

## URL ja sisältö

Julkinen osoite = **selvä URL** + **Gitea-yhteensopiva polku**:

```
https://pages.example.com/acme-corp/backend-api/reports/abc12345/index.html
         └─ selvä URL ─┘ └────────── Gitea-yhteensopiva polku ──────────┘
```

Levyllä (apex index-site):

```
/app/data/
  {owner}/
    {repo}/
      reports/
        {sha8}/
          index.html
          .meta          # branch, sha, published_at
```

Apex-juuri `/` on tyhjä — ei landing-sivua.

---

## Järjestelmäkaavio

```mermaid
flowchart TB
    subgraph ext["Ulkoiset"]
        PUB["Julkaisija\n(CI)"]
        BR["Selain"]
        GITEA["Gitea API\n(branch-lista)"]
    end

    subgraph edge["Reuna"]
        TRAEFIK["Traefik\nIngressRoute + Middleware"]
        CM["cert-manager\nTLS"]
    end

    subgraph cluster["git-pages"]
        GP["git-pages Pod"]
        PVC["PVC /app/data"]
        CJ["CronJob retention"]
    end

    PUB -->|"PATCH/PUT + BasicAuth\ntar"| TRAEFIK
    BR -->|"GET/HEAD"| TRAEFIK
    TRAEFIK --> GP
    CM --> TRAEFIK
    GP --> PVC
    CJ -->|"read branches"| GITEA
    CJ --> PVC
```

---

## Julkaisu

1. Julkaisija paketoi `{owner}/{repo}/reports/{sha8}/` tar-arkistoksi (sis. `.meta`)
2. `PATCH` tai `PUT` apex-URL:iin (`https://{host}/`) + `Content-Type: application/x-tar`
3. Traefik tarkistaa BasicAuth (`publish` + token) → välittää git-pagesille
4. git-pages kirjoittaa PVC:lle

Julkaisu kulkee aina julkisen ingressin kautta — ei suoraa ClusterIP-kirjoitusta ulkopuolelta.

---

## Luku

1. Selain avaa commit-statuslinkin (GET/HEAD)
2. Traefik välittää git-pagesille ilman julkaisu-Middlewarea
3. git-pages palauttaa HTML:n polusta

Luku-auth (OIDC) ei ole toteutettu — GET/HEAD on julkinen, jos URL tunnetaan.
Katso [design-rationale.md — Luku-auth](design-rationale.md#luku-auth).

---

## Retention

CronJob `git-pages-retention` (oletus kerran päivässä):

1. Skaalaa git-pages deployment hetkeksi pois (RWO-PVC)
2. Käy läpi `reports/{sha8}/.meta`
3. **Poistettu branch** — jos `.meta.branch` ei ole Gitean branch-listassa → poista (aina)
4. **Aktiivinen branch** — `maxAgeDays` + `keepMin` (`retention.rules` instanssiarvoissa)
5. Skaalaa deployment takaisin

Gitea API: `GET /api/v1/repos/{owner}/{repo}/branches` — `read:repository` PAT.
Katso [secrets.md](secrets.md).

---

## Rajapinnat

| Suunta | Protokolla | Auth | Kuvaus |
|--------|------------|------|--------|
| Julkaisija → Traefik | HTTPS PATCH/PUT | BasicAuth `publish` | tar → apex site |
| Selain → Traefik | HTTPS GET/HEAD | — (tänään) | HTML-raportti |
| CronJob → Gitea | HTTPS GET | PAT `read:repository` | branch-lista per repo |
| Traefik → git-pages | HTTP :3000 | — | sisäverkko |

git-pages ei käytä Gitea forge-API:a julkaisuun eikä `pages`-branchia.