API architecture overview

​

Architecture

​

Core components

• Orchestrator (src/index.ts) - State management, message loop, and agent invocation
• Message Router (src/router.ts) - Message formatting and outbound routing
• Container Runner (src/container-runner.ts) - Spawns agent containers with mounts
• Task Scheduler (src/task-scheduler.ts) - Runs scheduled tasks
• Database (src/db.ts) - SQLite operations for messages, groups, and tasks
• Channels (src/channels/) - Channel connections and message delivery

​

Key concepts

​

Groups

• Unique folder in groups/{name}/
• Isolated filesystem and memory
• Persistent session ID
• Optional trigger pattern (default: requires @{ASSISTANT_NAME} mention)

​

Message flow

1. Channel receives message and calls onMessage callback
2. Message is stored in database via storeMessage()
3. Message loop detects new messages for registered groups
4. Router formats messages as XML and passes to agent container
5. Agent processes messages and returns output
6. Output is stripped of <internal> tags and sent back through channel

​

Sessions

​

Database schema

• chats - Chat metadata (JID, name, last activity)
• messages - Full message history for registered groups
• registered_groups - Group configuration and settings
• sessions - Session IDs by group folder
• scheduled_tasks - Task definitions and schedules
• task_run_logs - Task execution history
• router_state - Message cursor positions

​

Configuration files

​

Next steps