gitea-dashboard/docs/technical/ARCHITECTURE.md

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)