docs: add comprehensive documentation for coding agents
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.
This commit is contained in:
parent
6b37cb059e
commit
83bc3af260
662
docs/planned/API_DOCUMENTATION_GUIDE.md
Normal file
662
docs/planned/API_DOCUMENTATION_GUIDE.md
Normal file
@ -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 <platform-jwt-token>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Legacy JWT (Local Development Only)**
|
||||||
|
```bash
|
||||||
|
# Request header
|
||||||
|
Authorization: Bearer <legacy-jwt-token>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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
|
||||||
1028
docs/planned/ARCHITECTURE_DOCUMENTATION.md
Normal file
1028
docs/planned/ARCHITECTURE_DOCUMENTATION.md
Normal file
File diff suppressed because it is too large
Load Diff
737
docs/planned/ONBOARDING_GUIDE.md
Normal file
737
docs/planned/ONBOARDING_GUIDE.md
Normal file
@ -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 <div>Your component</div>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
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 <View>Your screen</View>;
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
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!
|
||||||
1398
docs/planned/TROUBLESHOOTING_GUIDE.md
Normal file
1398
docs/planned/TROUBLESHOOTING_GUIDE.md
Normal file
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue
Block a user