IPO Catalogue

Relevant source files

The following files were used as context for generating this wiki page:

• frontend/README.md
• frontend/src/types/screener.ts
• frontend/src/api/realAdapter.ts
• frontend/src/components/NewListingsTab.tsx
• DO NOT DELETE EDL PIPELINE/fetch_scanx_ipo_data.py
• DO NOT DELETE EDL PIPELINE/fetch_ipo_provider_data.py
• DO NOT DELETE EDL PIPELINE/src/edl_pipeline/artifacts.py

The IPO Catalogue provides a centralized interface for equity researchers to browse, search, and screen recent NSE listings. It integrates data from external providers into the Nexus Scanner ecosystem, allowing users to evaluate new companies using the same technical and fundamental criteria applied to the mainboard universe.

Sources: frontend/README.md:25-26, frontend/README.md:126-128

Data Architecture and Pipeline

The system populates the catalogue through a multi-stage Python EDL (Extract, Data, Load) pipeline. This pipeline aggregates data from two primary enrichment sources: ScanX and an external "IPO Decode" provider.

Pipeline Components

1. ScanX Fetcher (fetch_scanx_ipo_data.py): Retrieves the public ScanX IPO list and detailed history. It archives data into scanx_ipo_listed_archive.json.gz and scanx_ipo_details_archive.json.gz.
   Sources: DO NOT DELETE EDL PIPELINE/fetch_scanx_ipo_data.py:22-26, DO NOT DELETE EDL PIPELINE/src/edl_pipeline/artifacts.py:38-39
2. Provider Ingestor (fetch_ipo_provider_data.py): Fetches data from ipodecode.mrchartist.com. It manages a "detail lane" limited to 18 issues per run to respect rate limits while maintaining a durable history cache.
   Sources: DO NOT DELETE EDL PIPELINE/fetch_ipo_provider_data.py:10-15, DO NOT DELETE EDL PIPELINE/fetch_ipo_provider_data.py:32
3. Artifact Builder (build_ipo_screener_artifact.py): Consolidates the fetched data into the final ipo_screener.json artifact used by the frontend.
   Sources: DO NOT DELETE EDL PIPELINE/src/edl_pipeline/artifacts.py:157-159

Data Flow Diagram

The following diagram illustrates how IPO data moves from external sources to the browser.

The diagram shows the sequential flow from raw API ingestion to immutable storage and final UI consumption.
Sources: frontend/README.md:239-251, DO NOT DELETE EDL PIPELINE/fetch_scanx_ipo_data.py:182-200

Data Model

The system defines the IPO data structure in TypeScript to ensure consistency between the API adapter and the UI components.

Field	Type	Description
symbol	string	The NSE stock ticker.
name	string	The company name.
listingDate	string	Date the security listed on the exchange.
currentPrice	number	The latest recorded close price.
turnoverCrore	number	Daily traded value in ₹Cr.
marketCapCrore	number	Total market capitalization in ₹Cr.
deliveryPct	number | null	Percentage of shares delivered for the session.
sector	string	Primary industrial sector.
ipoDetailStatus	object	Metadata regarding the last successful data refresh.

Sources: frontend/src/types/screener.ts:187-200, frontend/src/api/realAdapter.ts:168-181

Frontend Implementation

The frontend utilizes the NewListingsTab component to render the catalogue. It leverages TanStack Query for data fetching and useLocalStorageState for persisting user preferences.

Core Features

• Listing Windows: Users can filter listings by 30 days, 90 days, 6 months, 1 year, or "All Time".
  Sources: frontend/src/components/NewListingsTab.tsx:16, frontend/src/components/NewListingsTab.tsx:36-41
• Search and Sort: The UI supports text-based searching of symbols/companies and sorting by listing date, price, turnover, or market cap.
  Sources: frontend/src/components/NewListingsTab.tsx:18-20, frontend/src/components/NewListingsTab.tsx:42-47
• Status Indicators: The catalogue displays the status of the "IPO Decode" refresh, indicating if the data is complete, partial, or retained from a previous failure.
  Sources: frontend/src/components/NewListingsTab.tsx:109-115

API Integration

The realAdapter fetches the IPO catalogue from a revision-specific URL defined in the manifest (e.g., /data/revisions/<revision>/ipos.json). It maps the raw provider response into the standardized IPORow format.

// Example of data mapping in realAdapter.ts
const records = rows.map(r => ({
  symbol: r.symbol,
  name: r.name || r.company_name || '',
  listingDate: r.listing_date || '',
  currentPrice: r.close ?? 0,
  turnoverCrore: r.rupee_volume == null ? 0 : r.rupee_volume / 10_000_000,
  deliveryPct: r.delivery_percent ?? null,
  sector: r.sector || 'Unclassified',
  industry: r.industry || 'Unclassified',
  marketCapCrore: r.market_cap_crore ?? 0,
}));

Sources: frontend/src/api/realAdapter.ts:168-176

Integrated Screening

A critical capability of the IPO Catalogue is the "Run" feature. This evaluates active scanner conditions against the specific universe of symbols currently filtered in the catalogue.

1. Universe Definition: The component derives a listingSymbols array from the filtered results.
   Sources: frontend/src/components/NewListingsTab.tsx:55
2. Request Construction: It generates a ScreenerRunRequest with universe: 'custom' and customSymbols: listingSymbols.
   Sources: frontend/src/components/NewListingsTab.tsx:56-59
3. Result Rendering: When the user clicks "Run", the UI switches to the ResultsTable to show technical matches within the IPO set.
   Sources: frontend/src/components/NewListingsTab.tsx:117-126

The sequence diagram details the transition from browsing listings to executing a technical screen on those listings.
Sources: frontend/src/components/NewListingsTab.tsx:56-65, frontend/src/api/realAdapter.ts:133-150

Conclusion

The IPO Catalogue bridges the gap between new exchange listings and established market data. By providing automated ingestion from ScanX and IPO Decode, alongside a custom screening implementation, it allows analysts to identify momentum and trend patterns in newly public companies immediately following their listing.