Public Architecture
How Aelix becomes a public, multi-tenant, 24/7 product on the Robinhood network, pivoted to the safe Rule-Keeper + Portfolio X-Ray concept, with a real backend.
The desk in this repo is single-user and local: the Portfolio Manager *is* your Claude Code session, tied to one account and your approval. To serve many people, 24/7, that has to move server-side, you can't hold per-user OAuth tokens or run background scans in a browser. This page describes the public architecture that ships in `backend/`.
The core shift
- Local desk (this repo)
- PM = your Claude Code session. One account, one user, your machine, your approval. See Architecture.
- Public backend
- The orchestration runs as a server-side service (in
backend/) that many users hit through a web app. Each user connects their own Robinhood account; the server holds their encrypted token and scans for them around the clock.
System diagram
User (browser / app)
│ HTTPS + JWT
▼
┌──────────────────────── AELIX BACKEND (Node, zero-dep) ───────────────────────┐
│ auth (JWT · scrypt) rules (per-user caps) alerts (per-user) │
│ token vault (AES-256-GCM) ── per-user Robinhood OAuth token, encrypted at rest │
│ Rule-Keeper (deterministic) Portfolio X-Ray (analytics) │
│ scheduler ── scans every connected user on a cadence, even while they're offline│
│ broker client ──────────────┐ store: JSON (dev)/Postgres │
└──────────────────────────────┼─────────────────────── coach: Anthropic (opt.) ─┘
▼
Robinhood Agentic MCP (per user, read-only tools)What the backend contains
| Layer | Job | Prod note |
|---|---|---|
| Auth | Signup/login, JWT sessions, scrypt password hashing | Set a strong JWT_SECRET. |
| Token vault | Encrypts each user's Robinhood OAuth token (AES-256-GCM) before storage | Back VAULT_KEY with a KMS. |
| Rule-Keeper | Deterministic verdict on a trade the user wants to make vs their caps | The product core, no LLM needed. |
| Portfolio X-Ray | Concentration, sector, cash, and rule-vs-reality flags on holdings | Pure analytics, no advice. |
| Scheduler | Runs read-only scans for every connected user 24/7, emits alerts | Swap to a Redis/BullMQ worker to scale. |
| Broker client | Per-user connection to the Robinhood Agentic MCP | mock for dev; mcp for real accounts. |
| Store | Users, tokens, rules, state, alerts | JSON file ships; swap for Postgres. |
| Coach (optional) | Plain-language explanations via the Anthropic Messages API | Off unless an API key is set. |
Human-in-the-loop, preserved
Going 24/7 does not mean going autonomous. The scheduler only runs read-only research and produces alerts + verdicts. Any actual order still belongs to the user, on their own account, with their own approval, the same guardrail as the local desk, just async (notify → the user approves when they can).
Going to production
Real secrets
Set JWT_SECRET and a 32-byte base64 VAULT_KEY. The server refuses to boot in production without them. Back the vault key with a KMS.
Real database
Implement the store interface against Postgres and set STORE_DRIVER=postgres. The JSON driver is for dev/single-node only.
Real broker
Set BROKER_MODE=mcp and verify the live Robinhood MCP tool names/response shapes. Confirm the Agentic beta ToS permits a third-party multi-user app storing user tokens.
Scale the scheduler
Move the in-process loop to a Redis/BullMQ worker pool so scans fan out across processes.
Legal
Keep the anti-advice posture (analyze / guard / alert). Start with a paper-trading tier to sidestep most regulation while you validate, and get counsel before real-money launch.
The concrete endpoints, request/response shapes, and how to run it are in the Backend API reference.