# 01 - Frontend Architecture
### Overview
OpenAlgo features a modern React 19 Single Page Application (SPA) built with TypeScript, Vite, and Tailwind CSS 4. The frontend provides a responsive trading interface with real-time market data, visual workflow automation, and comprehensive strategy management.
### Technology Stack
| Technology | Version | Purpose |
| ---------------- | --------------- | ---------------------------- |
| React | 19.2.3 | UI framework |
| TypeScript | 5.9.3 | Type safety |
| Vite | 7.2.4 | Build tool & dev server |
| Tailwind CSS | 4.1.18 | Utility-first styling |
| React Router | 7.12.0 | Client-side routing |
| Zustand | 5.0.9 | Client state management |
| TanStack Query | 5.90.16 | Server state & caching |
| Axios | 1.13.5 | HTTP client |
| Socket.IO Client | 4.8.3 | Real-time events |
| @xyflow/react | 12.3.6 | Flow editor canvas |
| Plotly.js | react-plotly.js | Interactive analytics charts |
| Radix UI | Latest | Accessible UI primitives |
### Architecture Diagram
### Directory Structure
```
frontend/
├── src/
│ ├── api/ # API integration modules
│ │ ├── client.ts # Axios clients (apiClient, webClient, authClient)
│ │ ├── auth.ts # Authentication API
│ │ ├── trading.ts # Trading operations API
│ │ ├── strategy.ts # Strategy management API
│ │ ├── flow.ts # Flow workflow API
│ │ ├── gex.ts # GEX analytics API
│ │ ├── iv-chart.ts # IV Chart API
│ │ ├── iv-smile.ts # IV Smile API
│ │ ├── oi-profile.ts # OI Profile API
│ │ ├── oi-tracker.ts # OI Tracker API
│ │ ├── straddle-chart.ts # ATM Straddle Chart API
│ │ ├── vol-surface.ts # 3D Volatility Surface API
│ │ ├── option-chain.ts # Option chain API
│ │ ├── health.ts # Health monitoring API
│ │ ├── chartink.ts # Chartink API
│ │ ├── python-strategy.ts # Python strategy API
│ │ ├── telegram.ts # Telegram API
│ │ └── admin.ts # Admin API
│ │
│ ├── app/
│ │ └── providers.tsx # TanStack Query & theme providers
│ │
│ ├── components/
│ │ ├── auth/
│ │ │ └── AuthSync.tsx # Flask session ↔ Zustand sync
│ │ ├── flow/
│ │ │ ├── nodes/ # 50+ flow node components
│ │ │ ├── edges/ # Edge components
│ │ │ └── panels/ # Config, Palette, Execution panels
│ │ ├── layout/
│ │ │ ├── Layout.tsx # Main protected layout
│ │ │ ├── FullWidthLayout.tsx
│ │ │ ├── Navbar.tsx
│ │ │ ├── Footer.tsx
│ │ │ └── MobileBottomNav.tsx
│ │ ├── socket/
│ │ │ └── SocketProvider.tsx
│ │ └── ui/ # 30+ shadcn/ui components
│ │
│ ├── hooks/ # Custom React hooks
│ │ ├── useSocket.ts # Socket.IO connection
│ │ ├── useLivePrice.ts # Live price feed
│ │ ├── useLiveQuote.ts # Live quote feed
│ │ ├── useMarketData.ts # WebSocket market data
│ │ ├── useMarketStatus.ts # Market status tracking
│ │ ├── useOptionChainLive.ts # Live option chain data
│ │ ├── useOptionChainPolling.ts # Option chain polling
│ │ ├── useOrderEventRefresh.ts # Order event refresh
│ │ └── usePageVisibility.ts # Page visibility tracking
│ │
│ ├── pages/ # Page components (60+ all lazy-loaded)
│ │ ├── Dashboard.tsx # Main dashboard
│ │ ├── Positions.tsx # Position management
│ │ ├── Tools.tsx # Analytics tools hub
│ │ ├── GEXDashboard.tsx # Gamma Exposure dashboard
│ │ ├── IVSmile.tsx # IV Smile analysis
│ │ ├── IVChart.tsx # IV Chart
│ │ ├── OIProfile.tsx # OI Profile analysis
│ │ ├── OITracker.tsx # Open Interest tracker
│ │ ├── MaxPain.tsx # Max Pain analysis
│ │ ├── StraddleChart.tsx # ATM Straddle chart
│ │ ├── VolSurface.tsx # 3D Volatility Surface
│ │ ├── OptionChain.tsx # Option chain viewer
│ │ ├── strategy/ # Strategy pages
│ │ ├── flow/ # Flow editor pages
│ │ ├── admin/ # Admin pages
│ │ ├── monitoring/ # Monitoring dashboards
│ │ ├── python-strategy/ # Python strategy pages
│ │ ├── chartink/ # Chartink pages
│ │ └── telegram/ # Telegram pages
│ │
│ ├── stores/ # Zustand state stores
│ │ ├── authStore.ts # Authentication state
│ │ ├── themeStore.ts # Theme preferences
│ │ └── flowWorkflowStore.ts
│ │
│ ├── types/ # TypeScript type definitions
│ │
│ ├── App.tsx # Route definitions
│ ├── main.tsx # Entry point
│ └── index.css # Global styles + CSS variables
│
├── vite.config.ts # Vite configuration
├── tsconfig.app.json # TypeScript config
├── biome.json # Linter/formatter config
└── package.json
```
### State Management
#### 1. Zustand (Client State)
Lightweight state management for UI state that persists across sessions.
```typescript
// stores/authStore.ts
interface AuthStore {
user: User | null
apiKey: string | null
isAuthenticated: boolean
login: (username: string, broker: string) => void
logout: () => void
checkSession: () => boolean // 3 AM IST expiry
}
// Usage in component
const { user, isAuthenticated } = useAuthStore()
```
**Stores:**
* `authStore` - User session, API key, authentication state
* `themeStore` - Dark/light mode, analyzer mode toggle
* `alertStore` - Toast notification state and management
* `flowWorkflowStore` - Flow editor nodes, edges, selection state
#### 2. TanStack Query (Server State)
Handles all server data fetching with automatic caching and refetching.
```typescript
// Configuration (app/providers.tsx)
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 60 * 1000, // 1 minute
refetchOnWindowFocus: true,
retry: 1,
},
},
})
// Usage in component
const { data: positions, isLoading } = useQuery({
queryKey: ['positions'],
queryFn: () => tradingApi.getPositions()
})
```
### API Integration
#### Three Axios Clients
```typescript
// 1. apiClient - For /api/v1/* endpoints (API key auth)
const apiClient = axios.create({
baseURL: '/api/v1',
headers: { 'Content-Type': 'application/json' }
})
// 2. webClient - For session-based routes (CSRF required)
const webClient = axios.create({
baseURL: '',
withCredentials: true
})
// 3. authClient - For login/setup (form data + CSRF)
const authClient = axios.create({
baseURL: '',
headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
})
```
#### CSRF Protection
```typescript
// Automatic CSRF token injection
webClient.interceptors.request.use(async (config) => {
if (['post', 'put', 'delete'].includes(config.method)) {
const csrfToken = await fetchCSRFToken()
config.headers['X-CSRFToken'] = csrfToken
}
return config
})
```
### Routing Structure
#### Route Categories
| Category | Example Routes | Layout |
| ----------- | --------------------------------------------------------------------- | ----------------- |
| Public | `/`, `/login`, `/setup`, `/download` | None |
| Broker Auth | `/broker`, `/broker/:broker/totp` | None |
| Protected | `/dashboard`, `/positions`, `/strategy` | Standard Layout |
| Analytics | `/tools`, `/gex`, `/ivsmile`, `/oitracker`, `/maxpain`, `/volsurface` | Standard Layout |
| Full-Width | `/flow/editor/:id`, `/playground`, `/historify` | Full-Width Layout |
#### Code Splitting
All pages are lazy-loaded for optimal bundle size:
```typescript
const Dashboard = lazy(() => import('@/pages/Dashboard'))
const Positions = lazy(() => import('@/pages/Positions'))
// With Suspense fallback
}>
} />
```
### Real-Time Communication
#### Socket.IO (Order Events)
```typescript
// hooks/useSocket.ts
socket.on('order_event', (data) => {
playAlertSound()
toast.success(`Order ${data.status}: ${data.symbol}`)
queryClient.invalidateQueries(['orders'])
})
```
**Events:** `order_event`, `cancel_order_event`, `modify_order_event`, `close_position_event`
#### WebSocket (Market Data)
```typescript
// hooks/useMarketData.ts
const ws = new WebSocket('ws://localhost:8765')
ws.send(JSON.stringify({
action: 'subscribe',
symbols: ['NSE:SBIN-EQ'],
mode: 'ltp'
}))
ws.onmessage = (event) => {
const data = JSON.parse(event.data)
// Update price state
}
```
### Component Library (shadcn/ui)
Built on Radix UI primitives with Tailwind styling:
| Category | Components |
| -------- | ----------------------------------------------- |
| Form | Button, Input, Select, Checkbox, Switch, Label |
| Display | Card, Table, Badge, Avatar, Skeleton |
| Overlay | Dialog, Sheet, Popover, Tooltip, DropdownMenu |
| Custom | JsonEditor, PythonEditor, LogViewer, PageLoader |
### Build & Development
```bash
# Development
npm run dev # Vite dev server on :5173
# Production build
npm run build # Output to /frontend/dist/
# Testing
npm test # Vitest watch mode
npm run e2e # Playwright E2E tests
# Code quality
npm run lint # Biome linting
npm run format # Biome formatting
```
### Bundle Optimization
Vite splits the bundle into chunks:
| Chunk | Contents |
| ------------- | ----------------------------------- |
| vendor-react | React, ReactDOM |
| vendor-router | React Router |
| vendor-radix | Radix UI components |
| vendor-icons | Lucide React icons |
| vendor-syntax | Code highlighter (loaded on demand) |
### Key Files Reference
| File | Purpose |
| ---------------------------------- | ------------------------------ |
| `src/App.tsx` | Route definitions |
| `src/api/client.ts` | Axios clients configuration |
| `src/stores/authStore.ts` | Authentication state |
| `src/components/layout/Layout.tsx` | Main layout with Navbar/Footer |
| `src/components/auth/AuthSync.tsx` | Flask session sync |
| `vite.config.ts` | Build configuration |
```mermaid
```