Skip to main content

Frontend Developer Guide

Technology Stacks​

  • React 18 with TypeScript
  • Vite for fast development builds
  • Tailwind CSS + ShadCN UI for components
  • Axios (src/services/api.js) as the centralized HTTP client
  • Lightweight Charts for candlestick and line charts

Project Structure​

frontend/
├── src/
│ ├── pages/ # Route-level page components
│ ├── components/ # Reusable UI components
│ ├── services/
│ │ └── api.js # All API calls (Axios instance + method map)
│ ├── hooks/ # Custom React hooks
│ ├── types/ # TypeScript interfaces
│ └── App.tsx # Root component + router
├── public/
├── index.html
├── vite.config.ts
└── package.json

Key Pages​

PageFileDescription
BhavDownloadersrc/pages/BhavDownloader.tsxNSE sync + AMI data download
Dashboardsrc/pages/Dashboard.tsxMarket summary
TradeEntrysrc/pages/TradeEntry.tsxTrade journal
OptionChainsrc/pages/OptionChain.tsxF&O chain viewer

Reusable Components​

TEChart​

frontend/src/components/TEChart.jsx — a hand-drawn <canvas> OHLC chart (no charting library). Originally built for Range Analysis (as AmiChart), it is now a shared component any page can import. Current consumers:

PageUsage
Range Analysis — Candle tab (pages/RangeAnalysis/CandleTab.jsx)One bar per range window, candle/wave toggle, MA overlay
Range Analysis — Wave tab (pages/RangeAnalysis/WaveTab.jsx)Small-timeframe bars for the selected window, NeoWave order
Corporate Actions (pages/CorporateActions.jsx)Raw-vs-adjusted preview chart for a pending action

It is data-agnostic: it only renders the bars it's given. Timeframe selection and fetching data for that timeframe is the caller's job (see rangeEngine.js / api.rangeAnalysis.getPrices for how Range Analysis does this) — TEChart never calls the API itself.

Bar shape

{ t, o, h, l, c, hiFirst?, assumed? }[]

t is epoch seconds, exchange wall-clock time stored as if it were UTC (e.g. 09:15 IST is stored as 09:15Z), so the chart shows exchange time with no timezone conversion.

Props

PropTypeDefaultDescription
barsBar[]—Required. Bars to render, oldest first.
mode'candle' | 'bar' | 'wave' | 'line''candle'Render style. 'bar' is a classic OHLC tick chart (left tick = open, right tick = close). 'wave' is NeoWave-specific (2 points/bar, hollow markers on "assumed" bars).
selectednumberlast barIndex of the selected bar (controlled).
onSelect(index) => void—Called when the user clicks a bar or moves the selector with arrow keys / Home / End.
range[number, number] | nullnullOptional highlighted bar range.
onRangeChange(range | null) => void—Passing this enables range-marker mode (B/E keys, Shift+click, Esc).
onActivate(index) => void—Called on double-click or Enter on the selected bar.
logScalebooleanfalseLog-scale the price axis (ignored if any bar has l <= 0).
maPeriodnumber0SMA period overlay, drawn in candle/bar modes only; 0 disables it.
heightnumber460Chart height in px; width follows the parent container.
title / subtitlestring—Header text (e.g. exchange/symbol, timeframe label).
axisKind'date' | 'datetime' | 'time' | 'full''date'Date-axis / tag label format.
barLabel(index) => string—Overrides the default bar-time label in the header/selector tag (used by Range Analysis to show window labels).
chartTypes{value, label}[]candle/bar/lineButtons shown by the built-in toolbar (see below).
onModeChange(value) => void—Passing this renders a chart-type toggle button group in the chart header, wired to chartTypes. Omit it to keep mode fully external (no toolbar), as Corporate Actions does with its fixed mode="candle".

Built in for free: bar selector (click, arrow keys, Home/End), mouse-wheel / Up-Down zoom, drag-to-pan, crosshair with price/date tags, and (when onRangeChange is passed) B/E range markers. See the help line rendered at the bottom of the chart for the exact key bindings.

Page links live in src/components/Sidebar.jsx, not a top nav bar — it renders only when the logged-in user's rank is DEVELOPER or higher (rankOf(user?.catcode) >= RANK.DEVELOPER, checked in Layout.jsx). A FREE/PAID/POWER/anonymous viewer gets no sidebar at all — just Header.jsx and full-width content. Desktop renders it as a fixed left column; below md it collapses to an off-canvas drawer toggled by a hamburger button in the header.

Asset Allocation is the one exception — it's linked directly from Header.jsx, not the sidebar, because it's the one page visible to every viewer regardless of rank (see User System Design "Public surface in v2.0").

src/constants/rank.js exports the RANK map (ANON..ADMIN) and a rankOf(catcode) helper — mirrors backend/app/auth/deps.py's RANK constant, and is the single copy Sidebar.jsx/Layout.jsx/ProtectedRoute.jsx all import, instead of each keeping its own.

src/components/UserMenu.jsx is the top-right account control: avatar (initial) + email + role badge, click-to-open dropdown with Profile/Sign Out, renders the old "Sign In" button when logged out.

src/components/AdminUserManagement.jsx is ADMIN-only — see teudb Overview "Admin API reference" for the endpoints it drives and where it's mounted.

API Service Pattern​

All API calls go through src/services/api.js:

const apiClient = axios.create({
baseURL: import.meta.env.VITE_API_URL || 'http://localhost:8000/api',
});

export const api = {
bhavDownloader: {
triggerDownload: async (date, testingMode) => { ... },
getStatus: async () => { ... },
getAmiFiles: async () => { ... },
}
};

Polling Pattern (BhavDownloader)​

Background tasks use a polling loop with a hasSeenRunning guard to prevent premature termination on stale stats.json:

const startPolling = useCallback((alreadyRunning = false) => {
let hasSeenRunning = alreadyRunning;
pollingRef.current = setInterval(async () => {
const res = await api.bhavDownloader.getStatus();
if (res.status === 'RUNNING') {
hasSeenRunning = true;
// Update UI...
} else if (hasSeenRunning) {
// Task completed — stop polling
stopPolling();
}
// If !hasSeenRunning and not RUNNING: task hasn't started writing yet — continue polling silently
}, 1500);
}, []);

Environment Variables​

VariableDescription
VITE_API_URLBackend API base URL

Set in .env or .env.local at frontend/.

Running the Frontend​

cd frontend
npm install
npm run dev # dev server at http://localhost:5173
npm run build # production build → dist/
npm run preview # preview production build locally