traderalice/openalice

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.