# ai-adriane/ailu-core architecture

> Architecture diagram of the GitHub repository ai-adriane/ailu-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ai-adriane/ailu-core
- Repository: https://github.com/ai-adriane/ailu-core

## Overview

Ailu is a stateful agent-graph framework: developers define and compile graphs through the SDK, then run or resume them on the Rust engine. Human gates, checkpoints, model calls, tools, streaming, and retrieval support that workflow; the repository also includes DSL compilers, a CLI, and an MCP server. The graph emphasizes README-documented execution and sampled RAG orchestration; several subsystems are represented by tree-supported paths because their implementation was not sampled.

Main entry points: [`packages/graph-sdk/src/compiled-graph.ts`](https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-sdk/src/compiled-graph.ts) (Graph SDK), [`crates/graph-runtime/src/runtime.rs`](https://github.com/ai-adriane/ailu-core/blob/main/crates/graph-runtime/src/runtime.rs) (Rust Graph Runtime), [`crates/rag-pipeline/src/pipeline.rs`](https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/pipeline.rs) (RAG Orchestrator), [`crates/bindings/src/lib.rs`](https://github.com/ai-adriane/ailu-core/blob/main/crates/bindings/src/lib.rs) (Native Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Graph Authoring"]
  node_sdk["Graph SDK<br/>[compiled-graph.ts]"]
  node_dsl["Ailu DSL<br/>[compile-file.ts]"]
  node_graphmodel["Graph Model<br/>[types.ts]"]
end

subgraph group_execution["Graph Execution"]
  node_native["Native Bridge<br/>[lib.rs]"]
  node_runtime["Rust Graph Runtime<br/>[runtime.rs]"]
  node_checkpoint["Checkpoints and Resume<br/>[rust-engine.ts]"]
  node_stream["Execution Streaming<br/>[compiled-graph.ts]"]
  node_callbacks["Callbacks<br/>[manager.ts]"]
end

subgraph group_governance["Governance and State"]
  node_human["Human Approval"]
  node_artifacts[("Artifact Storage")]
  node_memory[("Memory Store<br/>[in-memory-store.ts]")]
end

subgraph group_intelligence["Agents and Retrieval"]
  node_agents["Agent Patterns<br/>[react-agent.ts]"]
  node_llm["LLM Gateway<br/>[gateway.ts]"]
  node_provider["Model Provider"]
  node_rag["RAG Orchestrator<br/>[pipeline.rs]"]
  node_loaders["Document Loaders<br/>[loaders.rs]"]
  node_splitters["Chunk Splitters<br/>[splitters.rs]"]
  node_embeddings["Embeddings<br/>[embeddings.rs]"]
  node_vectorstore[("Vector Store<br/>[vector_store.rs]")]
  node_reranker["Reranker<br/>[reranker.rs]"]
end

subgraph group_interfaces["Developer Interfaces"]
  node_cli["CLI<br/>[run.ts]"]
  node_mcp["MCP Server<br/>[server.mts]"]
  node_observability["Observability<br/>[interfaces.ts]"]
end

node_developer(("Graph Developer"))

node_developer -->|"defines graphs"| node_sdk
node_sdk -->|"builds definitions"| node_graphmodel
node_dsl -->|"compiles YAML"| node_graphmodel
node_sdk -->|"invokes engine"| node_native
node_native -->|"dispatches execution"| node_runtime
node_runtime -->|"calls JS seams"| node_sdk
node_sdk -->|"saves checkpoints"| node_checkpoint
node_sdk -->|"streams events"| node_stream
node_runtime -->|"pauses at gates"| node_human
node_sdk -->|"resumes after approval"| node_human
node_runtime -.->|"emits callbacks"| node_callbacks
node_callbacks -.->|"reports events"| node_observability
node_agents -.->|"requests generation"| node_llm
node_llm -->|"calls model"| node_provider
node_rag -->|"loads documents"| node_loaders
node_rag -->|"splits documents"| node_splitters
node_rag -->|"embeds chunks"| node_embeddings
node_rag -->|"stores and searches"| node_vectorstore
node_rag -->|"reranks results"| node_reranker
node_cli -.->|"runs graphs"| node_sdk
node_mcp -->|"uses SDK"| node_sdk
node_runtime -.->|"persists artifacts"| node_artifacts
node_runtime -.->|"uses memory"| node_memory

click node_sdk "https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-sdk/src/compiled-graph.ts"
click node_dsl "https://github.com/ai-adriane/ailu-core/blob/main/packages/lang-ailu/src/compiler/compile-file.ts"
click node_graphmodel "https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-core/src/types.ts"
click node_cli "https://github.com/ai-adriane/ailu-core/blob/main/packages/ailu-cli/src/commands/run.ts"
click node_mcp "https://github.com/ai-adriane/ailu-core/blob/main/plugin/mcp/server.mts"
click node_native "https://github.com/ai-adriane/ailu-core/blob/main/crates/bindings/src/lib.rs"
click node_runtime "https://github.com/ai-adriane/ailu-core/blob/main/crates/graph-runtime/src/runtime.rs"
click node_checkpoint "https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-sdk/src/rust-engine.ts"
click node_stream "https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-sdk/src/compiled-graph.ts"
click node_human "https://github.com/ai-adriane/ailu-core/blob/main/packages/approval-engine/src/in-memory-approval-engine.ts"
click node_artifacts "https://github.com/ai-adriane/ailu-core/blob/main/packages/artifact-store/src/in-memory-artifact-store.ts"
click node_memory "https://github.com/ai-adriane/ailu-core/blob/main/packages/memory-store/src/in-memory-store.ts"
click node_agents "https://github.com/ai-adriane/ailu-core/blob/main/packages/agents-core/src/react-agent.ts"
click node_llm "https://github.com/ai-adriane/ailu-core/blob/main/packages/llm-gateway/src/gateway.ts"
click node_rag "https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/pipeline.rs"
click node_loaders "https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/loaders.rs"
click node_splitters "https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/splitters.rs"
click node_embeddings "https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/embeddings.rs"
click node_vectorstore "https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/vector_store.rs"
click node_reranker "https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/reranker.rs"
click node_callbacks "https://github.com/ai-adriane/ailu-core/blob/main/packages/callbacks/src/manager.ts"
click node_observability "https://github.com/ai-adriane/ailu-core/blob/main/packages/observability/src/interfaces.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sdk,node_dsl,node_graphmodel toneBlue
class node_native,node_runtime,node_checkpoint,node_stream,node_callbacks toneAmber
class node_human,node_artifacts,node_memory toneMint
class node_agents,node_llm,node_provider,node_rag,node_loaders,node_splitters,node_embeddings,node_vectorstore,node_reranker toneRose
class node_cli,node_mcp,node_observability,node_developer toneIndigo
```

## Components

### Graph Authoring

- [Graph SDK](https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-sdk/src/compiled-graph.ts): `packages/graph-sdk/src/compiled-graph.ts`
- [Ailu DSL](https://github.com/ai-adriane/ailu-core/blob/main/packages/lang-ailu/src/compiler/compile-file.ts): `packages/lang-ailu/src/compiler/compile-file.ts`
- [Graph Model](https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-core/src/types.ts): `packages/graph-core/src/types.ts`

### Graph Execution

- [Native Bridge](https://github.com/ai-adriane/ailu-core/blob/main/crates/bindings/src/lib.rs): `crates/bindings/src/lib.rs`
- [Rust Graph Runtime](https://github.com/ai-adriane/ailu-core/blob/main/crates/graph-runtime/src/runtime.rs): `crates/graph-runtime/src/runtime.rs`
- [Checkpoints and Resume](https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-sdk/src/rust-engine.ts): `packages/graph-sdk/src/rust-engine.ts`
- [Execution Streaming](https://github.com/ai-adriane/ailu-core/blob/main/packages/graph-sdk/src/compiled-graph.ts): `packages/graph-sdk/src/compiled-graph.ts`
- [Callbacks](https://github.com/ai-adriane/ailu-core/blob/main/packages/callbacks/src/manager.ts): `packages/callbacks/src/manager.ts`

### Governance and State

- [Human Approval](https://github.com/ai-adriane/ailu-core/blob/main/packages/approval-engine/src/in-memory-approval-engine.ts): `packages/approval-engine/src/in-memory-approval-engine.ts`
- [Artifact Storage](https://github.com/ai-adriane/ailu-core/blob/main/packages/artifact-store/src/in-memory-artifact-store.ts): `packages/artifact-store/src/in-memory-artifact-store.ts`
- [Memory Store](https://github.com/ai-adriane/ailu-core/blob/main/packages/memory-store/src/in-memory-store.ts): `packages/memory-store/src/in-memory-store.ts`

### Agents and Retrieval

- [Agent Patterns](https://github.com/ai-adriane/ailu-core/blob/main/packages/agents-core/src/react-agent.ts): `packages/agents-core/src/react-agent.ts`
- [LLM Gateway](https://github.com/ai-adriane/ailu-core/blob/main/packages/llm-gateway/src/gateway.ts): `packages/llm-gateway/src/gateway.ts`
- **Model Provider**
- [RAG Orchestrator](https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/pipeline.rs): `crates/rag-pipeline/src/pipeline.rs`
- [Document Loaders](https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/loaders.rs): `crates/rag-pipeline/src/loaders.rs`
- [Chunk Splitters](https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/splitters.rs): `crates/rag-pipeline/src/splitters.rs`
- [Embeddings](https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/embeddings.rs): `crates/rag-pipeline/src/embeddings.rs`
- [Vector Store](https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/vector_store.rs): `crates/rag-pipeline/src/vector_store.rs`
- [Reranker](https://github.com/ai-adriane/ailu-core/blob/main/crates/rag-pipeline/src/reranker.rs): `crates/rag-pipeline/src/reranker.rs`

### Developer Interfaces

- [CLI](https://github.com/ai-adriane/ailu-core/blob/main/packages/ailu-cli/src/commands/run.ts): `packages/ailu-cli/src/commands/run.ts`
- [MCP Server](https://github.com/ai-adriane/ailu-core/blob/main/plugin/mcp/server.mts): `plugin/mcp/server.mts`
- [Observability](https://github.com/ai-adriane/ailu-core/blob/main/packages/observability/src/interfaces.ts): `packages/observability/src/interfaces.ts`

### Other components

- **Graph Developer**

## Connections

- Graph Developer → Graph SDK: defines graphs (evidence: `README.md`)
- Graph SDK → Graph Model: builds definitions (evidence: `README.md`)
- Ailu DSL → Graph Model: compiles YAML (evidence: `README.md`)
- Graph SDK → Native Bridge: invokes engine (evidence: `README.md`)
- Native Bridge → Rust Graph Runtime: dispatches execution (evidence: `README.md`)
- Rust Graph Runtime → Graph SDK: calls JS seams (evidence: `README.md`)
- Graph SDK → Checkpoints and Resume: saves checkpoints (evidence: `packages/graph-sdk/src/rust-engine.ts`)
- Graph SDK → Execution Streaming: streams events (evidence: `README.md`)
- Rust Graph Runtime → Human Approval: pauses at gates (evidence: `README.md`)
- Graph SDK → Human Approval: resumes after approval (evidence: `README.md`)
- Rust Graph Runtime → Callbacks: emits callbacks
- Callbacks → Observability: reports events
- Agent Patterns → LLM Gateway: requests generation
- LLM Gateway → Model Provider: calls model (evidence: `README.md`)
- RAG Orchestrator → Document Loaders: loads documents (evidence: `crates/rag-pipeline/src/pipeline.rs`)
- RAG Orchestrator → Chunk Splitters: splits documents (evidence: `crates/rag-pipeline/src/pipeline.rs`)
- RAG Orchestrator → Embeddings: embeds chunks (evidence: `crates/rag-pipeline/src/pipeline.rs`)
- RAG Orchestrator → Vector Store: stores and searches (evidence: `crates/rag-pipeline/src/pipeline.rs`)
- RAG Orchestrator → Reranker: reranks results (evidence: `crates/rag-pipeline/src/pipeline.rs`)
- CLI → Graph SDK: runs graphs
- MCP Server → Graph SDK: uses SDK (evidence: `plugin/mcp/server.mts`)
- Rust Graph Runtime → Artifact Storage: persists artifacts
- Rust Graph Runtime → Memory Store: uses memory
