# 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
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.openalgo.in/developers/design-documentation/architecture.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.