# Architecture — Gitea Actions CI -kirjasto

> Hub-dokumentti. Komponentit, niiden roolit ja rajapinnat. Yksityiskohtaiset kuvaukset linkitetyissä detail-dokumenteissa.
>
> Tämä dokumentti on **normatiivinen** — se määrittelee mikä on rakennettava. `design-rationale.md` kertoo miksi.

---

## Yleiskuvaus

Kirjasto on kokoelma **Gitea Actions reusable workflow** -tiedostoja, jotka orkestroivat mikropalveluiden build-, testaus-, raportointi-, deployment- ja test flow -prosessit. Projekti käyttää kirjastoa `uses:`-direktiivillä `.gitea/workflows/*.yml`-tiedostossaan ja määrittelee konfigurationsa `ci-flow-values.yaml`-tiedostossa.

Kirjasto on Gitea-spesifi. Se hyödyntää Gitean REST API:a commit-statusraportointiin, workflow-dispatchiin ja run-pollaukseen. Raportit tallennetaan MinIO:hon, josta ne ovat selailtavissa HTML-muodossa.

---

## Komponentit

### Reusable workflowt (4 kpl)

| Workflow | Tiedosto | Rooli |
|----------|----------|-------|
| **Feature flow** | `ci-feature.yml` | Testaa feature-branchin, generoi raportit, raportoi statuksen committiin. Ei buildaa konttia. |
| **Master flow** | `ci-master.yml` | Testaa, buildaa kontin, pushaa rekisteriin, tagittaa commitin, ketjuttaa test flow'n. |
| **Deployment flow** | `deploy.yml` | GitOps-deployment: päivittää YAML-arvoa, committaa, pushaa, raportoi cross-repo-statuksen. |
| **Test flow** | `test.yml` | Vastaanottaa dispatchin, ajaa testit, generoi raportit, raportoi statuksen. |

> Yksityiskohtaiset kuvaukset: [workflows.md](workflows.md)

### Jaetut skriptit

| Skripti | Rooli |
|---------|-------|
| **`report-status.sh`** | POSTaa build-statuksen Gitea `/api/v1/repos/{owner}/{repo}/statuses/{sha}` |
| **`dispatch-workflow.sh`** | Dispatchaa workflow'n toisessa repossa ja pollaa sen valmistumista |
| **`push-reports.sh`** | Puskaa testiraportit MinIO:hon ja generoi URL:n |
| **`tag-commit.sh`** | Tagittaa commitin versiolla Gitea REST API:n kautta |

> Yksityiskohtaiset kuvaukset: [shared-scripts.md](shared-scripts.md)

### Konfiguraatio

| Artefakti | Sijainti | Rooli |
|-----------|----------|-------|
| **`ci-flow-values.yaml`** | Projektin repo | Projektikohtainen konfiguraatio (docker, sonar, deployment, test-flow) |
| **Gitea org secrets** | Gitea organization | Tokenit ja salasanat |
| **Gitea org variables** | Gitea organization | Infra-tason asetukset (MinIO URL, SonarQube URL) |

> Yksityiskohtaiset kuvaukset: [config-model.md](config-model.md)

### Ulkoiset palvelut

| Palvelu | Rooli |
|---------|-------|
| **Gitea REST API** | Commit-statusraportointi, workflow-dispatch, run-pollaus, taggaus |
| **Gitea Packages** | Docker-imagen ja NPM-paketin säilytys |
| **Gitea act runner** | Suorittaa workflowt. Konteista, DinD:stä ja label-järjestelmästä: [runner.md](runner.md) |
| **MinIO** | Testiraporttien tallennus ja staattinen web-hosting |
| **SonarQube** | Koodin laadun analyysi ja quality gate |

---

## Järjestelmäkaavio

