# gbnathworkspace/stockservs architecture

> Architecture diagram of the GitHub repository gbnathworkspace/stockservs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gbnathworkspace/stockservs
- Repository: https://github.com/gbnathworkspace/stockservs

## Overview

#### Purpose and Entry Points
Stock Servs is a market-data and virtual-trading platform centered on Indian equities, F&O/options, portfolios, watchlists, and market analytics. The Python backend starts from `main.py`; database initialization is represented by `init_db.py` and `setup_db.py`. The primary React/Vite client starts at `frontend/src/main.jsx` and renders `frontend/src/App.jsx`.

#### Backend API Boundary
The backend is organized as route modules that expose domain APIs and delegate business work to services. Major API surfaces include authentication, users, market data, broker connectivity, portfolios, and watchlists: `routes/auth.py`, `routes/market_data.py`, `routes/fyers.py`, `routes/portfolio.py`, and `routes/watchlist.py`. Specialized analytical/trading endpoints are split into `routes/option_apex.py`, `routes/option_clock.py`, `routes/market_pulse.py`, `routes/swing_spectrum.py`, and `routes/insider_strategy.py`.

#### Service and Market-Data Layer
Services isolate data acquisition, caching, scheduling, and domain calculations from HTTP routes. Core components are `services/market_data_service.py`, `services/cache.py`, `services/data_scheduler.py`, `services/fii_dii_scheduler.py`, and `services/portfolio_service.py`. Broker-facing integrations are encapsulated in `services/fyers_service.py` and `services/zerodha_service.py`, providing a boundary between application workflows and external trading/data-provider APIs.

#### NSE Ingestion and Analytics
NSE-specific source adapters provide discrete market datasets—indices, F&O, movers, sector data, activity, delivery, and FII/DII figures—under `nse_data/indices.py`, `nse_data/fno.py`, `nse_data/movers.py`, `nse_data/fii_dii.py`, and `nse_data/most_active.py`. Symbol master files in `data/symbols/NSE_CM.csv` and `data/symbols/NSE_FO.csv` support cash-market and derivatives instrument lookup. Scheduled fetching and caching should feed API services rather than the frontend directly.

#### Persistence
Database access is centralized through connection, ORM/model, and repository layers: `database/connection.py`, `database/models.py`, and `database/repository.py`. This boundary likely owns persisted users, credentials or broker state, portfolios/orders, and watchlists. Schema lifecycle is handled through `init_db.py`, `setup_db.py`, and SQL migrations such as `migrations/add_is_default_to_watchlists.sql`.

#### Frontend Application
The React single-page application provides dashboard, market-data, FII/DII, watchlist, wallet, order-history, settings, and documentation views: `frontend/src/components/sections/Dashboard.jsx`, `frontend/src/components/sections/MarketData.jsx`, `frontend/src/components/sections/Watchlist.jsx`, `frontend/src/components/sections/FiiDiiActivity.jsx`, and `frontend/src/components/sections/OrderHistory.jsx`. Virtual trading is assembled from trading views and trade/chart modals in `frontend/src/components/VirtualTrading.jsx`, `frontend/src/components/trading/TradeModal.jsx`, and `frontend/src/components/trading/PortfolioView.jsx`. HTTP communication is centralized at `frontend/src/lib/api.js`; shared loading, theme, and notification state use `frontend/src/contexts/LoadingContext.jsx`, `frontend/src/contexts/ThemeContext.jsx`, and `frontend/src/contexts/ToastContext.jsx`.

#### Runtime and Deployment
The system uses a Python backend runtime with dependencies declared in `requirements.txt`, plus a Node/Vite frontend defined by `frontend/package.json` and `frontend/vite.config.js`. Container and process deployment artifacts are `Dockerfile`, `Procfile`, and `render.yaml`; automated deployment is configured at `.github/workflows/deploy.yml`. Built frontend assets also exist under `static/app/index.html`, indicating the backend may serve a production frontend bundle.

