From 83bc3af260bc0c8c77a0f71ee2ad7728177974c4 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 9 May 2026 17:02:05 -0700 Subject: [PATCH] docs: add comprehensive documentation for coding agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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. --- docs/planned/API_DOCUMENTATION_GUIDE.md | 662 +++++++++ docs/planned/ARCHITECTURE_DOCUMENTATION.md | 1028 ++++++++++++++ docs/planned/ONBOARDING_GUIDE.md | 737 +++++++++++ docs/planned/TROUBLESHOOTING_GUIDE.md | 1398 ++++++++++++++++++++ 4 files changed, 3825 insertions(+) create mode 100644 docs/planned/API_DOCUMENTATION_GUIDE.md create mode 100644 docs/planned/ARCHITECTURE_DOCUMENTATION.md create mode 100644 docs/planned/ONBOARDING_GUIDE.md create mode 100644 docs/planned/TROUBLESHOOTING_GUIDE.md diff --git a/docs/planned/API_DOCUMENTATION_GUIDE.md b/docs/planned/API_DOCUMENTATION_GUIDE.md new file mode 100644 index 0000000..75d88e2 --- /dev/null +++ b/docs/planned/API_DOCUMENTATION_GUIDE.md @@ -0,0 +1,662 @@ +# API Documentation Guide + +**Purpose:** Comprehensive guide for documenting the trading dashboard API endpoints for consumption by web, mobile, and external clients. + +**Target Audience:** API consumers (web developers, mobile developers, external integrators), backend developers maintaining API contracts. + +--- + +## Overview + +The trading dashboard backend exposes REST APIs and WebSocket endpoints for trading operations, state management, and administrative controls. This guide provides a structured approach to documenting all API endpoints. + +--- + +## Current API Documentation State + +### Existing Documentation + +- **BACKEND_API_DEPRECATION.md** - Lists deprecated endpoints and migration paths +- **docs/BACKEND_AUDIT_SCHEMA.md** - Documents audit event schema +- **docs/BACKEND_LEGACY_SUPABASE_SCRIPTS.md** - Documents legacy Supabase script usage + +### Documentation Gaps + +- No comprehensive API endpoint catalog +- No OpenAPI/Swagger specification +- No request/response examples +- No authentication documentation +- No error response documentation +- No rate limiting documentation +- No WebSocket namespace documentation + +--- + +## API Documentation Structure + +### Recommended Documentation Structure + +Create a comprehensive API documentation file: `docs/API_REFERENCE.md` + +```markdown +# Trading Dashboard API Reference + +## Table of Contents +- Authentication +- REST API Endpoints + - Health & Diagnostics + - User & Profile + - Trading Control + - Orders & Positions + - Trade History + - Market Data + - Research & Screener + - Backtesting + - Feature Flags + - Admin Operations +- WebSocket Namespaces + - /trading (user-scoped) + - /admin (admin-only) + - / (root, backward-compatible) +- Error Responses +- Rate Limiting +- Deprecation Policy +``` + +--- + +## Authentication Documentation + +### Authentication Methods + +**Platform JWT (Recommended for Production)** +```bash +# Request header +Authorization: Bearer +``` + +**Legacy JWT (Local Development Only)** +```bash +# Request header +Authorization: Bearer +``` + +### Token Validation + +Backend validates JWT tokens using: +- Platform public key (production) +- Platform JWKS URL (production) +- JWT_SECRET (local development) + +### Authentication Endpoints + +**GET /api/me/profile** +- **Purpose:** Get authenticated user profile +- **Authentication:** Required +- **Response:** User profile with role, permissions, tenant info + +**POST /api/auth/login** (if legacy auth is enabled) +- **Purpose:** Authenticate user +- **Request Body:** `{ email, password }` +- **Response:** JWT token + +--- + +## REST API Endpoints + +### Health & Diagnostics + +#### GET /health/live +- **Purpose:** Liveness probe +- **Authentication:** None +- **Response:** `{ status: "ok", service: "trading-backend" }` +- **Usage:** Docker healthcheck, monitoring + +#### GET /health/ready +- **Purpose:** Readiness probe +- **Authentication:** None +- **Response:** `{ status: "ready", checks: {...} }` +- **Usage:** Kubernetes readiness probe + +#### GET /api/health/dependencies +- **Purpose:** Check external dependencies +- **Authentication:** Required (admin role) +- **Response:** Dependency health status + +--- + +### User & Profile + +#### GET /api/me/profile +- **Purpose:** Get authenticated user profile +- **Authentication:** Required +- **Response:** +```json +{ + "userId": "string", + "email": "string", + "role": "admin" | "user", + "tenantId": "string", + "permissions": ["string"] +} +``` + +#### GET /api/users/:userId/profile +- **Purpose:** Get user profile (admin only) +- **Authentication:** Required (admin role) +- **Response:** User profile + +#### PUT /api/users/:userId/profile +- **Purpose:** Update user profile (admin only) +- **Authentication:** Required (admin role) +- **Request Body:** Profile update + +--- + +### Trading Control + +#### GET /api/trading/control +- **Purpose:** Get global trading control state +- **Authentication:** Required +- **Response:** +```json +{ + "globalTradingEnabled": boolean, + "pausedAt": "timestamp | null", + "pausedBy": "string | null", + "pausedReason": "string | null" +} +``` + +#### POST /api/trading/pause +- **Purpose:** Pause global trading +- **Authentication:** Required (admin role) +- **Request Body:** +```json +{ + "reason": "string" +} +``` + +#### POST /api/trading/resume +- **Purpose:** Resume global trading +- **Authentication:** Required (admin role) +- **Request Body:** None + +#### POST /api/trading/pause/profile/:profileId +- **Purpose:** Pause specific trading profile +- **Authentication:** Required +- **Request Body:** +```json +{ + "reason": "string" +} +``` + +#### POST /api/trading/resume/profile/:profileId +- **Purpose:** Resume specific trading profile +- **Authentication:** Required +- **Request Body:** None + +--- + +### Orders & Positions + +#### GET /api/orders +- **Purpose:** Get user orders +- **Authentication:** Required +- **Query Parameters:** `status`, `symbol`, `limit`, `offset` +- **Response:** Array of orders + +#### GET /api/orders/:orderId +- **Purpose:** Get specific order +- **Authentication:** Required +- **Response:** Order details + +#### GET /api/positions +- **Purpose:** Get open positions +- **Authentication:** Required +- **Response:** Array of positions + +#### GET /api/positions/:positionId +- **Purpose:** Get specific position +- **Authentication:** Required +- **Response:** Position details + +#### POST /api/orders +- **Purpose:** Create manual order +- **Authentication:** Required +- **Request Body:** +```json +{ + "symbol": "string", + "side": "buy" | "sell", + "quantity": number, + "orderType": "market" | "limit", + "price": number | null +} +``` + +#### POST /api/orders/:orderId/cancel +- **Purpose:** Cancel order +- **Authentication:** Required +- **Request Body:** None + +--- + +### Trade History + +#### GET /api/trade-history +- **Purpose:** Get closed trade history +- **Authentication:** Required +- **Query Parameters:** `symbol`, `startDate`, `endDate`, `limit`, `offset` +- **Response:** Array of closed trades + +#### GET /api/trade-history/:tradeId +- **Purpose:** Get specific trade +- **Authentication:** Required +- **Response:** Trade details + +--- + +### Market Data + +#### GET /api/market/quote/:symbol +- **Purpose:** Get current quote for symbol +- **Authentication:** Required +- **Response:** +```json +{ + "symbol": "string", + "price": number, + "change": number, + "changePercent": number, + "volume": number, + "timestamp": number +} +``` + +#### GET /api/market/bars/:symbol +- **Purpose:** Get OHLCV bars for symbol +- **Authentication:** Required +- **Query Parameters:** `period`, `limit` +- **Response:** Array of OHLCV bars + +--- + +### Research & Screener + +#### GET /api/research/profile/:symbol +- **Purpose:** Get company profile +- **Authentication:** Required +- **Response:** Company profile data + +#### GET /api/research/metrics/:symbol +- **Purpose:** Get financial metrics +- **Authentication:** Required +- **Response:** Financial metrics + +#### GET /api/screener +- **Purpose:** Run stock screener +- **Authentication:** Required +- **Query Parameters:** Screener criteria +- **Response:** Screener results + +--- + +### Backtesting + +#### GET /api/backtest/strategies +- **Purpose:** Get available backtest strategies +- **Authentication:** Required +- **Feature Flag:** ENABLE_BACKTEST +- **Response:** Array of strategies + +#### POST /api/backtest/run +- **Purpose:** Run backtest +- **Authentication:** Required +- **Feature Flag:** ENABLE_BACKTEST +- **Request Body:** +```json +{ + "strategyId": "string", + "symbol": "string", + "startDate": "timestamp", + "endDate": "timestamp", + "initialCapital": number +} +``` + +#### GET /api/backtest/results/:backtestId +- **Purpose:** Get backtest results +- **Authentication:** Required +- **Feature Flag:** ENABLE_BACKTEST +- **Response:** Backtest results + +--- + +### Feature Flags + +#### GET /api/feature-flags +- **Purpose:** Get feature flags for authenticated user +- **Authentication:** Required +- **Response:** +```json +{ + "backtest": { + "enabled": boolean, + "customerEnabled": boolean + }, + "tabs": { + "marketplace": boolean, + "membership": boolean + } +} +``` + +--- + +### Admin Operations + +#### GET /api/admin/audit +- **Purpose:** Get audit events +- **Authentication:** Required (admin role) +- **Query Parameters:** `userId`, `action`, `startDate`, `endDate`, `limit`, `offset` +- **Response:** Array of audit events + +#### POST /api/admin/config +- **Purpose:** Update dynamic config +- **Authentication:** Required (admin role) +- **Request Body:** Config update +- **Response:** Updated config + +#### GET /api/admin/config +- **Purpose:** Get dynamic config +- **Authentication:** Required (admin role) +- **Response:** Current config + +#### POST /internal/trading/pause +- **Purpose:** Internal endpoint to pause trading +- **Authentication:** Required (admin role, internal only) +- **Request Body:** +```json +{ + "reason": "string" +} +``` + +#### POST /internal/trading/resume +- **Purpose:** Internal endpoint to resume trading +- **Authentication:** Required (admin role, internal only) +- **Request Body:** None + +--- + +## WebSocket Namespaces + +### /trading (User-Scoped) + +**Connection:** +```javascript +const socket = io(`${TRADING_API_URL}/trading`, { + auth: { token: platformJwt } +}); +``` + +**Events:** + +**Server → Client:** +- `bot_state` - Full bot state update +- `positions_update` - Positions changed +- `orders_update` - Orders changed +- `trade_closed` - Trade closed +- `health_update` - Backend health status + +**Client → Server:** +- `subscribe_profiles` - Subscribe to profile updates +- `unsubscribe_profiles` - Unsubscribe from profile updates + +**Authentication:** Required (platform JWT) +**Scoping:** User receives only their own data + +--- + +### /admin (Admin-Only) + +**Connection:** +```javascript +const socket = io(`${TRADING_API_URL}/admin`, { + auth: { token: platformJwt } +}); +``` + +**Events:** + +**Server → Client:** +- `all_bot_states` - All users' bot states +- `system_health` - System-wide health +- `audit_event` - Audit event stream + +**Authentication:** Required (admin role) +**Scoping:** Admin receives cross-user state + +--- + +### / (Root, Backward-Compatible) + +**Connection:** +```javascript +const socket = io(TRADING_API_URL, { + auth: { token: platformJwt } +}); +``` + +**Events:** Same as `/trading` namespace +**Authentication:** Required +**Scoping:** User receives only their own data + +--- + +## Error Responses + +### Standard Error Format + +All errors follow this format: + +```json +{ + "error": { + "code": "ERROR_CODE", + "message": "Human-readable error message", + "details": "Additional error details", + "requestId": "x-request-id from request header" + } +} +``` + +### Common Error Codes + +| Code | HTTP Status | Description | +|------|-------------|-------------| +| UNAUTHORIZED | 401 | Missing or invalid authentication | +| FORBIDDEN | 403 | Insufficient permissions | +| NOT_FOUND | 404 | Resource not found | +| VALIDATION_ERROR | 400 | Request validation failed | +| RATE_LIMIT_EXCEEDED | 429 | Rate limit exceeded | +| INTERNAL_ERROR | 500 | Internal server error | +| SERVICE_UNAVAILABLE | 503 | Service temporarily unavailable | + +--- + +## Rate Limiting + +### Current State +- No explicit rate limiting implemented +- Recommended: Add rate limiting to prevent API abuse + +### Recommended Rate Limits + +| Endpoint | Rate Limit | Time Window | +|----------|------------|--------------| +| GET /api/* | 100 requests | 1 minute | +| POST /api/orders | 10 requests | 1 minute | +| POST /api/trading/* | 20 requests | 1 minute | +| WebSocket connections | 5 connections | 1 minute | + +### Rate Limit Headers + +```http +X-RateLimit-Limit: 100 +X-RateLimit-Remaining: 95 +X-RateLimit-Reset: 1715356800 +``` + +--- + +## Request ID Propagation + +### Header +```http +x-request-id: uuid +``` + +### Usage +- All requests should include `x-request-id` header +- If not provided, backend generates one +- Backend echoes `x-request-id` in response header +- Use `x-request-id` to trace requests across logs + +--- + +## Deprecation Policy + +### Deprecation Process + +1. Document endpoint in `BACKEND_API_DEPRECATION.md` +2. Add `X-Deprecated: true` header to deprecated endpoint +3. Add `X-Deprecation-Date: YYYY-MM-DD` header +4. Add `X-Sunset-Date: YYYY-MM-DD` header (when endpoint will be removed) +5. Provide migration guide in documentation +6. Maintain deprecated endpoint for minimum 90 days + +### Example Deprecated Response + +```http +HTTP/1.1 200 OK +X-Deprecated: true +X-Deprecation-Date: 2026-05-09 +X-Sunset-Date: 2026-08-09 +Content-Type: application/json + +{ + "data": {...}, + "deprecation": { + "message": "This endpoint is deprecated. Use POST /api/v2/orders instead.", + "migrationGuide": "/docs/api-migration.html#orders" + } +} +``` + +--- + +## OpenAPI/Swagger Generation + +### Recommended Tool + +Use `swagger-jsdoc` to generate OpenAPI specification from JSDoc comments: + +```bash +pnpm add -D swagger-jsdoc swagger-ui-express +``` + +### Implementation Steps + +1. Add JSDoc comments to all API routes +2. Generate OpenAPI specification +3. Host Swagger UI +4. Keep documentation in sync with code + +### Example JSDoc Comment + +```javascript +/** + * @swagger + * /api/orders: + * get: + * summary: Get user orders + * tags: [Orders] + * security: + * - bearerAuth: [] + * parameters: + * - in: query + * name: status + * schema: + * type: string + * description: Filter by order status + * responses: + * 200: + * description: Orders retrieved successfully + * content: + * application/json: + * schema: + * type: array + * items: + * $ref: '#/components/schemas/Order' + */ +router.get('/api/orders', async (req, res) => { + // implementation +}); +``` + +--- + +## Documentation Maintenance + +### When to Update Documentation + +- When adding new endpoints +- When modifying existing endpoints +- When deprecating endpoints +- When changing authentication requirements +- When adding new WebSocket events + +### Documentation Review Process + +1. Code review should check for documentation updates +2. Ensure JSDoc comments are added for new endpoints +3. Ensure OpenAPI spec is regenerated +4. Update API reference document + +--- + +## Next Steps for API Documentation + +### Immediate (This Week) + +1. Create `docs/API_REFERENCE.md` with endpoint catalog +2. Document authentication methods +3. Document error responses +4. Document WebSocket namespaces + +### Short-term (This Month) + +1. Add JSDoc comments to all API routes +2. Generate OpenAPI specification +3. Host Swagger UI +4. Add request/response examples + +### Medium-term (This Quarter) + +1. Implement rate limiting +2. Add rate limiting documentation +3. Add API versioning +4. Create API migration guide + +--- + +## References + +- **BACKEND_API_DEPRECATION.md** - Deprecated endpoints +- **BACKEND_AUDIT_SCHEMA.md** - Audit event schema +- **backend/src/services/apiServer.ts** - API implementation +- **shared/realtime.ts** - WebSocket namespace definitions diff --git a/docs/planned/ARCHITECTURE_DOCUMENTATION.md b/docs/planned/ARCHITECTURE_DOCUMENTATION.md new file mode 100644 index 0000000..d53f3a2 --- /dev/null +++ b/docs/planned/ARCHITECTURE_DOCUMENTATION.md @@ -0,0 +1,1028 @@ +# 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 diff --git a/docs/planned/ONBOARDING_GUIDE.md b/docs/planned/ONBOARDING_GUIDE.md new file mode 100644 index 0000000..1d9c4bd --- /dev/null +++ b/docs/planned/ONBOARDING_GUIDE.md @@ -0,0 +1,737 @@ +# Developer Onboarding Guide + +**Purpose:** Comprehensive onboarding guide for new developers joining the trading dashboard monorepo project. + +**Target Audience:** New developers, contractors, contributors. + +--- + +## Table of Contents + +- [Project Overview](#project-overview) +- [Prerequisites](#prerequisites) +- [Development Setup](#development-setup) +- [Project Structure](#project-structure) +- [Development Workflow](#development-workflow) +- [Testing](#testing) +- [Code Review Process](#code-review-process) +- [Common Tasks](#common-tasks) +- [Resources](#resources) +- [Getting Help](#getting-help) + +--- + +## Project Overview + +### What is the Trading Dashboard? + +The trading dashboard is a monorepo containing three product surfaces: +- **Backend** - Trading engine, REST API, WebSocket server (port 4018) +- **Web** - React 19 + Vite dashboard (port 3050) +- **Mobile** - Expo + React Native app + +### Tech Stack + +**Backend:** +- Node.js with TypeScript (ESM) +- Express.js REST API +- Socket.IO WebSocket +- Azure Cosmos DB (primary data store) +- Alpaca + CCXT for exchange integration +- Platform-service for auth and feature flags + +**Web:** +- React 19 + Vite +- React Router v7 +- Recharts for charts +- Socket.IO client +- @bytelyst/ui for UI components +- TailwindCSS v4 + +**Mobile:** +- Expo + React Native +- Expo Router +- React Native Web +- Socket.IO client +- @bytelyst/react-native-platform-sdk + +### Key Concepts + +- **Monorepo** - Single repo with backend, web, mobile workspaces +- **Common Platform** - Shared packages from `learning_ai_common_plat` +- **Platform Auth** - JWT-based authentication via platform-service +- **Kill Switch** - Product-wide maintenance mode +- **Feature Flags** - Product-level feature flags +- **Tenant Isolation** - Data scoped by tenant/user +- **Trading Control** - Global and profile-level trading pause/resume + +--- + +## Prerequisites + +### Required Software + +**For All Development:** +- Node.js 18+ (LTS recommended) +- pnpm 10.6.5+ +- Git +- Docker (optional, for containerized development) + +**For Backend Development:** +- TypeScript 5.9+ +- Azure Cosmos DB emulator (local) or Azure Cosmos DB (production) + +**For Web Development:** +- Modern web browser (Chrome, Firefox, Safari, Edge) +- Node.js 18+ + +**For Mobile Development:** +- Node.js 18+ +- Expo CLI +- iOS: Xcode (for iOS builds) +- Android: Android Studio (for Android builds) + +### Required Accounts + +- GitHub account (for code access) +- Azure account (for production Cosmos DB) +- Platform-service access (for auth and feature flags) + +### Optional Tools + +- VS Code (recommended IDE) +- Postman (for API testing) +- Expo Go app (for mobile testing) +- Docker Desktop (for containerized development) + +--- + +## Development Setup + +### 1. Clone the Repository + +```bash +git clone https://github.com/saravanakumardb1/learning_ai_invt_trdg.git +cd learning_ai_invt_trdg +``` + +### 2. Install Dependencies + +**Using local common platform packages (default):** +```bash +BYTELYST_PACKAGE_SOURCE=common-plat pnpm install +``` + +**Using Gitea registry (requires auth):** +```bash +BYTELYST_PACKAGE_SOURCE=gitea pnpm install +``` + +### 3. Configure Environment Variables + +**Backend (.env):** +```bash +cd backend +cp .env.example .env +# Edit .env with your values +``` + +**Required backend environment variables:** +- `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 (true/false) +- `PLATFORM_JWT_PUBLIC_KEY` - JWT public key (if platform auth enabled) +- `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 (true/false) +- `PAPER_TRADING` - Paper trading mode (true/false) + +**Web (.env.local):** +```bash +cd web +cp .env.local.example .env.local +# Edit .env.local with your values +``` + +**Required web environment variables:** +- `VITE_TRADING_API_URL` - Backend API URL +- `VITE_PLATFORM_URL` - Platform-service URL +- `VITE_PRODUCT_ID` - Product ID (invttrdg) +- `VITE_BACKTEST_ENABLED` - Backtest enabled (true/false) + +**Mobile (.env.local):** +```bash +cd mobile +cp .env.local.example .env.local +# Edit .env.local with your values +``` + +**Required mobile environment variables:** +- `EXPO_PUBLIC_PRODUCT_ID` - Product ID (invttrdg) +- `EXPO_PUBLIC_PLATFORM_URL` - Platform-service URL +- `EXPO_PUBLIC_TRADING_API_URL` - Backend API URL + +### 4. Verify Setup + +```bash +# From monorepo root +pnpm verify +``` + +This runs: +- Type checking for all workspaces +- Tests for all workspaces +- Linting for all workspaces + +--- + +## Project Structure + +### Monorepo Layout + +``` +learning_ai_invt_trdg/ +├── backend/ # 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 +│ ├── 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 +│ ├── 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 +``` + +### Key Files + +**Root:** +- `package.json` - Root package.json with workspace scripts +- `pnpm-workspace.yaml` - Workspace configuration +- `README.md` - Project overview +- `docs/PRD.md` - Product requirements +- `docs/ROADMAP.md` - Implementation status + +**Backend:** +- `backend/src/bootstrap.ts` - Server entry point +- `backend/src/services/apiServer.ts` - REST API server +- `backend/src/services/TradeExecutor.ts` - Order execution +- `backend/src/strategies/ProStrategyEngine.ts` - Strategy engine + +**Web:** +- `web/src/main.tsx` - Entry point +- `web/src/App.tsx` - Root app component +- `web/src/views/HomeView.tsx` - Dashboard overview +- `web/src/components/ui/Primitives.tsx` - UI adapter + +**Mobile:** +- `mobile/app/_layout.tsx` - Root layout +- `mobile/app/(tabs)/index.tsx` - Overview tab +- `mobile/lib/runtime.ts` - Runtime configuration + +--- + +## Development Workflow + +### Starting Development + +**Option 1: Using dev script (recommended):** +```bash +pnpm dev +``` +This starts: +- Backend (port 4018) +- Web (port 3050) +- Mobile dev server + +**Option 2: Starting individually:** + +**Backend:** +```bash +cd backend +npm run dev +# Backend starts on port 4018 +``` + +**Web:** +```bash +cd web +pnpm dev +# Web starts on port 3050 +``` + +**Mobile:** +```bash +cd mobile +pnpm dev +# Mobile dev server starts +# Scan QR code with Expo Go app +``` + +### Making Changes + +1. **Create a branch:** +```bash +git checkout -b feature/your-feature-name +# or +git checkout -b fix/your-fix-name +``` + +2. **Make your changes:** +- Edit files in the appropriate workspace +- Follow existing code style +- Add tests if needed + +3. **Test your changes:** +```bash +# Type check +pnpm typecheck + +# Run tests +pnpm test + +# Lint +pnpm lint +``` + +4. **Commit your changes:** +```bash +git add . +git commit -m "feat(scope): description" +# or +git commit -m "fix(scope): description" +``` + +### Commit Message Format + +Follow conventional commits: +- `feat:` - New feature +- `fix:` - Bug fix +- `docs:` - Documentation changes +- `refactor:` - Code refactoring +- `test:` - Test changes +- `chore:` - Maintenance tasks + +Examples: +- `feat(backend): add order cancellation endpoint` +- `fix(web): resolve WebSocket reconnection issue` +- `docs(readme): update setup instructions` + +### Pushing Changes + +```bash +git push origin feature/your-feature-name +``` + +--- + +## Testing + +### Backend Tests + +```bash +cd backend +npm test +``` + +Backend tests include: +- Contract tests (API, WebSocket, session rules) +- Security tests (tenant isolation, security guards) +- Lifecycle tests (trade executor, reconciliation) +- Integration tests (market data, chat copilot) + +### Web Tests + +```bash +cd web +pnpm test +``` + +Web tests include: +- Unit tests (components, hooks) +- DOM tests (component rendering) +- E2E tests (Playwright) + +**Run E2E tests:** +```bash +cd web +pnpm test:e2e +``` + +### Mobile Tests + +```bash +cd mobile +pnpm typecheck +# Mobile currently has limited test coverage +``` + +### Verification Script + +```bash +pnpm verify +``` + +This runs: +- Type checking for all workspaces +- Tests for all workspaces +- Linting for all workspaces + +--- + +## Code Review Process + +### Pull Request Process + +1. **Create a pull request:** + - Go to GitHub + - Create PR from your branch to main + - Include description of changes + - Link to relevant issues + +2. **PR Checklist:** + - [ ] Tests pass + - [ ] Type checking passes + - [ ] Linting passes + - [ ] Documentation updated if needed + - [ ] Commit messages follow conventional commits + +3. **Code Review:** + - At least one approval required + - Address review comments + - Make requested changes + +4. **Merge:** + - Squash and merge + - Delete branch after merge + +### Code Review Guidelines + +**What reviewers look for:** +- Code correctness +- Code style consistency +- Test coverage +- Documentation +- Performance considerations +- Security considerations + +**How to respond to review:** +- Address all comments +- Explain if you disagree +- Make requested changes +- Ask for re-review + +--- + +## Common Tasks + +### Adding a New Backend Endpoint + +1. **Add route handler:** +```typescript +// backend/src/services/apiServer.ts +app.get('/api/your-endpoint', async (req, res) => { + // implementation +}); +``` + +2. **Add validation:** +```typescript +// Use Zod for validation +const schema = z.object({ + param1: z.string(), + param2: z.number(), +}); +``` + +3. **Add authentication:** +```typescript +// Use platform auth middleware +// Check user permissions +``` + +4. **Add tests:** +```typescript +// Add contract test +// Add integration test +``` + +5. **Update documentation:** +```typescript +// Add JSDoc comments +// Update API documentation +``` + +### Adding a New Web Component + +1. **Create component:** +```typescript +// web/src/components/YourComponent.tsx +export function YourComponent() { + return
Your component
; +} +``` + +2. **Use UI primitives:** +```typescript +import { Button } from '../components/ui/Primitives'; +``` + +3. **Add tests:** +```typescript +// web/src/components/YourComponent.test.tsx +// Add unit test +// Add DOM test +``` + +4. **Add Storybook story:** +```typescript +// web/stories/YourComponent.stories.tsx +``` + +### Adding a New Mobile Screen + +1. **Create screen:** +```typescript +// mobile/app/your-screen.tsx +export function YourScreen() { + return Your screen; +} +``` + +2. **Add to navigation:** +```typescript +// mobile/app/_layout.tsx +// Add screen to navigation +``` + +3. **Add tests:** +```typescript +// Add mobile tests +``` + +### Adding a New Feature Flag + +1. **Define flag:** +```typescript +// shared/feature-flags.ts +export const FEATURE_FLAGS = { + yourFeature: { + enabled: false, + description: 'Your feature description', + }, +}; +``` + +2. **Implement flag check:** +```typescript +// Use flag in code +if (FEATURE_FLAGS.yourFeature.enabled) { + // feature code +} +``` + +3. **Test flag:** +```typescript +// Test with flag enabled/disabled +``` + +--- + +## Resources + +### Documentation + +- **README.md** - Project overview +- **PRD.md** - Product requirements +- **ROADMAP.md** - Implementation status +- **ARCHITECTURE_DOCUMENTATION.md** - System architecture +- **API_DOCUMENTATION_GUIDE.md** - API documentation +- **TROUBLESHOOTING_GUIDE.md** - Troubleshooting guide +- **FUNCTIONALITY_REVIEW.md** - Functional gaps and issues +- **UX_TESTING_SETUP_GUIDE.md** - UX testing setup + +### External Documentation + +- **@bytelyst packages** - Common platform packages +- **Platform-service** - Platform service documentation +- **Azure Cosmos DB** - Cosmos DB documentation +- **Alpaca API** - Alpaca API documentation +- **CCXT** - CCXT documentation +- **Expo** - Expo documentation + +### Tools + +- **pnpm** - Package manager +- **TypeScript** - TypeScript documentation +- **React** - React documentation +- **Vite** - Vite documentation +- **Expo** - Expo documentation +- **Playwright** - Playwright documentation +- **Storybook** - Storybook documentation + +--- + +## Getting Help + +### Internal Resources + +- **Team Slack** - #trading-dashboard channel +- **On-call engineer** - For production issues +- **Tech lead** - For architectural questions + +### Common Issues + +**Setup issues:** +- Check TROUBLESHOOTING_GUIDE.md +- Verify environment variables +- Check dependencies + +**Development issues:** +- Check logs for errors +- Verify configuration +- Check network connectivity + +**Code issues:** +- Check existing code for patterns +- Ask team for guidance +- Review documentation + +### Asking Questions + +1. **Check documentation first** - Look for answers in docs +2. **Search existing issues** - Check GitHub issues +3. **Ask in Slack** - Post in #trading-dashboard channel +4. **Create issue** - If it's a bug or feature request + +### Best Practices + +- **Be specific** - Include error messages, logs, context +- **Provide context** - Explain what you're trying to do +- **Show research** - Show what you've already tried +- **Be patient** - Team members may be busy + +--- + +## Next Steps + +### First Week + +1. **Complete setup:** + - [ ] Clone repository + - [ ] Install dependencies + - [ ] Configure environment variables + - [ ] Verify setup with `pnpm verify` + +2. **Explore codebase:** + - [ ] Read README.md + - [ ] Read PRD.md + - [ ] Read ARCHITECTURE_DOCUMENTATION.md + - [ ] Explore project structure + +3. **Make first contribution:** + - [ ] Fix a small bug + - [ ] Add a test + - [ ] Update documentation + +### First Month + +1. **Deep dive into your area:** + - Backend: Understand trading loop, strategy engine + - Web: Understand component structure, data flow + - Mobile: Understand app structure, navigation + +2. **Contribute to features:** + - Pick up a feature from ROADMAP.md + - Implement and test + - Submit PR + +3. **Learn the ecosystem:** + - Understand common platform packages + - Understand platform-service integration + - Understand deployment process + +### Ongoing + +1. **Stay updated:** + - Read team updates + - Review PRs + - Attend standups + +2. **Improve documentation:** + - Update docs as you learn + - Add examples + - Fix errors + +3. **Help others:** + - Review PRs + - Answer questions + - Mentor new developers + +--- + +## Summary + +Welcome to the trading dashboard team! This guide should help you get started with development. If you have questions, don't hesitate to ask in Slack or create an issue. + +**Key takeaways:** +- Use `pnpm verify` to validate your changes +- Follow conventional commit format +- Use @bytelyst/ui primitives for web components +- Check documentation before asking questions +- Be specific when asking for help + +Good luck and happy coding! diff --git a/docs/planned/TROUBLESHOOTING_GUIDE.md b/docs/planned/TROUBLESHOOTING_GUIDE.md new file mode 100644 index 0000000..d513d5f --- /dev/null +++ b/docs/planned/TROUBLESHOOTING_GUIDE.md @@ -0,0 +1,1398 @@ +# Troubleshooting Guide + +**Purpose:** Comprehensive troubleshooting guide for the trading dashboard, covering common issues, resolution steps, and escalation procedures. + +**Target Audience:** Developers, operators, support engineers. + +--- + +## Table of Contents + +- [Backend Issues](#backend-issues) +- [Web Issues](#web-issues) +- [Mobile Issues](#mobile-issues) +- [Database Issues](#database-issues) +- [Authentication Issues](#authentication-issues) +- [WebSocket Issues](#websocket-issues) +- [Performance Issues](#performance-issues) +- [Deployment Issues](#deployment-issues) +- [Escalation Procedures](#escalation-procedures) + +--- + +## Backend Issues + +### Backend Won't Start + +**Symptoms:** +- Backend fails to start +- Error message on startup +- Process exits immediately + +**Common Causes:** +1. Missing environment variables +2. Invalid configuration +3. Database connection failure +4. Port already in use + +**Resolution Steps:** + +1. **Check environment variables:** +```bash +cd backend +cat .env +# Ensure all required variables are set +``` + +2. **Verify configuration:** +```bash +cd backend +npm run dev +# Check error messages for specific issues +``` + +3. **Check database connection:** +```bash +# Test Cosmos DB connection +curl -I $COSMOS_ENDPOINT +# Check if Cosmos DB is accessible +``` + +4. **Check port availability:** +```bash +lsof -i :4018 +# Kill process using port 4018 if needed +kill -9 +``` + +5. **Check logs:** +```bash +# Backend logs should show startup errors +# Look for specific error messages +``` + +**Prevention:** +- Use `.env.example` as template +- Validate environment variables at startup +- Add configuration validation script + +--- + +### Backend Health Check Failing + +**Symptoms:** +- `GET /health/live` returns non-200 status +- Health check endpoint unreachable +- Docker healthcheck failing + +**Common Causes:** +1. Backend not running +2. Health check endpoint not implemented +3. Database connection issues +4. Dependencies unhealthy + +**Resolution Steps:** + +1. **Check if backend is running:** +```bash +curl http://localhost:4018/health/live +``` + +2. **Check backend logs:** +```bash +# Look for health check errors +# Check for database connection errors +``` + +3. **Check dependencies:** +```bash +curl http://localhost:4003/health +# Check platform-service health +``` + +4. **Check database:** +```bash +# Verify Cosmos DB is accessible +# Check database container exists +``` + +**Prevention:** +- Implement comprehensive health checks +- Add dependency health checks +- Monitor health check failures + +--- + +### Trading Loop Not Running + +**Symptoms:** +- No trades executing +- Bot state shows "idle" +- Positions not updating + +**Common Causes:** +1. Trading disabled globally +2. Profile disabled +3. Market closed +4. Configuration error +5. Exchange API issue + +**Resolution Steps:** + +1. **Check trading control state:** +```bash +curl -H "Authorization: Bearer " http://localhost:4018/api/trading/control +# Check if globalTradingEnabled is true +``` + +2. **Check profile status:** +```bash +# Check if specific profile is enabled +# Look for profile-level disable +``` + +3. **Check market hours:** +```bash +# Verify SessionRule is not blocking +# Check if market is open +``` + +4. **Check exchange API:** +```bash +# Verify exchange API credentials +# Test exchange API connectivity +``` + +5. **Check backend logs:** +```bash +# Look for trading loop errors +# Check for strategy rule failures +``` + +**Prevention:** +- Add trading loop status monitoring +- Add exchange API health checks +- Implement trading loop alerts + +--- + +### Orders Not Executing + +**Symptoms:** +- Orders submitted but not executed +- Orders stuck in "pending" state +- Exchange API errors + +**Common Causes:** +1. Exchange API issue +2. Insufficient capital +3. Risk management blocking +4. Exchange maintenance +5. Invalid order parameters + +**Resolution Steps:** + +1. **Check exchange API:** +```bash +# Test exchange API connectivity +# Verify API credentials +# Check exchange status page +``` + +2. **Check capital:** +```bash +# Verify sufficient capital available +# Check capital ledger +``` + +3. **Check risk engine:** +```bash +# Check if risk management is blocking +# Look for risk rule failures +``` + +4. **Check order parameters:** +```bash +# Verify order parameters are valid +# Check symbol, quantity, price +``` + +5. **Check backend logs:** +```bash +# Look for order execution errors +# Check for exchange API errors +``` + +**Prevention:** +- Add order execution monitoring +- Add exchange API health checks +- Implement order execution alerts + +--- + +### Reconciliation Failures + +**Symptoms:** +- Reconciliation service failing +- Data inconsistencies +- Reconciliation errors in logs + +**Common Causes:** +1. Exchange API issue +2. Database connection issue +3. Data format mismatch +4. Missing data +5. Logic error + +**Resolution Steps:** + +1. **Check reconciliation logs:** +```bash +# Look for reconciliation errors +# Check for specific failure reasons +``` + +2. **Run reconciliation manually:** +```bash +cd backend +npm run reconcile:lifecycle-history +# Run specific reconciliation script +``` + +3. **Check exchange data:** +```bash +# Verify exchange API is returning correct data +# Check for data format changes +``` + +4. **Check database:** +```bash +# Verify database is accessible +# Check for data corruption +``` + +**Prevention:** +- Add reconciliation monitoring +- Add reconciliation alerts +- Implement reconciliation retry logic + +--- + +## Web Issues + +### Web Won't Load + +**Symptoms:** +- Blank screen +- Loading spinner indefinitely +- Browser console errors + +**Common Causes:** +1. Backend API unreachable +2. Authentication failure +3. Build error +4. JavaScript error +5. Network issue + +**Resolution Steps:** + +1. **Check browser console:** +```javascript +// Open browser devtools +// Check for JavaScript errors +// Check for network errors +``` + +2. **Check backend API:** +```bash +curl http://localhost:4018/health/live +# Verify backend is running +``` + +3. **Check authentication:** +```bash +# Verify auth token is valid +# Check platform-service is reachable +``` + +4. **Check build:** +```bash +cd web +pnpm build +# Verify build succeeds +``` + +5. **Check network:** +```bash +# Check network connectivity +# Verify CORS settings +``` + +**Prevention:** +- Add error boundaries +- Add loading states +- Implement graceful degradation + +--- + +### Authentication Failing + +**Symptoms:** +- Login fails +- Session expires immediately +- Auth token invalid +- 401/403 errors + +**Common Causes:** +1. Platform-service unreachable +2. Invalid credentials +3. Token expired +4. Platform-service down +5. Configuration error + +**Resolution Steps:** + +1. **Check platform-service:** +```bash +curl http://localhost:4003/health +# Verify platform-service is running +``` + +2. **Check credentials:** +```bash +# Verify username/password are correct +# Check platform-service user exists +``` + +3. **Check token:** +```bash +# Verify JWT token is valid +# Check token expiration +``` + +4. **Check configuration:** +```bash +cat web/.env.local +# Verify VITE_PLATFORM_URL is correct +# Verify auth configuration +``` + +5. **Check logs:** +```bash +# Check platform-service logs +# Check backend auth logs +``` + +**Prevention:** +- Add auth error handling +- Implement token refresh +- Add auth monitoring + +--- + +### WebSocket Connection Failing + +**Symptoms:** +- WebSocket won't connect +- Connection drops repeatedly +- No real-time updates +- WebSocket errors in console + +**Common Causes:** +1. Backend unreachable +2. Auth token invalid +3. WebSocket blocked by firewall +4. Namespace mismatch +5. Connection limit exceeded + +**Resolution Steps:** + +1. **Check backend WebSocket:** +```bash +# Verify backend is running +# Check WebSocket port is accessible +``` + +2. **Check auth token:** +```bash +# Verify JWT token is valid +# Check token is included in connection +``` + +3. **Check firewall:** +```bash +# Verify WebSocket port is not blocked +# Check network settings +``` + +4. **Check namespace:** +```bash +# Verify correct namespace (/trading) +# Check namespace exists in backend +``` + +5. **Check logs:** +```bash +# Check backend WebSocket logs +# Look for connection errors +``` + +**Prevention:** +- Add WebSocket error handling +- Implement reconnection logic +- Add WebSocket monitoring + +--- + +### Data Not Updating + +**Symptoms:** +- Data stale +- No real-time updates +- Manual refresh required +- WebSocket connected but no updates + +**Common Causes:** +1. WebSocket not receiving events +2. Backend not broadcasting +3. Event subscription issue +4. Data cache issue +5. Filter/mask issue + +**Resolution Steps:** + +1. **Check WebSocket connection:** +```javascript +// Check WebSocket is connected +// Check for connection errors +``` + +2. **Check backend broadcasting:** +```bash +# Check backend logs for broadcast events +# Verify events are being sent +``` + +3. **Check event subscription:** +```javascript +// Verify correct events are subscribed +// Check for subscription errors +``` + +4. **Check data cache:** +```javascript +// Clear cache if needed +// Verify cache is not stale +``` + +5. **Check filters:** +```javascript +// Verify data filters are correct +# Check for masking issues +``` + +**Prevention:** +- Add data staleness monitoring +- Implement cache invalidation +- Add data update alerts + +--- + +## Mobile Issues + +### Mobile App Won't Launch + +**Symptoms:** +- App crashes on launch +- Blank screen +- Loading spinner indefinitely +- Expo Go won't load + +**Common Causes:** +1. Build error +2. Configuration error +3. Platform-service unreachable +4. Backend unreachable +5. Expo Go version mismatch + +**Resolution Steps:** + +1. **Check Expo logs:** +```bash +# Check Expo dev server logs +# Look for build errors +``` + +2. **Check configuration:** +```bash +cat mobile/.env.local +# Verify EXPO_PUBLIC_* variables are set +``` + +3. **Check platform-service:** +```bash +curl http://localhost:4003/health +# Verify platform-service is running +``` + +4. **Check backend:** +```bash +curl http://localhost:4018/health/live +# Verify backend is running +``` + +5. **Check Expo Go:** +```bash +# Verify Expo Go is latest version +# Try clearing Expo Go cache +``` + +**Prevention:** +- Add error boundaries +- Add launch error handling +- Implement graceful degradation + +--- + +### Mobile Authentication Failing + +**Symptoms:** +- Login fails +- Session won't restore +- Auth token invalid +- Secure storage issue + +**Common Causes:** +1. Platform-service unreachable +2. Invalid credentials +3. Token expired +4. Secure storage error +5. Platform-service down + +**Resolution Steps:** + +1. **Check platform-service:** +```bash +curl http://localhost:4003/health +# Verify platform-service is running +``` + +2. **Check credentials:** +```bash +# Verify credentials are correct +# Check platform-service user exists +``` + +3. **Check token:** +```bash +# Verify JWT token is valid +# Check token expiration +``` + +4. **Check secure storage:** +```bash +# Verify secure storage is working +# Check for storage errors +``` + +5. **Check logs:** +```bash +# Check mobile logs +# Look for auth errors +``` + +**Prevention:** +- Add auth error handling +- Implement token refresh +- Add secure storage error handling + +--- + +### Mobile WebSocket Connection Failing + +**Symptoms:** +- WebSocket won't connect +- Connection drops repeatedly +- No real-time updates +- WebSocket errors in logs + +**Common Causes:** +1. Backend unreachable +2. Auth token invalid +3. WebSocket blocked by network +4. Namespace mismatch +5. Connection limit exceeded + +**Resolution Steps:** + +1. **Check backend WebSocket:** +```bash +# Verify backend is running +# Check WebSocket port is accessible +``` + +2. **Check auth token:** +```bash +# Verify JWT token is valid +# Check token is included in connection +``` + +3. **Check network:** +```bash +# Verify network allows WebSocket +# Check mobile network settings +``` + +4. **Check namespace:** +```bash +# Verify correct namespace (/trading) +# Check namespace exists in backend +``` + +5. **Check logs:** +```bash +# Check mobile logs +# Look for connection errors +``` + +**Prevention:** +- Add WebSocket error handling +- Implement reconnection logic +- Add polling fallback + +--- + +### Mobile Data Not Updating + +**Symptoms:** +- Data stale +- No real-time updates +- Manual refresh required +- WebSocket connected but no updates + +**Common Causes:** +1. WebSocket not receiving events +2. Backend not broadcasting +3. Event subscription issue +4. Data cache issue +5. Polling fallback not working + +**Resolution Steps:** + +1. **Check WebSocket connection:** +```javascript +// Check WebSocket is connected +// Check for connection errors +``` + +2. **Check backend broadcasting:** +```bash +# Check backend logs for broadcast events +# Verify events are being sent +``` + +3. **Check polling fallback:** +```javascript +// Verify polling is working +// Check polling interval +``` + +4. **Check data cache:** +```javascript +// Clear cache if needed +# Verify cache is not stale +``` + +5. **Check logs:** +```bash +# Check mobile logs +# Look for update errors +``` + +**Prevention:** +- Add data staleness monitoring +- Implement polling fallback +- Add data update alerts + +--- + +## Database Issues + +### Cosmos DB Connection Failing + +**Symptoms:** +- Backend can't connect to Cosmos +- Connection timeout +- Authentication error +- Database not found + +**Common Causes:** +1. Invalid credentials +2. Network issue +3. Cosmos DB down +4. Container not found +5. Firewall blocking + +**Resolution Steps:** + +1. **Check credentials:** +```bash +cat backend/.env +# Verify COSMOS_ENDPOINT and COSMOS_KEY are correct +``` + +2. **Test connection:** +```bash +curl -I $COSMOS_ENDPOINT +# Verify Cosmos DB is accessible +``` + +3. **Check database:** +```bash +# Verify database exists +# Check container exists +``` + +4. **Check network:** +```bash +# Verify network allows connection +# Check firewall settings +``` + +5. **Check logs:** +```bash +# Check backend logs for Cosmos errors +# Look for connection errors +``` + +**Prevention:** +- Add connection retry logic +- Implement connection pooling +- Add connection monitoring + +--- + +### Cosmos DB Slow Performance + +**Symptoms:** +- Slow query response times +- Timeout errors +- Performance degradation + +**Common Causes:** +1. Large result sets +2. Missing indexes +3. High RU consumption +4. Network latency +5. Database throttling + +**Resolution Steps:** + +1. **Check query performance:** +```bash +# Check query execution time +# Look for slow queries +``` + +2. **Check indexes:** +```bash +# Verify indexes exist +# Check index usage +``` + +3. **Check RU consumption:** +```bash +# Monitor RU consumption +# Check for throttling +``` + +4. **Optimize queries:** +```bash +# Add query filters +# Use pagination +# Reduce result set size +``` + +**Prevention:** +- Add query performance monitoring +- Implement query optimization +- Add performance alerts + +--- + +### Data Inconsistency + +**Symptoms:** +- Data mismatch between surfaces +- Stale data +- Missing data +- Duplicate data + +**Common Causes:** +1. Reconciliation failure +2. Cache issue +3. Race condition +4. Data corruption +5. Sync issue + +**Resolution Steps:** + +1. **Run reconciliation:** +```bash +cd backend +npm run reconcile:lifecycle-history +# Run reconciliation script +``` + +2. **Check cache:** +```bash +# Clear cache if needed +# Verify cache is not stale +``` + +3. **Check sync:** +```bash +# Verify sync is working +# Check for sync errors +``` + +4. **Check data integrity:** +```bash +# Verify data integrity +# Check for corruption +``` + +**Prevention:** +- Add data consistency monitoring +- Implement reconciliation +- Add data integrity checks + +--- + +## Authentication Issues + +### Platform-Service Unreachable + +**Symptoms:** +- Can't authenticate +- Token validation fails +- Platform-service health check fails + +**Common Causes:** +1. Platform-service down +2. Network issue +3. Wrong URL +4. Firewall blocking +5. DNS issue + +**Resolution Steps:** + +1. **Check platform-service:** +```bash +curl http://localhost:4003/health +# Verify platform-service is running +``` + +2. **Check configuration:** +```bash +cat backend/.env +# Verify PLATFORM_API_URL is correct +cat web/.env.local +# Verify VITE_PLATFORM_URL is correct +``` + +3. **Check network:** +```bash +# Verify network allows connection +# Check firewall settings +``` + +4. **Check DNS:** +```bash +# Verify DNS resolution +# Check host file +``` + +**Prevention:** +- Add platform-service monitoring +- Implement fallback auth +- Add auth monitoring + +--- + +### JWT Token Invalid + +**Symptoms:** +- 401 errors +- Token validation fails +- Session expires immediately + +**Common Causes:** +1. Token expired +2. Token malformed +3. Wrong signing key +4. Token revoked +5. Clock skew + +**Resolution Steps:** + +1. **Check token expiration:** +```bash +# Decode JWT token +# Check expiration time +``` + +2. **Check token format:** +```bash +# Verify JWT format is correct +# Check for token errors +``` + +3. **Check signing key:** +```bash +# Verify signing key is correct +# Check key rotation +``` + +4. **Check clock skew:** +```bash +# Verify system time is correct +# Check NTP sync +``` + +**Prevention:** +- Implement token refresh +- Add token validation +- Add token monitoring + +--- + +## WebSocket Issues + +### WebSocket Connection Drops + +**Symptoms:** +- Connection drops repeatedly +- Reconnection fails +- Connection timeout + +**Common Causes:** +1. Network instability +2. Backend restart +3. Auth token expired +4. Connection limit +5. Firewall timeout + +**Resolution Steps:** + +1. **Check network:** +```bash +# Verify network stability +# Check for packet loss +``` + +2. **Check backend:** +```bash +# Verify backend is not restarting +# Check backend logs +``` + +3. **Check auth token:** +```bash +# Verify JWT token is valid +# Check token expiration +``` + +4. **Check connection limit:** +```bash +# Verify connection limit not exceeded +# Check for connection leaks +``` + +**Prevention:** +- Implement reconnection logic +- Add connection monitoring +- Implement heartbeat + +--- + +### WebSocket Not Receiving Events + +**Symptoms:** +- WebSocket connected but no events +- Events not arriving +- Event subscription issue + +**Common Causes:** +1. Not subscribed to events +2. Namespace mismatch +3. Backend not broadcasting +4. Event filtering +5. Room mismatch + +**Resolution Steps:** + +1. **Check subscription:** +```javascript +// Verify correct events are subscribed +// Check for subscription errors +``` + +2. **Check namespace:** +```bash +# Verify correct namespace +# Check namespace exists +``` + +3. **Check backend:** +```bash +# Verify backend is broadcasting +# Check backend logs +``` + +4. **Check filtering:** +```javascript +// Verify event filters are correct +# Check for filtering errors +``` + +**Prevention:** +- Add event monitoring +- Implement event acknowledgment +- Add event logging + +--- + +## Performance Issues + +### Backend Slow Response Times + +**Symptoms:** +- API responses slow +- High latency +- Timeout errors + +**Common Causes:** +1. Database query slow +2. External API slow +3. CPU bottleneck +4. Memory bottleneck +5. Network latency + +**Resolution Steps:** + +1. **Check database queries:** +```bash +# Check query performance +# Look for slow queries +``` + +2. **Check external APIs:** +```bash +# Check exchange API latency +# Verify API performance +``` + +3. **Check system resources:** +```bash +# Check CPU usage +# Check memory usage +``` + +4. **Check network:** +```bash +# Check network latency +# Verify network bandwidth +``` + +**Prevention:** +- Add performance monitoring +- Implement caching +- Add performance alerts + +--- + +### Web Slow Load Times + +**Symptoms:** +- Slow page load +- Large bundle size +- Slow initial render + +**Common Causes:** +1. Large bundle size +2. Too many requests +3. Slow API responses +4. Unoptimized assets +5. No caching + +**Resolution Steps:** + +1. **Check bundle size:** +```bash +cd web +pnpm build +# Check bundle size +``` + +2. **Check network requests:** +```javascript +// Check network tab +// Look for large requests +``` + +3. **Check API responses:** +```bash +# Check API response times +# Look for slow endpoints +``` + +4. **Optimize assets:** +```bash +# Optimize images +# Minify assets +# Implement caching +``` + +**Prevention:** +- Add performance monitoring +- Implement code splitting +- Add caching + +--- + +## Deployment Issues + +### Docker Build Failing + +**Symptoms:** +- Docker build fails +- Build timeout +- Dependency install fails + +**Common Causes:** +1. Invalid Dockerfile +2. Missing dependencies +3. Network issue +4. Insufficient resources +5. Build context too large + +**Resolution Steps:** + +1. **Check Dockerfile:** +```bash +# Verify Dockerfile syntax +# Check for errors +``` + +2. **Check dependencies:** +```bash +# Verify package.json is valid +# Check for missing dependencies +``` + +3. **Check network:** +```bash +# Verify network connectivity +# Check registry access +``` + +4. **Check resources:** +```bash +# Verify sufficient disk space +# Check memory availability +``` + +**Prevention:** +- Add Docker build validation +- Implement build caching +- Add build monitoring + +--- + +### Docker Container Won't Start + +**Symptoms:** +- Container won't start +- Container exits immediately +- Container crashes + +**Common Causes:** +1. Invalid configuration +2. Missing environment variables +3. Port conflict +4. Dependency unavailable +5. Health check failing + +**Resolution Steps:** + +1. **Check container logs:** +```bash +docker logs +# Look for startup errors +``` + +2. **Check configuration:** +```bash +# Verify environment variables +# Check configuration files +``` + +3. **Check ports:** +```bash +# Verify port availability +# Check for conflicts +``` + +4. **Check dependencies:** +```bash +# Verify dependencies are available +# Check service health +``` + +**Prevention:** +- Add container health checks +- Implement dependency checks +- Add startup validation + +--- + +## Escalation Procedures + +### When to Escalate + +Escalate to on-call if: +- Production outage +- Data loss or corruption +- Security breach +- Critical bug affecting multiple users +- Issue cannot be resolved within 30 minutes + +### Escalation Steps + +1. **Document the issue:** + - Describe the problem + - Include error messages + - Include logs + - Include request IDs + +2. **Attempt resolution:** + - Follow troubleshooting steps + - Document attempted solutions + - Note what worked/didn't work + +3. **Escalate:** + - Contact on-call engineer + - Provide documentation + - Provide context + - Provide urgency + +4. **Follow up:** + - Monitor resolution + - Document resolution + - Update runbooks + - Share learnings + +### On-Call Contact + +- **Primary:** [On-call engineer] +- **Secondary:** [Backup engineer] +- **Escalation:** [Engineering manager] + +### Incident Response + +1. **Detect:** Monitoring alert or user report +2. **Acknowledge:** Acknowledge alert within 5 minutes +3. **Investigate:** Gather information, check logs +4. **Mitigate:** Implement temporary fix if needed +5. **Resolve:** Implement permanent fix +6. **Post-mortem:** Document incident, learnings, improvements + +--- + +## Common Error Messages + +### Backend Errors + +| Error | Cause | Resolution | +|-------|-------|------------| +| `ECONNREFUSED` | Port not available | Check port, kill process | +| `ETIMEDOUT` | Connection timeout | Check network, increase timeout | +| `Unauthorized` | Invalid auth | Check credentials, token | +| `Forbidden` | Insufficient permissions | Check user role, permissions | +| `InternalServerError` | Server error | Check logs, fix bug | + +### Web Errors + +| Error | Cause | Resolution | +|-------|-------|------------| +| `Network Error` | Backend unreachable | Check backend, network | +| `401 Unauthorized` | Invalid token | Refresh token, re-auth | +| `403 Forbidden` | Insufficient permissions | Check user role | +| `404 Not Found` | Resource not found | Check URL, resource exists | +| `500 Internal Server Error` | Server error | Check logs, fix bug | + +### Mobile Errors + +| Error | Cause | Resolution | +|-------|-------|------------| +| `Network request failed` | Network issue | Check network, backend | +| `Auth failed` | Invalid credentials | Check credentials, re-auth | +| `WebSocket error` | Connection issue | Check backend, network | +| `Storage error` | Secure storage issue | Check storage permissions | +| `App crashed` | Runtime error | Check logs, fix bug | + +--- + +## Monitoring and Alerts + +### Key Metrics to Monitor + +**Backend:** +- CPU usage +- Memory usage +- API response times +- Error rate +- Database query times +- WebSocket connection count + +**Web:** +- Page load time +- Bundle size +- API response times +- Error rate +- WebSocket connection count + +**Mobile:** +- App launch time +- API response times +- Error rate +- WebSocket connection count +- Crash rate + +### Alert Thresholds + +| Metric | Warning | Critical | +|--------|---------|----------| +| CPU usage | 70% | 90% | +| Memory usage | 70% | 90% | +| API response time | 1s | 5s | +| Error rate | 5% | 10% | +| Database query time | 500ms | 2s | + +### Monitoring Tools + +- Backend: Winston logging, Prometheus metrics +- Web: Browser devtools, Lighthouse +- Mobile: Expo logs, Sentry + +--- + +## References + +- **README.md** - Project overview +- **ARCHITECTURE_DOCUMENTATION.md** - System architecture +- **API_DOCUMENTATION_GUIDE.md** - API documentation +- **FUNCTIONALITY_REVIEW.md** - Functional gaps and issues +- **CUTOVER_WEB.md** - Web cutover procedures +- **CUTOVER_MOBILE.md** - Mobile cutover procedures