# ljxpython/ai-agent-platform architecture

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

- Interactive diagram: https://gitdiagram.com/ljxpython/ai-agent-platform
- Repository: https://github.com/ljxpython/ai-agent-platform

## Overview

This is an enterprise AI-agent platform split into a governance/control-plane API, a Vue console, and a LangGraph runtime. The main user journey is: authenticate and choose a project or agent in the console; the platform authorizes the request and assembles managed runtime parameters; the runtime executes the graph and tools, then streams run events back for chat and trace display. Other documented product capabilities include model catalog governance, project and identity management, audit, workspace, memory, skills, and human approval. Runtime details beyond the documented flow are not fully represented in the sampled source.

Main entry points: [`apps/platform-api/src/platform_api/main.py`](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/main.py) (Platform API), [`apps/platform-api/src/platform_api/modules/runtime_gateway/application/service.py`](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/runtime_gateway/application/service.py) (Runtime Gateway), [`apps/runtime-service/src/runtime_service/graphs`](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service/graphs) (Agent Graphs), [`apps/runtime-service/src/runtime_service/services/dearflow_agent`](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service/services/dearflow_agent) (DeerFlow Capabilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Web Console"]
  node_chat["Chat Session<br/>[useChatSession.ts]"]
  node_chatapi["Session Service<br/>[session.service.ts]"]
  node_consoleareas["Console Areas"]
end

subgraph group_governance["Platform Governance"]
  node_api["Platform API<br/>[main.py]"]
  node_context["Request Context<br/>[models.py]"]
  node_iam["IAM Policies<br/>[policies.py]"]
  node_projects["Project Governance<br/>[service.py]"]
  node_projectstore["Project Repository<br/>[repository.py]"]
  node_catalog["Model Catalog<br/>[service.py]"]
  node_serviceaccounts["Service Accounts<br/>[service.py]"]
  node_audit["Audit"]
  node_gateway["Runtime Gateway<br/>[service.py]"]
  node_adapter["LangGraph Adapter<br/>[runtime_client.py]"]
end

subgraph group_execution["Agent Execution"]
  node_runtime["Runtime Service"]
  node_resolver["Runtime Resolver<br/>[resolver.py]"]
  node_agent["Agent Graphs"]
  node_tools["Tools and MCP"]
  node_state[("Run State")]
end

subgraph group_workspace["Agent Workspace"]
  node_workspaceui["Workspace UI"]
  node_workspaceapi["Workspace Runtime API<br/>[workspace.py]"]
  node_deerflow["DeerFlow Capabilities"]
end

node_user(("Platform User"))
node_externalservices{{"LLM and MCP Services"}}

node_user -->|"starts chat"| node_chat
node_chat -->|"loads and submits"| node_chatapi
node_chatapi -.->|"sends requests"| node_api
node_api -->|"installs middleware"| node_context
node_api -.->|"routes requests"| node_gateway
node_gateway -->|"uses client"| node_adapter
node_gateway -->|"assembles model settings"| node_catalog
node_gateway -.->|"applies authorization"| node_iam
node_projects -->|"checks policies"| node_iam
node_projects -->|"reads and writes"| node_projectstore
node_serviceaccounts -->|"checks permissions"| node_iam
node_serviceaccounts -->|"checks project grants"| node_projectstore
node_api -.->|"records requests"| node_audit
node_adapter -.->|"forwards runtime calls"| node_runtime
node_runtime -.->|"resolves execution"| node_resolver
node_resolver -.->|"selects graph"| node_agent
node_agent -.->|"invokes tools"| node_tools
node_agent -.->|"requests model or MCP"| node_externalservices
node_agent -.->|"persists run state"| node_state
node_runtime -.->|"streams run events"| node_chatapi
node_workspaceui -.->|"browses workspace"| node_workspaceapi
node_deerflow -.->|"uses sandbox workspace"| node_workspaceapi
node_deerflow -.->|"provides agent tools"| node_tools
node_deerflow -->|"stores task and governance data"| node_state

click node_chat "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-web/src/modules/chat/composables/useChatSession.ts"
click node_chatapi "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-web/src/services/threads/session.service.ts"
click node_consoleareas "https://github.com/ljxpython/ai-agent-platform/tree/main/apps/platform-web/src/modules"
click node_api "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/main.py"
click node_context "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/core/context/models.py"
click node_iam "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/iam/application/policies.py"
click node_projects "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/projects/service.py"
click node_projectstore "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/projects/repository.py"
click node_catalog "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/runtime_catalog/application/service.py"
click node_serviceaccounts "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/service_accounts/service.py"
click node_audit "https://github.com/ljxpython/ai-agent-platform/tree/main/apps/platform-api/src/platform_api/modules/audit"
click node_gateway "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/runtime_gateway/application/service.py"
click node_adapter "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/adapters/langgraph/runtime_client.py"
click node_runtime "https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service"
click node_resolver "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/runtime-service/src/runtime_service/runtime/resolver.py"
click node_agent "https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service/graphs"
click node_tools "https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service/tools"
click node_state "https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service"
click node_workspaceui "https://github.com/ljxpython/ai-agent-platform/tree/main/apps/platform-web/src/components/workspace"
click node_workspaceapi "https://github.com/ljxpython/ai-agent-platform/blob/main/apps/runtime-service/src/runtime_service/http/workspace.py"
click node_deerflow "https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service/services/dearflow_agent"

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_chat,node_chatapi,node_consoleareas,node_user toneBlue
class node_api,node_context,node_iam,node_projects,node_projectstore,node_catalog,node_serviceaccounts,node_audit,node_gateway,node_adapter toneAmber
class node_runtime,node_resolver,node_agent,node_tools,node_state toneMint
class node_workspaceui,node_workspaceapi,node_deerflow toneRose
class node_externalservices toneIndigo
```

## Components

### Web Console

- [Chat Session](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-web/src/modules/chat/composables/useChatSession.ts): `apps/platform-web/src/modules/chat/composables/useChatSession.ts`
- [Session Service](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-web/src/services/threads/session.service.ts): `apps/platform-web/src/services/threads/session.service.ts`
- [Console Areas](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/platform-web/src/modules): `apps/platform-web/src/modules`

### Platform Governance

- [Platform API](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/main.py): `apps/platform-api/src/platform_api/main.py`
- [Request Context](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/core/context/models.py): `apps/platform-api/src/platform_api/core/context/models.py`
- [IAM Policies](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/iam/application/policies.py): `apps/platform-api/src/platform_api/modules/iam/application/policies.py`
- [Project Governance](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/projects/service.py): `apps/platform-api/src/platform_api/modules/projects/service.py`
- [Project Repository](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/projects/repository.py): `apps/platform-api/src/platform_api/modules/projects/repository.py`
- [Model Catalog](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/runtime_catalog/application/service.py): `apps/platform-api/src/platform_api/modules/runtime_catalog/application/service.py`
- [Service Accounts](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/service_accounts/service.py): `apps/platform-api/src/platform_api/modules/service_accounts/service.py`
- [Audit](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/platform-api/src/platform_api/modules/audit): `apps/platform-api/src/platform_api/modules/audit`
- [Runtime Gateway](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/modules/runtime_gateway/application/service.py): `apps/platform-api/src/platform_api/modules/runtime_gateway/application/service.py`
- [LangGraph Adapter](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/platform-api/src/platform_api/adapters/langgraph/runtime_client.py): `apps/platform-api/src/platform_api/adapters/langgraph/runtime_client.py`

### Agent Execution

- [Runtime Service](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service): `apps/runtime-service/src/runtime_service`
- [Runtime Resolver](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/runtime-service/src/runtime_service/runtime/resolver.py): `apps/runtime-service/src/runtime_service/runtime/resolver.py`
- [Agent Graphs](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service/graphs): `apps/runtime-service/src/runtime_service/graphs`
- [Tools and MCP](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service/tools): `apps/runtime-service/src/runtime_service/tools`
- [Run State](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service): `apps/runtime-service`

### Agent Workspace

- [Workspace UI](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/platform-web/src/components/workspace): `apps/platform-web/src/components/workspace`
- [Workspace Runtime API](https://github.com/ljxpython/ai-agent-platform/blob/main/apps/runtime-service/src/runtime_service/http/workspace.py): `apps/runtime-service/src/runtime_service/http/workspace.py`
- [DeerFlow Capabilities](https://github.com/ljxpython/ai-agent-platform/tree/main/apps/runtime-service/src/runtime_service/services/dearflow_agent): `apps/runtime-service/src/runtime_service/services/dearflow_agent`

### Other components

- **Platform User**
- **LLM and MCP Services**

## Connections

- Platform User → Chat Session: starts chat
- Chat Session → Session Service: loads and submits (evidence: `apps/platform-web/src/modules/chat/composables/useChatSession.ts`)
- Session Service → Platform API: sends requests
- Platform API → Request Context: installs middleware (evidence: `apps/platform-api/src/platform_api/main.py`)
- Platform API → Runtime Gateway: routes requests
- Runtime Gateway → LangGraph Adapter: uses client (evidence: `apps/platform-api/src/platform_api/modules/runtime_gateway/application/service.py`)
- Runtime Gateway → Model Catalog: assembles model settings (evidence: `apps/platform-api/src/platform_api/modules/runtime_gateway/application/service.py`)
- Runtime Gateway → IAM Policies: applies authorization
- Project Governance → IAM Policies: checks policies (evidence: `apps/platform-api/src/platform_api/modules/projects/service.py`)
- Project Governance → Project Repository: reads and writes (evidence: `apps/platform-api/src/platform_api/modules/projects/service.py`)
- Service Accounts → IAM Policies: checks permissions (evidence: `apps/platform-api/src/platform_api/modules/service_accounts/service.py`)
- Service Accounts → Project Repository: checks project grants (evidence: `apps/platform-api/src/platform_api/modules/service_accounts/service.py`)
- Platform API → Audit: records requests (evidence: `apps/platform-api/src/platform_api/main.py`)
- LangGraph Adapter → Runtime Service: forwards runtime calls
- Runtime Service → Runtime Resolver: resolves execution (evidence: `apps/runtime-service/src/runtime_service/runtime/auth.py`)
- Runtime Resolver → Agent Graphs: selects graph
- Agent Graphs → Tools and MCP: invokes tools
- Agent Graphs → LLM and MCP Services: requests model or MCP
- Agent Graphs → Run State: persists run state
- Runtime Service → Session Service: streams run events
- Workspace UI → Workspace Runtime API: browses workspace
- DeerFlow Capabilities → Workspace Runtime API: uses sandbox workspace
- DeerFlow Capabilities → Tools and MCP: provides agent tools
- DeerFlow Capabilities → Run State: stores task and governance data (evidence: `apps/runtime-service/src/runtime_service/services/dearflow_agent/external_task_storage.py`)
