Symbol List Integration
Relevant source files
The following files were used as context for generating this wiki page:
Symbol List Integration allows you to normalize, validate, and screen custom batches of NSE tickers. The system processes arbitrary text input, identifies valid equities against a published scanner revision, and enables targeted technical screening on the validated subset.
This feature operates independently of the mainboard universe, allowing you to bypass broader market filters and focus analysis on a specific list of interest.
Sources: frontend/README.md, frontend/src/components/SymbolListTab.tsx:30-45
Architecture and Data Flow
The integration consists of a React UI component (SymbolListTab), a central API facade (screenerApi), and an adapter (realAdapter or mockAdapter) that executes tasks via a Web Worker or a backend Python bridge.
Normalization Process
When you paste symbols, the system parses the text using a regular expression to handle various separators (commas, spaces, newlines). It converts tickers to uppercase and removes duplicates before sending them for validation.
The flow shows how raw text input is transformed into a validated set of symbols.
Sources: frontend/src/components/SymbolListTab.tsx:32-42, frontend/src/api/realAdapter.ts:257-261
Screening Workflow
After validation, you can trigger a screener run. The system passes the valid symbols as customSymbols in a ScreenerRunRequest with the universe set to custom.
This diagram illustrates the two-stage process: list validation followed by custom universe screening.
Sources: frontend/src/api/realAdapter.ts:161-175, frontend/src/components/SymbolListTab.tsx:112-120
Key Components and Data Structures
UI Component: SymbolListTab
This component serves as the primary interface for "Custom Symbol Batch Normalizer". It utilizes @tanstack/react-query to manage the state of the comparison mutation.
- State: Manages
inputTextfor raw ticker entry. - Actions:
onRunOnCustomSymbols: Callback to execute a screen on validated tickers.onAddToWatchlist: Optional callback to add validated tickers to a watchlist.
Sources: frontend/src/components/SymbolListTab.tsx:1-30
API Contracts
The system uses specific TypeScript interfaces to ensure consistency between the frontend and the data adapters.
| Interface | Purpose | Key Fields |
|---|---|---|
SymbolComparisonRequest | Input for validation | symbols: string[] |
SymbolComparisonItem | Metadata for a valid symbol | symbol, close, marketCapCrore, isValid |
SymbolComparisonResponse | Result of validation | validSymbols, invalidSymbols, immutableRevision |
ScreenerRunRequest | Input for screening | universe: 'custom', customSymbols: string[] |
Sources: frontend/src/types/screener.ts:213-239, frontend/src/api/screenerApi.ts:18-20
Implementation Details
Validation Logic
The compareSymbols method in realAdapter.ts delegates the task to runSnapshotTask. This task compares the input list against the stocks.json (or .json.gz) snapshot associated with the current immutableRevision.
// frontend/src/api/realAdapter.ts:257-261
async compareSymbols(req: SymbolComparisonRequest): Promise<SymbolComparisonResponse> {
const response = await runSnapshotTask({type:'compare',source:await snapshotSource(),symbols:req.symbols});
if (response.type !== 'compare') throw new Error('Unexpected comparison response');
return response.result;
}
Mock Mode Behavior
In development mode (VITE_USE_MOCK=true), the mockAdapter simulates the validation by checking against a hardcoded list of mainboard stocks. It populates SymbolComparisonItem with mock technical data like sma50Status and rsRating.
Sources: frontend/src/api/mockAdapter.ts:251-285
Technical Requirements and Constraints
- Revision Pinning: Comparison and screening must occur against the same
immutableRevision. The adapter rejects backend responses if theimmutableRevisiondoes not match the snapshot revision. - Normalization: Symbols are normalized to uppercase and trimmed of whitespace.
- Separators: Supported separators include spaces, commas, semicolons, and newlines.
- Worker Timeout: Web Worker tasks (including comparison) have a 60-second timeout.
Sources: frontend/README.md, frontend/src/api/realAdapter.ts:173, frontend/src/components/SymbolListTab.tsx:33-35
Conclusion
Symbol List Integration provides a bridge between arbitrary user-defined ticker lists and the quantitative screening engine. By validating symbols against the immutable scanner snapshot before execution, the system ensures that "custom universe" screens are technically accurate and consistent with the published trading session data.
Sources: frontend/README.md, frontend/src/components/SymbolListTab.tsx