Saravana Achu Mac
83bc3af260
Created detailed documentation files to guide coding agents in implementing the fixes and improvements identified in the functionality review: 1. API_DOCUMENTATION_GUIDE.md - Complete API endpoint catalog - Authentication documentation - REST API endpoints (health, user, trading, orders, market data, research, backtesting, feature flags, admin) - WebSocket namespaces (/trading, /admin, /) - Error responses and error codes - Rate limiting recommendations - Request ID propagation - Deprecation policy - OpenAPI/Swagger generation guide - Documentation maintenance process 2. ARCHITECTURE_DOCUMENTATION.md - System overview and high-level architecture - Monorepo structure and directory layout - Backend architecture (component structure, data flow, trading loop) - Web architecture (component structure, data flow, UI architecture) - Mobile architecture (component structure, data flow) - Shared code architecture (shared modules, platform integration) - Data architecture (Cosmos DB containers, data flow) - Service boundaries (backend, platform-service, web, mobile responsibilities) - Integration points (backend ↔ platform-service, web ↔ backend, mobile ↔ backend, etc.) - Security architecture (authentication, authorization, tenant isolation) - Monitoring & observability (telemetry, logging) - Deployment architecture (Docker, environment variables) - Scalability considerations (horizontal scaling, WebSocket scaling) 3. TROUBLESHOOTING_GUIDE.md - Backend issues (won't start, health check failing, trading loop not running, orders not executing, reconciliation failures) - Web issues (won't load, authentication failing, WebSocket connection failing, data not updating) - Mobile issues (won't launch, authentication failing, WebSocket connection failing, data not updating) - Database issues (Cosmos DB connection failing, slow performance, data inconsistency) - Authentication issues (platform-service unreachable, JWT token invalid) - WebSocket issues (connection drops, not receiving events) - Performance issues (backend slow response times, web slow load times) - Deployment issues (Docker build failing, container won't start) - Escalation procedures (when to escalate, escalation steps, on-call contact, incident response) - Common error messages (backend, web, mobile) - Monitoring and alerts (key metrics, alert thresholds, monitoring tools) 4. ONBOARDING_GUIDE.md - Project overview (what is the trading dashboard, tech stack, key concepts) - Prerequisites (required software, required accounts, optional tools) - Development setup (clone repo, install dependencies, configure environment, verify setup) - Project structure (monorepo layout, key files) - Development workflow (starting development, making changes, commit message format, pushing changes) - Testing (backend tests, web tests, mobile tests, verification script) - Code review process (PR process, PR checklist, code review guidelines) - Common tasks (adding backend endpoint, adding web component, adding mobile screen, adding feature flag) - Resources (documentation, external documentation, tools) - Getting help (internal resources, common issues, asking questions) - Best practices - Next steps (first week, first month, ongoing) These documentation files provide detailed guidance for coding agents to implement the fixes and improvements identified in FUNCTIONALITY_REVIEW.md without needing to understand the entire codebase from scratch.
49 KiB
49 KiB
Architecture Documentation
Purpose: Comprehensive architecture documentation for the trading dashboard monorepo, covering system design, data flow, service boundaries, and integration points.
Target Audience: System architects, backend developers, frontend developers, DevOps engineers.
System Overview
The trading dashboard is a monorepo containing three product surfaces (backend, web, mobile) that share common platform packages and communicate via REST APIs and WebSockets.
High-Level Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Trading Dashboard │
│ (Monorepo: learning_ai_invt_trdg) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Backend │ │ Web │ │ Mobile │ │
│ │ (port 4018) │ │ (port 3050) │ │ (Expo App) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Azure Cosmos DB │ │
│ │ (Primary Store) │ │
│ └──────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Common Platform Services │
│ (learning_ai_common_plat) │
├─────────────────────────────────────────────────────────────────┤
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Platform-Service │ │ Gitea Registry │ │
│ │ (port 4003) │ │ (npm packages) │ │
│ └──────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Monorepo Structure
Directory Layout
learning_ai_invt_trdg/
├── backend/ # Trading backend service
│ ├── src/
│ │ ├── strategies/ # Trading strategy engine
│ │ ├── services/ # Business logic services
│ │ ├── connectors/ # Exchange connectors
│ │ ├── config/ # Configuration
│ │ ├── scripts/ # Maintenance scripts
│ │ └── bootstrap.ts # Server entry point
│ ├── Dockerfile
│ └── package.json
│
├── web/ # Web dashboard (Vite + React 19)
│ ├── src/
│ │ ├── views/ # Page components
│ │ ├── components/ # Reusable components
│ │ ├── hooks/ # Custom React hooks
│ │ ├── lib/ # API clients, utilities
│ │ ├── context/ # React contexts
│ │ └── main.tsx # Entry point
│ ├── e2e/ # Playwright E2E tests
│ ├── stories/ # Storybook stories
│ ├── Dockerfile
│ └── package.json
│
├── mobile/ # Mobile app (Expo + React Native)
│ ├── app/ # Expo Router screens
│ │ ├── (tabs)/ # Tab navigation
│ │ ├── _layout.tsx # Root layout
│ │ ├── marketplace.tsx
│ │ └── chat.tsx
│ ├── components/ # Mobile components
│ ├── lib/ # Mobile utilities
│ ├── providers/ # React Native providers
│ ├── Dockerfile
│ └── package.json
│
├── shared/ # Shared code
│ ├── product.json # Canonical product identity
│ ├── platform-*.ts # Platform integration
│ ├── feature-flags.ts # Feature flag definitions
│ ├── realtime.ts # WebSocket contracts
│ └── runtime.ts # Runtime configuration
│
├── docs/ # Documentation
│ ├── planned/ # Planned work documentation
│ ├── inprogress/ # In-progress work documentation
│ └── completed/ # Completed work documentation
│
├── scripts/ # Root scripts
│ ├── tests/ # Test runners
│ ├── verify.sh # Verification script
│ └── dev.sh # Development script
│
├── package.json # Root package.json
├── pnpm-workspace.yaml # Workspace configuration
├── docker-compose.yml # Production Docker compose
├── docker-compose.dev.yml # Development Docker compose
└── .env.example # Environment variables template
Backend Architecture
Component Structure
backend/src/
├── bootstrap.ts # Server entry point
├── config/ # Configuration loading
│ └── index.ts
│
├── strategies/ # Trading strategy engine
│ ├── ProStrategyEngine.ts # Main strategy orchestrator
│ ├── rules/ # 7-rule pipeline
│ │ ├── TrendBiasRule.ts
│ │ ├── SessionRule.ts
│ │ ├── ZoneRule.ts
│ │ ├── MomentumRule.ts
│ │ ├── EntryTriggerRule.ts
│ │ ├── RiskManagementRule.ts
│ │ └── AIAnalysisRule.ts
│ └── directionTracker.ts
│
├── services/ # Business logic
│ ├── apiServer.ts # REST API server (183KB - needs refactoring)
│ ├── TradeExecutor.ts # Order execution (128KB - needs refactoring)
│ ├── AutoTrader.ts # Automated trading
│ ├── ManualTrader.ts # Manual trading
│ ├── riskEngine.ts # Risk management
│ ├── executionManager.ts # Execution orchestration
│ ├── reconciliationService.ts # Trade reconciliation
│ ├── tradingTelemetry.ts # Telemetry singleton
│ ├── platformAuthService.ts # Platform auth integration
│ ├── SupabaseService.ts # Legacy Supabase (118KB - needs refactoring)
│ ├── legacySupabaseClient.ts # Legacy Supabase client
│ ├── observabilityService.ts # Observability
│ ├── healthTracker.ts # Health monitoring
│ ├── notifier.ts # Notification service
│ └── [Repositories] # Cosmos-backed repositories
│ ├── profileRepository.ts
│ ├── tradingControlRepository.ts
│ ├── snapshotRepository.ts
│ ├── capitalLedgerRepository.ts
│ ├── dynamicConfigRepository.ts
│ ├── distributedLockRepository.ts
│ ├── runtimeOrderRepository.ts
│ ├── tradeHistoryRepository.ts
│ ├── manualEntryRepository.ts
│ ├── orderActivityRepository.ts
│ └── auditRepository.ts
│
├── connectors/ # Exchange integrations
│ ├── factory.ts # Connector factory
│ ├── alpaca.ts # Alpaca connector
│ └── ccxt.ts # CCXT connector
│
├── domain/ # Domain models
│ └── tradingEnums.ts
│
├── scripts/ # Maintenance scripts
│ ├── verifyWebsocketContract.ts
│ ├── reconcileTradeLifecycle.ts
│ ├── cleanupStaleOrders.ts
│ └── revertExpiredOrders.ts
│
└── utils/ # Utilities
├── symbolMapper.ts
└── [other utilities]
Data Flow
┌─────────────┐
│ Market │
│ Data API │
└──────┬──────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Backend Trading Loop │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Fetch │ │ 7-Rule │ │ Risk │ │ Execute │ │
│ │ Market │──│ Strategy │──│ Engine │──│ Order │ │
│ │ Data │ │ Engine │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └────┬─────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Exchange API │ │
│ │ (Alpaca/CCXT) │ │
│ └──────────────────┘ │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────┐
│ Azure Cosmos DB │
│ (Primary Store) │
└──────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ WebSocket Broadcast │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ /trading │ │ /admin │ │ / │ │ Bot │ │
│ │ (user) │ │ (admin) │ │ (legacy) │ │ State │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└──────────────────────────────────────────────────────────────┘
│
▼
┌──────────────┐ ┌──────────────┐
│ Web │ │ Mobile │
│ Dashboard │ │ App │
└──────────────┘ └──────────────┘
Trading Loop Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Trading Loop (POLLING_INTERVAL) │
├─────────────────────────────────────────────────────────────────┤
│ │
│ For each user → profile → symbol: │
│ │
│ 1. Fetch market data (price, indicators) │
│ 2. Run 7-rule ProStrategyEngine: │
│ a. TrendBiasRule - EMA 50/200 trend filter │
│ b. SessionRule - Market hours gating │
│ c. ZoneRule - Price proximity to S/R zones │
│ d. MomentumRule - RSI confirmation │
│ e. EntryTriggerRule - EMA reclaim / pattern detection │
│ f. RiskManagementRule - ATR-based stop sizing │
│ g. AIAnalysisRule - LLM sentiment (Perplexity → OpenAI) │
│ │
│ 3. Route signal through: │
│ a. AutoTrader - Automated trading logic │
│ b. riskEngine - Risk checks │
│ c. TradeExecutor - Order execution │
│ d. Exchange connector - Order submission │
│ │
│ 4. Persist to Cosmos: │
│ a. Orders → runtimeOrderRepository │
│ b. Positions → runtimeOrderRepository │
│ c. Trade history → tradeHistoryRepository │
│ d. Capital ledger → capitalLedgerRepository │
│ e. Audit events → auditRepository │
│ │
│ 5. Broadcast via WebSocket: │
│ a. /trading namespace → user-scoped updates │
│ b. /admin namespace → admin-scoped updates │
│ │
└─────────────────────────────────────────────────────────────────┘
Web Architecture
Component Structure
web/src/
├── main.tsx # Entry point
├── App.tsx # Root app component
├── App.css # Global styles
├── index.css # CSS variables / design tokens
│
├── views/ # Page components
│ ├── HomeView.tsx # Dashboard overview
│ ├── PortfolioView.tsx # Portfolio view
│ ├── ResearchView.tsx # Research/screener
│ ├── ScreenerView.tsx # Stock screener
│ ├── SettingsView.tsx # User settings
│ ├── AlertsView.tsx # Alerts
│ ├── WatchlistView.tsx # Watchlist
│ └── MarketsView.tsx # Markets
│
├── components/ # Reusable components
│ ├── AuthContext.tsx # Auth context
│ ├── Login.tsx # Login component
│ ├── ChatControl.tsx # Chat copilot (58KB - needs refactoring)
│ ├── TradeProfileManager.tsx # Profile manager (92KB - needs refactoring)
│ ├── EntryForm.tsx # Manual entry form
│ ├── StrategyWizard.tsx # Strategy wizard
│ ├── GlobalConfigManager.tsx # Config manager
│ ├── AlertFeed.tsx # Alert feed
│ ├── PriceChart.tsx # Price chart
│ ├── SymbolCard.tsx # Symbol card
│ ├── MarketOpportunities.tsx # Market opportunities
│ ├── LivePulseTicker.tsx # Live ticker
│ ├── MarketTicker.tsx # Market ticker
│ ├── ProductAvailabilityGate.tsx # Kill-switch gate
│ ├── ResetPassword.tsx # Password reset
│ ├── PresetMarketplace.tsx # Marketplace presets
│ └── ui/ # UI primitives (product adapter)
│ └── Primitives.tsx # @bytelyst/ui adapter
│
├── hooks/ # Custom React hooks
│ ├── useWebSocket.ts # WebSocket hook
│ ├── useTabFeatureFlags.ts # Feature flag hook
│ └── useCanonicalLifecycle.ts # Lifecycle hook
│
├── context/ # React contexts
│ └── AppContext.tsx # App context
│
├── lib/ # Utilities and API clients
│ ├── api-helpers.ts # API helpers
│ ├── auth.ts # Auth client
│ ├── marketApi.ts # Market data API
│ ├── product-config.ts # Product config
│ ├── platform.ts # Platform client
│ ├── telemetry.ts # Telemetry client
│ └── [other utilities]
│
├── tabs/ # Tab-specific code
│ └── [tab-specific components]
│
└── test/ # Test utilities
Data Flow
┌──────────────┐
│ Web │
│ Dashboard │
└──────┬───────┘
│
│ 1. Authenticate
▼
┌──────────────────┐
│ Platform-Service │
│ (JWT Auth) │
└────────┬─────────┘
│
│ 2. Get platform JWT
▼
┌──────────────┐
│ Web │
│ Dashboard │
└──────┬───────┘
│
│ 3. REST API calls
▼
┌──────────────────┐
│ Backend API │
│ (port 4018) │
└────────┬─────────┘
│
│ 4. WebSocket connection
▼
┌──────────────────┐
│ WebSocket / │
│ trading │
└────────┬─────────┘
│
│ 5. Real-time updates
▼
┌──────────────┐
│ Web │
│ Dashboard │
└──────────────┘
UI Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Web UI Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ App Shell │ │
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ │ Sidebar │ │ Main │ │ Right │ │ │
│ │ │ (Nav) │ │ Content │ │ Panel │ │ │
│ │ └──────────┘ └──────────┘ └──────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Product Adapter Layer │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ Primitives.tsx - @bytelyst/ui adapter │ │ │
│ │ │ - Product-specific variants │ │ │
│ │ │ - Status tone mapping │ │ │
│ │ │ - Component wrappers │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Common Platform UI (@bytelyst/ui) │ │
│ │ - Badge, Button, AlertBanner, DataTable, etc. │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Design Tokens (@bytelyst/design-tokens) │ │
│ │ - CSS variables for colors, spacing, typography │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Mobile Architecture
Component Structure
mobile/
├── app/ # Expo Router screens
│ ├── _layout.tsx # Root layout
│ ├── (tabs)/ # Tab navigation
│ │ ├── _layout.tsx # Tab layout
│ │ ├── index.tsx # Overview tab
│ │ ├── positions.tsx # Positions tab
│ │ ├── history.tsx # History tab
│ │ ├── strategies.tsx # Strategies tab
│ │ └── settings.tsx # Settings tab
│ ├── marketplace.tsx # Marketplace (modal)
│ ├── chat.tsx # Chat (modal)
│ └── +not-found.tsx # 404 screen
│
├── components/ # Mobile components
│ ├── ProductAvailabilityGate.tsx # Kill-switch gate
│ ├── AuthGate.tsx # Auth gate
│ └── [other components]
│
├── lib/ # Mobile utilities
│ ├── runtime.ts # Runtime configuration
│ ├── error-utils.ts # Error utilities
│ ├── telemetry.ts # Telemetry client
│ └── [other utilities]
│
├── providers/ # React Native providers
│ ├── MobileAuthProvider.tsx # Auth provider
│ └── TradingDataProvider.tsx # Trading data provider
│
├── hooks/ # Custom hooks
│ └── useFrameworkReady.ts # Framework ready hook
│
├── constants/ # Constants
│ └── [constants]
│
└── utils/ # Utilities
└── [utilities]
Data Flow
┌──────────────┐
│ Mobile │
│ App │
└──────┬───────┘
│
│ 1. Authenticate
▼
┌──────────────────┐
│ Platform-Service │
│ (JWT Auth) │
└────────┬─────────┘
│
│ 2. Get platform JWT
▼
┌──────────────┐
│ Mobile │
│ App │
│ (Secure │
│ Storage) │
└──────┬───────┘
│
│ 3. REST API calls
▼
┌──────────────────┐
│ Backend API │
│ (port 4018) │
└────────┬─────────┘
│
│ 4. WebSocket connection
▼
┌──────────────────┐
│ WebSocket / │
│ trading │
└────────┬─────────┘
│
│ 5. Real-time updates
▼
┌──────────────┐
│ Mobile │
│ App │
└──────────────┘
Shared Code Architecture
Shared Modules
shared/
├── product.json # Canonical product identity
│ - productId: "invttrdg"
│ - displayName: "ByteLyst Trading"
│ - domain: "bytelyst.com"
│ - backendPort: 4018
│ - platforms: ["web", "mobile"]
│
├── product.ts # Product identity loader
├── runtime.ts # Runtime configuration
├── platform-*.ts # Platform integration
│ ├── platform-web.ts # Web platform client
│ ├── platform-mobile.ts # Mobile platform client
│ └── platform-clients.ts # Platform client factory
│
├── platform-mobile.ts # Mobile-specific platform code
├── platform-clients.ts # Platform client exports
├── feature-flags.ts # Feature flag definitions
├── control-plane.ts # Control plane contracts
├── backend-control-config.ts # Backend control config
├── realtime.ts # WebSocket contracts
│ - /trading namespace
│ - /admin namespace
│ - / namespace (legacy)
│
└── request-id.ts # Request ID utilities
Platform Integration
┌─────────────────────────────────────────────────────────────────┐
│ Platform Integration Layer │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ @bytelyst/react-auth (Web) │ │
│ │ - AuthProvider │ │
│ │ - useAuth hook │ │
│ │ - Session management │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ @bytelyst/react-native-platform-sdk (Mobile) │ │
│ │ - Auth bootstrap │ │
│ │ - Secure storage │ │
│ │ - Session management │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Platform-Service │ │
│ │ (port 4003) │ │
│ │ - JWT validation │ │
│ │ - Kill-switch │ │
│ │ - Feature flags │ │
│ │ - Telemetry │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Data Architecture
Cosmos DB Containers
Azure Cosmos DB
├── trading-profiles # User trading profiles
├── trading-control # Global trading control state
├── trading-records # Orders, positions, trade history
├── dynamic-config # Dynamic configuration
├── snapshots # Strategy snapshots
├── capital-ledger # Capital ledger
├── distributed-locks # Distributed locks
└── audit-events # Audit events (needs to be created)
Data Flow
┌──────────────┐
│ Exchange │
│ API │
└──────┬───────┘
│
▼
┌──────────────────┐
│ Backend │
│ Trading Loop │
└──────┬───────────┘
│
│ 1. Write orders, positions, trade history
▼
┌──────────────────┐
│ Cosmos DB │
│ trading-records │
└──────────────────┘
│
│ 2. Read orders, positions, trade history
▼
┌──────────────────┐
│ Web / Mobile │
│ Clients │
└──────────────────┘
Service Boundaries
Backend Responsibilities
- Trading state authority - Orders, positions, lifecycle, reconciliation
- Runtime control - Global trade halt, tenant disable, profile disable
- Trading admin operations - Domain-specific admin actions
- Market data ingestion - Fetch from exchanges
- Order execution - Submit orders to exchanges
- Reconciliation - Ensure data consistency
- Capital ledger - Track capital movements
- Audit logging - Domain audit events
Platform-Service Responsibilities
- Product accessibility controls - Product-wide kill switch, maintenance mode
- Authentication - JWT issuance and validation
- Feature flags - Product-level feature flags
- Telemetry - Product telemetry ingestion
- Kill switch - Product-level kill switch
- Diagnostics - Product diagnostics hooks
Web Responsibilities
- Authenticated presentation - User-facing UI
- User interaction - User flows and actions
- State rendering - Display backend state
- Action requests - Request backend actions
- Kill-switch UX - Display degraded states
- Telemetry client - Send web telemetry
Mobile Responsibilities
- Secure session restore - Session persistence
- Launch-time kill-switch - Check kill switch on launch
- Live monitoring - Display live state
- Safe interventions - Limited safe actions
- Degraded-state handling - Handle offline/degraded states
- Telemetry client - Send mobile telemetry
Integration Points
Backend ↔ Platform-Service
Backend → Platform-Service:
- Validate JWT tokens
- Check kill-switch status
- Fetch feature flags
- Send telemetry events
- Check maintenance mode
Platform-Service → Backend:
- JWT validation results
- Kill-switch status
- Feature flag values
- Telemetry acknowledgments
- Maintenance mode status
Web ↔ Backend
Web → Backend:
- REST API calls (GET, POST, PUT, DELETE)
- WebSocket connection (/trading namespace)
- Request ID propagation
Backend → Web:
- REST API responses
- WebSocket events (bot_state, positions_update, orders_update)
- Request ID echo
Mobile ↔ Backend
Mobile → Backend:
- REST API calls (GET, POST, PUT, DELETE)
- WebSocket connection (/trading namespace)
- Request ID propagation
Backend → Mobile:
- REST API responses
- WebSocket events (bot_state, positions_update, orders_update)
- Request ID echo
Web ↔ Platform-Service
Web → Platform-Service:
- Authenticate user
- Refresh token
- Check kill-switch
- Fetch feature flags
- Send telemetry
Platform-Service → Web:
- JWT token
- Kill-switch status
- Feature flag values
- Telemetry acknowledgments
Mobile ↔ Platform-Service
Mobile → Platform-Service:
- Authenticate user
- Refresh token
- Check kill-switch
- Fetch feature flags
- Send telemetry
Platform-Service → Mobile:
- JWT token
- Kill-switch status
- Feature flag values
- Telemetry acknowledgments
Security Architecture
Authentication Flow
┌──────────────┐
│ User │
└──────┬───────┘
│
│ 1. Sign in
▼
┌──────────────────┐
│ Platform-Service │
│ (Auth) │
└──────┬───────────┘
│
│ 2. Issue JWT
▼
┌──────────────┐
│ Web / │
│ Mobile │
└──────┬───────┘
│
│ 3. Include JWT in requests
▼
┌──────────────────┐
│ Backend │
│ (Validate) │
└──────────────────┘
Authorization Flow
┌──────────────┐
│ Backend │
└──────┬───────┘
│
│ 1. Validate JWT
▼
┌──────────────────┐
│ Extract Role │
│ (admin / user) │
└──────┬───────────┘
│
│ 2. Check permissions
▼
┌──────────────────┐
│ Allow / Deny │
└──────────────────┘
Tenant Isolation
┌──────────────┐
│ Request │
└──────┬───────┘
│
│ 1. Extract tenantId from JWT
▼
┌──────────────────┐
│ Query Scope │
│ (tenantId) │
└──────┬───────────┘
│
│ 2. Enforce tenant scoping
▼
┌──────────────────┐
│ Return only │
│ tenant data │
└──────────────────┘
Monitoring & Observability
Telemetry Architecture
┌──────────────┐
│ Web / │
│ Mobile │
└──────┬───────┘
│
│ 1. Send telemetry events
▼
┌──────────────────┐
│ @bytelyst/ │
│ telemetry-client │
└──────┬───────────┘
│
│ 2. Buffer events
▼
┌──────────────────┐
│ Platform-Service │
│ (Telemetry) │
└──────────────────┘
Logging Architecture
┌──────────────┐
│ Backend │
└──────┬───────┘
│
│ 1. Log events
▼
┌──────────────────┐
│ Structured Logs │
│ (request-id, │
│ timestamp, │
│ level, message) │
└──────┬───────────┘
│
│ 2. Aggregate logs
▼
┌──────────────────┐
│ Log Aggregation │
│ (Loki, etc.) │
└──────────────────┘
Deployment Architecture
Docker Deployment
┌─────────────────────────────────────────────────────────────────┐
│ Docker Deployment Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Docker Compose │ │
│ │ ┌──────────────┐ ┌──────────────┐ │ │
│ │ │ Backend │ │ Web │ │ │
│ │ │ (port 4018) │ │ (port 3085) │ │ │
│ │ └──────────────┘ └──────────────┘ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ platform_net (external network) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Platform-Service (port 4003) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Azure Cosmos DB │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Environment Variables
Backend (.env)
COSMOS_ENDPOINT- Cosmos DB endpointCOSMOS_KEY- Cosmos DB keyCOSMOS_DATABASE- Cosmos DB database namePLATFORM_API_URL- Platform-service URLPLATFORM_AUTH_ENABLED- Enable platform authPLATFORM_JWT_PUBLIC_KEY- JWT public keyJWT_SECRET- Legacy JWT secret (dev only)ALPACA_API_KEY- Alpaca API keyALPACA_API_SECRET- Alpaca API secretFMP_API_KEY- Financial Modeling Prep keyOPENAI_API_KEY- OpenAI API keyENABLE_TRADING- Enable live tradingPAPER_TRADING- Paper trading modeAZURE_KEYVAULT_URL- Azure Key Vault URL
Web (.env.local)
VITE_TRADING_API_URL- Backend API URLVITE_PLATFORM_URL- Platform-service URLVITE_PRODUCT_ID- Product IDVITE_BACKTEST_ENABLED- Backtest enabled
Mobile (.env.local)
EXPO_PUBLIC_PRODUCT_ID- Product IDEXPO_PUBLIC_PLATFORM_URL- Platform-service URLEXPO_PUBLIC_TRADING_API_URL- Backend API URL
Scalability Considerations
Horizontal Scaling
┌─────────────────────────────────────────────────────────────────┐
│ Horizontal Scaling │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Backend │ │ Backend │ │ Backend │ │
│ │ Instance 1 │ │ Instance 2 │ │ Instance 3 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Azure Cosmos DB (Shared) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
WebSocket Scaling
┌─────────────────────────────────────────────────────────────────┐
│ WebSocket Scaling │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Backend │ │ Backend │ │ Backend │ │
│ │ Instance 1 │ │ Instance 2 │ │ Instance 3 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Redis Pub/Sub (for scaling) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Next Steps
Documentation Updates
- Create diagrams for data flow
- Add sequence diagrams for key flows
- Add component interaction diagrams
- Document error handling flows
- Document reconciliation flows
Architecture Improvements
- Refactor large backend services (apiServer, TradeExecutor, SupabaseService)
- Refactor large web components (ChatControl, TradeProfileManager)
- Implement API rate limiting
- Add request tracing
- Add performance monitoring
References
- README.md - Project overview
- PRD.md - Product requirements
- ROADMAP.md - Implementation status
- BACKEND_API_DEPRECATION.md - API deprecation policy
- BACKEND_AUDIT_SCHEMA.md - Audit event schema
- shared/realtime.ts - WebSocket contracts
- shared/product.json - Product identity