# nishichandra/stock-index-screenr architecture

> Architecture diagram of the GitHub repository nishichandra/stock-index-screenr, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nishichandra/stock-index-screenr
- Repository: https://github.com/nishichandra/stock-index-screenr

## Overview

##### Project type and purpose
- This is a containerized backend API service (“stock-index-screenr”) built with FastAPI. Its primary purpose is to ingest raw stock data, build and store stock index metrics in a local DuckDB database, cache hot reads in Redis, and expose a RESTful interface (with Swagger UI) for clients to query or export that data.

##### File structure
- Top-level:
- Dockerfile & docker-compose.yml – containers for the FastAPI app, Redis, (and possibly other services).
- app/ – Python source for ingestion, indexing, database connectivity, API routes, models, and utilities.
- outputs/ – sample artifacts (Excel export, Swagger UI PDF).
- requirements.txt – Python dependencies.
- app/:
- data_ingest.py – standalone job to pull raw data and populate DuckDB.
- build_index.py – logic to compute index performance and composition.
- database.py – DuckDB connection management (and Redis caching hooks).
- main.py – FastAPI application with route definitions.
- models.py – Pydantic schemas for request/response bodies.
- utils.py – shared helpers.
- data/index_data.duckdb – the embedded database file.

##### README for additional insights
- Describes Docker vs. local setup, API endpoints (build-index, index-performance, index-composition, composition-changes, export-data), and the DuckDB schema (stock_metadata, daily_data, index_composition, index_performance).
- Mentions Redis for caching but does not list a Redis config file—assumed to be defined in docker-compose.yml.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Dependencies
    ExtData["External Data Sources"]:::external

    %% Docker Compose Cluster
    subgraph "Docker Compose" 
        direction TB
        subgraph "Batch Pipeline"
            direction TB
            DataIngestJob["Data Ingestion Job"]:::container
            IndexBuilder["Index Builder"]:::container
        end
        subgraph "Online API"
            direction TB
            Client["Client (curl/Postman)"]:::external
            FastAPI["FastAPI Service\n(routes: build-index,\nindex-performance,\nindex-composition,\ncomposition-changes,\nexport-data)"]:::container
            Redis["Redis Cache"]:::datastore
        end
        DuckDB["DuckDB Database"]:::datastore
        Outputs["Exported Artifacts\n(Excel, Swagger PDF)"]:::artifact
    end

    %% Data Flow - Batch Pipeline
    ExtData -->|fetch raw data| DataIngestJob
    DataIngestJob -->|writes raw tables| DuckDB
    FastAPI -->|POST /build-index| IndexBuilder
    IndexBuilder -->|writes index tables| DuckDB

    %% Data Flow - Online API
    Client -->|HTTP requests| FastAPI
    FastAPI -->|GET/SET cache| Redis
    FastAPI -->|reads/writes| DuckDB
    FastAPI -->|export read| Outputs

    %% Project Files
    subgraph "Project Files"
        direction TB
        DockerfileNode["Dockerfile"]:::file
        ComposeNode["docker-compose.yml"]:::file
        RequirementsNode["requirements.txt"]:::file
        ReadmeNode["README.md"]:::file
    end

    %% Styling and Click Events
    classDef container fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef datastore fill:#FFDDAA,stroke:#d9730d,stroke-width:1px
    classDef external fill:#E8E8E8,stroke:#888888,stroke-width:1px
    classDef artifact fill:#DFFFD8,stroke:#28a745,stroke-width:1px
    classDef file fill:#FFFFFF,stroke:#000000,stroke-width:1px

    click DataIngestJob "https://github.com/nishichandra/stock-index-screenr/blob/main/app/data_ingest.py"
    click FastAPI "https://github.com/nishichandra/stock-index-screenr/blob/main/app/main.py"
    click IndexBuilder "https://github.com/nishichandra/stock-index-screenr/blob/main/app/build_index.py"
    click DuckDB "https://github.com/nishichandra/stock-index-screenr/blob/main/app/data/index_data.duckdb"
    click DockerfileNode "https://github.com/nishichandra/stock-index-screenr/tree/main/Dockerfile"
    click ComposeNode "https://github.com/nishichandra/stock-index-screenr/blob/main/docker-compose.yml"
    click RequirementsNode "https://github.com/nishichandra/stock-index-screenr/blob/main/requirements.txt"
    click ReadmeNode "https://github.com/nishichandra/stock-index-screenr/blob/main/README.md"
```
