# jaikumararjunan/alchemy architecture

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

- Interactive diagram: https://gitdiagram.com/jaikumararjunan/alchemy
- Repository: https://github.com/jaikumararjunan/alchemy

## Overview

Alchemy is an AI-powered trading platform with a React interface and FastAPI backend. Its principal workflow accepts an order, validates its state and risk, then dispatches execution to a paper-trading engine or exchange gateway; users can review portfolios, history, and analytics. Authentication, capital preservation, alerts, market intelligence, and security auditing are substantial supporting capabilities. The graph reflects documented features and sampled/indexed relationships; unsampled route wiring and several subsystem internals remain unverified, so those connections are omitted.

Main entry points: [`alchemy/workflows/engine.py`](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/workflows/engine.py) (Order workflow), [`alchemy/api/auth_routes.py`](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/api/auth_routes.py) (Authentication API), [`alchemy/api/paper_trading_routes.py`](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/api/paper_trading_routes.py) (Paper trading API), [`alchemy/execution/order_pipeline.py`](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/order_pipeline.py) (Order pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User interface"]
  node_web["Trading UI<br/>[App.jsx]"]
  node_authui["Sign-in pages<br/>[LoginPage.jsx]"]
end

subgraph group_identity["Identity and security"]
  node_authroutes["Authentication API<br/>[auth_routes.py]"]
  node_authservice["Authentication service<br/>[service.py]"]
  node_middleware["Request security<br/>[middleware.py]"]
  node_audit["Security audit<br/>[audit_engine.py]"]
end

subgraph group_trading["Trading and execution"]
  node_ordersapi["Paper trading API"]
  node_workflow["Order workflow<br/>[engine.py]"]
  node_risk["Risk manager<br/>[manager.py]"]
  node_pipeline["Order pipeline<br/>[order_pipeline.py]"]
  node_paper["Paper execution<br/>[engine.py]"]
  node_capital["Capital engine<br/>[capital_engine.py]"]
  node_tokens["Exchange credentials<br/>[manager.py]"]
  node_binance["Binance gateway<br/>[binance_gateway.py]"]
  node_delta["Delta gateway<br/>[delta_gateway.py]"]
  node_kite["Kite gateway<br/>[kite_gateway.py]"]
  node_ib["IB gateway<br/>[ib_gateway.py]"]
  node_store[("Capital state<br/>[capital_engine.py]")]
end

subgraph group_insight["Market insight"]
  node_analytics["Portfolio analytics<br/>[portfolio.py]"]
  node_signals["Signal engine<br/>[engine.py]"]
  node_emotion["Market emotion<br/>[ei_engine.py]"]
  node_alerts["Price alerts<br/>[alert_routes.py]"]
  node_notifications["Notifications<br/>[dispatcher.py]"]
end

node_user(("Trader"))
node_exchange{{"Trading exchanges"}}

node_user -->|"uses"| node_web
node_web -->|"offers sign-in"| node_authui
node_authroutes -->|"delegates auth"| node_authservice
node_authroutes -->|"uses audit"| node_audit
node_authroutes -->|"uses identity checks"| node_middleware
node_ordersapi -->|"requires identity"| node_middleware
node_ordersapi -->|"reads and resets portfolio"| node_paper
node_workflow -->|"checks trade risk"| node_risk
node_workflow -->|"gets credentials"| node_tokens
node_workflow -->|"dispatches orders"| node_binance
node_workflow -->|"dispatches orders"| node_delta
node_workflow -->|"dispatches orders"| node_kite
node_workflow -->|"dispatches orders"| node_ib
node_pipeline -->|"applies risk checks"| node_risk
node_pipeline -->|"executes paper orders"| node_paper
node_capital -->|"loads and saves state"| node_store
node_ordersapi -->|"configures capital"| node_capital
node_user -->|"connects accounts"| node_exchange
node_exchange -->|"supports Binance"| node_binance
node_exchange -->|"supports Delta"| node_delta
node_exchange -->|"supports Zerodha"| node_kite
node_user -->|"reviews portfolio"| node_analytics
node_user -->|"uses AI strategies"| node_signals
node_user -->|"views market regimes"| node_emotion
node_user -->|"sets price alerts"| node_alerts
node_alerts -->|"dispatches alerts"| node_notifications

click node_web "https://github.com/jaikumararjunan/alchemy/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/jaikumararjunan/alchemy/blob/main/frontend/src/pages/auth/LoginPage.jsx"
click node_authroutes "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/api/auth_routes.py"
click node_authservice "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/auth/service.py"
click node_middleware "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/auth/middleware.py"
click node_audit "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/security/audit_engine.py"
click node_ordersapi "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/api/paper_trading_routes.py"
click node_workflow "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/workflows/engine.py"
click node_risk "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/risk/manager.py"
click node_pipeline "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/order_pipeline.py"
click node_paper "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/paper_trading/engine.py"
click node_capital "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/trading/capital_engine.py"
click node_tokens "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/tokens/manager.py"
click node_binance "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/crypto/binance_gateway.py"
click node_delta "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/crypto/delta_gateway.py"
click node_kite "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/kite_gateway.py"
click node_ib "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/ib_gateway.py"
click node_store "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/trading/capital_engine.py"
click node_analytics "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/analytics/portfolio.py"
click node_signals "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/signals/engine.py"
click node_emotion "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/intelligence/emotion/ei_engine.py"
click node_alerts "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/api/alert_routes.py"
click node_notifications "https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/notifications/dispatcher.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_web,node_authui toneBlue
class node_authroutes,node_authservice,node_middleware,node_audit toneAmber
class node_ordersapi,node_workflow,node_risk,node_pipeline,node_paper,node_capital,node_tokens,node_binance,node_delta,node_kite,node_ib,node_store toneMint
class node_analytics,node_signals,node_emotion,node_alerts,node_notifications toneRose
class node_user,node_exchange toneIndigo
```

## Components

### User interface

- [Trading UI](https://github.com/jaikumararjunan/alchemy/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Sign-in pages](https://github.com/jaikumararjunan/alchemy/blob/main/frontend/src/pages/auth/LoginPage.jsx): `frontend/src/pages/auth/LoginPage.jsx`

### Identity and security

- [Authentication API](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/api/auth_routes.py): `alchemy/api/auth_routes.py`
- [Authentication service](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/auth/service.py): `alchemy/auth/service.py`
- [Request security](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/auth/middleware.py): `alchemy/auth/middleware.py`
- [Security audit](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/security/audit_engine.py): `alchemy/security/audit_engine.py`

### Trading and execution

- [Paper trading API](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/api/paper_trading_routes.py): `alchemy/api/paper_trading_routes.py`
- [Order workflow](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/workflows/engine.py): `alchemy/workflows/engine.py`
- [Risk manager](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/risk/manager.py): `alchemy/risk/manager.py`
- [Order pipeline](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/order_pipeline.py): `alchemy/execution/order_pipeline.py`
- [Paper execution](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/paper_trading/engine.py): `alchemy/paper_trading/engine.py`
- [Capital engine](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/trading/capital_engine.py): `alchemy/trading/capital_engine.py`
- [Exchange credentials](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/tokens/manager.py): `alchemy/tokens/manager.py`
- [Binance gateway](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/crypto/binance_gateway.py): `alchemy/execution/crypto/binance_gateway.py`
- [Delta gateway](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/crypto/delta_gateway.py): `alchemy/execution/crypto/delta_gateway.py`
- [Kite gateway](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/kite_gateway.py): `alchemy/execution/kite_gateway.py`
- [IB gateway](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/execution/ib_gateway.py): `alchemy/execution/ib_gateway.py`
- [Capital state](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/trading/capital_engine.py): `alchemy/trading/capital_engine.py`

### Market insight

- [Portfolio analytics](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/analytics/portfolio.py): `alchemy/analytics/portfolio.py`
- [Signal engine](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/signals/engine.py): `alchemy/signals/engine.py`
- [Market emotion](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/intelligence/emotion/ei_engine.py): `alchemy/intelligence/emotion/ei_engine.py`
- [Price alerts](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/api/alert_routes.py): `alchemy/api/alert_routes.py`
- [Notifications](https://github.com/jaikumararjunan/alchemy/blob/main/alchemy/notifications/dispatcher.py): `alchemy/notifications/dispatcher.py`

### Other components

- **Trader**
- **Trading exchanges**

## Connections

- Trader → Trading UI: uses (evidence: `README.md`)
- Trading UI → Sign-in pages: offers sign-in (evidence: `frontend/src/App.jsx`)
- Authentication API → Authentication service: delegates auth (evidence: `alchemy/api/auth_routes.py`)
- Authentication API → Security audit: uses audit (evidence: `alchemy/api/auth_routes.py`)
- Authentication API → Request security: uses identity checks (evidence: `alchemy/api/auth_routes.py`)
- Paper trading API → Request security: requires identity (evidence: `alchemy/api/paper_trading_routes.py`)
- Paper trading API → Paper execution: reads and resets portfolio (evidence: `alchemy/api/paper_trading_routes.py`)
- Order workflow → Risk manager: checks trade risk (evidence: `alchemy/workflows/engine.py`)
- Order workflow → Exchange credentials: gets credentials (evidence: `alchemy/workflows/engine.py`)
- Order workflow → Binance gateway: dispatches orders (evidence: `alchemy/workflows/engine.py`)
- Order workflow → Delta gateway: dispatches orders (evidence: `alchemy/workflows/engine.py`)
- Order workflow → Kite gateway: dispatches orders (evidence: `alchemy/workflows/engine.py`)
- Order workflow → IB gateway: dispatches orders (evidence: `alchemy/workflows/engine.py`)
- Order pipeline → Risk manager: applies risk checks (evidence: `alchemy/execution/order_pipeline.py`)
- Order pipeline → Paper execution: executes paper orders (evidence: `alchemy/execution/order_pipeline.py`)
- Capital engine → Capital state: loads and saves state (evidence: `alchemy/trading/capital_engine.py`)
- Paper trading API → Capital engine: configures capital
- Trader → Trading exchanges: connects accounts (evidence: `README.md`)
- Trading exchanges → Binance gateway: supports Binance (evidence: `README.md`)
- Trading exchanges → Delta gateway: supports Delta (evidence: `README.md`)
- Trading exchanges → Kite gateway: supports Zerodha (evidence: `README.md`)
- Trader → Portfolio analytics: reviews portfolio (evidence: `README.md`)
- Trader → Signal engine: uses AI strategies (evidence: `README.md`)
- Trader → Market emotion: views market regimes (evidence: `README.md`)
- Trader → Price alerts: sets price alerts (evidence: `README.md`)
- Price alerts → Notifications: dispatches alerts (evidence: `README.md`)
