Golden Flow

Golden Flow — Aegis Decision Intelligence Platform

» **Every future change must preserve this flow.**
» If any step breaks, the platform is not production-ready.

---


THE FLOW

Launch
  ↓
Login (local session, no external auth required)
  ↓
Connect Zerodha
  ├── Enter API Key + API Secret (Settings → Broker Connections)
  ├── Click "Connect Zerodha" → opens Kite login in new tab
  ├── User authorizes → redirected back with request_token
  └── Paste request_token → token exchange → encrypted storage
  ↓
OAuth Success
  ├── Access token stored in SecureVault (AES-GCM, session key in memory)
  ├── Broker connection established (BrokerRuntime.CONNECTED)
  ├── Capability Registry populated (Positions, Orders, RealtimeTicks, etc.)
  └── StatusBar shows: Zerodha · connected · Vault encrypted
  ↓
Portfolio Sync
  ├── BrokerRuntime.sync() pulls positions from Kite API
  ├── Portfolio computePortfolio() aggregates across brokers
  ├── Exposure engine calculates notional, exposure %, concentration
  ├── Capital health: available funds, used margin, margin ratio
  └── Verification layer validates every API response shape
  ↓
Mission Control
  ├── Capital Health widget ← runtime (real funds from Kite)
  ├── Broker Health widget ← runtime (live connection status)
  ├── Exposure widget ← runtime (real position exposure)
  ├── P&L widget ← runtime (real unrealized P&L from positions)
  ├── Open Positions widget ← runtime (real positions from Kite)
  └── Protection widget ← runtime (rules armed/triggered from engine)
  ↓
Protection Enabled
  ├── ProtectionRuntime bootstraps with default rules
  ├── Rules evaluate against LIVE broker metrics (daily_pnl, exposure, etc.)
  ├── UNKNOWN verdicts for missing metrics (never guesses)
  ├── Priority suppression on conflicts (highest priority wins)
  ├── Emergency mode available (only high-priority rules armed)
  └── Rule Studio compiles visual rules → Protection Engine
  ↓
Live Updates
  ├── BrokerRuntime polls positions every 30s (configurable)
  ├── Staleness detection: data older than threshold → warning
  ├── Reconciliation: broker state vs platform state
  ├── Conflict resolution: broker-wins for broker fields
  └── Mission Control widgets refresh on sync events

---


WHAT EACH MODULE DOES

  Step | Module | What It Does | Runtime
  Launch | `app/layout.tsx` | Shell renders, sidebar, statusbar, command palette | React
  Connect | `Settings → Broker Connections` | OAuth flow: credentials → login URL → token exchange | React
  OAuth | `ZerodhaBroker.authenticate()` | POST /session/token with SHA-256 checksum | WebCrypto
  Encrypted Storage | `SecureVault` | AES-GCM encrypt session, store ciphertext | WebCrypto
  Broker Connection | `BrokerRuntime.connect()` | Auth → sync → health monitoring | Pure TS
  Capability Detection | `CapabilityRegistry` | Register broker capabilities, query via supports() | Pure TS
  Position Sync | `BrokerRuntime.sync()` | GET /portfolio/positions → validate → cache | Pure TS
  Portfolio Compute | `computePortfolio()` | Aggregate positions, exposure, allocation, P&L | Pure TS
  Protection Eval | `ProtectionRuntime.evaluate()` | Rules × metrics → verdicts + traces | Pure TS
  Rule Compilation | `compileRule()` | Visual IF/THEN → domain ProtectionRule | Pure TS
  Mission Control | `MissionControlView` | Widgets subscribe to runtimes via hooks | React
  Verification | `verification.ts` | Validate shapes, detect staleness, reconcile | Pure TS

---


DATA FLOW

Zerodha API ←→ ZerodhaBroker (adapter)
       ↓
  BrokerRuntime (connect, sync, cache, health)
       ↓
  ┌────┴────┐
  │         │
  ↓         ↓
Portfolio  Protection
Runtime    Runtime
  │         │
  ↓         ↓
Mission    Rule
Control    Studio
(Widgets)  (Compiler)

**Every number the user sees traces back to a real broker API call.**
No hardcoded values. No mock data in production. No fabricated numbers.

---


FAILURE MODES

  Failure | Response | User Sees
  Broker disconnected | Status bar shows "disconnected" | Red indicator, "Reconnect" button
  API key invalid | Token exchange fails | Error message in Settings
  Token expired (06:00 IST) | Session stale detection | Warning in status bar, re-auth prompt
  API response malformed | Verification layer rejects | Empty state, "Data unavailable"
  Positions stale (>60s) | Staleness check triggers | Warning in Mission Control
  Metric missing for rule | UNKNOWN verdict (never guess) | "Insufficient data" in Protection
  Vault locked | Credentials not readable | "Vault locked" in status bar
  WebCrypto unavailable | No encryption | "Unsecured" warning in status bar

---


ACCEPTANCE CRITERIA

A trader with a real Zerodha account can:

1. ✅ Install Aegis and launch it
2. ✅ See the Settings page with broker connections
3. ✅ Enter their API key and secret
4. ✅ Click "Connect Zerodha" → Kite login opens
5. ✅ Authorize → paste request_token → connection established
6. ✅ See real positions in Mission Control
7. ✅ See real capital/funds in Mission Control
8. ✅ See live P&L updating
9. ✅ Protection rules evaluating against real data
10. ✅ Vault status showing "encrypted" in status bar
11. ✅ Disconnect and reconnect working
12. ✅ No mock data visible anywhere

**Without touching mock data.**