Skip to main content

Security Notes for Architecture Documentation

What is Safe to Publish​

✅ Safe to publish publicly:

  • Logical architecture and data flows
  • API endpoint names (e.g., /api/topstepx/risk-state)
  • Module/function names (e.g., calculatePositionSize, getTopstepXRiskState)
  • Database table names (e.g., risk_config, alerts)
  • Configuration field names (e.g., payout_security_enabled, account_floor_balance)
  • Trust boundaries and security gates
  • Flow logic and decision points
  • Integration patterns (TopstepX API, TradingView webhooks)

What Should NEVER Be Published​

❌ Never publish:

  • API keys, tokens, or secrets
  • Actual environment variable values
  • Database connection strings
  • Private URLs or internal IP addresses
  • User credentials or authentication tokens
  • Actual account IDs or user IDs
  • Real balance or P&L values
  • Internal error messages with stack traces
  • Deployment infrastructure details (specific server IPs, ports)

Diagram Update Checklist​

When updating diagrams after code changes, verify:

  • No secrets or keys appear in any diagram
  • No real URLs or IPs are shown (use placeholders like api.topstepx.com)
  • Trust boundaries are clearly marked
  • Source-of-truth labels are accurate
  • Fail-closed gates are explicitly shown
  • Forbidden paths (red dashed lines) are marked
  • Security-critical decisions are highlighted
  • File references match actual codebase structure

Maintenance​

Diagrams should be updated when:

  • New API endpoints are added
  • Risk engine logic changes
  • Security gates are modified
  • Integration patterns change
  • New trust boundaries are introduced