Engineer Primer — IIO für InformatikerEngineer Primer — IIO for Software Engineers
Fachlicher Einstieg in die IIO-Architektur. Was IIO ist, warum es gebaut wurde, welche etablierten Konzepte es geerbt hat — und wo es bewusst abweicht. Empfohlene Lesereihenfolge inklusive.Technical introduction to IIO architecture. What IIO is, why it was built, which established concepts it inherits — and where it deliberately diverges. Includes a recommended reading order.
1. Was ist IIO?1. What is IIO?
IIO (Intelligent Infrastructure Organism) ist ein Actor-agnostisches Governance- und Betriebsrahmenwerk für infrastruktur-nahe Systeme, in denen Menschen und KI-Agenten als gleichwertige operative Einheiten behandelt werden.IIO (Intelligent Infrastructure Organism) is an actor-agnostic governance and operations framework for infrastructure-adjacent systems where humans and AI agents are treated as equivalent operational units.
Das klingt abstrakt — konkret bedeutet es: IIO definiert, wie ein System aus Rollen, Berechtigungen, Transaktionen, Boundaries und Stories aufgebaut wird, sodass dasselbe Regelwerk ohne Anpassung für einen menschlichen Operator, ein Deployment-Skript oder einen LLM-Agenten gilt.Concretely: IIO defines how a system of roles, permissions, transactions, boundaries, and stories is structured so that the same ruleset applies without modification to a human operator, a deployment script, or an LLM agent.
2. Die 9 Layer des Unified Control Model2. The 9 Layers of the Unified Control Model
Jedes Layer beantwortet genau eine Frage. Kein Layer übernimmt die Verantwortung eines anderen. Alle Layer folgen identischen Actor-agnostischen Mustern.Each layer answers exactly one question. No layer takes on the responsibility of another. All layers follow identical actor-agnostic patterns.
→ Vollständige Referenz: Layer-Architektur Deep-Dive→ Full reference: Layer Architecture Deep-Dive
3. Die zwei ontologischen Kernentscheidungen3. The Two Core Ontological Decisions
Hier weicht IIO am stärksten von allem ab, was vorher existierte.This is where IIO diverges most sharply from everything that came before.
Entscheidung 1: Entity → Actor (P-CORE-003)Decision 1: Entity → Actor (P-CORE-003)
❌ Klassisch❌ Classic
Passive Ressourcen (Dateien, Datenbanken, Services) sind keine Actors. Nur bestimmte Subjekte handeln. Ressourcen werden von Subjects benutzt.Passive resources (files, databases, services) are not actors. Only certain subjects act. Resources are used by subjects.
✓ IIO✓ IIO
Alles ist ein Actor. Passivität ist eine Role, keine ontologische Kategorie. Ein Datenspeicher hat die Role data-provider. Eine Datei hat die Role artifact.Everything is an actor. Passivity is a role, not an ontological category. A data store has the role data-provider. A file has the role artifact.
Konsequenz: Eine ganze Kategorie-Ebene verschwindet. Das Modell wird konsistenter — keine Sonderfälle für "Ressourcen".Consequence: An entire category tier disappears. The model becomes more consistent — no special cases for "resources".
Entscheidung 2: Human/Agent → Communication Mode (P-CORE-004)Decision 2: Human/Agent → Communication Mode (P-CORE-004)
❌ Klassisch❌ Classic
Mensch und KI-Agent sind verschiedene Typen mit verschiedenen Regeln, verschiedenen Zugriffspfaden, verschiedenen Interfaces. IAM-Systeme behandeln "Service Accounts" separat von "User Accounts".Human and AI agent are different types with different rules, access paths, and interfaces. IAM systems treat "service accounts" separately from "user accounts".
✓ IIO✓ IIO
Beide sind Intelligent Actors. Der Unterschied ist ein Communication Mode — wie ein Actor bevorzugt Input empfängt und Output produziert. Dieselbe Boundary-Regel gilt für beide.Both are Intelligent Actors. The difference is a communication mode — how an actor prefers to receive input and produce output. The same boundary rule applies to both.
| Machine-Optimized | Narrative-Optimized | |
|---|---|---|
| PrimärquellePrimary source | AGENTS.md | README.md |
| FormatFormat | YAML / JSON / TX-Logs | Prosa, Story, MetaphernProse, story, metaphor |
| EntscheidungDecision style | deterministischdeterministic | heuristischheuristic |
| BeispielExample | LLM-Agent, CI-Pipeline, Cron | Operator, Architekt, RevisorOperator, architect, reviewer |
Konsequenz: Kein Dual-Track (Human-IAM vs. Service-Account-IAM). Ein Actor, ein Regelwerk — egal ob Mensch oder Maschine.Consequence: No dual track (human IAM vs. service account IAM). One actor, one ruleset — whether human or machine.
4. Was IIO geerbt hat — und wo es abweicht4. What IIO Inherits — and Where It Diverges
IIO ist kein Greenfield-Entwurf. Es synthetisiert Konzepte aus mehreren etablierten Disziplinen — und macht dabei explizit, was in jedem Vorläufer implizit oder getrennt war.IIO is not a greenfield design. It synthesises concepts from several established disciplines — making explicit what was implicit or siloed in each predecessor.
| Konzept / HerkunftConcept / Origin | Was IIO übernimmtWhat IIO inherits | Wo IIO abweichtWhere IIO diverges |
|---|---|---|
| RBAC Enterprise IAM, LDAP, Keycloak |
Role-basierter Zugriff, keine Sonderregeln per Actor-TypRole-based access, no special rules per actor type | + temporale Gültigkeit, + Audit-Pflicht, + fail-closed default statt permit-by-default+ temporal validity, + mandatory audit, + fail-closed default instead of permit-by-default |
| Zero Trust NIST SP 800-207, BeyondCorp |
"Never trust, always verify" — explizite Grants statt implizitem Netzwerk-Vertrauen"Never trust, always verify" — explicit grants instead of implicit network trust | IIO operationalisiert das auf Datei-/Artefakt-Ebene, nicht nur NetzwerkebeneIIO operationalises this at file/artefact level, not just network level |
| Actor Model Hewitt 1973, Erlang, Akka |
Alle Entitäten = Actors, Kommunikation per Message, isolation by defaultAll entities = actors, communication via message, isolation by default | IIO fügt Fractal Composition + Communication-Mode-Schicht hinzu. Kein Mailbox-/Concurrency-Fokus.IIO adds fractal composition + communication mode layer. No mailbox/concurrency focus. |
| Domain-Driven Design Evans 2003 |
Bounded Contexts → Boundary-Typen. Ubiquitous Language → Premises-Katalog.Bounded contexts → boundary types. Ubiquitous language → premises catalogue. | IIO macht Boundaries formal (4 Typen, YAML-Schema, Violation-Handling) statt implizit.IIO formalises boundaries (4 types, YAML schema, violation handling) instead of keeping them implicit. |
| GitOps Weaveworks, Kubernetes |
Git = Single Source of Truth, deklarative State-BeschreibungGit = single source of truth, declarative state description | IIO erweitert auf Governance-Artefakte: Premises, Grants, Gates — alles versioniert, nicht nur Deployment-Configs.IIO extends this to governance artefacts: premises, grants, gates — all versioned, not just deployment configs. |
| Event Sourcing / CQRS Fowler, Vernon |
Unveränderliche Audit-Logs, State aus Events rekonstruierbarImmutable audit logs, state reconstructable from events | In IIO: Transaction Layer als formale Interaktionseinheit — maschinenlesbar, gate-geprüft, nicht nur Log.In IIO: transaction layer as a formal interaction unit — machine-readable, gate-checked, not just a log. |
| Control Plane / Data Plane Kubernetes, Service Mesh |
Trennung Steuerung vs. AusführungSeparation of control vs. execution | Foundation Layer = Control Plane. Skill-Packages = Data Plane. Aber beide sind Actors — gleiche Ontologie.Foundation layer = control plane. Skill packages = data plane. But both are actors — same ontology. |
| ISO 27001 / Compliance ISO, SOC2, BSI |
Governance-Tiefe, Audit-Trails, Gate-Reviews, dokumentierte EntscheidungenGovernance depth, audit trails, gate reviews, documented decisions | IIO macht das maschinenlesbar + agent-ausführbar statt dokument-basiert. Premises sind Code, nicht PDF.IIO makes this machine-readable + agent-executable instead of document-based. Premises are code, not PDF. |
Kernthese:Core thesis: RBAC, DDD, GitOps, Zero Trust, ISO 27001 existieren in der Praxis nebeneinander in getrennten Silos. IIO's Behauptung: Ein einziges Unified Control Model kann alle diese Belange in einer konsistenten Sprache abbilden — weil die zugrundeliegende Abstraktion (Actor + Role + Boundary + Story + Transaction) mächtig genug ist, um jeden dieser Bereiche zu modellieren.RBAC, DDD, GitOps, Zero Trust, ISO 27001 exist in practice alongside each other in separate silos. IIO's claim: a single unified control model can represent all these concerns in one consistent language — because the underlying abstraction (Actor + Role + Boundary + Story + Transaction) is powerful enough to model each of these domains.
5. Fractal Composition — ein Modell, alle Ebenen5. Fractal Composition — One Model, All Levels
Das Gleiche, was für einen einzelnen Entwickler gilt, gilt für ein Team, eine Organisation und eine Federation von Organisationen. Keine Sonderregeln pro Ebene.What applies to an individual developer applies equally to a team, an organisation, and a federation of organisations. No special rules per level.
→ Details: Composition Layer · Federation Model→ Details: Composition Layer · Federation Model
6. Fail-Closed — das operative Sicherheitsprinzip6. Fail-Closed — the Operational Safety Principle
Anders als klassische Systeme, die bei Unklarheit erlauben (permit-by-default), gilt in IIO das Gegenteil: bei fehlender expliziter Freigabe ist alles geblockt.Unlike classic systems that permit on ambiguity (permit-by-default), IIO inverts this: without an explicit grant, everything is blocked.
❌ Permit-by-Default❌ Permit-by-Default
Zugriff wird erlaubt, wenn keine explizite Deny-Regel existiert. Fehler → Zugriff. Unbekannte Situation → Zugriff.Access is permitted when no explicit deny rule exists. Error → access. Unknown situation → access.
✓ Fail-Closed (IIO)✓ Fail-Closed (IIO)
Zugriff wird erlaubt, wenn eine explizite Grant-Regel existiert. Fehler → BLOCK. Unbekannte Situation → BLOCK + Eskalation.Access is permitted only when an explicit grant rule exists. Error → BLOCK. Unknown situation → BLOCK + escalation.
Das gilt nicht nur für Zugriffskontrolle, sondern für alle Gates: Deployment, Review, Publikation, Agent-Entscheidungen.This applies not just to access control, but to all gates: deployment, review, publication, agent decisions.
→ Details: Guardrail-Architektur · Review Gate Reference · Premises-Katalog→ Details: Guardrail Architecture · Review Gate Reference · Premises Catalogue
7. Seed → Node — wie IIO deployed wird7. Seed → Node — how IIO is deployed
IIO existiert als Seed — ein unveränderliches Referenz-Template. Konkrete Betriebsinstanzen heißen Nodes. Nodes sind Projektionen des Seed mit eigenem Tenant-Profil.IIO exists as a Seed — an immutable reference template. Concrete operational instances are called Nodes. Nodes are projections of the seed with their own tenant profile.
iio/)Referenz-Template. Unveränderlich. Governance-Rails für alle Nodes.Reference template. Immutable. Governance rails for all nodes.intelego/, pm24/, …)Konkrete Projektion. Eigenes Profil, eigene Tenant-Daten, gleiche Grundregeln.Concrete projection. Own profile, own tenant data, same base rules.*/public/)Publizierte Artefakte — read-only, versioniert, deployment-ready.Published artefacts — read-only, versioned, deployment-ready.→ Details: Seed-Node Operating Model · Projection Manifest→ Details: Seed-Node Operating Model · Projection Manifest
8. Empfohlene Lesereihenfolge für Einsteiger8. Recommended Reading Order for New Engineers
Nach diesem Primer: diese Seiten in der Reihenfolge lesen. Jede Seite baut auf der vorherigen auf.After this primer: read these pages in order. Each page builds on the previous one.
9. Implementierungs-Mapping: IIO in echter Systemlandschaft9. Implementation Mapping: IIO in Real System Landscapes
IIO ersetzt bestehende Plattformen nicht zwingend. Typisch ist ein Mapping-Ansatz: bestehende Tools bleiben, aber Governance-Logik wird über IIO standardisiert und fail-closed gemacht.IIO does not necessarily replace existing platforms. Typical rollout uses mapping: existing tools remain, while governance logic is standardised and fail-closed through IIO.
Identity & Access (IAM)Identity & Access (IAM)
- Bestehend: Keycloak / LDAP / Entra IDExisting: Keycloak / LDAP / Entra ID
- IIO-Layer: Role + Boundary + TransactionIIO layers: Role + Boundary + Transaction
- Effekt: gleiche Regelkette fuer Human, Service, AgentEffect: same rule chain for human, service, agent
Delivery & OpsDelivery & Ops
- Bestehend: GitLab CI, Kubernetes, TerraformExisting: GitLab CI, Kubernetes, Terraform
- IIO-Layer: Story + Transaction + IntegrationIIO layers: Story + Transaction + Integration
- Effekt: deployment-faehige Flows mit expliziten GatesEffect: deployment-ready flows with explicit gates
Governance & AuditGovernance & Audit
- Bestehend: ISO/SOC2 Doku, Tickets, manuelle ReviewsExisting: ISO/SOC2 docs, tickets, manual reviews
- IIO-Layer: Premises + Review Gates + Diagram SemanticsIIO layers: Premises + Review Gates + Diagram Semantics
- Effekt: auditierbare Entscheidungskette statt EinzelartefakteEffect: auditable decision chain instead of isolated artefacts
AI-Agent IntegrationAI Agent Integration
- Bestehend: LLM-Agenten, MCP-Tools, AutomationsskripteExisting: LLM agents, MCP tools, automation scripts
- IIO-Layer: Ontology + Role + BoundaryIIO layers: Ontology + Role + Boundary
- Effekt: kein Sonderweg fuer Agenten, nur anderer Communication ModeEffect: no special path for agents, only a different communication mode
Praxisregel: Erst Mapping, dann Migration. IIO zuerst als Governance-Shell etablieren, danach schrittweise technische Konsolidierung.Practical rule: map first, migrate second. Establish IIO as governance shell first, then consolidate technology step by step.
10. Haeufige Anti-Patterns (und korrekte IIO-Alternative)10. Common Anti-Patterns (and Correct IIO Alternative)
| Anti-PatternAnti-pattern | Warum problematischWhy problematic | IIO-konforme LoesungIIO-compliant solution |
|---|---|---|
| "Agent hat Sonderrechte, weil sonst zu langsam""Agent gets elevated rights because speed" | Umgeht Role/Boundary-Layer, erzeugt unsichtbare BackdoorsBypasses role/boundary layer, creates invisible backdoors | Explizite Role + Grant mit Zeitfenster und Audit-TraceExplicit role + grant with time window and audit trace |
| Story fehlt, nur Ticket + SkriptStory missing, only ticket + script | Keine nachvollziehbare Intent-Kette, schwacher ReviewNo traceable intent chain, weak review quality | Story-Layer zuerst: Zweck, Constraints, Erfolgskriterien festhaltenStory layer first: define purpose, constraints, success criteria |
| Diagramm als Dekoration statt SemantikDiagram used as decoration, not semantics | Visuelle Drift: Bild und realer Gate-Status widersprechen sichVisual drift: image and real gate state diverge | Diagram Semantics Layer nutzen, Zustandsableitung aus echten ArtefaktenUse diagram semantics layer, derive state from real artefacts |
| Fail-open bei UnsicherheitFail-open on uncertainty | Sicherheits- und Compliance-Risiko in unbekannten ZustaendenSecurity and compliance risk in unknown states | Fail-closed erzwingen: BLOCK, dann Eskalation mit dokumentierter EntscheidungEnforce fail-closed: BLOCK, then escalate with documented decision |
11. Onboarding-Plan fuer Informatiker (30/60/90)11. Engineer Onboarding Plan (30/60/90)
Wenn du neu in IIO bist, folge einem gestuften Einstieg statt "alles auf einmal".If you are new to IIO, use a staged onboarding instead of "everything at once".
Tag 1-30 · VerstehenDay 1-30 · Understand
Ontologie, Layer-Architektur, Boundary Model lesen. Ziel: Begriffe sicher verwenden, Premises erkennen.Read ontology, layer architecture, boundary model. Goal: use terminology safely, recognise premises.
Tag 31-60 · AnwendenDay 31-60 · Apply
Kleine Aenderungen mit Review Gates durchziehen. Ziel: Story→Plan→TX→Review Kette selbst fahren.Ship small changes through review gates. Goal: run story→plan→TX→review chain independently.
Tag 61-90 · SkalierenDay 61-90 · Scale
Seed→Node Mapping fuer eigenes Team aufsetzen. Ziel: IIO-Regeln in bestehende Tool-Landschaft integrieren.Set up seed→node mapping for your own team. Goal: integrate IIO rules into existing tool landscape.
Checkliste "bereit fuer produktive IIO-Arbeit"Checklist "ready for productive IIO work"
- Ich kann erklaeren, warum Human/Agent in IIO kein Typ-Unterschied ist.I can explain why human/agent is not a type distinction in IIO.
- Ich kann einen Zugriff als Role + Boundary + Grant modellieren.I can model an access path as role + boundary + grant.
- Ich kann fail-closed Entscheidungen von fail-open sauber unterscheiden.I can clearly distinguish fail-closed from fail-open decisions.
- Ich kann fuer eine Aenderung die Story→TX→Review Kette dokumentieren.I can document the story→TX→review chain for a change.
- Ich kann Seed und Node in unserem Workspace korrekt abgrenzen.I can correctly separate seed and node in our workspace.