# 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