Architecture Diagram Index
Purpose
This document provides an index of all architecture diagrams and explains what to look for when auditing the platform's security and design.
Diagram Levels
Level 0: System Context
File: 01-context.md
Shows the platform in relation to external systems and users. Identifies:
- External actors (TradingView, Traders, Admins)
- External systems (TopstepX API, PostgreSQL)
- Trust boundaries
- High-level data flows
What to look for:
- Clear separation between external and internal systems
- Proper authentication boundaries
- No direct access from untrusted sources to sensitive systems
Level 1: Container Diagram
File: 02-container.md
Shows the major containers (applications/services) within the platform. Identifies:
- Frontend (Static HTML/JS)
- Backend API (Express/Node.js)
- Database (PostgreSQL)
- External APIs (TopstepX Gateway)
- Trust boundaries between containers
What to look for:
- Frontend never directly accesses database
- Frontend never directly calls TopstepX API
- All sensitive operations go through backend
- Clear separation of concerns
Level 2: Detailed Flows
1. Live Entry Flow
File: flows/01-live-entry.md
Shows the complete flow from TradingView alert to live order placement. Includes:
- Webhook reception
- TopstepX state fetching (source of truth)
- Risk engine calculation
- Safety gates (fail-closed, verification, staleness)
- Order placement
What to look for:
- ❌ FORBIDDEN: UI to TopstepX direct (red dashed line)
- ❌ FORBIDDEN: Live trading using DB state without TopstepX verification
- ✅ REQUIRED: TopstepX state always fetched in live mode
- ✅ REQUIRED: Fail-closed gates block trading on invalid/stale state
- ✅ REQUIRED: Verification mismatch blocks if
fail_closed=true
2. Exit/Reduce Flow
File: flows/02-exit-reduce.md
Shows how exit and reduce-only orders are processed. Includes:
- Order intent determination (
order_intent="exit"or"reduce_only") - Payout mode checks (allow_manage_only, block_new_entries)
- Risk engine validation
- Order execution
What to look for:
- Payout processing modes correctly differentiate entry vs exit
- Exit orders bypass entry restrictions when appropriate
- Risk engine still validates exit orders
3. Pyramiding Flow
File: flows/03-pyramiding.md
Shows the pyramiding decision logic. Includes:
- Consistency rule checks (best day cap)
- Payout security checks
- Risk engine
canPyramid()function - Position size calculation for adds
What to look for:
- Pyramiding blocked when consistency cap reached
- Pyramiding blocked during payout processing
- Pyramiding respects soft threshold
4. Payout Security Flow
File: flows/04-payout.md
Shows payout request and completion flows. Includes:
- Payout request initiation
- Trading lock activation
- Funded account MLL=0 floor logic
- Payout completion and unlock
What to look for:
- Trading locked immediately on payout request
- Floor source priority: TopstepX > config > assumed
- Funded accounts use hard floor instead of trailing drawdown
- Floor source clearly marked in details
5. Consistency Rule Flow
File: flows/05-consistency-rule.md
Shows Topstep consistency rule enforcement (best day less than or equal to 50% profit target). Includes:
- Daily P&L calculation (trading session boundary)
- Cap calculation (best day % of target)
- Soft threshold logic
- Mode differentiation (hard_block, no_new_entries, disable_pyramiding)
What to look for:
- Trading session boundary correctly applied (5pm ET)
- Soft threshold restricts pyramiding before hard cap
- Mode correctly differentiates behavior
6. Simulation Flow
File: flows/06-simulation.md
Shows simulation/backtesting flow. Includes:
- Trade data loading
- Risk engine simulation
- Consistency rule application
- Results aggregation
What to look for:
- ❌ FORBIDDEN: Simulation to Live executor (red dashed line)
- Simulation uses internal state (not TopstepX)
- Consistency rule applied in simulation
- Results never affect live trading
7. Settings & Verification Flow
File: flows/07-settings-verification-refresh.md
Shows settings management and state verification. Includes:
- Settings save/load
- TopstepX state refresh
- Verification mismatch detection
- Warning badge display
What to look for:
- Settings validated before save
- State refresh respects max age
- Mismatch warnings displayed
- No secrets exposed in UI
Legend
All flow diagrams use the following conventions:
- Solid arrows to Allowed data flow
- Red dashed arrows to Forbidden/should never happen paths
- Gate nodes to Fail-closed/verification checkpoints
- Source-of-truth labels to Indicates where data originates
- Security-critical decisions to Highlighted nodes (payout lock, consistency rule, MLL floor, etc.)
Potential Issues Spotted from Structure
✅ Good Practices Identified
- Clear Source of Truth: TopstepX is always the source of truth in live mode
- Fail-Closed Design: Invalid/stale state blocks trading by default
- Trust Boundaries: Frontend never directly accesses database or TopstepX
- Verification Gates: Multiple verification checkpoints prevent stale data usage
- Mode Differentiation: Payout modes correctly handle entry vs exit
⚠️ Areas Requiring Attention
- Simulation Isolation: Ensure simulation never accidentally calls live executor
- State Freshness: UI warnings help but operators must monitor state age
- Floor Source: Assumed floor in funded accounts requires manual verification
- Verification Mismatch: Even with
fail_closed=false, warnings are shown but trading continues
🔒 Security-Critical Decisions
The following decisions are security-critical and must be audited:
- TopstepX State Fetch: Always fetched in live mode, overwrites DB state
- Fail-Closed Gates: Block trading on invalid/stale state (default: ON)
- Payout Lock: Immediately locks trading on payout request
- Consistency Rule: Prevents best day from exceeding 50% of profit target
- Funded Floor: Hard floor replaces trailing drawdown when MLL=0
- Order Intent: Determines if payout modes allow/block orders