# loorksy/nanoagent architecture

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

- Interactive diagram: https://gitdiagram.com/loorksy/nanoagent
- Repository: https://github.com/loorksy/nanoagent

## Overview

mokli is a self-hosted personal AI agent framework, with a browser UI, terminal and chat integrations, APIs, and a companion mobile app. The central workflow is a user request entering through a surface, being handled in a persistent session with model and tool support, and returning a response; scheduled automation and long-term memory extend that workflow. The tree also contains a distinct trading subsystem. Relationships involving unsampled modules are included only where the README documents the capability; source-level wiring is not inferred from directory names.

Main entry points: [`mokli/agent`](https://github.com/loorksy/nanoagent/tree/main/mokli/agent) (Agent Loop), [`mokli-ui/src`](https://github.com/loorksy/nanoagent/tree/main/mokli-ui/src) (Browser UI), [`mokli-ui/backend/mokli_ui/main.py`](https://github.com/loorksy/nanoagent/blob/main/mokli-ui/backend/mokli_ui/main.py) (UI Backend), [`tui/src/app.ts`](https://github.com/loorksy/nanoagent/blob/main/tui/src/app.ts) (Terminal UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["User Surfaces"]
  node_terminal["Terminal UI<br/>[app.ts]"]
  node_browser["Browser UI"]
  node_mobile["Mobile App"]
  node_api["OpenAI API<br/>[server.py]"]
end

subgraph group_runtime["Agent Runtime"]
  node_agent["Agent Loop"]
  node_sessions[("Session Manager<br/>[manager.py]")]
  node_models["Model Providers"]
  node_tools["Agent Tools"]
  node_memory["Long-term Memory"]
  node_cron["Scheduled Automation<br/>[service.py]"]
end

subgraph group_integrations["Integrations"]
  node_channels["Chat Channels<br/>[manager.py]"]
  node_gateway["Agent Gateway<br/>[service.py]"]
  node_sdk["Python SDK<br/>[clients.py]"]
  node_ui_backend["UI Backend<br/>[main.py]"]
  node_retrieval["Retrieval"]
  node_pipeline["Pipeline Routes<br/>[pipelines.py]"]
end

subgraph group_trading["Trading"]
  node_trading_engine["Trade Management<br/>[engine.py]"]
  node_backtest["Backtesting<br/>[engine.py]"]
  node_broker["MT5 Broker"]
end

node_user(("User"))
node_external_chat(("Chat Apps"))

node_user -->|"enters request"| node_terminal
node_user -->|"enters request"| node_browser
node_user -.->|"uses app"| node_mobile
node_user -->|"submits request"| node_api
node_terminal -->|"sends request"| node_agent
node_browser -->|"sends request"| node_agent
node_api -->|"routes request"| node_agent
node_agent -->|"keeps history"| node_sessions
node_agent -->|"routes models"| node_models
node_agent -->|"uses tools"| node_tools
node_agent -->|"uses memory"| node_memory
node_cron -->|"automates work"| node_agent
node_external_chat -->|"sends messages"| node_channels
node_channels -->|"forwards messages"| node_agent
node_gateway -->|"runs agent"| node_agent
node_sdk -->|"integrates with"| node_agent
node_browser -.->|"requests services"| node_ui_backend
node_ui_backend -.->|"uses retrieval"| node_retrieval
node_ui_backend -->|"routes pipelines"| node_pipeline
node_trading_engine -.->|"reads positions"| node_broker
node_backtest -.->|"shares policy"| node_trading_engine

click node_terminal "https://github.com/loorksy/nanoagent/blob/main/tui/src/app.ts"
click node_browser "https://github.com/loorksy/nanoagent/tree/main/mokli-ui/src"
click node_mobile "https://github.com/loorksy/nanoagent/tree/main/mobile/app"
click node_api "https://github.com/loorksy/nanoagent/blob/main/mokli/api/server.py"
click node_agent "https://github.com/loorksy/nanoagent/tree/main/mokli/agent"
click node_sessions "https://github.com/loorksy/nanoagent/blob/main/mokli/session/manager.py"
click node_models "https://github.com/loorksy/nanoagent/tree/main/mokli/providers"
click node_tools "https://github.com/loorksy/nanoagent/tree/main/mokli/agent/tools"
click node_memory "https://github.com/loorksy/nanoagent/tree/main/mokli/agent"
click node_cron "https://github.com/loorksy/nanoagent/blob/main/mokli/cron/service.py"
click node_channels "https://github.com/loorksy/nanoagent/blob/main/mokli/channels/manager.py"
click node_gateway "https://github.com/loorksy/nanoagent/blob/main/mokli/gateway/service.py"
click node_sdk "https://github.com/loorksy/nanoagent/blob/main/mokli/sdk/clients.py"
click node_ui_backend "https://github.com/loorksy/nanoagent/blob/main/mokli-ui/backend/mokli_ui/main.py"
click node_retrieval "https://github.com/loorksy/nanoagent/tree/main/mokli-ui/backend/mokli_ui/retrieval"
click node_pipeline "https://github.com/loorksy/nanoagent/blob/main/mokli-ui/backend/mokli_ui/routers/pipelines.py"
click node_trading_engine "https://github.com/loorksy/nanoagent/blob/main/mokli/trading/management/engine.py"
click node_backtest "https://github.com/loorksy/nanoagent/blob/main/mokli/trading/backtest/engine.py"
click node_broker "https://github.com/loorksy/nanoagent/tree/main/mokli/trading"

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_terminal,node_browser,node_mobile,node_api,node_user toneBlue
class node_agent,node_sessions,node_models,node_tools,node_memory,node_cron toneAmber
class node_channels,node_gateway,node_sdk,node_ui_backend,node_retrieval,node_pipeline toneMint
class node_trading_engine,node_backtest,node_broker toneRose
class node_external_chat toneIndigo
```

## Components

### User Surfaces

- [Terminal UI](https://github.com/loorksy/nanoagent/blob/main/tui/src/app.ts): `tui/src/app.ts`
- [Browser UI](https://github.com/loorksy/nanoagent/tree/main/mokli-ui/src): `mokli-ui/src`
- [Mobile App](https://github.com/loorksy/nanoagent/tree/main/mobile/app): `mobile/app`
- [OpenAI API](https://github.com/loorksy/nanoagent/blob/main/mokli/api/server.py): `mokli/api/server.py`

### Agent Runtime

- [Agent Loop](https://github.com/loorksy/nanoagent/tree/main/mokli/agent): `mokli/agent`
- [Session Manager](https://github.com/loorksy/nanoagent/blob/main/mokli/session/manager.py): `mokli/session/manager.py`
- [Model Providers](https://github.com/loorksy/nanoagent/tree/main/mokli/providers): `mokli/providers`
- [Agent Tools](https://github.com/loorksy/nanoagent/tree/main/mokli/agent/tools): `mokli/agent/tools`
- [Long-term Memory](https://github.com/loorksy/nanoagent/tree/main/mokli/agent): `mokli/agent`
- [Scheduled Automation](https://github.com/loorksy/nanoagent/blob/main/mokli/cron/service.py): `mokli/cron/service.py`

### Integrations

- [Chat Channels](https://github.com/loorksy/nanoagent/blob/main/mokli/channels/manager.py): `mokli/channels/manager.py`
- [Agent Gateway](https://github.com/loorksy/nanoagent/blob/main/mokli/gateway/service.py): `mokli/gateway/service.py`
- [Python SDK](https://github.com/loorksy/nanoagent/blob/main/mokli/sdk/clients.py): `mokli/sdk/clients.py`
- [UI Backend](https://github.com/loorksy/nanoagent/blob/main/mokli-ui/backend/mokli_ui/main.py): `mokli-ui/backend/mokli_ui/main.py`
- [Retrieval](https://github.com/loorksy/nanoagent/tree/main/mokli-ui/backend/mokli_ui/retrieval): `mokli-ui/backend/mokli_ui/retrieval`
- [Pipeline Routes](https://github.com/loorksy/nanoagent/blob/main/mokli-ui/backend/mokli_ui/routers/pipelines.py): `mokli-ui/backend/mokli_ui/routers/pipelines.py`

### Trading

- [Trade Management](https://github.com/loorksy/nanoagent/blob/main/mokli/trading/management/engine.py): `mokli/trading/management/engine.py`
- [Backtesting](https://github.com/loorksy/nanoagent/blob/main/mokli/trading/backtest/engine.py): `mokli/trading/backtest/engine.py`
- [MT5 Broker](https://github.com/loorksy/nanoagent/tree/main/mokli/trading): `mokli/trading`

### Other components

- **User**
- **Chat Apps**

## Connections

- User → Terminal UI: enters request
- User → Browser UI: enters request
- User → Mobile App: uses app
- User → OpenAI API: submits request
- Terminal UI → Agent Loop: sends request
- Browser UI → Agent Loop: sends request
- OpenAI API → Agent Loop: routes request (evidence: `mokli/api/server.py`)
- Agent Loop → Session Manager: keeps history (evidence: `mokli/agent/loop.py`)
- Agent Loop → Model Providers: routes models (evidence: `mokli/agent/loop.py`)
- Agent Loop → Agent Tools: uses tools (evidence: `mokli/agent/loop.py`)
- Agent Loop → Long-term Memory: uses memory
- Scheduled Automation → Agent Loop: automates work
- Chat Apps → Chat Channels: sends messages
- Chat Channels → Agent Loop: forwards messages
- Agent Gateway → Agent Loop: runs agent
- Python SDK → Agent Loop: integrates with (evidence: `mokli/sdk/clients.py`)
- Browser UI → UI Backend: requests services
- UI Backend → Retrieval: uses retrieval
- UI Backend → Pipeline Routes: routes pipelines (evidence: `mokli-ui/backend/mokli_ui/main.py`)
- Trade Management → MT5 Broker: reads positions (evidence: `mokli/trading/management/engine.py`)
- Backtesting → Trade Management: shares policy
