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
| Page | File | Description |
|---|---|---|
| BhavDownloader | src/pages/BhavDownloader.tsx | NSE sync + AMI data download |
| Dashboard | src/pages/Dashboard.tsx | Market summary |
| TradeEntry | src/pages/TradeEntry.tsx | Trade journal |
| OptionChain | src/pages/OptionChain.tsx | F&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:
| Page | Usage |
|---|---|
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
| Prop | Type | Default | Description |
|---|---|---|---|
bars | Bar[] | — | 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). |
selected | number | last bar | Index 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] | null | null | Optional 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. |
logScale | boolean | false | Log-scale the price axis (ignored if any bar has l <= 0). |
maPeriod | number | 0 | SMA period overlay, drawn in candle/bar modes only; 0 disables it. |
height | number | 460 | Chart height in px; width follows the parent container. |
title / subtitle | string | — | 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/line | Buttons 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.
Navigation & access control
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
| Variable | Description |
|---|---|
VITE_API_URL | Backend 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