# sweetcornna/corlinman architecture

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

- Interactive diagram: https://gitdiagram.com/sweetcornna/corlinman
- Repository: https://github.com/sweetcornna/corlinman

## Overview

Corlinman is a self-hosted intelligent-agent platform. A user sends a request through a chat channel, the admin chat, or the HTTP/SSE interface; the shared agent loop reasons with configured models and tools, then returns a response through the initiating interface. Separate capabilities provide session history, searchable knowledge, approvals, channel integrations, and scheduled evolution. The README documents these major product branches; sampled source confirms selected embedding, scheduler, and MCP-client behavior, but not every gateway or UI connection.

Main entry points: [`python/packages/corlinman-agent/src/corlinman_agent/reasoning_loop.py`](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-agent/src/corlinman_agent/reasoning_loop.py) (Reasoning Loop), [`ui`](https://github.com/sweetcornna/corlinman/tree/main/ui) (Admin Console), [`python/packages/corlinman-server/src/corlinman_server`](https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-server/src/corlinman_server) (Gateway), [`python/packages/corlinman-providers/src/corlinman_providers`](https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-providers/src/corlinman_providers) (Model Providers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_channels["Chat Channels"]
  node_admin["Admin Console"]
  node_gateway["Gateway"]
end

subgraph group_agent["Agent Runtime"]
  node_agent_loop["Reasoning Loop<br/>[reasoning_loop.py]"]
  node_agent_defs["Agent Definitions"]
  node_providers["Model Providers"]
end

subgraph group_memory["Memory and Retrieval"]
  node_embedding_router["Embedding Router"]
  node_session_memory[("Session History<br/>[session.py]")]
  node_rag[("Knowledge Retrieval")]
end

subgraph group_tools["Tools and Governance"]
  node_plugin_runtime["Plugin Runtime"]
  node_mcp_clients["MCP Clients<br/>[client_manager.py]"]
  node_approvals["Approval Gate<br/>[approval_gate.py]"]
end

subgraph group_operations["Operations"]
  node_scheduler["Scheduler"]
  node_evolution["Evolution Engine<br/>[engine.py]"]
  node_evolution_store[("Evolution Store<br/>[store.py]")]
end

node_user(("User"))
node_model_service{{"Model APIs"}}
node_plugin_services{{"External MCP Servers"}}
node_operator(("Operator"))

node_user -->|"sends message"| node_channels
node_channels -->|"routes request"| node_gateway
node_user -->|"uses console"| node_admin
node_admin -->|"HTTP/SSE"| node_gateway
node_gateway -->|"dispatches turn"| node_agent_loop
node_agent_defs -->|"configures agent"| node_agent_loop
node_agent_loop -->|"requests completion"| node_providers
node_providers -->|"calls model"| node_model_service
node_agent_loop -->|"reads/writes history"| node_session_memory
node_agent_loop -->|"retrieves knowledge"| node_rag
node_agent_loop -->|"requests embeddings"| node_embedding_router
node_embedding_router -->|"forwards embedding"| node_providers
node_agent_loop -->|"discovers and invokes tools"| node_mcp_clients
node_mcp_clients -.->|"connects to servers"| node_plugin_services
node_agent_loop -->|"checks tool permission"| node_approvals
node_operator -->|"governs platform"| node_admin
node_scheduler -->|"runs pass"| node_evolution
node_evolution -->|"persists proposals"| node_evolution_store
node_operator -->|"reviews proposals"| node_evolution_store

click node_channels "https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-channels/src/corlinman_channels"
click node_admin "https://github.com/sweetcornna/corlinman/tree/main/ui"
click node_gateway "https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-server/src/corlinman_server"
click node_agent_loop "https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-agent/src/corlinman_agent/reasoning_loop.py"
click node_agent_defs "https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-agent/src/corlinman_agent/agents"
click node_providers "https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-providers/src/corlinman_providers"
click node_embedding_router "https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-providers/src/corlinman_providers/embedding_router.py"
click node_session_memory "https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-agent/src/corlinman_agent/session.py"
click node_rag "https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-memory-host/src/corlinman_memory_host"
click node_plugin_runtime "https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-mcp-server/src/corlinman_mcp_server"
click node_mcp_clients "https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-mcp-server/src/corlinman_mcp_server/client_manager.py"
click node_approvals "https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-agent/src/corlinman_agent/approval_gate.py"
click node_scheduler "https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-server/src/corlinman_server/scheduler/builtins/evolution_engine_run_once.py"
click node_evolution "https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-evolution-engine/src/corlinman_evolution_engine/engine.py"
click node_evolution_store "https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-evolution-engine/src/corlinman_evolution_engine/store.py"

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_channels,node_admin,node_gateway,node_user toneBlue
class node_agent_loop,node_agent_defs,node_providers toneAmber
class node_embedding_router,node_session_memory,node_rag,node_model_service,node_plugin_services toneMint
class node_plugin_runtime,node_mcp_clients,node_approvals toneRose
class node_scheduler,node_evolution,node_evolution_store,node_operator toneIndigo
```

## Components

### User Interfaces

- [Chat Channels](https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-channels/src/corlinman_channels): `python/packages/corlinman-channels/src/corlinman_channels`
- [Admin Console](https://github.com/sweetcornna/corlinman/tree/main/ui): `ui`
- [Gateway](https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-server/src/corlinman_server): `python/packages/corlinman-server/src/corlinman_server`

### Agent Runtime

- [Reasoning Loop](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-agent/src/corlinman_agent/reasoning_loop.py): `python/packages/corlinman-agent/src/corlinman_agent/reasoning_loop.py`
- [Agent Definitions](https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-agent/src/corlinman_agent/agents): `python/packages/corlinman-agent/src/corlinman_agent/agents`
- [Model Providers](https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-providers/src/corlinman_providers): `python/packages/corlinman-providers/src/corlinman_providers`

### Memory and Retrieval

- [Embedding Router](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-providers/src/corlinman_providers/embedding_router.py): `python/packages/corlinman-providers/src/corlinman_providers/embedding_router.py`
- [Session History](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-agent/src/corlinman_agent/session.py): `python/packages/corlinman-agent/src/corlinman_agent/session.py`
- [Knowledge Retrieval](https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-memory-host/src/corlinman_memory_host): `python/packages/corlinman-memory-host/src/corlinman_memory_host`

### Tools and Governance

- [Plugin Runtime](https://github.com/sweetcornna/corlinman/tree/main/python/packages/corlinman-mcp-server/src/corlinman_mcp_server): `python/packages/corlinman-mcp-server/src/corlinman_mcp_server`
- [MCP Clients](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-mcp-server/src/corlinman_mcp_server/client_manager.py): `python/packages/corlinman-mcp-server/src/corlinman_mcp_server/client_manager.py`
- [Approval Gate](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-agent/src/corlinman_agent/approval_gate.py): `python/packages/corlinman-agent/src/corlinman_agent/approval_gate.py`

### Operations

- [Scheduler](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-server/src/corlinman_server/scheduler/builtins/evolution_engine_run_once.py): `python/packages/corlinman-server/src/corlinman_server/scheduler/builtins/evolution_engine_run_once.py`
- [Evolution Engine](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-evolution-engine/src/corlinman_evolution_engine/engine.py): `python/packages/corlinman-evolution-engine/src/corlinman_evolution_engine/engine.py`
- [Evolution Store](https://github.com/sweetcornna/corlinman/blob/main/python/packages/corlinman-evolution-engine/src/corlinman_evolution_engine/store.py): `python/packages/corlinman-evolution-engine/src/corlinman_evolution_engine/store.py`

### Other components

- **User**
- **Model APIs**
- **External MCP Servers**
- **Operator**

## Connections

- User → Chat Channels: sends message
- Chat Channels → Gateway: routes request
- User → Admin Console: uses console
- Admin Console → Gateway: HTTP/SSE
- Gateway → Reasoning Loop: dispatches turn
- Agent Definitions → Reasoning Loop: configures agent
- Reasoning Loop → Model Providers: requests completion
- Model Providers → Model APIs: calls model
- Reasoning Loop → Session History: reads/writes history
- Reasoning Loop → Knowledge Retrieval: retrieves knowledge
- Reasoning Loop → Embedding Router: requests embeddings
- Embedding Router → Model Providers: forwards embedding
- Reasoning Loop → MCP Clients: discovers and invokes tools
- MCP Clients → External MCP Servers: connects to servers
- Reasoning Loop → Approval Gate: checks tool permission
- Operator → Admin Console: governs platform
- Scheduler → Evolution Engine: runs pass
- Evolution Engine → Evolution Store: persists proposals
- Operator → Evolution Store: reviews proposals