```mermaid
%%{init: {'theme': 'base', 'flowchart': {'arrowheadScale': 2}}}%%
flowchart TB
    subgraph PROJ["Projektin repo"]
        WF[".gitea/workflows/ci.yml
        uses: gitea-ci-library/ci-master@v1"]
        CONF["ci-flow-values.yaml"]
    end

    subgraph LIB["gitea-ci-library (reusable workflowt)"]
        FEATURE["ci-feature.yml"]
        MASTER["ci-master.yml"]
        DEPLOY["deploy.yml"]
        TEST["test.yml"]
    end

    subgraph SCRIPTS["Jaetut skriptit"]
        REPORT["report-status.sh"]
        DISPATCH["dispatch-workflow.sh"]
        PUSHREP["push-reports.sh"]
        TAG["tag-commit.sh"]
    end

    subgraph EXT["Ulkoiset palvelut"]
        GITEA["Gitea API
        + Packages"]
        MINIO["MinIO
        (S3 + static web)"]
        SONAR["SonarQube"]
    end

    subgraph HELM["Helm-repo"]
        VALUES["values-{env}.yaml"]
    end

    subgraph TESTREPO["Testi-repo"]
        TESTWF[".gitea/workflows/test.yml"]
    end

    WF -- "kutsuu" --> MASTER
    WF -- "lukee" --> CONF
    MASTER -- "käyttää" --> SCRIPTS
    DEPLOY -- "käyttää" --> SCRIPTS
    TEST -- "käyttää" --> SCRIPTS
    REPORT -- "POST status" --> GITEA
    DISPATCH -- "dispatch + poll" --> GITEA
    PUSHREP -- "S3 upload" --> MINIO
    TAG -- "POST tag" --> GITEA
    MASTER -- "quality gate" --> SONAR
    DEPLOY -- "muokkaa" --> VALUES
    DEPLOY -- "commit + push" --> HELM
    DISPATCH -- "dispatch" --> TESTWF
    TESTWF -- "raportoi" --> GITEA
    MINIO -- "URL commit-statusviestiin" --> GITEA

    style PROJ fill:#1e3a5f,color:#f9fafb,stroke:#64748b
    style LIB fill:#1f2937,color:#f9fafb,stroke:#64748b
    style SCRIPTS fill:#064e3b,color:#f9fafb,stroke:#64748b
    style EXT fill:#5c1a1a,color:#f9fafb,stroke:#64748b
    style HELM fill:#4a1a6b,color:#f9fafb,stroke:#64748b
    style TESTREPO fill:#4a1a6b,color:#f9fafb,stroke:#64748b
    style WF fill:#2563eb,color:#ffffff
    style CONF fill:#f59e0b,color:#111827
    style FEATURE fill:#2563eb,color:#ffffff
    style MASTER fill:#2563eb,color:#ffffff
    style DEPLOY fill:#2563eb,color:#ffffff
    style TEST fill:#2563eb,color:#ffffff
    style REPORT fill:#059669,color:#ffffff
    style DISPATCH fill:#059669,color:#ffffff
    style PUSHREP fill:#059669,color:#ffffff
    style TAG fill:#059669,color:#ffffff
    style GITEA fill:#dc2626,color:#ffffff
    style MINIO fill:#dc2626,color:#ffffff
    style SONAR fill:#dc2626,color:#ffffff
    style VALUES fill:#9333ea,color:#ffffff
    style TESTWF fill:#9333ea,color:#ffffff
    linkStyle default stroke:#9ca3af,stroke-width:3px
```

---

## Tietovuot

### 1. Commit-statusraportointi

```
Workflow-steppi → report-status.sh → POST Gitea API → commitin status päivittyy
                                                    ↘ URL → raporttiin / buildiin
```

Jokainen vaihe (test, build, push) POSTaa oman statusviestinsä uniikilla `key`-arvolla. Samaan committiin kertyy useita rinnakkaisia statuksia.

### 2. Cross-repo traceability

```
Mikropalvelu (root-build)  →  Helm (deployment)  →  Testi (integraatio)
       ↓                           ↓                       ↓
  Status omaan committiin    Status omaan committiin  Status omaan committiin
       ↑                           ↑                       ↑
  Status root-committiin ←  Status root-committiin ←  Status root-committiin
  (deployattu, testattu)   (mistä kontti tuli)       (mitä testattiin)
```

Root-build-viite kulkee `workflow_dispatch`in `inputs`-parametrina koko ketjun läpi.

### 3. Raporttien URL-generointi

```
push-reports.sh → mc cp ./reports/ minio/bucket/{repo}/{commit_short}/{report}/
                → URL = {MINIO_BASE}/{repo}/{commit_short}/{report}/index.html
                → report-status.sh POSTaa URL:n commit-statusviestiin
```

### 4. Test flow -ketjutus

```
ci-master.yml → test-flow-taulukko (ci-flow-values.yaml)
              → for each step:
                  dispatch-workflow.sh {test-repo} {inputs}
                  poll Gitea API run status
                  success? → next step
                  failure? → stop
```

---

## Laajennuspisteet

| Piste | Mekanismi | Tila |
|-------|-----------|------|
| **Docker-rekisterit** | Factory/adapter — `ci-flow-values.yaml` → `docker.type` → valitsee pusherin | MVP: Gitea Packages. Artifactory, Nexus myöhemmin |
| **Testikehykset** | `push-reports.sh` tukee mitä tahansa hakemistoa → MinIO | Cucumber, JUnit, JaCoCo, Maven Site, custom |
| **Build-ekosysteemit** | Workflow'n `container:` määrittelee projektin itse | Maven, Gradle, npm, mikä tahansa |
| **SonarQube** | Rajapinta vaihdettavissa — parempi kuin pollaus tutkitaan | Quality gate -tarkistus |

---

## Top-level rajoitteet

- Kaikki integraatio Gitea REST API:n kautta — ei suoria tietokantakytkentöjä, ei jaettua filesysteemiä
- Workflowt eivät jaa tilaa keskenään paitsi `workflow_dispatch`in `inputs`-parametrien kautta
- Raporttien URL on deterministinen: `{MINIO_BASE}/{repo_slug}/{commit_short}/{report}/`
- Cross-repo-statusraportoinnissa root-build on aina se mikropalvelun commit, josta ketju käynnistyi

## Repo-jako

| Repo | Sisältö |
|------|---------|
| **`gitea-ci-library`** | Reusable workflowt, jaetut skriptit, `report-service/`-moduuli (raporttiskriptit, retention CronJob, index.html-generointi) |
| **Deployment / infra -repo** (olemassa oleva) | MinIO Kubernetes-manifestit, Traefik OIDC middleware, ConfigMap, ingress |

`gitea-ci-library/report-service/` on oma moduulinsa samassa repossa — ei erillistä repositoriota, mutta selkeä sisäinen raja workflow-skriptien ja raporttipalvelun koodin välillä. Moduuli sisältää `docs/`-hakemiston deploy-esimerkeillä, mutta varsinainen deployment hoidetaan GitOps/Helm-repon kautta kuten muutkin palvelut.