IIO Architecture

1. System Structure: One Engine, Many Adapters

IIO consists of a core — the Governance Engine — and a variety of adapters that enable different ways of working:

• Governance Engine: Policy Decision Points (PDPs), HITL gates, compliance checks, evidence trail
• 5 Adapters:
  • coding — AI coding agents with sandbox and planner-worker-judge
  • flow-runner — declarative workflows from flow.yaml
  • www-publishing — content, websites, living books
  • execution-dispatch — remote operations (SSH, Ansible, stack ops)
  • direct-executor — direct configuration and calculations
• Projection Engine: takes a tenant profile (SME, enterprise, developer partner) and materializes a concrete system state

Result: a tenant with the enterprise profile gets Keycloak, monitoring, dedicated GPU, service topology — automatically. A kmu-standard tenant gets shared GPU, central Keycloak, simpler monitoring.

2. Execution Path: Intent → Policy → Adapter → Evidence

Every action in IIO follows the same path — whether coding, deployment, content publishing, or infrastructure operations:

graph TD
    A["Operator/Agent
states intent"] -->|"Deploy Keycloak"| B["Policy Decision Point
aggregates 5 sources"]
    B -->|"Context: server,
sensitivity, budget"| CPDP<br/>decision?
    C -->|AUTO| D["Adapter
auto-exec"]
    C -->|HITL| E["Open gate
operator waits"]
    C -->|BLOCK| F["Stop action
documented"]
    E -->|"approved"| D
    D -->|"coding"| G1["Sandbox +
planner-worker-judge"]
    D -->|"flow-runner"| G2["flow.yaml
stages+gates"]
    D -->|"www-publishing"| G3["Emotion rendering
GEO optimize"]
    D -->|"execution-dispatch"| G4["SSH/Ansible
multi-server"]
    D -->|"direct-executor"| G5["Direct config"]
    G1 --> H["Evidence:
SHA+gate+actor
+timestamp"]
    G2 --> H
    G3 --> H
    G4 --> H
    G5 --> H
    H --> I["Action
completed"]
          

Execution path as steps:

1. State intent: Operator or agent expresses a wish: "Deploy Keycloak to this server", "Generate code for feature X", "Publish blog post".
2. Policy Decision Point (PDP) checks: The PDP aggregates 5 sources: governance policy, infra mode, cost budget, data sensitivity, deployment zone. Example:
   • Small change on standard server → AUTO
   • Production deploy → HITL (gate opens, operator approves)
   • Costly cluster restart during cost hold → BLOCK
3. PDP decides: AUTO / HITL / BLOCK
   • AUTO: adapter is invoked immediately
   • HITL: gate opens, operator waits for approval
   • BLOCK: action is stopped, reason is documented
4. Adapter selects execution mode: Depending on the action type (code-feature, flow, content, infra, config):
   • coding: sandbox spins up, planner-worker-judge loop, code is generated
   • flow-runner: flow.yaml is processed sequentially/in parallel, HITL gates respected
   • www-publishing: emotion sensitivity determines tone, GEO optimization scales images
   • execution-dispatch: SSH command or Ansible playbook on multi-server, with automatic retry
   • direct-executor: direct YAML write or configuration application
5. Action executed: The adapter does the work (code, deployment, content, calculation).
6. Log evidence: Every step is documented:
   • Git commit SHA or deployment manifest ID
   • Gate ID (if HITL)
   • Actor (operator/agent ID)
   • Timestamp and result
7. Audit trail complete: The action is traceable forever. No silent state — everything is evidence.

3. Flow Model: Workflows with Gates and Maturity

IIO defines 683 flows — declarative workflows that build complex operations from reusable stages.

Flow structure:

• flow.yaml: declaration of a workflow sequence (or DAG)
• Stages: each stage has a distinct task (Ansible, Bash, Python, HTTP call, etc.)
• HITL gates: any number of gates per flow — operator can pause and approve workflows
• Evidence collection: every stage writes its outputs (logs, metrics, results)
• Maturity: flows have status (draft, stable, production, deprecated) — checked at execution time

Example: the deploy-new-tenant flow is part of 3803 cumulative steps across all flows. A single flow can have 20–50 stages.

For inspection: /flows (page shows all flows with maturity, last run, and details).

4. Operating Models: Shared, Dedicated, On-Prem

The Projection Engine can instantiate any tenant in one of three operating models:

A tenant can mix multiple models: e.g. database dedicated, AI inference shared, secret keys on-prem.

5. AI Operations: Local Models, LiteLLM Router, €0 Token Cost

IIO operates local AI models on Nvidia GPUs. That means: all inference runs inside our own data center, €0 token cost.

Infrastructure:

• GPU fleet: several specialized machines with Nvidia GPUs (H100, A40, etc.), pooled under Ollama
• LiteLLM router: intelligently distributes requests to the best GPU. Load balancing and fallback on failures.
• Ollama: open-source server that hosts local models (Llama, Mistral, CodeLlama)
• Cost Guard: monitors GPU utilization, memory, heat. Automatic shutdown on thermal issues.

Why €0?

When a coding agent sends requests or an operator starts a publishing flow, the AI computation happens locally:

1. Request comes in → LiteLLM router decides which GPU
2. Ollama runs inference locally (in our own data center)
3. Result comes back
4. Zero outbound network traffic → zero external API cost

Boundary: External APIs

Explicit boundary: we only use external APIs when it's not possible locally:

• Real-time financial quotes → external API (costs ~€0.02/request)
• Legal validation (GDPR query) → external specialist API (costs €0.50/query)
• Image generation via FLUX → local, or external FLUX API if the GPU is too slow

Transparency: every tenant knows where the boundaries are. We state the costs explicitly.

6. Data Storage and Tenant Separation

Every tenant has a logical data boundary. Physically, multiple tenants may share infrastructure, but data is isolated:

• Database namespace: PostgreSQL/Directus schemas per tenant
• Keycloak realm: each tenant has its own SSO realm, or shares realms with RBAC separation
• Filesystem separation: S3 buckets or local volumes per tenant
• HITL identity: access policy determines who may access which tenant's data

No tenant sees another tenant's data. This is enforced by policy and monitored with automatic audit control.

7. Observability: Metrics, Logs, Alerts, Rogue-Unit Detection

IIO operates a continuous monitoring system that observes every layer of the infrastructure:

Pillars of observability:

• Metrics: VictoriaMetrics collects time-series data (CPU, memory, network, GPU VRAM) from all servers
• Logs: Loki stores structured and unstructured logs (syslog, Docker, application logs) with 30-day retention
• Alerts: Grafana + Alertmanager trigger on critical metrics (e.g. disk >90%, API error rate >5%)
• Health checks: Blackbox exporter tests service reachability every 30 seconds
• Service Topology: monitors which systemd services are authorized on each server (and detects illegal/suspicious services)

Service Topology — Rogue-Unit Detection:

The Service Topology Layer maintains a desired-state list of all authorized systemd services per server. On every check, the actual list is compared against the desired list:

• Expected: e.g. caddy.service, iio-mcp.service — authorized
• Missing: e.g. fail2ban.service should be running, is missing → WARN, service is reconstructed
• Rogue: e.g. crypto-miner.service is running but not on the desired list → CRITICAL, HITL gate opens immediately, service is disabled

Practical example: if a security incident smuggles a systemd unit with a suspicious name (e.g. system-update-helper.service, which is actually a cryptominer) onto a server, Service Topology detects it on the next scan and reports it as a rogue unit with top priority.

Node Health:

Per-server state is continuously updated: disk usage, swap, Docker daemon health, SSH key rotation, certificate expiry. Proactive notifications ahead of critical events.

8. Cooperation with External Systems: MCP, A2A, Agent Docking

IIO is designed to cooperate with external systems. Three protocols connect external agents/tools to IIO:

• MCP (Model Context Protocol): Claude, ChatGPT, Cursor and others can call 12 IIO governance tools. Via stdio or HTTP.
• A2A (Agent-to-Agent): other AI agents (e.g. Gemini, CrewAI, AutoGen) can send tasks to IIO and wait for results.
• Agent Docking: a coding agent or agency AI can "dock" itself into IIO — then gets access to Keycloak, queue, HITL gates.

For details: /kooperation (page shows protocols, examples and integration steps).

9. Boundaries: What IIO Does Not Solve