Architecture

How OpenSoul is structured — from startup chain to core data flow.

High-Level Data Flow

Messages flow from channels through the Gateway to the agent runtime and back.

Inbound Channels
WhatsApp
Telegram
Discord
Slack
+25 more
↓
Core Gateway
⚡ Gateway Runtime
Route Resolution
Session Manager
Plugin Registry
↓
Agent & Services
Agent Runtime
Memory & Storage
Skills & Tools
↓
Clients
Web Control UI
CLI / TUI
Native Apps

Startup Chain

How the gateway boots from the entry point to a fully running server.

opensoul.mjs
→
src/entry.ts
→
cli/program
→
gateway/server

The gateway process initializes sidecars for channels, cron jobs, hooks, discovery, and browser control — all orchestrated from src/gateway/server.impl.ts.

Core Data Flow

How a message travels through the system.

  1. Channel Inbound — A message arrives from a channel adapter (e.g. WhatsApp webhook)
  2. Route Resolution — src/routing/resolve-route.ts determines the target agent, workspace, and session
  3. Session Run — The agent runtime executes with the resolved context, calling tools and hooks as needed
  4. Plugin Pipeline — Pre/post hooks, tool calls, and plugins execute in the configured order
  5. Outbound Adapter — The response is sent back through the originating channel

Core Modules

The building blocks of the OpenSoul monorepo.

Gateway

src/gateway/

HTTP & WebSocket server, orchestration layer, sidecar management (channels, cron, hooks, discovery, browser control).

Agent Runtime

src/agents/

Session execution, tool injection, model provider integration, context window management.

Routing

src/routing/

Message-to-agent/session resolution. Supports identity links, thread parents, channel overrides, and multi-agent routing.

Plugins

src/plugins/

Plugin discovery, loading, registry, and runtime API. Powers the extension system for channels, tools, hooks, and providers.

Channels

src/channels/ + extensions/

Channel adapters implementing the ChannelPlugin contract. Each channel is a separate extension package.

Memory

src/memory/

Long-term memory with embedded SQLite + sqlite-vec for vector search. Stores conversations, embeddings, and metadata.

Config System

src/config/

JSON5 config with includes, ${ENV} substitution, Zod validation, and per-plugin schema merging.

Web Control UI

ui/

Browser dashboard built with Lit 3 + Vite. Chat, configuration, session management, and node pairing interface.

CLI

src/cli/ + src/commands/

Commander-based CLI with clack/prompts for interactive flows. Manages gateway, channels, onboarding, and diagnostics.

Native Apps

apps/

macOS (SwiftUI), iOS, Android, and Windows desktop clients. Shared protocol layer in apps/shared/.

Infrastructure

src/infra/

Shared error types, logging (createSubsystemLogger), secret redaction, and cross-cutting utilities.

Plugin SDK

src/plugin-sdk/

Public API surface for external extensions. Import from opensoul/plugin-sdk — never from internal src/* modules.

Repository Layout

High-level directory structure of the pnpm monorepo.

opensoul/
├── src/           Core gateway, agent runtime, routing, config, plugins
├── extensions/    Channel/provider/hook extension packages (30+)
├── ui/            Web Control UI (Lit + Vite)
├── skills/        50+ built-in skills
├── docs/          User and reference documentation
├── apps/          Native clients (Android, iOS, macOS, Windows)
├── packages/      Shared packages and protocol definitions
├── scripts/       Build, release, test, and tooling scripts
├── test/          E2E and integration test suites
└── tools/         Internal development tools

Want to Dive Deeper?

Check out the source code or start building extensions.

Browse Source on GitHub → Quick Start Guide →