Skip to content

Architecture Overview

Runtime Layers

flowchart TD
  client[Expo web and native clients] --> api[FastAPI API]
  client --> auth[Better Auth sidecar]
  api --> db[(Postgres, Timescale, pgvector)]
  api --> valkey[(Valkey cache and queues)]
  api --> journal[Native Journal routes]
  api --> brokers[Broker adapters]
  celery[Celery workers] --> db
  celery --> valkey
  celery --> ai_runtime[TradeMate native LLM compatibility layer]
  celery --> brokers
  ai_runtime --> openai[OpenAI native SDK]
  ai_runtime --> anthropic[Anthropic native SDK]
  api --> signoz[SigNoz traces]
  celery --> phoenix[Phoenix LLM traces]

LLM runtime note: ADR 0017 makes the native compatibility layer the production runtime. Customer AI calls go through TradeMate-owned provider adapters with per-user BYOK keys, Phoenix traces, and database governance/audit records.

Container Topology

flowchart LR
  subgraph Coolify
    web[trademate-web]
    api[trademate-api]
    auth[trademate-auth]
    celery[trademate-celery]
    db[(Postgres)]
    valkey[(Valkey)]
    backup[database-backup cron]
  end
  web --> api
  web --> auth
  api --> auth
  api --> db
  api --> valkey
  celery --> db
  celery --> valkey
  backup --> db
  backup --> s3[S3-compatible backups]

Trade Pipeline

sequenceDiagram
  participant Event as Catalyst Event
  participant Strategy as Strategy Team
  participant Risk as Risk Manager
  participant Order as Order Manager
  participant Broker as Broker Adapter
  participant Journal as API Journal/Audit
  participant PM as Position Manager

  Event->>Strategy: ticker, portfolio, regime context
  Strategy->>Risk: structured signal
  Risk-->>Strategy: block or approved sizing
  Risk->>Order: approved risk decision
  Order->>Broker: paper-safe execution plan
  Broker-->>Journal: order and fill evidence
  Journal-->>PM: canonical trade state
  PM->>Journal: lifecycle events and reflections

The account-level Journal remains the source of truth for trades, fills, agent decisions, and audit events. Strategy history, portfolio recent trades, and agent reflections should query filtered journal/audit data rather than creating parallel history stores.

Stock Intelligence Layer

Ticker research, Smart Screener results, global Derived Universes, Smart Watchlists, strategy analyst agents, Trading Lab validation, and automated trading candidates should consume the same point-in-time stock intelligence scorecard contract. Core Universes define coverage pools, but scorecards are the canonical layer for Growth, Quality, Value, Momentum, Risk, Liquidity, Catalyst, composite scores, ML overlays, data freshness, and cited evidence.

Scorecards can create research and strategy candidates, but cannot execute trades directly. Execution still flows through strategy configuration, deterministic risk checks, order construction, broker adapters, paper/live authorization, and Journal/audit persistence.

See docs/architecture/stock-intelligence-scorecards.md and ADR 0013.