Architecture Overview

Sophon is a modular monolith built on .NET 10. A single Gateway process hosts the REST API, SignalR hubs, scheduler, and background workers; clients (Dashboard, Desktop, Mobile, CLI, DevStudio) connect to it; and sandboxed runtimes (skills, browsers, nodes) execute work on its behalf.

This page is a map of the pieces and how they talk.

The big picture

          ┌─────────────────────────────────────────────────────┐
          │                    Clients                          │
          │  Dashboard   Desktop   Mobile   CLI   DevStudio     │
          └──────────────────────┬──────────────────────────────┘
                                 │  HTTP REST + SignalR
                                 ▼
          ┌─────────────────────────────────────────────────────┐
          │                Sophon Gateway                        │
          │  (ASP.NET Core Minimal APIs + SignalR + Quartz)     │
          │                                                     │
          │   • Auth / RBAC / tenant isolation                  │
          │   • Session + chat message routing                  │
          │   • Cron scheduler, webhook delivery                │
          │   • Push notifications (Expo → APNs / FCM)          │
          │   • Approval gate (SignalR)                         │
          │   • MCP server + Node hub                           │
          └──────────────────────┬──────────────────────────────┘
                                 │
      ┌──────────────────────────┼──────────────────────────┐
      │                          │                          │
      ▼                          ▼                          ▼
┌───────────┐          ┌──────────────────┐      ┌──────────────────┐
│ Sophon.   │          │ Sophon.Core      │      │ Storage & data    │
│ Skills    │          │ domain + orche-  │      │ SQLite / Postgres │
│ (tools)   │◄─────────┤ stration + agent │─────▶│ Qdrant / pgvector │
│           │          │ runtime + memory │      │ ~/.sophon/        │
└─────┬─────┘          └────────┬─────────┘      └──────────────────┘
      │                         │
      ▼                         ▼
┌───────────┐          ┌──────────────────┐
│ Sandboxes │          │ External systems │
│ Docker +  │          │ LLM providers    │
│ gVisor    │          │ OAuth services   │
│ Playwright│          │ MCP servers      │
│ Node      │          │ Channels         │
└───────────┘          └──────────────────┘

Layers and processes

Gateway

The single deployable process. It owns HTTP, WebSockets, scheduled jobs, and background workers. Everything that users and clients talk to, they talk to here.

The Gateway is not a passive proxy — it hosts the orchestration pipeline, runs the scheduler, delivers webhooks, bridges push notifications to Expo/APNs/FCM, serves the MCP server, and coordinates Sophon Nodes over SignalR.

Core (domain)

Sophon.Core is a pure .NET class library — no ASP.NET, no HTTP. It holds the domain model and the orchestration engine:

Agents — personalities, tool allowlists, routing rules
Orchestration pipeline — the 12-middleware chain that processes every user message (Orchestration Pipeline)
Memory engine — user/agent long-term memory plus daily logs (Memory)
Planning — multi-step plan generation and execution (Planning)
Approvals — risk classification and human-in-the-loop gating (Approval Gates)
Credentials — vault abstraction (Local / HashiCorp / AWS / Azure)
Scheduling — cron and one-shot at jobs via Quartz.NET
Webhooks, insights, discussions, remote access — domain services for each feature

Keeping Core HTTP-free means it can be embedded in the CLI, the Desktop app, or tests without dragging the web host along.

Sandboxed runtimes

Some work can't safely run inside the Gateway process. Sophon pushes it into isolated runtimes:

Skills sandbox — Python or C# skill code runs in Docker + gVisor with resource limits, no host filesystem, and explicit network rules.
Browser sandbox — Playwright-driven Chromium with per-profile storage state, used by browser automation skills.
Sophon Node — a lightweight .NET 10 worker that runs on a user's desktop, receives commands from the Gateway over SignalR, and executes screen/input/app/shell automation locally. See Sophon Node.

Clients

Every client talks to the Gateway over HTTPS + SignalR:

Dashboard — React 19 + Vite, shipped from the Gateway. The administrative and everyday-use UI.
Desktop — Electron wrapper around the Dashboard with tray/menu-bar integration.
Mobile — Expo React Native app with push notifications, voice, and a home feed of insights.
DevStudio — Electron IDE for authoring skills, agents, plugins, and apps.
CLI — scripted access to every major feature; uses the same REST API the clients do.

Extensibility surfaces

Sophon is extensible at four points:

Surface	Use when you want to…	Format
Skills	Add a new tool the agent can call	Python/C# + `manifest.json` + `SKILL.md`
Plugins	Deep Gateway extension (new channel, model provider, vault backend)	.NET DLL implementing a gRPC interface
MCP server	Expose any tool over the Model Context Protocol	JSON-RPC; register in `~/.sophon/config/mcp.json`
Apps	Ship a mini-app UI inside Sophon	React + `@sophon/app-sdk`

Data and storage

All user state lives under ~/.sophon/ (data directory separation is a hard rule — application code never writes outside its install dir):

config/ — appsettings.json, appsettings.user.json, mcp.json, mcp-server.json
db/ — SQLite on Personal; Postgres connection string on Pro/Enterprise
documents/ — extracted text, embeddings, FTS5 index
agents/ — per-agent SOUL.md / BOOT.md / HEARTBEAT.md / TOOLS.md / AGENTS.md
memory/ — legacy MEMORY.md + daily logs (migrated to DB on first run)
logs/ — Serilog rolling files

Vector store is pluggable. Personal skips vector search; Pro/Enterprise use Qdrant, Milvus, or pgvector.

Flow of one user message

Follow a single chat turn through the system:

User sends a message from Dashboard (or Mobile / channel adapter).
Gateway's ChatHub enqueues an AgentTask and returns immediately.
BackgroundAgentService dequeues the task and calls the orchestration pipeline (Orchestration Pipeline).
The pipeline budgets, routes to a model provider, compacts context if needed, filters tools, optionally plans, then runs the agentic loop: LLM call → tool execution (parallel / approval-gated / sandboxed) → loop until the LLM produces a final answer.
SignalR streams status + token chunks back to the client in real time.
The final response is saved to session history and fed to the memory engine.
If the user has mobile push on, a notification may fire for completed tasks or pending approvals.

Where to go next

Agents & SOUL — how an agent is defined
Orchestration Pipeline — what the 12 middlewares do
Planning — how complex requests get decomposed
Tiers — which features are available on Personal vs Pro vs Enterprise

Architecture Overview

On this page