Architecture de la plateforme
Version anglaise : en/ARCHITECTURE.md. Architecture antérieure : overview.md, overview.html.
Chaque élément cite un chemin vérifié dans le dépôt. Le code du Control Plane est sous services/control-plane/src/eai/ (abrégé eai/).
Diagrammes
- diagrams/planes.html : les dix plans et leurs liens principaux.
- diagrams/agent-run.html : une exécution d'agent avec contexte signé, délégation et audit.
- diagrams/kill-switch.html : cycle de confinement du Kill Switch (observed_state).
- diagrams/roadmap.html : dépendances des lots L0 à L10.
- diagrams/infrastructure-manager.html : Platform Manager, Management Gateway, agents et stockage de sauvegarde du client.
Sources JSON :
diagrams/src/.
Les dix plans (kit section 2.1)
| Plan | Code | Intégrations et déploiement |
|---|---|---|
| Experience | portal/ (Next.js), navin-manager/ui/ (Vite) | portal/src/locales, docs/ |
| Platform Management | navin-manager/server, agent-go, operator, catalog, packaging | catalog/components (ManagedComponent), release/ |
| Identity/Governance/Policy | domains/identity, authz, context, delegation, policies, approvals, governance | deploy/keycloak, deploy/spire, deploy/policies/opa, deploy/policies/openfga |
| Agent Execution | domains/agents, mcp, tools, sdks/python/src/enterprise_ai/loop et runtime | integrations/nats.py, temporal.py, sandbox.py, deploy/apisix |
| Model | domains/llm, finops | deploy/litellm, integrations/litellm.py, vllm.py |
| Data/Privacy | domains/knowledge, privacy, storage, lineage, retention ; sql/postgres | eai/storage (S3, Azure, GCS), integrations/qdrant.py, presidio.py, docling.py, ocr.py |
| Multimodal | domains/multimodal, realtime ; media_worker.py | deploy/livekit, tools/multimodal |
| Observability/Audit/SOC | eai/audit.py, domains/evidence, soc, incidents, observability | deploy/observability (opik, opensearch, jaeger, prometheus, alertmanager, otel-collector), deploy/runtime-security |
| Infrastructure/DevSecOps | deploy/helm, gitops, argocd, cilium, keda, cert-manager, velero, terraform, policies/kyverno | deploy/ci, .forgejo/workflows/ci.yml, .gitlab-ci.yml |
| Commercial | domains/licensing, tools/license-issuer | release/lock-manifest.json, release/sbom |
Flux
- Requête : client ou portail -> API Gateway APISIX (
deploy/apisix) -> Control Plane (python -m eai.main) -> authentification (eai/auth.py), tenant tiré de l'identifiant d'accès, transactiondb.tx(principal)sous RLS. - Décision de politique :
eai/policy.pyetintegrations/opa.py(OPA),require_relationviaintegrations/openfga.py; puis/v1/delegations/authorizecalcule l'intersection utilisateur, agent, délégation (domains/delegation/runtime.py). Défaut : refus. - Modèle : Model Gateway
/v1/gateway/*(domains/llm/gateway.py) -> LiteLLM -> vLLM local ou fournisseur approuvé ; quota réservé avant l'appel (domains/finops/reservation.py). - Audit : chaque mutation écrit un événement chaîné (
eai/audit.py), outbox et scellés (V150, V151), preuves (domains/evidence). - Séparation des trois flux (kit section 11) : télémétrie OTel échantillonnable (
eai/tracing.py, Opik, Jaeger, Prometheus) ; événements de sécuritésecurity.*écrits dans leur propre transaction (eai/security, OpenSearch SIEM) ; audit critique non échantillonné dans PostgreSQL. - Release : manifestes de
catalog/components,release/lock-manifest.json, SBOMrelease/sbom(tools/components/sbom.sh), bundle hors lignenavin-manager/packaging/offline/build-bundle.pyetverify-bundle.py, déploiement GitOps Argo CD (deploy/gitops/<env>).
Frontières de confiance
- Navigateur vers API : le frontend n'est jamais source d'autorisation, toutes les routes sont vérifiées au backend.
- Tenant vers tenant : RLS forcée (ADR-0106).
- Plateforme vers Internet : seul
eai.security.egresssort (ADR-0121). - Manager vers hôtes : l'agent ouvre les connexions, mTLS + HMAC (ADR-0119).
- Contenu non fiable (RAG, outils, MCP, mémoire) : détection d'injection et encapsulation.
- Secrets : OpenBao ou coffre client, jamais dans le dépôt, les journaux ou les traces (ADR-0112).
Interdictions de conception (kit section 2.2) et leur mise en application
| Interdiction | Où elle est appliquée |
|---|---|
| Builder drag-and-drop comme cœur | développement code-first : SDK sdks/, CLI, packs packs/ ; le portail ne rend que des graphes de topologie (portal/tests/topology.test.ts) |
| Framework étranger imposé à Navin | ADR-0102, sdks/python/src/enterprise_ai/runtime/ (adaptateurs optionnels) |
| Appel LLM direct | ADR-0104, domains/llm/gateway.py, domains/llm/embedder.py |
| Accès non contrôlé MCP, RAG, services sensibles | domains/mcp, domains/knowledge/governance.py, eai/security/egress.py, tests/test_gateway_pep_untrusted.py |
| Credentials en dur ou token brut | credential_ref dans les manifestes, eai/secrets via domains/secrets, CI gitleaks (.forgejo/workflows/ci.yml) |
Gestion des machines, HA, sauvegarde et PRA (addendum 20)
Trois niveaux de contrôle : SSH pour l'installation initiale, agents et opérateur pour l'exploitation, contrôleurs HA, sauvegarde et PRA pour la continuité (diagrams/infrastructure-manager.html).
| Fonction | Où dans le dépôt | Décision |
|---|---|---|
| Bootstrap SSH, préflight, enrôlement, commandes signées | navin-manager/server/src/navin_manager/hosts, infrastructure, agentapi | ADR-0124 |
| Node Agent Go (systemd) | navin-manager/agent-go | ADR-0124, ADR-0119 |
| Cluster Agent et Platform Operator | navin-manager/cluster-agent, navin-manager/operator, navin-manager/server/src/navin_manager/kubernetes | ADR-0124 |
| Propriété, modes de déploiement, placement | navin-manager/server/src/navin_manager/availability | ADR-0125 |
| Groupes HA, baux, fencing, tests de panne | navin-manager/server/src/navin_manager/availability, deploy/helm/enterprise-ai/values-ha.yaml | ADR-0126 |
| Sauvegardes, restaurations, PRA | navin-manager/server/src/navin_manager/backup, recovery, deploy/velero | ADR-0127 |
| Moteur d'opérations du Manager (reprise, tentatives, retour arrière) à la place de Temporal | navin-manager/server/src/navin_manager/engine | ADR-0150 |
| Matrice de compatibilité dans le catalogue signé | navin-manager/catalog, navin-manager/server/src/navin_manager/services/upgrades.py | ADR-0151 |
| Pile frontend du portail (design system, client API généré, composants transversaux) | portal/src/components, portal/src/lib | ADR-0148 |
| Espace Platform Manager du portail : sauvegarde et PRA, centre de configuration, liens profonds | services/control-plane/src/eai/domains/platform_manager, portal/src/screens/platform-manager.tsx | ADR-0162 |
| Test dédié par écran du portail, atelier de plugins | portal/tests/screens-spaces.test.ts, portal/src/screens/studio.tsx | ADR-0163 |
| Bibliothèque Navin (compétences, plugins, commandes, agents, préréglages MCP, canaux) activée par projet, règles de projet | catalog/navin, tools/navin_library/sync.py, services/control-plane/src/eai/domains/navin_library, navin-manager/server/src/navin_manager/api/mcp.py | ADR-0164 |
| Hébergement MCP dans le Navin Manager (service mcp-host) et isolation par projet de la passerelle MCP | navin-manager/mcp-host, navin-manager/catalog/services/mcp-host.yaml, services/control-plane/src/eai/domains/mcp/gateway.py, services/control-plane/src/eai/domains/mcp/hosted.py | ADR-0165 |
| Haute disponibilité déclarée par service dans le catalogue du Manager, contrôles d'installation HA, analyse obligatoire des fichiers par ClamAV et YARA-X avant toute ingestion | navin-manager/catalog/schema/service.schema.json, navin-manager/server/src/navin_manager/services/ha_checks.py, navin-manager/catalog/services/clamav.yaml, navin-manager/catalog/services/yara-x.yaml, services/control-plane/src/eai/domains/file_security | ADR-0166 |
| Runtime MCP : instances MCP isolées par tenant, projet et utilisateur sur le ToolHive Kubernetes Operator, créées à la demande et détruites après usage | services/control-plane/src/eai/domains/mcp_runtime, deploy/toolhive, deploy/policies/kyverno/mcp-runtime.yaml, deploy/cilium/mcp-runtime.yaml | ADR-0167 |
| Aucun MCP en ligne, catalogue MCP de l'entreprise dans SeaweedFS, destruction dès la panne et réveil à l'appel, traçabilité par défaut du Runtime MCP | services/control-plane/src/eai/domains/mcp_runtime/service.py, services/control-plane/src/eai/domains/mcp_runtime/controller.py, services/control-plane/src/eai/domains/mcp_runtime/templates.py, services/control-plane/src/eai/domains/mcp/gateway.py, sql/postgres/V201__mcp_runtime_lifecycle.sql | ADR-0170 |
| Moteurs d'inférence locale vLLM et Ollama gérés derrière LiteLLM | navin-manager/catalog/services/vllm.yaml, navin-manager/catalog/services/ollama.yaml | ADR-0168 |
| Retrait de Perses et d'Infisical OSS : tableaux de bord dans le Navin Manager et le portail, secrets dans OpenBao ou le coffre du client, packs sans tableaux de bord | navin-manager/server/src/navin_manager/services/dashboard.py, services/control-plane/src/eai/domains/platform_manager/config_center.py, sdks/python/src/enterprise_ai/packs | ADR-0169 |
| Installation durcie pour la production bancaire : réseau isolé, Quadlet, profils de sécurité, Trusted Hub, rollback | navin-manager/server/src/navin_manager/catalog/render.py, navin-manager/catalog/templates/_common/ | ADR-0171 |
| Labellisation des données (Label Studio) et affinage des modèles (LLaMA-Factory) dans le catalogue, modèle exporté servi par vLLM derrière LiteLLM | navin-manager/catalog/services/label-studio.yaml, navin-manager/catalog/services/llama-factory.yaml | ADR-0172 |
Résumé borné des spans, objectifs SLO en base (eai.telemetry_spans, eai.service_slos) | services/control-plane/src/eai/domains/observability | ADR-0157 |
Provenance SLSA, portes G6/G9, contenus de pack (eai.marketplace_assets), kill switch, supervision, import hors ligne | services/control-plane/src/eai/domains/marketplace | ADR-0158 |
Pipeline unique de gestion du changement (eai.change_requests) | services/control-plane/src/eai/domains/marketplace/changes.py | ADR-0159 |
| Hiérarchie du tenant (organisations, unités métier), champs communs stampés, identifiant runtime séparé | services/control-plane/src/eai/domains/tenancy, services/control-plane/src/eai/db.py | ADR-0156 |
Index d'audit partitionné par event_time, clés de chaîne eai.audit_event_keys, vue eai.audit_index | sql/postgres/V186__audit_events_partitioned.sql, sql/postgres/V187__audit_index_view.sql | ADR-0154 |
| Plans du worker (audit, SOC, télémétrie), operation_id des opérations longues, compensation des actions externes | services/control-plane/src/eai/worker.py, services/control-plane/src/eai/domains/operations | ADR-0155 |
L'état réel de chaque exigence (HOST, CLUS, HAVA, BACK, DR, INFUI, INFSDK) est dans ../implementation/STATUS.md.
Décisions
Voir ADRs/ et ../implementation/DECISIONS.md.