Main entry points: [`main.py`](https://github.com/gbnathworkspace/stockservs/blob/main/main.py) (Backend entry), [`routes/market_data.py`](https://github.com/gbnathworkspace/stockservs/blob/main/routes/market_data.py) (Core domain APIs), [`services/market_data_service.py`](https://github.com/gbnathworkspace/stockservs/blob/main/services/market_data_service.py) (Market-data service), [`services/data_scheduler.py`](https://github.com/gbnathworkspace/stockservs/blob/main/services/data_scheduler.py) (Data schedulers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Client"]
  node_react_entry["React entry<br/>Vite bootstrap<br/>[main.jsx]"]
  node_app_shell["Application shell<br/>React SPA<br/>[App.jsx]"]
  node_client_views["Market &amp; portfolio views<br/>React sections<br/>[Dashboard.jsx]"]
  node_virtual_trading["Virtual trading UI<br/>React trading UI<br/>[VirtualTrading.jsx]"]
  node_api_client["HTTP client<br/>frontend API layer<br/>[api.js]"]
end

subgraph group_api["Python API"]
  node_backend_entry["Backend entry<br/>Python runtime<br/>[main.py]"]
  node_core_routes["Core domain APIs<br/>route modules<br/>[market_data.py]"]
  node_analytics_routes["Analytics &amp; strategy APIs<br/>route modules<br/>[option_apex.py]"]
end

subgraph group_services["Market Services"]
  node_market_service["Market-data service<br/>service layer"]
  node_portfolio_service["Portfolio service<br/>service layer"]
  node_broker_services["Broker integrations<br/>provider adapters<br/>[fyers_service.py]"]
  node_cache[("Market cache<br/>cache service<br/>[cache.py]")]
  node_schedulers["Data schedulers<br/>scheduled jobs<br/>[data_scheduler.py]"]
end

subgraph group_data["Data &amp; Persistence"]
  node_nse_adapters["NSE source adapters<br/>market ingestion<br/>[indices.py]"]
  node_symbol_masters["NSE symbol masters<br/>instrument catalog<br/>[NSE_CM.csv]"]
  node_repository["Repository layer<br/>persistence access<br/>[repository.py]"]
  node_models["ORM models<br/>data model<br/>[models.py]"]
  node_database[("Application database<br/>database connection<br/>[connection.py]")]
  node_schema_setup["Schema lifecycle<br/>database initialization<br/>[init_db.py]"]
end

subgraph group_operations["Runtime &amp; Delivery"]
  node_deployment{{"Deployment runtime<br/>container/process deployment"}}
  node_production_bundle["Production frontend bundle<br/>static assets<br/>[index.html]"]
end

node_react_entry -->|"renders"| node_app_shell
node_app_shell -->|"hosts"| node_client_views
node_app_shell -->|"hosts"| node_virtual_trading
node_client_views -->|"uses"| node_api_client
node_virtual_trading -->|"uses"| node_api_client
node_api_client -->|"HTTP requests"| node_backend_entry
node_backend_entry -->|"mounts"| node_core_routes
node_backend_entry -->|"mounts"| node_analytics_routes
node_core_routes -->|"delegates market work"| node_market_service
node_core_routes -->|"delegates portfolio work"| node_portfolio_service
node_core_routes -->|"delegates broker work"| node_broker_services
node_analytics_routes -->|"uses market data"| node_market_service
node_market_service -->|"reads and writes"| node_cache
node_schedulers -->|"fetches from"| node_nse_adapters
node_schedulers -->|"uses instruments"| node_symbol_masters
node_schedulers -->|"refreshes"| node_cache
node_market_service -.->|"acquires data"| node_nse_adapters
node_portfolio_service -->|"persists through"| node_repository
node_broker_services -->|"stores state through"| node_repository
node_repository -->|"uses"| node_models
node_models -->|"maps to"| node_database
node_schema_setup -->|"initializes"| node_database
node_deployment -->|"runs"| node_backend_entry
node_backend_entry -.->|"serves"| node_production_bundle

click node_react_entry "https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/main.jsx"
click node_app_shell "https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/App.jsx"
click node_client_views "https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/components/sections/Dashboard.jsx"
click node_virtual_trading "https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/components/VirtualTrading.jsx"
click node_api_client "https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/lib/api.js"
click node_backend_entry "https://github.com/gbnathworkspace/stockservs/blob/main/main.py"
click node_core_routes "https://github.com/gbnathworkspace/stockservs/blob/main/routes/market_data.py"
click node_analytics_routes "https://github.com/gbnathworkspace/stockservs/blob/main/routes/option_apex.py"
click node_market_service "https://github.com/gbnathworkspace/stockservs/blob/main/services/market_data_service.py"
click node_portfolio_service "https://github.com/gbnathworkspace/stockservs/blob/main/services/portfolio_service.py"
click node_broker_services "https://github.com/gbnathworkspace/stockservs/blob/main/services/fyers_service.py"
click node_cache "https://github.com/gbnathworkspace/stockservs/blob/main/services/cache.py"
click node_schedulers "https://github.com/gbnathworkspace/stockservs/blob/main/services/data_scheduler.py"
click node_nse_adapters "https://github.com/gbnathworkspace/stockservs/blob/main/nse_data/indices.py"
click node_symbol_masters "https://github.com/gbnathworkspace/stockservs/blob/main/data/symbols/NSE_CM.csv"
click node_repository "https://github.com/gbnathworkspace/stockservs/blob/main/database/repository.py"
click node_models "https://github.com/gbnathworkspace/stockservs/blob/main/database/models.py"
click node_database "https://github.com/gbnathworkspace/stockservs/blob/main/database/connection.py"
click node_schema_setup "https://github.com/gbnathworkspace/stockservs/blob/main/init_db.py"
click node_deployment "https://github.com/gbnathworkspace/stockservs/blob/main/Dockerfile"
click node_production_bundle "https://github.com/gbnathworkspace/stockservs/blob/main/static/app/index.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_react_entry,node_app_shell,node_client_views,node_virtual_trading,node_api_client toneBlue
class node_backend_entry,node_core_routes,node_analytics_routes toneAmber
class node_market_service,node_portfolio_service,node_broker_services,node_cache,node_schedulers toneMint
class node_nse_adapters,node_symbol_masters,node_repository,node_models,node_database,node_schema_setup toneRose
class node_deployment,node_production_bundle toneIndigo
```

## Components

### React Client

- [React entry](https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/main.jsx): Vite bootstrap · `frontend/src/main.jsx`
- [Application shell](https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/App.jsx): React SPA · `frontend/src/App.jsx`
- [Market & portfolio views](https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/components/sections/Dashboard.jsx): React sections · Dashboard, market, watchlist, FII/DII, and order-history screens. · `frontend/src/components/sections/Dashboard.jsx`
- [Virtual trading UI](https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/components/VirtualTrading.jsx): React trading UI · `frontend/src/components/VirtualTrading.jsx`
- [HTTP client](https://github.com/gbnathworkspace/stockservs/blob/main/frontend/src/lib/api.js): frontend API layer · `frontend/src/lib/api.js`

### Python API

- [Backend entry](https://github.com/gbnathworkspace/stockservs/blob/main/main.py): Python runtime · `main.py`
- [Core domain APIs](https://github.com/gbnathworkspace/stockservs/blob/main/routes/market_data.py): route modules · Authentication, market data, broker, portfolio, and watchlist APIs. · `routes/market_data.py`
- [Analytics & strategy APIs](https://github.com/gbnathworkspace/stockservs/blob/main/routes/option_apex.py): route modules · Options, pulse, swing, and insider strategy endpoints. · `routes/option_apex.py`

### Market Services

- [Market-data service](https://github.com/gbnathworkspace/stockservs/blob/main/services/market_data_service.py): service layer · `services/market_data_service.py`
- [Portfolio service](https://github.com/gbnathworkspace/stockservs/blob/main/services/portfolio_service.py): service layer · `services/portfolio_service.py`
- [Broker integrations](https://github.com/gbnathworkspace/stockservs/blob/main/services/fyers_service.py): provider adapters · Fyers and Zerodha integration boundary. · `services/fyers_service.py`
- [Market cache](https://github.com/gbnathworkspace/stockservs/blob/main/services/cache.py): cache service · `services/cache.py`
- [Data schedulers](https://github.com/gbnathworkspace/stockservs/blob/main/services/data_scheduler.py): scheduled jobs · Refreshes market and FII/DII datasets. · `services/data_scheduler.py`

### Data & Persistence

- [NSE source adapters](https://github.com/gbnathworkspace/stockservs/blob/main/nse_data/indices.py): market ingestion · Indices, F&O, movers, activity, and FII/DII sources. · `nse_data/indices.py`
- [NSE symbol masters](https://github.com/gbnathworkspace/stockservs/blob/main/data/symbols/NSE_CM.csv): instrument catalog · Cash and derivatives symbol lookup. · `data/symbols/NSE_CM.csv`
- [Repository layer](https://github.com/gbnathworkspace/stockservs/blob/main/database/repository.py): persistence access · `database/repository.py`
- [ORM models](https://github.com/gbnathworkspace/stockservs/blob/main/database/models.py): data model · `database/models.py`
- [Application database](https://github.com/gbnathworkspace/stockservs/blob/main/database/connection.py): database connection · Stores users, broker state, portfolios, orders, and watchlists. · `database/connection.py`
- [Schema lifecycle](https://github.com/gbnathworkspace/stockservs/blob/main/init_db.py): database initialization · Initialization, setup, and SQL migrations. · `init_db.py`

### Runtime & Delivery

- [Deployment runtime](https://github.com/gbnathworkspace/stockservs/blob/main/Dockerfile): container/process deployment · Container, process, Render, and GitHub deployment artifacts. · `Dockerfile`
- [Production frontend bundle](https://github.com/gbnathworkspace/stockservs/blob/main/static/app/index.html): static assets · Backend-served built SPA assets. · `static/app/index.html`

## Connections

- React entry → Application shell: renders
- Application shell → Market & portfolio views: hosts
- Application shell → Virtual trading UI: hosts
- Market & portfolio views → HTTP client: uses
- Virtual trading UI → HTTP client: uses
- HTTP client → Backend entry: HTTP requests
- Backend entry → Core domain APIs: mounts
- Backend entry → Analytics & strategy APIs: mounts
- Core domain APIs → Market-data service: delegates market work
- Core domain APIs → Portfolio service: delegates portfolio work
- Core domain APIs → Broker integrations: delegates broker work
- Analytics & strategy APIs → Market-data service: uses market data
- Market-data service → Market cache: reads and writes
- Data schedulers → NSE source adapters: fetches from
- Data schedulers → NSE symbol masters: uses instruments
- Data schedulers → Market cache: refreshes
- Market-data service → NSE source adapters: acquires data
- Portfolio service → Repository layer: persists through
- Broker integrations → Repository layer: stores state through
- Repository layer → ORM models: uses
- ORM models → Application database: maps to
- Schema lifecycle → Application database: initializes
- Deployment runtime → Backend entry: runs
- Backend entry → Production frontend bundle: serves