# linmowudie/civitasai architecture

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

- Interactive diagram: https://gitdiagram.com/linmowudie/civitasai
- Repository: https://github.com/linmowudie/civitasai

## Overview

Civitas-AI is a desktop-oriented autonomous multi-agent system, with a separate account and synchronization server. The main workflow is a user task entering through the client/API, being managed by the loop and decision/runtime layers, using models and tools, and returning observable results. Major supporting capabilities include durable recovery, human approval, governance and arbitration, token budgets, memory, and audit/trace events. The README documents the product flow and capabilities; source excerpts and the index confirm selected wiring, so uncertain implementation links are omitted.

Main entry points: [`Src/Core/Loop/loopEngine.ts`](https://github.com/linmowudie/civitasai/blob/main/Src/Core/Loop/loopEngine.ts) (Loop Engine), [`Client/src/App.tsx`](https://github.com/linmowudie/civitasai/blob/main/Client/src/App.tsx) (Desktop Client), [`Server/src/app.ts`](https://github.com/linmowudie/civitasai/blob/main/Server/src/app.ts) (Account API), [`Src/Interface/IpcBridge/ipcBridge.ts`](https://github.com/linmowudie/civitasai/blob/main/Src/Interface/IpcBridge/ipcBridge.ts) (IPC Bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interfaces"]
  node_client["Desktop Client<br/>[App.tsx]"]
  node_ipc["IPC Bridge<br/>[ipcBridge.ts]"]
  node_rest["REST API<br/>[chatApi.ts]"]
  node_server_routes["Web Routes<br/>[routes.ts]"]
  node_main["Runtime Bootstrap<br/>[main.ts]"]
end

subgraph group_execution["Agent Execution"]
  node_loop["Loop Engine<br/>[loopEngine.ts]"]
  node_loop_config["Loop Configuration<br/>[loopConfig.ts]"]
  node_decision["Task Decisions<br/>[orchestrator.ts]"]
  node_agent_runtime["Agent Runtime<br/>[agentRuntime.ts]"]
  node_model["Model Caller<br/>[modelCaller.ts]"]
  node_tool_safety["Tool Safety Gate<br/>[toolSafetyGate.ts]"]
  node_tool_registry["Tool Registry<br/>[toolDispatcher.ts]"]
end

subgraph group_governance["Governance Services"]
  node_arbitration["Arbitration<br/>[tribunal.ts]"]
  node_supervision["Supervision<br/>[loopSupervision.ts]"]
  node_token_economy[("Token Economy<br/>[tokenLedger.ts]")]
  node_memory[("Shared Memory<br/>[longTermMemory.ts]")]
end

subgraph group_infrastructure["Runtime Infrastructure"]
  node_durable[("Durable Execution<br/>[index.ts]")]
  node_database[("Runtime Database<br/>[database.ts]")]
  node_event_bus["Event Bus<br/>[eventBus.ts]"]
end

subgraph group_account["Account Services"]
  node_server_app["Account API<br/>[app.ts]"]
  node_auth_service["Authentication<br/>[authService.ts]"]
  node_server_db[("Account Database<br/>[pool.ts]")]
end

node_user(("User"))

node_user -->|"submits task"| node_client
node_client -.->|"uses desktop bridge"| node_ipc
node_client -.->|"sends API requests"| node_rest
node_ipc -->|"starts bridge"| node_main
node_main -.->|"starts runtime"| node_loop
node_server_routes -->|"registers routes"| node_rest
node_loop -->|"reads configuration"| node_loop_config
node_loop -.->|"coordinates task decisions"| node_decision
node_decision -.->|"dispatches agents"| node_agent_runtime
node_agent_runtime -.->|"runs agent loop"| node_loop
node_loop -.->|"calls model"| node_model
node_loop -.->|"gates tool actions"| node_tool_safety
node_loop -.->|"executes tools"| node_tool_registry
node_loop -.->|"checkpoints execution"| node_durable
node_durable -.->|"persists state"| node_database
node_loop -.->|"runs supervision"| node_supervision
node_loop -.->|"enforces budgets"| node_token_economy
node_loop -.->|"uses memory"| node_memory
node_arbitration -->|"publishes events"| node_event_bus
node_supervision -.->|"emits observations"| node_event_bus
node_server_app -->|"constructs service"| node_auth_service
node_auth_service -->|"uses database"| node_server_db
node_server_app -->|"checks readiness"| node_server_db

click node_client "https://github.com/linmowudie/civitasai/blob/main/Client/src/App.tsx"
click node_ipc "https://github.com/linmowudie/civitasai/blob/main/Src/Interface/IpcBridge/ipcBridge.ts"
click node_rest "https://github.com/linmowudie/civitasai/blob/main/Src/Interface/RestApi/chatApi.ts"
click node_server_routes "https://github.com/linmowudie/civitasai/blob/main/Src/Interface/WebServer/routes.ts"
click node_main "https://github.com/linmowudie/civitasai/blob/main/Src/main.ts"
click node_loop "https://github.com/linmowudie/civitasai/blob/main/Src/Core/Loop/loopEngine.ts"
click node_loop_config "https://github.com/linmowudie/civitasai/blob/main/Src/Core/Loop/loopConfig.ts"
click node_decision "https://github.com/linmowudie/civitasai/blob/main/Src/Core/Decision/orchestrator/orchestrator.ts"
click node_agent_runtime "https://github.com/linmowudie/civitasai/blob/main/Src/Core/AgentRuntime/agentRuntime.ts"
click node_model "https://github.com/linmowudie/civitasai/blob/main/Src/Core/Model/modelCaller.ts"
click node_tool_safety "https://github.com/linmowudie/civitasai/blob/main/Src/Services/LoopControl/middleware/toolSafetyGate.ts"
click node_tool_registry "https://github.com/linmowudie/civitasai/blob/main/Src/Tools/Registry/toolDispatcher.ts"
click node_durable "https://github.com/linmowudie/civitasai/blob/main/Src/Infra/DurableExecution/index.ts"
click node_database "https://github.com/linmowudie/civitasai/blob/main/Src/Infra/Db/database.ts"
click node_event_bus "https://github.com/linmowudie/civitasai/blob/main/Src/Services/EventBus/eventBus.ts"
click node_arbitration "https://github.com/linmowudie/civitasai/blob/main/Src/Services/Arbitration/tribunal.ts"
click node_supervision "https://github.com/linmowudie/civitasai/blob/main/Src/Services/Supervision/loopSupervision.ts"
click node_token_economy "https://github.com/linmowudie/civitasai/blob/main/Src/Services/TokenEconomy/tokenLedger.ts"
click node_memory "https://github.com/linmowudie/civitasai/blob/main/Src/Services/SharedMemory/longTermMemory.ts"
click node_server_app "https://github.com/linmowudie/civitasai/blob/main/Server/src/app.ts"
click node_auth_service "https://github.com/linmowudie/civitasai/blob/main/Server/src/services/authService.ts"
click node_server_db "https://github.com/linmowudie/civitasai/blob/main/Server/src/db/pool.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_client,node_ipc,node_rest,node_server_routes,node_main,node_user toneBlue
class node_loop,node_loop_config,node_decision,node_agent_runtime,node_model,node_tool_safety,node_tool_registry toneAmber
class node_arbitration,node_supervision,node_token_economy,node_memory toneMint
class node_durable,node_database,node_event_bus toneRose
class node_server_app,node_auth_service,node_server_db toneIndigo
```

## Components

### User Interfaces

- [Desktop Client](https://github.com/linmowudie/civitasai/blob/main/Client/src/App.tsx): `Client/src/App.tsx`
- [IPC Bridge](https://github.com/linmowudie/civitasai/blob/main/Src/Interface/IpcBridge/ipcBridge.ts): `Src/Interface/IpcBridge/ipcBridge.ts`
- [REST API](https://github.com/linmowudie/civitasai/blob/main/Src/Interface/RestApi/chatApi.ts): `Src/Interface/RestApi/chatApi.ts`
- [Web Routes](https://github.com/linmowudie/civitasai/blob/main/Src/Interface/WebServer/routes.ts): `Src/Interface/WebServer/routes.ts`
- [Runtime Bootstrap](https://github.com/linmowudie/civitasai/blob/main/Src/main.ts): `Src/main.ts`

### Agent Execution

- [Loop Engine](https://github.com/linmowudie/civitasai/blob/main/Src/Core/Loop/loopEngine.ts): `Src/Core/Loop/loopEngine.ts`
- [Loop Configuration](https://github.com/linmowudie/civitasai/blob/main/Src/Core/Loop/loopConfig.ts): `Src/Core/Loop/loopConfig.ts`
- [Task Decisions](https://github.com/linmowudie/civitasai/blob/main/Src/Core/Decision/orchestrator/orchestrator.ts): `Src/Core/Decision/orchestrator/orchestrator.ts`
- [Agent Runtime](https://github.com/linmowudie/civitasai/blob/main/Src/Core/AgentRuntime/agentRuntime.ts): `Src/Core/AgentRuntime/agentRuntime.ts`
- [Model Caller](https://github.com/linmowudie/civitasai/blob/main/Src/Core/Model/modelCaller.ts): `Src/Core/Model/modelCaller.ts`
- [Tool Safety Gate](https://github.com/linmowudie/civitasai/blob/main/Src/Services/LoopControl/middleware/toolSafetyGate.ts): `Src/Services/LoopControl/middleware/toolSafetyGate.ts`
- [Tool Registry](https://github.com/linmowudie/civitasai/blob/main/Src/Tools/Registry/toolDispatcher.ts): `Src/Tools/Registry/toolDispatcher.ts`

### Governance Services

- [Arbitration](https://github.com/linmowudie/civitasai/blob/main/Src/Services/Arbitration/tribunal.ts): `Src/Services/Arbitration/tribunal.ts`
- [Supervision](https://github.com/linmowudie/civitasai/blob/main/Src/Services/Supervision/loopSupervision.ts): `Src/Services/Supervision/loopSupervision.ts`
- [Token Economy](https://github.com/linmowudie/civitasai/blob/main/Src/Services/TokenEconomy/tokenLedger.ts): `Src/Services/TokenEconomy/tokenLedger.ts`
- [Shared Memory](https://github.com/linmowudie/civitasai/blob/main/Src/Services/SharedMemory/longTermMemory.ts): `Src/Services/SharedMemory/longTermMemory.ts`

### Runtime Infrastructure

- [Durable Execution](https://github.com/linmowudie/civitasai/blob/main/Src/Infra/DurableExecution/index.ts): `Src/Infra/DurableExecution/index.ts`
- [Runtime Database](https://github.com/linmowudie/civitasai/blob/main/Src/Infra/Db/database.ts): `Src/Infra/Db/database.ts`
- [Event Bus](https://github.com/linmowudie/civitasai/blob/main/Src/Services/EventBus/eventBus.ts): `Src/Services/EventBus/eventBus.ts`

### Account Services

- [Account API](https://github.com/linmowudie/civitasai/blob/main/Server/src/app.ts): `Server/src/app.ts`
- [Authentication](https://github.com/linmowudie/civitasai/blob/main/Server/src/services/authService.ts): `Server/src/services/authService.ts`
- [Account Database](https://github.com/linmowudie/civitasai/blob/main/Server/src/db/pool.ts): `Server/src/db/pool.ts`

### Other components

- **User**

## Connections

- User → Desktop Client: submits task (evidence: `README.md`)
- Desktop Client → IPC Bridge: uses desktop bridge
- Desktop Client → REST API: sends API requests
- IPC Bridge → Runtime Bootstrap: starts bridge (evidence: `Src/main.ts`)
- Runtime Bootstrap → Loop Engine: starts runtime
- Web Routes → REST API: registers routes (evidence: `Src/Interface/WebServer/routes.ts`)
- Loop Engine → Loop Configuration: reads configuration (evidence: `Src/Core/Loop/loopEngine.ts`)
- Loop Engine → Task Decisions: coordinates task decisions
- Task Decisions → Agent Runtime: dispatches agents
- Agent Runtime → Loop Engine: runs agent loop (evidence: `README.md`)
- Loop Engine → Model Caller: calls model (evidence: `README.md`)
- Loop Engine → Tool Safety Gate: gates tool actions (evidence: `README.md`)
- Loop Engine → Tool Registry: executes tools (evidence: `README.md`)
- Loop Engine → Durable Execution: checkpoints execution (evidence: `README.md`)
- Durable Execution → Runtime Database: persists state
- Loop Engine → Supervision: runs supervision (evidence: `README.md`)
- Loop Engine → Token Economy: enforces budgets (evidence: `README.md`)
- Loop Engine → Shared Memory: uses memory (evidence: `README.md`)
- Arbitration → Event Bus: publishes events
- Supervision → Event Bus: emits observations
- Account API → Authentication: constructs service (evidence: `Server/src/app.ts`)
- Authentication → Account Database: uses database (evidence: `Server/src/services/authService.ts`)
- Account API → Account Database: checks readiness (evidence: `Server/src/app.ts`)
