Architecture générale

Cette section présente l’architecture logique d’Aquila dans sa version GOV + PRO V1.

Vue d’ensemble

Aquila se compose des éléments suivants :

• API Aquila (FastAPI / Python) :
• endpoints de santé et de version ;
• endpoints de gouvernance GOV ;
• endpoints PRO (décision, historique, statistiques).
• Stockage :
• SQLite ou PostgreSQL pour l’édition PRO (historique, dernier état) ;
• fichiers de configuration pour la politique globale et les projets.
• Proxy HTTPS (facultatif mais recommandé) :
• Caddy, NGINX ou équivalent pour terminer TLS et exposer l’API Aquila en HTTPS.
• Intégration CI/CD :
• GitHub Actions (ou autre orchestrateur) appelant l’API Aquila en début de pipeline.

Runner CI/CD   --->   Aquila API (GOV/PRO)   --->   Base de données (PRO)
     |                        |
     +---- logs / métriques --+

Flux principaux

1. Vérification de santé

2. Le pipeline ou les outils de supervision appellent /health pour vérifier que l’agent est disponible.

3. Décision de gouvernance (PRO)

4. Un job de garde (“guard job”) appelle /agent/publish avec le contexte (référentiel, branche, pipeline, etc.).

5. Aquila PRO évalue la demande selon les règles configurées et répond accepted ou refused.

6. Historisation

7. Chaque demande traitée par l’agent PRO est stockée dans une table d’historique.

8. Une vue “dernier état” permet de récupérer rapidement le statut récent d’un couple projet / pipeline / branche.

9. Observabilité

10. Des métriques sont exposées via /metrics au format Prometheus.
11. Les logs structurés permettent de reconstituer le détail des décisions.

Déploiement de référence

• 1 VM Linux ou 1 cluster de containers (Docker / Kubernetes).
• 1 reverse proxy HTTPS (Caddy, NGINX, Traefik, …).
• Base SQLite (petits environnements) ou PostgreSQL (production, multi‑équipes).
• Runners CI/CD autorisés à joindre l’API Aquila (firewall / ACL ajustés).

L’architecture détaillée pour la partie PRO est décrite dans pro/overview.md et pro/packaging.md.