# traderalice/openalice architecture

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

- Interactive diagram: https://gitdiagram.com/traderalice/openalice
- Repository: https://github.com/traderalice/openalice

## Overview

1. **This is a pnpm monorepo with two main runtime tiers**
   - The repo is organized into shared packages plus two long-lived backend processes: the **Alice process** and the **UTA service**.
   - The frontend is a separate React/Vite app under `ui/`, and there is also a desktop wrapper in `apps/desktop` (Electron-style main/preload process).

2. **The core architectural boundary is “decide” vs “do”**
   - **Alice process** owns orchestration, AI/workspace execution, research tools, web/API surfaces, and user interaction.
   - **UTA service** owns broker credentials, broker adapters, order execution, trading history, guards, FX, and snapshots.
   - Alice never talks to exchanges directly; it reaches trading through the **UTA protocol/client** layer.

3. **User-facing surfaces hang off the Alice process**
   - The main surfaces are the **Web UI**, the **Inbox**, the **MCP server**, and the **workspace terminal/session UI**.
   - `src/webui` provides HTTP routes, SSE/WebSocket-style live updates, and auth middleware.
   - `src/server/mcp.ts` exposes tools to external MCP clients.
   - The web UI in `ui/` is a Vite React app consuming Alice’s APIs and live channels.

4. **Workspaces are the execution substrate for AI work**
   - A workspace is a per-task directory plus git repo plus persistent terminal session running a native agent CLI such as Claude Code, Codex, opencode, Pi, or shell.
   - `src/workspaces` manages workspace creation, lifecycle, templates, session registry, PTY/process plumbing, and credential/context injection.
   - Workspaces connect back to Alice via `.mcp.json`, so tools are available inside the terminal session rather than through an in-process model loop.

5. **Scheduled automation uses the same workspace substrate**
   - `src/task/cron` implements typed scheduling and event emission.
   - When a scheduled run fires, it spawns a **headless workspace**, not a separate agent runtime.
   - The run reports back through the Inbox, so scheduled and interactive execution share the same operational path.

6. **The shared core in `src/core` is the orchestration backbone**
   - This layer contains the event bus/log, tool registry, inbox storage, media storage, entity store/backlinks, session handling, compaction, and config plumbing.
   - It is the central coordination layer that other subsystems plug into, rather than a business domain itself.
   - Configuration and secrets are modeled as validated JSON stores under the OpenAlice home directory.

7. **Research and analysis are first-class Alice-side domains**
   - `src/domain/market-data` handles cross-asset data access: equities, crypto, commodities, forex, indices, and macro/reference datasets.
   - `src/domain/analysis` provides calculators, indicator functions, and sector-rotation logic.
   - `src/domain/news` collects RSS/news and provides archive/query behavior.
   - These domains are exposed to AI and UI through tool registrations, not by direct broker coupling.

8. **Market data is split between a hosted hub and provider fallbacks**
   - The README describes **TraderHub** as the low-frequency hosted data source for boards and datasets.
   - In code, the market-data layer is abstracted through provider/client adapters and normalized standard models.
   - The data flow is: Alice tools or UI request market data → provider selection / hub fallback → normalized domain models → UI or agent consumption.

9. **Trading is centralized in the UTA service and treated like a state machine**
   - `services/uta/src/domain/trading` contains the trading domain: order entry, order history, position math, cost basis, contract search, FX service, guard pipeline, snapshots, and broker registry/factory.
   - The “Trading-as-Git” model means orders are staged, committed with history, then pushed to execute.
   - Guards such as max position size, cooldown, and symbol whitelist run before execution.
   - Snapshots are taken periodically and after execution for account/equity-curve history.

10. **Broker implementations are isolated behind adapters**
   - The UTA domain supports broker-specific adapters for **Alpaca, CCXT, Interactive Brokers, Longbridge, and MockBroker**.
   - Broker contracts/types live beside each adapter so the rest of the system uses a unified account model.
   - External connectivity is broker-specific, but Alice and the UI only talk to the UTA service through its typed client/protocol boundary.

11. **The IBKR integration is a dedicated package with protocol-heavy internals**
   - `packages/ibkr` contains the Interactive Brokers client bindings, message encoding/decoding, generated protobuf message classes, and tests.
   - This package is effectively the low-level broker transport/codec layer for IBKR, separate from the higher-level UTA domain.
   - `packages/uta-protocol` defines the typed client/schema boundary used to talk to the UTA service.

12. **OpenBB-style market/provider abstraction is another major package boundary**
   - `packages/opentypebb` is a large provider abstraction layer with standard models, provider-specific adapters, routing, and API utilities.
   - It normalizes many external data providers into a common shape for market-data consumption.
   - Its structure mirrors the domain boundaries in `src/domain/market-data`, making it the data-provider side of the research stack.

