AIEN Architecture

Canonical architecture, flows, boundaries, decisions, research notes, and implementation roadmap for the AIEN ecosystem.

This repository is intentionally documentation-first. It does not replace the implementation repositories. It defines how the pieces are intended to compose and gives implementation agents one place to answer:

• What owns this responsibility?
• What talks to what?
• What is already implemented?
• What is partial?
• What is missing?
• Which boundary is security-critical?
• Which repository contains the current implementation?
• Which planned subsystem should be built next?

Naming rule: physical hosts are always called Machine 1, Machine 2, Machine 3, and so on. Hardware/vendor details are capabilities, never architectural identities.

Start here

1. Language
2. Complete system architecture
3. System map
4. GitHub repository map
5. Implementation status
6. Flows
7. Capabilities, skills, tools, and MCP
8. Fabric and portable compute
9. J-Space
10. Security, AEGIS, vault, and effects
11. World, Cortex, and provenance
12. RSI and evaluation
13. PEARL-inspired relational path engine
14. Gap analysis
15. Roadmap
16. Golden path
17. Architecture decision records
18. Master architectural plan

One-line architecture

User/API
  → Runtime
  → J-Space
  → Skill Router
  → Capability Graph
  → Fabric placement
  → Model/Tool execution
  → AEGIS
  → Effect Broker
  → World Commit
  → Signed Provenance
  → Cortex
  → RSI feedback

Master diagram

flowchart TD
    U[User / Operator / API] --> CP[Control Plane]
    CP --> RT[AIEN Runtime]

    RT --> JS[J-Space]
    JS --> SR[Skill Router]
    SR --> CG[Capability Graph]

    CG --> NT[Native Tools]
    CG --> MCP[MCP Broker]
    CG --> FT[Fabric Tools]

    RT --> INF[Inference Runtime]
    INF --> MR[Model Router]
    MR --> FAB[AIEN Fabric]

    FAB --> M1[Machine 1]
    FAB --> M2[Machine 2]
    FAB --> M3[Machine 3]
    FAB --> MN[Machine N]

    JS --> W[World Store]
    RT --> CX[Cortex]
    CX --> RT

    NT --> A[AEGIS]
    MCP --> A
    FT --> A

    A --> EB[Effect Broker]
    EB --> EXT[External World]
    EB --> W

    W --> P[Signed Provenance]
    P --> CX

    RT --> RSI[RSI Optimizer]
    RSI --> EV[Harness / Inquisitor / Benchmarks]
    EV --> RT

Loading

Source-of-truth policy

This repository describes intended architecture and records resolved architecture decisions.

Implementation truth remains the current code in the linked repositories. When this repository and running code disagree:

1. Do not silently pretend the target is implemented.
2. Mark the discrepancy in implementation status.
3. Open an architecture-gap issue.
4. Update the relevant ADR when the intended design changes.

Repository role

This repo should become the architectural index linked from the top-level READMEs of major AIEN repositories. Code repositories should avoid re-explaining the entire system; they should link here for cross-system architecture and keep their own README focused on their component.

License

The AIEN ecosystem currently uses more than one license across repositories. Before publishing this architecture repository, copy or explicitly select the intended canonical documentation license rather than assuming one. See LICENSE-NOTICE.md.