# juma1-hub/supa_ai architecture

> Architecture diagram of the GitHub repository juma1-hub/supa_ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/juma1-hub/supa_ai
- Repository: https://github.com/juma1-hub/supa_ai

## Overview

Supa AI combines a trading dashboard and strategy-builder prototype with a backend that exposes authenticated account, market-analysis, and Demo-workflow APIs. The user-facing flow spans preview or Deriv sign-in, workspace navigation, strategy drafting/review, and market monitoring; the README cautions that frontend drafts are local and its digit panel may be illustrative. Sampled backend code confirms that analysis is read-only and Demo purchase is disabled. Some backend wiring is supported by the SOURCE INDEX; unsampled UI-to-backend connections are omitted.

Main entry points: [`backend/app/main.py`](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/main.py) (FastAPI endpoints), [`frontend/app/workspace/WorkspaceClient.tsx`](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/workspace/WorkspaceClient.tsx) (Workspace UI), [`frontend/app/account/page.tsx`](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/account/page.tsx) (Account selection), [`backend/app/deriv_market_data.py`](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/deriv_market_data.py) (Public market collector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard and workspace"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_preview["Preview workspace<br/>[page.tsx]"]
  node_workspace["Workspace UI"]
  node_auto_trader["Strategy workspace<br/>[SupaAutoTrader.tsx]"]
end

subgraph group_identity["Identity and accounts"]
  node_oauth_callback["OAuth callback<br/>[page.tsx]"]
  node_account_ui["Account selection<br/>[page.tsx]"]
  node_account_routes["Account API routes<br/>[route.ts]"]
  node_deriv_auth_routes["Deriv auth routes<br/>[route.ts]"]
  node_deriv_account["Deriv account checks<br/>[deriv_account.py]"]
end

subgraph group_analysis["Strategy and market analysis"]
  node_browser_engine["Browser strategy engine<br/>[strategy-engine.ts]"]
  node_rules["Strategy rule validation<br/>[strategy_rules.py]"]
  node_strategy_api["Strategy analysis API"]
  node_engine["Strategy state engine<br/>[engine.py]"]
  node_market_collector["Public market collector"]
end

subgraph group_backend["API and runtime"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_runtime["User runtime<br/>[user_runtime.py]"]
  node_purchase_reconciliation["Purchase reconciliation"]
  node_execution_guard["Execution guard<br/>[execution_guard.py]"]
  node_demo_trading["Demo proposals and status"]
end

subgraph group_persistence["Persistence and integrations"]
  node_auth["Supabase auth verifier<br/>[supa_auth.py]"]
  node_store["Supabase persistence adapter<br/>[supa_store.py]"]
end

node_visitor(("Visitor / user"))
node_deriv{{"Deriv services"}}
node_supabase[("Supabase services")]
node_local_storage[("Browser local storage")]

node_visitor -->|"opens"| node_dashboard
node_visitor -->|"previews"| node_preview
node_visitor -->|"signs in"| node_oauth_callback
node_dashboard -->|"opens workspace"| node_workspace
node_preview -->|"renders"| node_workspace
node_workspace -->|"renders"| node_auto_trader
node_auto_trader -->|"uses"| node_browser_engine
node_browser_engine -->|"persists drafts"| node_local_storage
node_oauth_callback -->|"exchanges code"| node_deriv
node_visitor -->|"selects account"| node_account_ui
node_account_ui -.->|"requests account choices"| node_deriv_auth_routes
node_account_ui -.->|"loads linked accounts"| node_account_routes
node_api -->|"verifies identity"| node_auth
node_auth -->|"verifies token"| node_supabase
node_api -->|"validates rules"| node_rules
node_api -->|"handles analysis"| node_strategy_api
node_strategy_api -->|"updates analysis"| node_engine
node_api -->|"controls collection"| node_market_collector
node_market_collector -->|"subscribes to ticks"| node_deriv
node_market_collector -->|"feeds statistics"| node_engine
node_api -->|"serves user state"| node_runtime
node_runtime -->|"uses analysis state"| node_engine
node_api -->|"handles reconciliation"| node_purchase_reconciliation
node_api -.->|"guards execution"| node_execution_guard
node_api -->|"checks accounts"| node_deriv_account
node_deriv_account -->|"checks balance"| node_deriv
node_api -->|"prepares Demo proposals"| node_demo_trading
node_demo_trading -->|"requests proposals"| node_deriv
node_api -->|"persists state"| node_store
node_store -->|"reads and writes"| node_supabase
node_workspace -->|"monitors public ticks"| node_deriv

click node_dashboard "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/page.tsx"
click node_preview "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/preview/page.tsx"
click node_workspace "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/workspace/WorkspaceClient.tsx"
click node_auto_trader "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/workspace/SupaAutoTrader.tsx"
click node_oauth_callback "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/auth/deriv/callback/page.tsx"
click node_account_ui "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/account/page.tsx"
click node_account_routes "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/api/account/links/route.ts"
click node_deriv_auth_routes "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/api/auth/deriv/accounts/route.ts"
click node_browser_engine "https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/workspace/strategy-engine.ts"
click node_api "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/main.py"
click node_rules "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/strategy_rules.py"
click node_strategy_api "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/strategy_engine_api.py"
click node_engine "https://github.com/juma1-hub/supa_ai/blob/main/backend/supa_ai_engine/engine.py"
click node_market_collector "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/deriv_market_data.py"
click node_runtime "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/user_runtime.py"
click node_purchase_reconciliation "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/purchase_reconciliation.py"
click node_execution_guard "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/execution_guard.py"
click node_deriv_account "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/deriv_account.py"
click node_demo_trading "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/deriv_demo_trading.py"
click node_auth "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/supa_auth.py"
click node_store "https://github.com/juma1-hub/supa_ai/blob/main/backend/app/supa_store.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_preview,node_workspace,node_auto_trader,node_visitor toneBlue
class node_oauth_callback,node_account_ui,node_account_routes,node_deriv_auth_routes,node_deriv_account,node_supabase,node_local_storage toneAmber
class node_browser_engine,node_rules,node_strategy_api,node_engine,node_market_collector toneMint
class node_api,node_runtime,node_purchase_reconciliation,node_execution_guard,node_demo_trading toneRose
class node_auth,node_store,node_deriv toneIndigo
```

## Components

### Dashboard and workspace

- [Dashboard](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Preview workspace](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/preview/page.tsx): `frontend/app/preview/page.tsx`
- [Workspace UI](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/workspace/WorkspaceClient.tsx): `frontend/app/workspace/WorkspaceClient.tsx`
- [Strategy workspace](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/workspace/SupaAutoTrader.tsx): `frontend/app/workspace/SupaAutoTrader.tsx`

### Identity and accounts

- [OAuth callback](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/auth/deriv/callback/page.tsx): `frontend/app/auth/deriv/callback/page.tsx`
- [Account selection](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/account/page.tsx): `frontend/app/account/page.tsx`
- [Account API routes](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/api/account/links/route.ts): `frontend/app/api/account/links/route.ts`
- [Deriv auth routes](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/api/auth/deriv/accounts/route.ts): `frontend/app/api/auth/deriv/accounts/route.ts`
- [Deriv account checks](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/deriv_account.py): `backend/app/deriv_account.py`

### Strategy and market analysis

- [Browser strategy engine](https://github.com/juma1-hub/supa_ai/blob/main/frontend/app/workspace/strategy-engine.ts): `frontend/app/workspace/strategy-engine.ts`
- [Strategy rule validation](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/strategy_rules.py): `backend/app/strategy_rules.py`
- [Strategy analysis API](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/strategy_engine_api.py): `backend/app/strategy_engine_api.py`
- [Strategy state engine](https://github.com/juma1-hub/supa_ai/blob/main/backend/supa_ai_engine/engine.py): `backend/supa_ai_engine/engine.py`
- [Public market collector](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/deriv_market_data.py): `backend/app/deriv_market_data.py`

### API and runtime

- [FastAPI endpoints](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [User runtime](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/user_runtime.py): `backend/app/user_runtime.py`
- [Purchase reconciliation](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/purchase_reconciliation.py): `backend/app/purchase_reconciliation.py`
- [Execution guard](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/execution_guard.py): `backend/app/execution_guard.py`
- [Demo proposals and status](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/deriv_demo_trading.py): `backend/app/deriv_demo_trading.py`

### Persistence and integrations

- [Supabase auth verifier](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/supa_auth.py): `backend/app/supa_auth.py`
- [Supabase persistence adapter](https://github.com/juma1-hub/supa_ai/blob/main/backend/app/supa_store.py): `backend/app/supa_store.py`

### Other components

- **Visitor / user**
- **Deriv services**
- **Supabase services**
- **Browser local storage**

## Connections

- Visitor / user → Dashboard: opens (evidence: `README.md`)
- Visitor / user → Preview workspace: previews (evidence: `README.md`)
- Visitor / user → OAuth callback: signs in (evidence: `README.md`)
- Dashboard → Workspace UI: opens workspace (evidence: `README.md`)
- Preview workspace → Workspace UI: renders (evidence: `frontend/app/preview/page.tsx`)
- Workspace UI → Strategy workspace: renders (evidence: `frontend/app/workspace/WorkspaceClient.tsx`)
- Strategy workspace → Browser strategy engine: uses (evidence: `frontend/app/workspace/SupaAutoTrader.tsx`)
- Browser strategy engine → Browser local storage: persists drafts (evidence: `README.md`)
- OAuth callback → Deriv services: exchanges code (evidence: `README.md`)
- Visitor / user → Account selection: selects account (evidence: `README.md`)
- Account selection → Deriv auth routes: requests account choices
- Account selection → Account API routes: loads linked accounts
- FastAPI endpoints → Supabase auth verifier: verifies identity (evidence: `backend/app/main.py`)
- Supabase auth verifier → Supabase services: verifies token (evidence: `backend/app/supa_auth.py`)
- FastAPI endpoints → Strategy rule validation: validates rules (evidence: `backend/app/main.py`)
- FastAPI endpoints → Strategy analysis API: handles analysis (evidence: `backend/app/main.py`)
- Strategy analysis API → Strategy state engine: updates analysis (evidence: `backend/app/strategy_engine_api.py`)
- FastAPI endpoints → Public market collector: controls collection (evidence: `backend/app/main.py`)
- Public market collector → Deriv services: subscribes to ticks (evidence: `backend/app/deriv_market_data.py`)
- Public market collector → Strategy state engine: feeds statistics (evidence: `backend/app/deriv_market_data.py`)
- FastAPI endpoints → User runtime: serves user state (evidence: `backend/app/main.py`)
- User runtime → Strategy state engine: uses analysis state (evidence: `backend/app/user_runtime.py`)
- FastAPI endpoints → Purchase reconciliation: handles reconciliation (evidence: `backend/app/main.py`)
- FastAPI endpoints → Execution guard: guards execution
- FastAPI endpoints → Deriv account checks: checks accounts (evidence: `backend/app/main.py`)
- Deriv account checks → Deriv services: checks balance (evidence: `backend/app/deriv_account.py`)
- FastAPI endpoints → Demo proposals and status: prepares Demo proposals (evidence: `backend/app/main.py`)
- Demo proposals and status → Deriv services: requests proposals (evidence: `backend/app/deriv_demo_trading.py`)
- FastAPI endpoints → Supabase persistence adapter: persists state (evidence: `backend/app/main.py`)
- Supabase persistence adapter → Supabase services: reads and writes (evidence: `backend/app/supa_store.py`)
- Workspace UI → Deriv services: monitors public ticks (evidence: `frontend/app/workspace/WorkspaceClient.tsx`)