13. **Security and trust boundaries are explicit**
   - The web boundary has an admin-token gate for non-loopback access, plus CSRF/origin controls for mutations and WebSocket access.
   - Broker credentials are isolated to the UTA service and are not exposed to the agent runtime.
   - The repo also includes `safe/` with threat-model and playbooks, indicating security analysis is part of the operational model.

14. **Deployment is local-first, but container and desktop entrypoints are supported**
   - `src/main.ts`, `src/server/*`, and the root scripts support the monorepo backend runtime.
   - `docker-compose.yml` and the `Dockerfile` package the system with bundled agent CLIs for server/self-hosted use.
   - `apps/desktop` wraps the same system for a desktop distribution path, while the web UI remains the main surface.

15. **Build and test tooling reflect the modular split**
   - The repo uses **pnpm workspaces** and **Turborepo** for build orchestration.
   - `tsup` is used for package/service bundling, Vite for the UI, and Vitest for unit/e2e coverage.
   - The test layout mirrors the architecture: package-level tests for protocol/data layers, domain tests for trading and market data, and E2E tests for broker/service integration.

Main entry points: [`src/main.ts`](https://github.com/traderalice/openalice/blob/master/src/main.ts) (Main runtime), [`src/webui`](https://github.com/traderalice/openalice/tree/master/src/webui) (Web UI), [`src/workspaces`](https://github.com/traderalice/openalice/tree/master/src/workspaces) (Workspaces), [`services/uta/src/domain/trading`](https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading) (Trading domain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_alice["Alice process"]
  node_main["Main runtime<br/>entrypoint<br/>[main.ts]"]
  node_core["Core bus<br/>orchestration core"]
  node_workspaces["Workspaces<br/>execution substrate"]
  node_cron(("Cron engine<br/>scheduler"))
  node_research["Research domains<br/>analysis stack"]
  node_marketdata["Market data<br/>research domain"]
  node_analysis["Analysis<br/>quant domain"]
  node_news["News"]
  node_webui["Web UI<br/>http/live api"]
  node_mcp["MCP server<br/>tool bridge<br/>[mcp.ts]"]
  node_authsvc(("Auth service<br/>security"))
  node_utaclient["UTA client<br/>typed protocol client"]
end

subgraph group_uta["UTA service"]
  node_utaentry["UTA runtime<br/>service entrypoint<br/>[main.ts]"]
  node_trading["Trading domain<br/>execution state machine"]
  node_brokers["Broker adapters<br/>adapter layer"]
  node_guards["Guards<br/>policy pipeline"]
  node_snapshots["Snapshots<br/>history service"]
end

subgraph group_shared["Shared packages"]
  node_protocol["UTA protocol<br/>shared schema"]
  node_ibkr["IBKR package<br/>broker transport"]
  node_opentypebb["OpenTypeBB<br/>provider abstraction"]
end

subgraph group_client["Clients"]
  node_uiapp["React app<br/>vite frontend"]
  node_desktop["Desktop wrapper<br/>electron shell"]
end

subgraph group_ops["Ops & safety"]
  node_safe["Safety docs<br/>threat model"]
  node_deploy["Deploy tooling<br/>packaging"]
end

node_main -->|"boots"| node_core
node_main -->|"hosts"| node_workspaces
node_main -->|"serves"| node_webui
node_main -->|"exports"| node_mcp
node_main -->|"authenticates"| node_authsvc
node_main -->|"calls"| node_utaclient
node_workspaces -->|"logs"| node_core
node_workspaces -->|"runs"| node_cron
node_workspaces -->|"injects"| node_mcp
node_webui -->|"consumes"| node_uiapp
node_webui -->|"reads/writes"| node_core
node_research -->|"includes"| node_marketdata
node_research -->|"includes"| node_analysis
node_research -->|"includes"| node_news
node_marketdata -->|"adapts"| node_opentypebb
node_analysis -->|"uses"| node_marketdata
node_news -->|"sources"| node_opentypebb
node_cron -->|"spawns"| node_workspaces
node_utaclient -->|"speaks"| node_protocol
node_utaentry -->|"hosts"| node_trading
node_trading -->|"routes to"| node_brokers
node_trading -->|"checks"| node_guards
node_trading -->|"records"| node_snapshots
node_brokers -->|"uses"| node_ibkr
node_uiapp -->|"calls"| node_utaclient
node_uiapp -->|"fetches"| node_webui
node_desktop -->|"wraps"| node_webui
node_safe -.->|"documents"| node_webui
node_deploy -.->|"packages"| node_main
node_deploy -.->|"packages"| node_utaentry

click node_main "https://github.com/traderalice/openalice/blob/master/src/main.ts"
click node_core "https://github.com/traderalice/openalice/tree/master/src/core"
click node_workspaces "https://github.com/traderalice/openalice/tree/master/src/workspaces"
click node_cron "https://github.com/traderalice/openalice/tree/master/src/task/cron"
click node_research "https://github.com/traderalice/openalice/tree/master/src/domain"
click node_marketdata "https://github.com/traderalice/openalice/tree/master/src/domain/market-data"
click node_analysis "https://github.com/traderalice/openalice/tree/master/src/domain/analysis"
click node_news "https://github.com/traderalice/openalice/tree/master/src/domain/news"
click node_webui "https://github.com/traderalice/openalice/tree/master/src/webui"
click node_mcp "https://github.com/traderalice/openalice/blob/master/src/server/mcp.ts"
click node_authsvc "https://github.com/traderalice/openalice/tree/master/src/services/auth"
click node_utaclient "https://github.com/traderalice/openalice/tree/master/src/services/uta-client"
click node_utaentry "https://github.com/traderalice/openalice/blob/master/services/uta/src/main.ts"
click node_trading "https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading"
click node_brokers "https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading/brokers"
click node_guards "https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading/guards"
click node_snapshots "https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading/snapshot"
click node_protocol "https://github.com/traderalice/openalice/tree/master/packages/uta-protocol"
click node_ibkr "https://github.com/traderalice/openalice/tree/master/packages/ibkr"
click node_opentypebb "https://github.com/traderalice/openalice/tree/master/packages/opentypebb"
click node_uiapp "https://github.com/traderalice/openalice/tree/master/ui"
click node_desktop "https://github.com/traderalice/openalice/tree/master/apps/desktop"
click node_safe "https://github.com/traderalice/openalice/tree/master/safe"
click node_deploy "https://github.com/traderalice/openalice/tree/master/Dockerfile"

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_main,node_core,node_workspaces,node_cron,node_research,node_marketdata,node_analysis,node_news,node_webui,node_mcp,node_authsvc,node_utaclient toneBlue
class node_utaentry,node_trading,node_brokers,node_guards,node_snapshots toneAmber
class node_protocol,node_ibkr,node_opentypebb toneMint
class node_uiapp,node_desktop toneRose
class node_safe,node_deploy toneIndigo
```

## Components

### Alice process

Orchestration, workspaces, research, UI-facing APIs, and agent-facing tools.

- [Main runtime](https://github.com/traderalice/openalice/blob/master/src/main.ts): entrypoint · Monorepo backend bootstrap and runtime composition. · `src/main.ts`
- [Core bus](https://github.com/traderalice/openalice/tree/master/src/core): orchestration core · Event bus, inbox, tools, sessions, entity/media stores, config, and compaction plumbing. · `src/core`
- [Workspaces](https://github.com/traderalice/openalice/tree/master/src/workspaces): execution substrate · Per-task workspace lifecycle, terminal/session plumbing, templates, credential injection, and headless runs. · `src/workspaces`
- [Cron engine](https://github.com/traderalice/openalice/tree/master/src/task/cron): scheduler · Typed scheduling and event emission that launches headless workspaces. · `src/task/cron`
- [Research domains](https://github.com/traderalice/openalice/tree/master/src/domain): analysis stack · Market data, analysis, and news domains exposed to tools and UI. · `src/domain`
- [Market data](https://github.com/traderalice/openalice/tree/master/src/domain/market-data): research domain · Cross-asset data access, provider selection, hub fallback, and normalized models. · `src/domain/market-data`
- [Analysis](https://github.com/traderalice/openalice/tree/master/src/domain/analysis): quant domain · Calculators, indicators, and sector-rotation logic. · `src/domain/analysis`
- [News](https://github.com/traderalice/openalice/tree/master/src/domain/news): news domain · RSS collection, archive, and query behavior. · `src/domain/news`
- [Web UI](https://github.com/traderalice/openalice/tree/master/src/webui): http/live api · HTTP routes, auth middleware, SSE/live channels, and browser-facing endpoints. · `src/webui`
- [MCP server](https://github.com/traderalice/openalice/blob/master/src/server/mcp.ts): tool bridge · External MCP tool surface for Alice capabilities. · `src/server/mcp.ts`
- [Auth service](https://github.com/traderalice/openalice/tree/master/src/services/auth): security · Session and token stores for Alice-side authentication. · `src/services/auth`
- [UTA client](https://github.com/traderalice/openalice/tree/master/src/services/uta-client): typed protocol client · Typed client boundary used by Alice and the UI to reach trading through UTA. · `src/services/uta-client`

### UTA service

Trading execution runtime, broker adapters, guards, order history, and snapshots.

- [UTA runtime](https://github.com/traderalice/openalice/blob/master/services/uta/src/main.ts): service entrypoint · Self-contained trading service bootstrap and HTTP surface. · `services/uta/src/main.ts`
- [Trading domain](https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading): execution state machine · Unified trading account, order entry/history, position math, contract search, FX, and broker registry. · `services/uta/src/domain/trading`
- [Broker adapters](https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading/brokers): adapter layer · Isolated Alpaca, CCXT, IBKR, Longbridge, MockBroker, and other broker-specific implementations. · `services/uta/src/domain/trading/brokers`
- [Guards](https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading/guards): policy pipeline · Pre-execution checks such as cooldown, max position size, and symbol whitelist. · `services/uta/src/domain/trading/guards`
- [Snapshots](https://github.com/traderalice/openalice/tree/master/services/uta/src/domain/trading/snapshot): history service · Periodic and post-execution account/equity snapshots and storage. · `services/uta/src/domain/trading/snapshot`

### Shared packages

Typed protocol and low-level provider/broker libraries reused across runtimes.

- [UTA protocol](https://github.com/traderalice/openalice/tree/master/packages/uta-protocol): shared schema · Typed schemas and client contract shared by Alice, UI, and UTA service. · `packages/uta-protocol`
- [IBKR package](https://github.com/traderalice/openalice/tree/master/packages/ibkr): broker transport · Interactive Brokers client bindings, codecs, and protobuf message layer. · `packages/ibkr`
- [OpenTypeBB](https://github.com/traderalice/openalice/tree/master/packages/opentypebb): provider abstraction · Market/provider routing, standard models, and external data adapters. · `packages/opentypebb`

### Clients

User-facing frontend and desktop distribution surfaces.

- [React app](https://github.com/traderalice/openalice/tree/master/ui): vite frontend · Browser UI consuming Alice APIs and live channels. · `ui`
- [Desktop wrapper](https://github.com/traderalice/openalice/tree/master/apps/desktop): electron shell · Desktop main/preload wrapper around the same system. · `apps/desktop`

### Ops & safety

Security analysis, deployment packaging, and maintenance tooling.

- [Safety docs](https://github.com/traderalice/openalice/tree/master/safe): threat model · Threat model, playbooks, and security analysis artifacts. · `safe`
- [Deploy tooling](https://github.com/traderalice/openalice/tree/master/Dockerfile): packaging · Docker, compose, and repo-level release/build orchestration. · `Dockerfile`

## Connections

- Main runtime → Core bus: boots · Main runtime composes the orchestration backbone.
- Main runtime → Workspaces: hosts · Main runtime starts and supervises workspace services.
- Main runtime → Web UI: serves · Alice exposes browser-facing routes and live channels.
- Main runtime → MCP server: exports · Alice exposes tools to external MCP clients.
- Main runtime → Auth service: authenticates · Alice uses session/token stores for access control.
- Main runtime → UTA client: calls · Alice reaches trading only through the typed UTA boundary.
- Workspaces → Core bus: logs · Workspace sessions and events feed the central bus and stores.
- Workspaces → Cron engine: runs · Scheduled jobs reuse the workspace substrate via headless runs.
- Workspaces → MCP server: injects · Workspaces mount MCP access for in-terminal tools.
- Web UI → React app: consumes · The React app consumes Alice APIs and live updates.
- Web UI → Core bus: reads/writes · Routes persist and query shared orchestration state.
- Research domains → Market data: includes · Market data is the primary research data boundary.
- Research domains → Analysis: includes · Indicator and sector logic power research workflows.
- Research domains → News: includes · News collection and archive support research flows.
- Market data → OpenTypeBB: adapts · Provider abstraction normalizes external market sources.
- Analysis → Market data: uses · Calculators and indicators depend on market/reference inputs.
- News → OpenTypeBB: sources · News and reference data can come from provider-backed adapters.
- Cron engine → Workspaces: spawns · Scheduled execution starts headless workspace sessions.
- UTA client → UTA protocol: speaks · Typed client and schemas define the service contract.
- UTA runtime → Trading domain: hosts · UTA service entrypoint hosts the trading state machine.
- Trading domain → Broker adapters: routes to · Trading delegates broker-specific behavior through adapters.
- Trading domain → Guards: checks · Guards run before execution.
- Trading domain → Snapshots: records · Execution and periodic snapshots capture trading history.
- Broker adapters → IBKR package: uses · IBKR adapter relies on the low-level broker transport package.
- React app → UTA client: calls · UI trading screens go through the typed UTA client.
- React app → Web UI: fetches · Frontend uses Alice HTTP and live endpoints.
- Desktop wrapper → Web UI: wraps · Desktop shell reuses the same backend surface.
- Safety docs → Web UI: documents · Security playbooks focus on web/auth boundaries.
- Deploy tooling → Main runtime: packages · Docker and compose package the backend runtime.
- Deploy tooling → UTA runtime: packages · Deployment also packages the trading service.