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.

// 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.

// 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

// 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

// 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:

const Dashboard = lazy(() => import('@/pages/Dashboard'))
const Positions = lazy(() => import('@/pages/Positions'))

// With Suspense fallback
<Suspense fallback={<PageLoader />}>
  <Routes>
    <Route path="/dashboard" element={<Dashboard />} />
  </Routes>
</Suspense>

Real-Time Communication

Socket.IO (Order Events)

// 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)

// 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

# 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