# varunsai1930/find-it architecture

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

- Interactive diagram: https://gitdiagram.com/varunsai1930/find-it
- Repository: https://github.com/varunsai1930/find-it

## Overview

FindIt turns monthly Indian mutual-fund portfolio disclosures into validated month-over-month activity and cross-AMC rankings, joined with timely quarterly shareholding filings. Users receive the rankings through a monthly report or read-only dashboard; separate backtesting tools assess whether the signals predict returns. The README documents the workflow and capabilities; sampled source confirms key validation, dashboard, summary, and pricing behavior, while some subsystem links rely on README descriptions.

Main entry points: [`db.py`](https://github.com/varunsai1930/find-it/blob/main/db.py) (Tracker database), [`run_pipeline.py`](https://github.com/varunsai1930/find-it/blob/main/run_pipeline.py) (Monthly pipeline), [`findit/cli/report.py`](https://github.com/varunsai1930/find-it/blob/main/findit/cli/report.py) (Monthly report), [`findit/web/app.py`](https://github.com/varunsai1930/find-it/blob/main/findit/web/app.py) (Read-only dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data ingestion"]
  node_parser["Workbook parser<br/>[amfi_mf_parser.py]"]
  node_pipeline["Monthly pipeline<br/>[run_pipeline.py]"]
  node_filings["Shareholding fetcher"]
  node_pricescli["Price commands<br/>[prices.py]"]
  node_priceingest["Price ingestion<br/>[prices.py]"]
end

subgraph group_analysis["Holdings analysis"]
  node_gate["Validation gate<br/>[validation_gate.py]"]
  node_deltas["Holdings changes"]
  node_consensus["Consensus ranking"]
  node_publication["Publication timing<br/>[publication.py]"]
end

subgraph group_storage["Persistent data"]
  node_db[("Tracker database<br/>[db.py]")]
end

subgraph group_outputs["Reports and dashboard"]
  node_report["Monthly report<br/>[report.py]"]
  node_web["Read-only dashboard<br/>[app.py]"]
  node_templates["Dashboard views"]
  node_summary["Safe summaries<br/>[summary.py]"]
end

subgraph group_research["Signal research"]
  node_monthlytest["Monthly backtest<br/>[backtest.py]"]
  node_quartertest["Quarterly backtest"]
end

node_amc(("AMC disclosures"))
node_exchanges(("BSE / NSE"))
node_user(("Analyst"))

node_amc -->|"provides workbooks"| node_parser
node_parser -->|"outputs parsed CSV"| node_pipeline
node_pipeline -->|"validates holdings"| node_gate
node_pipeline -->|"compares months"| node_deltas
node_pipeline -->|"ranks activity"| node_consensus
node_pipeline -->|"loads and stores"| node_db
node_gate -->|"returns validation"| node_pipeline
node_exchanges -->|"publishes filings"| node_filings
node_filings -->|"stores filings"| node_db
node_exchanges -->|"publishes prices"| node_priceingest
node_pricescli -->|"fetches prices"| node_priceingest
node_priceingest -->|"stores prices"| node_db
node_db -->|"supplies holdings"| node_deltas
node_db -->|"supplies holdings and filings"| node_consensus
node_publication -->|"sets cutoff rules"| node_pipeline
node_report -->|"requests ranking"| node_consensus
node_report -->|"reads coverage"| node_db
node_report -->|"includes evidence"| node_quartertest
node_web -->|"reads stored data"| node_db
node_web -->|"requests ranking"| node_consensus
node_web -->|"renders views"| node_templates
node_summary -->|"reads safety data"| node_db
node_summary -->|"summarizes changes"| node_deltas
node_monthlytest -->|"reads signals and prices"| node_db
node_quartertest -->|"reads filings and prices"| node_db
node_user -->|"requests report"| node_report
node_user -->|"views dashboard"| node_web

click node_parser "https://github.com/varunsai1930/find-it/blob/main/amfi_mf_parser.py"
click node_pipeline "https://github.com/varunsai1930/find-it/blob/main/run_pipeline.py"
click node_filings "https://github.com/varunsai1930/find-it/blob/main/fetch_shareholding.py"
click node_pricescli "https://github.com/varunsai1930/find-it/blob/main/findit/cli/prices.py"
click node_priceingest "https://github.com/varunsai1930/find-it/blob/main/findit/ingest/prices.py"
click node_gate "https://github.com/varunsai1930/find-it/blob/main/findit/store/validation_gate.py"
click node_deltas "https://github.com/varunsai1930/find-it/blob/main/delta_calculator.py"
click node_consensus "https://github.com/varunsai1930/find-it/blob/main/consensus_signals.py"
click node_publication "https://github.com/varunsai1930/find-it/blob/main/findit/core/publication.py"
click node_db "https://github.com/varunsai1930/find-it/blob/main/db.py"
click node_report "https://github.com/varunsai1930/find-it/blob/main/findit/cli/report.py"
click node_web "https://github.com/varunsai1930/find-it/blob/main/findit/web/app.py"
click node_templates "https://github.com/varunsai1930/find-it/tree/main/findit/web/templates"
click node_summary "https://github.com/varunsai1930/find-it/blob/main/findit/summary.py"
click node_monthlytest "https://github.com/varunsai1930/find-it/blob/main/findit/cli/backtest.py"
click node_quartertest "https://github.com/varunsai1930/find-it/blob/main/findit/cli/backtest_quarterly.py"

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_parser,node_pipeline,node_filings,node_pricescli,node_priceingest toneBlue
class node_gate,node_deltas,node_consensus,node_publication toneAmber
class node_db toneMint
class node_report,node_web,node_templates,node_summary toneRose
class node_monthlytest,node_quartertest,node_amc,node_exchanges,node_user toneIndigo
```

## Components

### Data ingestion

- [Workbook parser](https://github.com/varunsai1930/find-it/blob/main/amfi_mf_parser.py): `amfi_mf_parser.py`
- [Monthly pipeline](https://github.com/varunsai1930/find-it/blob/main/run_pipeline.py): `run_pipeline.py`
- [Shareholding fetcher](https://github.com/varunsai1930/find-it/blob/main/fetch_shareholding.py): `fetch_shareholding.py`
- [Price commands](https://github.com/varunsai1930/find-it/blob/main/findit/cli/prices.py): `findit/cli/prices.py`
- [Price ingestion](https://github.com/varunsai1930/find-it/blob/main/findit/ingest/prices.py): `findit/ingest/prices.py`

### Holdings analysis

- [Validation gate](https://github.com/varunsai1930/find-it/blob/main/findit/store/validation_gate.py): `findit/store/validation_gate.py`
- [Holdings changes](https://github.com/varunsai1930/find-it/blob/main/delta_calculator.py): `delta_calculator.py`
- [Consensus ranking](https://github.com/varunsai1930/find-it/blob/main/consensus_signals.py): `consensus_signals.py`
- [Publication timing](https://github.com/varunsai1930/find-it/blob/main/findit/core/publication.py): `findit/core/publication.py`

### Persistent data

- [Tracker database](https://github.com/varunsai1930/find-it/blob/main/db.py): `db.py`

### Reports and dashboard

- [Monthly report](https://github.com/varunsai1930/find-it/blob/main/findit/cli/report.py): `findit/cli/report.py`
- [Read-only dashboard](https://github.com/varunsai1930/find-it/blob/main/findit/web/app.py): `findit/web/app.py`
- [Dashboard views](https://github.com/varunsai1930/find-it/tree/main/findit/web/templates): `findit/web/templates`
- [Safe summaries](https://github.com/varunsai1930/find-it/blob/main/findit/summary.py): `findit/summary.py`

### Signal research

- [Monthly backtest](https://github.com/varunsai1930/find-it/blob/main/findit/cli/backtest.py): `findit/cli/backtest.py`
- [Quarterly backtest](https://github.com/varunsai1930/find-it/blob/main/findit/cli/backtest_quarterly.py): `findit/cli/backtest_quarterly.py`

### Other components

- **AMC disclosures**
- **BSE / NSE**
- **Analyst**

## Connections

- AMC disclosures → Workbook parser: provides workbooks
- Workbook parser → Monthly pipeline: outputs parsed CSV
- Monthly pipeline → Validation gate: validates holdings
- Monthly pipeline → Holdings changes: compares months
- Monthly pipeline → Consensus ranking: ranks activity
- Monthly pipeline → Tracker database: loads and stores
- Validation gate → Monthly pipeline: returns validation
- BSE / NSE → Shareholding fetcher: publishes filings
- Shareholding fetcher → Tracker database: stores filings
- BSE / NSE → Price ingestion: publishes prices
- Price commands → Price ingestion: fetches prices
- Price ingestion → Tracker database: stores prices
- Tracker database → Holdings changes: supplies holdings
- Tracker database → Consensus ranking: supplies holdings and filings
- Publication timing → Monthly pipeline: sets cutoff rules
- Monthly report → Consensus ranking: requests ranking
- Monthly report → Tracker database: reads coverage
- Monthly report → Quarterly backtest: includes evidence
- Read-only dashboard → Tracker database: reads stored data
- Read-only dashboard → Consensus ranking: requests ranking
- Read-only dashboard → Dashboard views: renders views
- Safe summaries → Tracker database: reads safety data
- Safe summaries → Holdings changes: summarizes changes
- Monthly backtest → Tracker database: reads signals and prices
- Quarterly backtest → Tracker database: reads filings and prices
- Analyst → Monthly report: requests report
- Analyst → Read-only dashboard: views dashboard