# erupts/erupt architecture

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

- Interactive diagram: https://gitdiagram.com/erupts/erupt
- Repository: https://github.com/erupts/erupt

## Overview

Erupt is a runtime, model-driven enterprise application platform with an AI harness. A user request enters through the admin/API surface; runtime model metadata drives generated-at-runtime views, permission-aware operations, and data access. AI capabilities extend that platform with chat and tool use, retrieval, decisioning, canvas generation, coding-agent workflows, and scheduled staff integrations. The graph combines README-described platform behavior with source-index-supported links; several module paths represent substantial subsystems whose internals were not sampled, so their unverified connections are omitted.

Main entry points: [`erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/service/LLMService.java`](https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/service/LLMService.java) (Chat orchestration), [`erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/service/RagService.java`](https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/service/RagService.java) (RAG service), [`erupt-core/src/main/java/xyz/erupt/core/view/EruptModel.java`](https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/view/EruptModel.java) (Business model), [`erupt-core/src/main/java/xyz/erupt/core/service/EruptCoreService.java`](https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/service/EruptCoreService.java) (Runtime registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_platform["Runtime Platform"]
  node_model["Business model<br/>[EruptModel.java]"]
  node_field["Field metadata"]
  node_runtime["Runtime registry"]
  node_data["Data operations"]
  node_dao["JPA access<br/>[EruptDao.java]"]
  node_session["Session storage"]
end

subgraph group_ai["AI Harness"]
  node_aiapi["AI API"]
  node_llmservice["Chat orchestration<br/>[LLMService.java]"]
  node_llmcore["LLM runtime<br/>[LlmCore.java]"]
  node_providers["LLM providers"]
  node_mcp["MCP and A2A"]
end

subgraph group_knowledge["Knowledge and Decisions"]
  node_ragapi["Retrieval API<br/>[RagController.java]"]
  node_rag["RAG service<br/>[RagService.java]"]
  node_vectors["Vector stores"]
  node_decisions["Decision engine"]
end

subgraph group_agents["Agent Workflows"]
  node_canvas["AI canvas"]
  node_claw["Claw agents"]
  node_dev["Coding workflows"]
  node_staff["AI staff"]
end

node_user(("Admin user"))

node_user -->|"uses model-driven app"| node_runtime
node_model -->|"registered at runtime"| node_runtime
node_model -->|"defines fields"| node_field
node_runtime -.->|"serves model operations"| node_data
node_data -->|"persists through"| node_dao
node_user -.->|"requests chat"| node_aiapi
node_aiapi -.->|"dispatches chat"| node_llmservice
node_llmservice -->|"requests completion"| node_llmcore
node_llmservice -.->|"uses provider"| node_providers
node_llmservice -.->|"offers agent tools"| node_mcp
node_ragapi -->|"routes retrieval"| node_rag
node_rag -->|"uses vector core"| node_vectors
node_rag -->|"embeds knowledge records"| node_model
node_user -.->|"evaluates decisions"| node_decisions
node_user -.->|"builds canvas"| node_canvas
node_user -.->|"invokes agent"| node_claw
node_user -.->|"directs coding agent"| node_dev
node_user -.->|"configures AI staff"| node_staff

click node_model "https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/view/EruptModel.java"
click node_field "https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/view/EruptFieldModel.java"
click node_runtime "https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/service/EruptCoreService.java"
click node_data "https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/service/EruptModifyService.java"
click node_dao "https://github.com/erupts/erupt/blob/master/erupt-data/erupt-data-jpa/src/main/java/xyz/erupt/jpa/dao/EruptDao.java"
click node_session "https://github.com/erupts/erupt/blob/master/erupt-upms/src/main/java/xyz/erupt/upms/service/EruptSessionService.java"
click node_aiapi "https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/controller/ChatController.java"
click node_llmservice "https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/service/LLMService.java"
click node_llmcore "https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/core/LlmCore.java"
click node_providers "https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/llm"
click node_mcp "https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/mcp"
click node_ragapi "https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/controller/RagController.java"
click node_rag "https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/service/RagService.java"
click node_vectors "https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/core/VectorStoreCore.java"
click node_decisions "https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-decision/src/main/java/xyz/erupt/decision/core"
click node_canvas "https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-canvas/src/main/java/xyz/erupt/ai_canvas"
click node_claw "https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-claw/src/main/java/xyz/erupt/ai_claw"
click node_dev "https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-dev/src/main/java/xyz/erupt/ai_dev"
click node_staff "https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-staff/src/main/java/xyz/erupt/ai_staff"

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_model,node_field,node_runtime,node_data,node_dao,node_session,node_user toneBlue
class node_aiapi,node_llmservice,node_llmcore,node_providers,node_mcp toneAmber
class node_ragapi,node_rag,node_vectors,node_decisions toneMint
class node_canvas,node_claw,node_dev,node_staff toneRose
```

## Components

### Runtime Platform

- [Business model](https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/view/EruptModel.java): `erupt-core/src/main/java/xyz/erupt/core/view/EruptModel.java`
- [Field metadata](https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/view/EruptFieldModel.java): `erupt-core/src/main/java/xyz/erupt/core/view/EruptFieldModel.java`
- [Runtime registry](https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/service/EruptCoreService.java): `erupt-core/src/main/java/xyz/erupt/core/service/EruptCoreService.java`
- [Data operations](https://github.com/erupts/erupt/blob/master/erupt-core/src/main/java/xyz/erupt/core/service/EruptModifyService.java): `erupt-core/src/main/java/xyz/erupt/core/service/EruptModifyService.java`
- [JPA access](https://github.com/erupts/erupt/blob/master/erupt-data/erupt-data-jpa/src/main/java/xyz/erupt/jpa/dao/EruptDao.java): `erupt-data/erupt-data-jpa/src/main/java/xyz/erupt/jpa/dao/EruptDao.java`
- [Session storage](https://github.com/erupts/erupt/blob/master/erupt-upms/src/main/java/xyz/erupt/upms/service/EruptSessionService.java): `erupt-upms/src/main/java/xyz/erupt/upms/service/EruptSessionService.java`

### AI Harness

- [AI API](https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/controller/ChatController.java): `erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/controller/ChatController.java`
- [Chat orchestration](https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/service/LLMService.java): `erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/service/LLMService.java`
- [LLM runtime](https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/core/LlmCore.java): `erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/core/LlmCore.java`
- [LLM providers](https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/llm): `erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/llm`
- [MCP and A2A](https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/mcp): `erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/mcp`

### Knowledge and Decisions

- [Retrieval API](https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/controller/RagController.java): `erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/controller/RagController.java`
- [RAG service](https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/service/RagService.java): `erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/service/RagService.java`
- [Vector stores](https://github.com/erupts/erupt/blob/master/erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/core/VectorStoreCore.java): `erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/core/VectorStoreCore.java`
- [Decision engine](https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-decision/src/main/java/xyz/erupt/decision/core): `erupt-ai/erupt-ai-decision/src/main/java/xyz/erupt/decision/core`

### Agent Workflows

- [AI canvas](https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-canvas/src/main/java/xyz/erupt/ai_canvas): `erupt-ai/erupt-ai-canvas/src/main/java/xyz/erupt/ai_canvas`
- [Claw agents](https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-claw/src/main/java/xyz/erupt/ai_claw): `erupt-ai/erupt-ai-claw/src/main/java/xyz/erupt/ai_claw`
- [Coding workflows](https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-dev/src/main/java/xyz/erupt/ai_dev): `erupt-ai/erupt-ai-dev/src/main/java/xyz/erupt/ai_dev`
- [AI staff](https://github.com/erupts/erupt/tree/master/erupt-ai/erupt-ai-staff/src/main/java/xyz/erupt/ai_staff): `erupt-ai/erupt-ai-staff/src/main/java/xyz/erupt/ai_staff`

### Other components

- **Admin user**

## Connections

- Admin user → Runtime registry: uses model-driven app (evidence: `README.md`)
- Business model → Runtime registry: registered at runtime (evidence: `erupt-core/src/main/java/xyz/erupt/core/service/EruptCoreService.java`)
- Business model → Field metadata: defines fields (evidence: `erupt-core/src/main/java/xyz/erupt/core/view/EruptModel.java`)
- Runtime registry → Data operations: serves model operations (evidence: `erupt-core/src/main/java/xyz/erupt/core/service/EruptModifyService.java`)
- Data operations → JPA access: persists through (evidence: `erupt-core/src/main/java/xyz/erupt/core/service/EruptModifyService.java`)
- Admin user → AI API: requests chat
- AI API → Chat orchestration: dispatches chat
- Chat orchestration → LLM runtime: requests completion (evidence: `erupt-ai/erupt-ai/src/main/java/xyz/erupt/ai/service/LLMService.java`)
- Chat orchestration → LLM providers: uses provider
- Chat orchestration → MCP and A2A: offers agent tools
- Retrieval API → RAG service: routes retrieval (evidence: `erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/controller/RagController.java`)
- RAG service → Vector stores: uses vector core (evidence: `erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/service/RagService.java`)
- RAG service → Business model: embeds knowledge records (evidence: `erupt-ai/erupt-ai-rag/src/main/java/xyz/erupt/ai_rag/service/RagService.java`)
- Admin user → Decision engine: evaluates decisions
- Admin user → AI canvas: builds canvas
- Admin user → Claw agents: invokes agent
- Admin user → Coding workflows: directs coding agent
- Admin user → AI staff: configures AI staff
