<!-- Type: reference (Diataxis). Style: factuel, exhaustif, structure par le code. Pas de tutoriel ici. -->

# Architecture — gitea-dashboard

## Vue d'ensemble

```
                         gitea-dashboard
                         ==============

  Terminal                    Application                     Gitea API
  --------                    -----------                     ---------

                      +------------------+
  $ gitea-dashboard   |     cli.py       |
  ------------------->| - lit env vars   |
                      | - configure      |
                      | - gere erreurs   |
                      +--------+---------+
                               |
                               v
                      +------------------+
                      |  collector.py    |
                      | - orchestre la   |
                      |   collecte       |     +------------------+
                      | - agrege en      |---->|   client.py      |
                      |   RepoData       |     | - auth token     |-----> GET /api/v1/user/repos
                      +--------+---------+     | - pagination     |-----> GET /repos/{o}/{r}/releases/latest
                               |               | - erreurs HTTP   |-----> GET /repos/{o}/{r}/milestones
                               v               +------------------+
                      +------------------+
                      |   display.py     |
                      | - tableau repos  |
  <-------------------| - milestones     |
  Output Rich         | - indicateurs    |
  (tableaux,          +------------------+
   couleurs)
```

## Composants

### cli.py — Point d'entree

Responsabilite : orchestration du flux principal.

- Lit les variables d'environnement `GITEA_URL` (defaut: `http://192.168.0.106:3000`) et `GITEA_TOKEN` (requis)
- Valide la configuration, affiche un message d'erreur clair si manquante
- Cree le `GiteaClient`, lance la collecte, passe les resultats a l'affichage
- Gere les erreurs globales (connexion refusee, timeout, erreurs API)
- Enregistre comme entry point : `gitea-dashboard = "gitea_dashboard.cli:main"`

### client.py — Client API Gitea

Responsabilite : communication avec l'API REST Gitea.

- Authentification via header `Authorization: token <GITEA_TOKEN>`
- Methode interne `_get_paginated()` pour la pagination transparente (limit=50, boucle tant que page pleine)
- Methodes publiques : `get_repos()`, `get_latest_release(owner, repo)`, `get_milestones(owner, repo)`
- Gestion du 404 sur `/releases/latest` (retourne `None`)
- Utilise `requests.Session` pour reutiliser les connexions HTTP

### collector.py — Collecteur de donnees

Responsabilite : agregation des donnees de tous les repos.

- Definit le dataclass `RepoData` qui normalise les donnees d'un repo
- Calcul des issues ouvertes reelles : `open_issues_count - open_pr_counter`
- Pour chaque repo : enrichit avec la derniere release et les milestones ouvertes
- Fonction principale `collect_all(client) -> list[RepoData]`

### display.py — Affichage Rich

Responsabilite : formatage et rendu terminal.

- Tableau principal : nom du repo, indicateurs visuels ([F]ork, [A]rchive, [M]irror), issues ouvertes, derniere release (tag + date)
- Section milestones : affichee uniquement pour les repos ayant des milestones ouvertes, avec progression (closed/total)
- Accepte un parametre `Console` optionnel pour l'injection dans les tests
- Fonction principale `render_dashboard(repos, console=None)`

## Structure du projet

```
gitea-dashboard/
  CLAUDE.md                          # Instructions projet
  pyproject.toml                     # Config build, deps, entry point
  README.md                          # Documentation utilisateur
  src/
    gitea_dashboard/
      __init__.py                    # Docstring du package
      cli.py                         # Point d'entree, config, orchestration
      client.py                      # Client API Gitea (auth, pagination)
      collector.py                   # Agregation des donnees repos
      display.py                     # Formatage Rich (tableaux, couleurs)
  tests/
    __init__.py
    test_client.py                   # Tests client API (mocks requests)
    test_collector.py                # Tests collecteur (mocks client)
    test_display.py                  # Tests affichage (capture console)
    test_cli.py                      # Tests integration CLI (mocks env)
  docs/
    plans/
      v1.0.0-plan.md                # Plan de version
    technical/
      ARCHITECTURE.md                # Ce fichier
      decisions.md                   # ADR
      research.md                    # Recherche technique API
    discovery/
      synthesis.md                   # Synthese discovery
    project/
      descriptif.md                  # Descriptif du projet
```

## Flux de donnees principal

```
1. cli.main()
   |
   +-- Lit os.environ["GITEA_TOKEN"] et os.environ.get("GITEA_URL", default)
   |
   +-- GiteaClient(url, token)
   |
   +-- collect_all(client)
   |     |
   |     +-- client.get_repos()           -> list[dict]  (pagine)
   |     |
   |     +-- Pour chaque repo:
   |           +-- client.get_latest_release(owner, name) -> dict | None
   |           +-- client.get_milestones(owner, name)     -> list[dict]
   |           +-- RepoData(...)
   |
   +-- render_dashboard(repos)
         |
         +-- Rich Table (repos)
         +-- Rich Table (milestones)
         +-- Console.print()
```

## Decisions architecturales

Les decisions sont tracees dans `docs/technical/decisions.md` (format ADR).

Decisions cles pour v1.0.0 :
- **ADR-001** : Stack Python + requests + rich
- **ADR-002** : 4 modules maximum (client, collector, display, cli)
- **ADR-003** : Pas de parallelisation en v1 (sequentiel, plus simple a deboguer)