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.
1029 lines
49 KiB
Markdown
1029 lines
49 KiB
Markdown
# 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 endpoint
|
|
- `COSMOS_KEY` - Cosmos DB key
|
|
- `COSMOS_DATABASE` - Cosmos DB database name
|
|
- `PLATFORM_API_URL` - Platform-service URL
|
|
- `PLATFORM_AUTH_ENABLED` - Enable platform auth
|
|
- `PLATFORM_JWT_PUBLIC_KEY` - JWT public key
|
|
- `JWT_SECRET` - Legacy JWT secret (dev only)
|
|
- `ALPACA_API_KEY` - Alpaca API key
|
|
- `ALPACA_API_SECRET` - Alpaca API secret
|
|
- `FMP_API_KEY` - Financial Modeling Prep key
|
|
- `OPENAI_API_KEY` - OpenAI API key
|
|
- `ENABLE_TRADING` - Enable live trading
|
|
- `PAPER_TRADING` - Paper trading mode
|
|
- `AZURE_KEYVAULT_URL` - Azure Key Vault URL
|
|
|
|
**Web (.env.local)**
|
|
- `VITE_TRADING_API_URL` - Backend API URL
|
|
- `VITE_PLATFORM_URL` - Platform-service URL
|
|
- `VITE_PRODUCT_ID` - Product ID
|
|
- `VITE_BACKTEST_ENABLED` - Backtest enabled
|
|
|
|
**Mobile (.env.local)**
|
|
- `EXPO_PUBLIC_PRODUCT_ID` - Product ID
|
|
- `EXPO_PUBLIC_PLATFORM_URL` - Platform-service URL
|
|
- `EXPO_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
|
|
|
|
1. Create diagrams for data flow
|
|
2. Add sequence diagrams for key flows
|
|
3. Add component interaction diagrams
|
|
4. Document error handling flows
|
|
5. Document reconciliation flows
|
|
|
|
### Architecture Improvements
|
|
|
|
1. Refactor large backend services (apiServer, TradeExecutor, SupabaseService)
|
|
2. Refactor large web components (ChatControl, TradeProfileManager)
|
|
3. Implement API rate limiting
|
|
4. Add request tracing
|
|
5. 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
|