Platform architecture

French version: ../ARCHITECTURE.md. Earlier architecture: ../overview.en.md, ../overview.html.

Every item cites a path verified in the repository. Control Plane code lives in services/control-plane/src/eai/ (shortened eai/; domains under eai/domains/).

Diagrams

• ../diagrams/planes.html: the ten planes and their main links.
• ../diagrams/agent-run.html: an agent run with signed context, delegation and audit.
• ../diagrams/kill-switch.html: Kill Switch containment lifecycle (observed_state).
• ../diagrams/roadmap.html: dependencies of lots L0 to L10.
• ../diagrams/infrastructure-manager.html: Platform Manager, Management Gateway, agents and the client's backup storage (labels in French). JSON sources: diagrams/src/.

The ten planes (kit section 2.1)

Plane	Code	Integrations and deployment
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 and 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

Flows

1. Request: client or portal -> APISIX API Gateway (deploy/apisix) -> Control Plane (python -m eai.main) -> authentication (eai/auth.py), tenant taken from the credential, db.tx(principal) transaction under RLS.
2. Policy decision: eai/policy.py and integrations/opa.py (OPA), require_relation through integrations/openfga.py; then /v1/delegations/authorize computes the user, agent, delegation intersection (domains/delegation/runtime.py). Default: deny.
3. Model: Model Gateway /v1/gateway/* (domains/llm/gateway.py) -> LiteLLM -> local vLLM or approved provider; quota reserved before the call (domains/finops/reservation.py).
4. Audit: every mutation writes a chained event (eai/audit.py), outbox and seals (V150, V151), evidence (domains/evidence).
5. Three separate flows (kit section 11): sampleable OTel telemetry (eai/tracing.py, Opik, Jaeger, Prometheus); security.* events written in their own transaction (eai/security, OpenSearch SIEM); unsampled critical audit in PostgreSQL.
6. Release: catalog/components manifests, release/lock-manifest.json, release/sbom SBOMs (tools/components/sbom.sh), offline bundle navin-manager/packaging/offline/build-bundle.py and verify-bundle.py, Argo CD GitOps (deploy/gitops/<env>).

Trust boundaries

• Browser to API: the frontend is never an authorization source, every route is checked by the backend.
• Tenant to tenant: forced RLS (ADR-0106).
• Platform to Internet: only eai.security.egress goes out (ADR-0121).
• Manager to hosts: the agent opens connections, mTLS + HMAC (ADR-0119).
• Untrusted content (RAG, tools, MCP, memory): injection detection and wrapping.
• Secrets: OpenBao or client vault, never in the repository, logs or traces (ADR-0112).

Forbidden design choices (kit section 2.2) and enforcement

Forbidden	Where enforced
Drag-and-drop builder as core	code-first development: SDKs sdks/, CLI, packs packs/; the portal only renders topology graphs (portal/tests/topology.test.ts)
Foreign framework imposed on Navin	ADR-0102, sdks/python/src/enterprise_ai/runtime/ (optional adapters)
Direct LLM call	ADR-0104, domains/llm/gateway.py, domains/llm/embedder.py
Uncontrolled MCP, RAG, sensitive service access	domains/mcp, domains/knowledge/governance.py, eai/security/egress.py, tests/test_gateway_pep_untrusted.py
Hard-coded credentials or raw token	credential_ref in manifests, domains/secrets, CI gitleaks (.forgejo/workflows/ci.yml)

Machine management, HA, backup and DR (addendum 20)

Three control levels: SSH for the initial installation, agents and operator for operations, HA, backup and DR controllers for continuity (../diagrams/infrastructure-manager.html).

Function	Where in the repository	Decision
SSH bootstrap, preflight, enrolment, signed commands	navin-manager/server/src/navin_manager/hosts, infrastructure, agentapi	ADR-0124
Go Node Agent (systemd)	navin-manager/agent-go	ADR-0124, ADR-0119
Cluster Agent and Platform Operator	navin-manager/cluster-agent, navin-manager/operator, navin-manager/server/src/navin_manager/kubernetes	ADR-0124
Ownership, deployment modes, placement	navin-manager/server/src/navin_manager/availability	ADR-0125
HA groups, leases, fencing, failure tests	navin-manager/server/src/navin_manager/availability, deploy/helm/enterprise-ai/values-ha.yaml	ADR-0126
Backups, restores, disaster recovery	navin-manager/server/src/navin_manager/backup, recovery, deploy/velero	ADR-0127
Operation engine of the Manager (resume, attempts, rollback) instead of Temporal	navin-manager/server/src/navin_manager/engine	ADR-0150
Compatibility matrix in the signed catalog	navin-manager/catalog, navin-manager/server/src/navin_manager/services/upgrades.py	ADR-0151
Portal frontend stack (design system, generated API client, shared components)	portal/src/components, portal/src/lib	ADR-0148
Portal Platform Manager space: backup and DR, configuration center, deep links	services/control-plane/src/eai/domains/platform_manager, portal/src/screens/platform-manager.tsx	ADR-0162
One dedicated test per portal screen, plugin builder	portal/tests/screens-spaces.test.ts, portal/src/screens/studio.tsx	ADR-0163
Navin library (skills, plugins, commands, agents, MCP presets, channels) activated per project, project rules	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
MCP hosting in the Navin Manager (service mcp-host) and isolation per project of the MCP gateway	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
High availability declared per service in the Manager catalog, HA install checks, mandatory ClamAV and YARA-X file scanning before any 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
MCP Runtime: MCP instances isolated per tenant, project and user on the ToolHive Kubernetes Operator, created on demand and destroyed after use	services/control-plane/src/eai/domains/mcp_runtime, deploy/toolhive, deploy/policies/kyverno/mcp-runtime.yaml, deploy/cilium/mcp-runtime.yaml	ADR-0167
No online MCP server, company MCP catalogue in SeaweedFS, destroyed on failure and woken on call, traceability by default of the MCP Runtime	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
Managed local inference engines vLLM and Ollama behind LiteLLM	navin-manager/catalog/services/vllm.yaml, navin-manager/catalog/services/ollama.yaml	ADR-0168
Perses and Infisical OSS removed: dashboards in the Navin Manager and the portal, secrets in OpenBao or the client vault, packs without dashboards	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
Hardened installation for banking production: isolated network, Quadlet, security profiles, Trusted Hub, rollback	navin-manager/server/src/navin_manager/catalog/render.py, navin-manager/catalog/templates/_common/	ADR-0171
Data labeling (Label Studio) and model fine-tuning (LLaMA-Factory) in the catalog, exported model served by vLLM behind LiteLLM	navin-manager/catalog/services/label-studio.yaml, navin-manager/catalog/services/llama-factory.yaml	ADR-0172
Bounded span summary, SLO objectives in the database (eai.telemetry_spans, eai.service_slos)	services/control-plane/src/eai/domains/observability	ADR-0157
SLSA provenance, G6/G9 gates, pack contents (eai.marketplace_assets), kill switch, supervision, offline import	services/control-plane/src/eai/domains/marketplace	ADR-0158
Single change management pipeline (eai.change_requests)	services/control-plane/src/eai/domains/marketplace/changes.py	ADR-0159
Tenant hierarchy (organizations, business units), stamped common fields, separate runtime login	services/control-plane/src/eai/domains/tenancy, services/control-plane/src/eai/db.py	ADR-0156
Audit index partitioned by event_time, chain keys eai.audit_event_keys, view eai.audit_index	sql/postgres/V186__audit_events_partitioned.sql, sql/postgres/V187__audit_index_view.sql	ADR-0154
Worker planes (audit, SOC, telemetry), operation_id of long operations, compensation of external actions	services/control-plane/src/eai/worker.py, services/control-plane/src/eai/domains/operations	ADR-0155

The real state of each requirement (HOST, CLUS, HAVA, BACK, DR, INFUI, INFSDK) is in ../../implementation/en/STATUS.md.

Decisions

See ../ADRs/ and ../../implementation/en/DECISIONS.md.