# antoniolg/aipal architecture

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

- Interactive diagram: https://gitdiagram.com/antoniolg/aipal
- Repository: https://github.com/antoniolg/aipal

## Overview

Aipal is a Telegram interface to locally executed coding agents. A user message enters through Telegram handlers, is queued and processed by the agent runner, then the response is returned to the chat; media adds transcription or file inputs. Separate branches cover topic/session settings, searchable memory, approvals and session resumption, scripts, recurring cron jobs, and one-shot schedules. The graph follows documented behavior and visible imports/calls; several command and runtime modules are listed but not excerpted, so their internal links are left out where evidence is unavailable.

Main entry points: [`src/commands`](https://github.com/antoniolg/aipal/tree/main/src/commands) (Bot commands), [`src/handlers`](https://github.com/antoniolg/aipal/tree/main/src/handlers) (Message handlers), [`src/services/agent-runner.js`](https://github.com/antoniolg/aipal/blob/main/src/services/agent-runner.js) (Agent runner), [`src/index.js`](https://github.com/antoniolg/aipal/blob/main/src/index.js) (Bot application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_telegram["Telegram interface"]
  node_app["Bot application<br/>[index.js]"]
  node_handlers["Message handlers"]
  node_media["Media processing<br/>[media.js]"]
  node_reply["Telegram replies<br/>[telegram-reply.js]"]
  node_topics["Topic routing<br/>[telegram-topics.js]"]
  node_commands["Bot commands"]
end

subgraph group_agents["Agent execution"]
  node_runner["Agent runner<br/>[agent-runner.js]"]
  node_adapters["Agent adapters"]
  node_appserver["Codex app-server"]
  node_approvals["Approval requests"]
  node_elicitation["Connector requests"]
end

subgraph group_memory["Memory and sessions"]
  node_threadstore[("Thread state<br/>[thread-store.js]")]
  node_memoryevents[("Memory events<br/>[memory-store.js]")]
  node_memoryindex[("Memory index<br/>[memory-index.js]")]
  node_retrieval["Memory retrieval"]
  node_resume["Session resume<br/>[resume-threads.js]"]
end

subgraph group_scheduling["Scheduled work"]
  node_cron["Cron scheduler<br/>[cron-scheduler.js]"]
  node_cronhandler["Cron execution<br/>[cron-handler.js]"]
  node_cronstate[("Cron state<br/>[cron-state.js]")]
  node_oneshot["One-shot scheduler"]
  node_scheduledruns[("Scheduled runs<br/>[scheduled-runs.js]")]
end

subgraph group_operations["Configuration and tools"]
  node_config[("Configuration store<br/>[config-store.js]")]
  node_scripts["Script manager<br/>[script-manager.js]"]
end

node_user(("Telegram user"))
node_telegram{{"Telegram API"}}
node_localagents{{"Local agent CLIs"}}
node_whisper{{"mlx_whisper"}}

node_user -->|"sends messages"| node_handlers
node_handlers -.->|"runs prompts"| node_runner
node_handlers -.->|"processes media"| node_media
node_media -->|"runs prompts"| node_runner
node_media -->|"transcribes audio"| node_whisper
node_runner -.->|"dispatches agent"| node_adapters
node_adapters -->|"invokes CLI"| node_localagents
node_app -->|"loads adapters"| node_adapters
node_app -->|"registers handlers"| node_handlers
node_app -->|"registers commands"| node_commands
node_reply -->|"sends responses"| node_telegram
node_approvals -->|"formats topic context"| node_topics
node_elicitation -->|"formats topic context"| node_topics
node_retrieval -->|"reads events"| node_memoryevents
node_retrieval -->|"queries index"| node_memoryindex
node_retrieval -->|"normalizes topics"| node_threadstore
node_cron -->|"loads configuration"| node_config
node_cron -->|"uses durable state"| node_cronstate
node_cronhandler -->|"runs scheduled prompt"| node_runner
node_cronhandler -->|"sends result"| node_reply
node_oneshot -->|"uses run store"| node_scheduledruns
node_commands -.->|"updates settings"| node_config
node_commands -.->|"manages scripts"| node_scripts
node_commands -.->|"resumes sessions"| node_resume
node_user -->|"uses bot"| node_telegram

click node_app "https://github.com/antoniolg/aipal/blob/main/src/index.js"
click node_handlers "https://github.com/antoniolg/aipal/tree/main/src/handlers"
click node_media "https://github.com/antoniolg/aipal/blob/main/src/handlers/media.js"
click node_reply "https://github.com/antoniolg/aipal/blob/main/src/services/telegram-reply.js"
click node_topics "https://github.com/antoniolg/aipal/blob/main/src/services/telegram-topics.js"
click node_commands "https://github.com/antoniolg/aipal/tree/main/src/commands"
click node_runner "https://github.com/antoniolg/aipal/blob/main/src/services/agent-runner.js"
click node_adapters "https://github.com/antoniolg/aipal/tree/main/src/agents"
click node_appserver "https://github.com/antoniolg/aipal/blob/main/src/services/codex-app-server.js"
click node_approvals "https://github.com/antoniolg/aipal/blob/main/src/services/approval-requests.js"
click node_elicitation "https://github.com/antoniolg/aipal/blob/main/src/services/elicitation-requests.js"
click node_threadstore "https://github.com/antoniolg/aipal/blob/main/src/thread-store.js"
click node_memoryevents "https://github.com/antoniolg/aipal/blob/main/src/memory-store.js"
click node_memoryindex "https://github.com/antoniolg/aipal/blob/main/src/memory-index.js"
click node_retrieval "https://github.com/antoniolg/aipal/blob/main/src/memory-retrieval.js"
click node_resume "https://github.com/antoniolg/aipal/blob/main/src/services/resume-threads.js"
click node_cron "https://github.com/antoniolg/aipal/blob/main/src/cron-scheduler.js"
click node_cronhandler "https://github.com/antoniolg/aipal/blob/main/src/services/cron-handler.js"
click node_cronstate "https://github.com/antoniolg/aipal/blob/main/src/services/cron-state.js"
click node_oneshot "https://github.com/antoniolg/aipal/blob/main/src/one-shot-scheduler.js"
click node_scheduledruns "https://github.com/antoniolg/aipal/blob/main/src/services/scheduled-runs.js"
click node_config "https://github.com/antoniolg/aipal/blob/main/src/config-store.js"
click node_scripts "https://github.com/antoniolg/aipal/blob/main/src/script-manager.js"

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_app,node_handlers,node_media,node_reply,node_topics,node_commands,node_user toneBlue
class node_runner,node_adapters,node_appserver,node_approvals,node_elicitation toneAmber
class node_threadstore,node_memoryevents,node_memoryindex,node_retrieval,node_resume,node_telegram toneMint
class node_cron,node_cronhandler,node_cronstate,node_oneshot,node_scheduledruns toneRose
class node_config,node_scripts,node_localagents,node_whisper toneIndigo
```

## Components

### Telegram interface

- [Bot application](https://github.com/antoniolg/aipal/blob/main/src/index.js): `src/index.js`
- [Message handlers](https://github.com/antoniolg/aipal/tree/main/src/handlers): `src/handlers`
- [Media processing](https://github.com/antoniolg/aipal/blob/main/src/handlers/media.js): `src/handlers/media.js`
- [Telegram replies](https://github.com/antoniolg/aipal/blob/main/src/services/telegram-reply.js): `src/services/telegram-reply.js`
- [Topic routing](https://github.com/antoniolg/aipal/blob/main/src/services/telegram-topics.js): `src/services/telegram-topics.js`
- [Bot commands](https://github.com/antoniolg/aipal/tree/main/src/commands): `src/commands`

### Agent execution

- [Agent runner](https://github.com/antoniolg/aipal/blob/main/src/services/agent-runner.js): `src/services/agent-runner.js`
- [Agent adapters](https://github.com/antoniolg/aipal/tree/main/src/agents): `src/agents`
- [Codex app-server](https://github.com/antoniolg/aipal/blob/main/src/services/codex-app-server.js): `src/services/codex-app-server.js`
- [Approval requests](https://github.com/antoniolg/aipal/blob/main/src/services/approval-requests.js): `src/services/approval-requests.js`
- [Connector requests](https://github.com/antoniolg/aipal/blob/main/src/services/elicitation-requests.js): `src/services/elicitation-requests.js`

### Memory and sessions

- [Thread state](https://github.com/antoniolg/aipal/blob/main/src/thread-store.js): `src/thread-store.js`
- [Memory events](https://github.com/antoniolg/aipal/blob/main/src/memory-store.js): `src/memory-store.js`
- [Memory index](https://github.com/antoniolg/aipal/blob/main/src/memory-index.js): `src/memory-index.js`
- [Memory retrieval](https://github.com/antoniolg/aipal/blob/main/src/memory-retrieval.js): `src/memory-retrieval.js`
- [Session resume](https://github.com/antoniolg/aipal/blob/main/src/services/resume-threads.js): `src/services/resume-threads.js`

### Scheduled work

- [Cron scheduler](https://github.com/antoniolg/aipal/blob/main/src/cron-scheduler.js): `src/cron-scheduler.js`
- [Cron execution](https://github.com/antoniolg/aipal/blob/main/src/services/cron-handler.js): `src/services/cron-handler.js`
- [Cron state](https://github.com/antoniolg/aipal/blob/main/src/services/cron-state.js): `src/services/cron-state.js`
- [One-shot scheduler](https://github.com/antoniolg/aipal/blob/main/src/one-shot-scheduler.js): `src/one-shot-scheduler.js`
- [Scheduled runs](https://github.com/antoniolg/aipal/blob/main/src/services/scheduled-runs.js): `src/services/scheduled-runs.js`

### Configuration and tools

- [Configuration store](https://github.com/antoniolg/aipal/blob/main/src/config-store.js): `src/config-store.js`
- [Script manager](https://github.com/antoniolg/aipal/blob/main/src/script-manager.js): `src/script-manager.js`

### Other components

- **Telegram user**
- **Telegram API**
- **Local agent CLIs**
- **mlx_whisper**

## Connections

- Telegram user → Message handlers: sends messages
- Message handlers → Agent runner: runs prompts
- Message handlers → Media processing: processes media
- Media processing → Agent runner: runs prompts (evidence: `src/handlers/media.js`)
- Media processing → mlx_whisper: transcribes audio
- Agent runner → Agent adapters: dispatches agent
- Agent adapters → Local agent CLIs: invokes CLI
- Bot application → Agent adapters: loads adapters (evidence: `src/agents/index.js`)
- Bot application → Message handlers: registers handlers
- Bot application → Bot commands: registers commands
- Telegram replies → Telegram API: sends responses
- Approval requests → Topic routing: formats topic context (evidence: `src/services/approval-requests.js`)
- Connector requests → Topic routing: formats topic context (evidence: `src/services/elicitation-requests.js`)
- Memory retrieval → Memory events: reads events (evidence: `src/memory-retrieval.js`)
- Memory retrieval → Memory index: queries index (evidence: `src/memory-retrieval.js`)
- Memory retrieval → Thread state: normalizes topics (evidence: `src/memory-retrieval.js`)
- Cron scheduler → Configuration store: loads configuration (evidence: `src/cron-scheduler.js`)
- Cron scheduler → Cron state: uses durable state (evidence: `src/cron-scheduler.js`)
- Cron execution → Agent runner: runs scheduled prompt (evidence: `src/services/cron-handler.js`)
- Cron execution → Telegram replies: sends result (evidence: `src/services/cron-handler.js`)
- One-shot scheduler → Scheduled runs: uses run store (evidence: `src/one-shot-scheduler.js`)
- Bot commands → Configuration store: updates settings
- Bot commands → Script manager: manages scripts
- Bot commands → Session resume: resumes sessions
- Telegram user → Telegram API: uses bot