alpaclaudia/docs/ARCHITECTURE.md

Architecture

Overview

┌─────────────────────────────────────────────────────┐
│                   systemd loop service               │
│   alpaclaudia loop  (every 900s, market hours only) │
└───────────────────────────┬─────────────────────────┘
                            │ tick()
                            ▼
┌─────────────────────────────────────────────────────┐
│                    scheduler.tick()                  │
│                                                      │
│  1. snapshot account / positions / orders  ─────────┼──► Alpaca REST
│  2. record_tick()  ─────────────────────────────────┼──► SQLite ticks
│  3. plan_wheel()  ──────────────────────────────────┼──► OrderIntent[]
│  4. plan_trailing_stops()  ─────────────────────────┼──► OrderIntent[]
│  5. risk.check_*()  per intent                      │
│     blocked → logged, dropped                       │
│  6. executor.submit_intent()  ──────────────────────┼──► Alpaca REST
│     (no-op if BOT_MODE=dry)   ──────────────────────┼──► SQLite order_intents
└─────────────────────────────────────────────────────┘

                    ┌─────────────────┐
                    │  Next.js dash   │
                    │  :3030          │
                    │                 │
                    │  reads SQLite ◄─┼── data/alpaclaudia.db
                    │  reads Alpaca ◄─┼── REST (read-only)
                    └─────────────────┘

                    ┌─────────────────┐
                    │ systemd timer   │
                    │ 22:30 Mon–Fri   │
                    │ alpaclaudia     │
                    │ report          │
                    │     │           │
                    │     ▼           │
                    │ Discord webhook │
                    └─────────────────┘

Key files

File	Purpose
bot/alpaclaudia/config.py	Load + validate all config from .env
bot/alpaclaudia/client.py	Alpaca SDK wrappers (account, positions, orders, options chain)
bot/alpaclaudia/state.py	SQLite store: ticks, order_intents, events
bot/alpaclaudia/risk.py	Pre-submit risk gates (pure functions, easily testable)
bot/alpaclaudia/scheduler.py	Orchestration: tick loop, clock check, risk enforcement
bot/alpaclaudia/executor.py	Translate OrderIntent → Alpaca request; dry-run vs live
bot/alpaclaudia/strategies/wheel.py	Wheel strategy: CSP + CC selection logic
bot/alpaclaudia/strategies/trailing_stop.py	Trailing-stop planner for long equity
bot/alpaclaudia/reporter.py	Build + post Discord daily summary
bot/alpaclaudia/__main__.py	Typer CLI: tick / loop / status / report / dump-state

SQLite schema

ticks — portfolio snapshot per tick. Fields: id, ts, equity, cash, buying_power, mode, note

order_intents — every order the bot considered, regardless of outcome. Fields: id, ts, strategy, symbol, side, qty, order_type, limit_price, stop_price, trail_percent, details_json, submitted, alpaca_order_id, status

Status values: dry_run · blocked · error · accepted / Alpaca status string

events — tick metadata and heartbeats. Fields: id, ts, kind, payload_json

Guard rails (two-layer)

BOT_MODE=dry    → executor.submit_intent() records intent to DB only, no network call
BOT_MODE=live   → executor submits to Alpaca

ALPACA_ENV=paper → TradingClient(paper=True) → paper-api.alpaca.markets
ALPACA_ENV=live  → TradingClient(paper=False) → api.alpaca.markets (real money!)

Both must be explicitly set. The defaults are dry + paper.

Risk gates (bot/alpaclaudia/risk.py)

All gates are pure functions returning CheckResult(ok, reason). scheduler.tick() calls the appropriate gate per intent before passing to executor.

Gate	Invariant
check_csp	Collateral ≤ free cash − buffer; ≤ max_position_pct of equity; ≤ max concurrent short puts
check_covered_call	Strike ≥ cost basis; ≥ qty×100 shares held
check_trailing_stop	Long position exists with ≥ qty shares

Strategy flow: Wheel

For each symbol in WHEEL_UNIVERSE:
  shares_held = long stock qty
  short_puts  = count open short put positions

  if shares_held >= 100:
    uncovered_lots = shares_held // 100 − open short calls
    if uncovered_lots > 0:
      → pick covered-call candidate (DTE window, target delta, above cost basis)
      → emit OrderIntent(strategy="wheel:covered_call", side="sell_to_open")

  if short_puts < MAX_SHORT_PUTS_PER_SYMBOL:
    → list option contracts (DTE window)
    → get snapshots (greeks, quotes)
    → pick contract closest to TARGET_DELTA (fallback: closest to OTM_PCT below spot)
    → compute annualised yield; skip if < MIN_ANNUAL_YIELD
    → emit OrderIntent(strategy="wheel:cash_secured_put", side="sell_to_open")

Adding a new strategy

1. Create bot/alpaclaudia/strategies/my_strategy.py with a plan_*() function returning list[OrderIntent].
2. Add a risk gate in risk.py if needed.
3. Wire it into scheduler.tick() — add intents.extend(plan_my_strategy(...)) and a _enforce_risk branch.
4. Add tests in bot/tests/.