# as1605/mf-screener-ai architecture

> Architecture diagram of the GitHub repository as1605/mf-screener-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/as1605/mf-screener-ai
- Repository: https://github.com/as1605/mf-screener-ai

## Overview

MF Screener AI fetches Indian mutual-fund data, applies independently authored LLM-generated scoring strategies, combines their sector scores into consensus rankings, and publishes results. Separate experiments inspect holdings and returns; rank-history and XIRR tooling evaluates historical outcomes against benchmarks. The README documents the main stages, while the source index confirms algorithm-to-provider dependencies and `run.py`'s compilation and publishing calls. Scoring invocation details and some experiment internals were not sampled, so those links are documented rather than inferred from module co-location.

Main entry points: [`src/mf_data_provider.py`](https://github.com/as1605/mf-screener-ai/blob/main/src/mf_data_provider.py) (Fund data provider), [`run.py`](https://github.com/as1605/mf-screener-ai/blob/main/run.py) (Compile and publish runner), [`src/compile_xirr.py`](https://github.com/as1605/mf-screener-ai/blob/main/src/compile_xirr.py) (Strategy XIRR evaluator), [`src/compile_results.py`](https://github.com/as1605/mf-screener-ai/blob/main/src/compile_results.py) (Consensus score compiler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Fund data"]
  node_data_provider["Fund data provider"]
  node_nav_cache[("Cached NAV and holdings")]
end

subgraph group_scoring["Scoring"]
  node_strategies["Sector scoring strategies"]
  node_grok_engine["Grok scoring engine<br/>[grok_engine.py]"]
  node_model_scores[("Model score CSVs")]
end

subgraph group_analysis["Experiments and evaluation"]
  node_xirr_compiler["Strategy XIRR evaluator<br/>[compile_xirr.py]"]
  node_focused_experiment["Holdings and returns snapshot<br/>[focused.py]"]
  node_returns_experiment["Point-to-point returns<br/>[returns.py]"]
  node_sif_experiment["SIF experiment<br/>[sif.py]"]
  node_statistics["Fund statistics"]
end

subgraph group_delivery["Rankings and publishing"]
  node_results_compiler["Consensus score compiler<br/>[compile_results.py]"]
  node_run_orchestrator["Compile and publish runner<br/>[run.py]"]
  node_rank_compiler["Rank history compiler<br/>[compile_ranks.py]"]
  node_rank_files[("Compiled rankings")]
  node_sheet_publisher["Google Sheets publisher<br/>[publish_sheet.py]"]
end

node_investor(("Investor or operator"))
node_ticker(("Tickertape API"))
node_google_sheets[("Google Sheets")]

node_data_provider -->|"fetches data"| node_ticker
node_data_provider -->|"caches data"| node_nav_cache
node_strategies -->|"reads fund data"| node_data_provider
node_grok_engine -->|"reads fund data"| node_data_provider
node_strategies -->|"writes scores"| node_model_scores
node_grok_engine -.->|"writes scores"| node_model_scores
node_investor -->|"runs compilation"| node_run_orchestrator
node_run_orchestrator -->|"calls compiler"| node_results_compiler
node_run_orchestrator -->|"calls publisher"| node_sheet_publisher
node_run_orchestrator -->|"optionally calls"| node_rank_compiler
node_results_compiler -->|"reads model scores"| node_model_scores
node_results_compiler -.->|"writes composites"| node_rank_files
node_rank_compiler -->|"calls evaluator"| node_xirr_compiler
node_rank_compiler -->|"writes rank history"| node_rank_files
node_xirr_compiler -->|"fetches NAV"| node_data_provider
node_xirr_compiler -->|"writes XIRR scores"| node_rank_files
node_sheet_publisher -->|"publishes worksheets"| node_google_sheets
node_focused_experiment -->|"reads fund data"| node_data_provider
node_returns_experiment -->|"reads NAV data"| node_data_provider
node_sif_experiment -->|"uses provider"| node_data_provider
node_statistics -->|"uses provider"| node_data_provider
node_investor -->|"views live ranks"| node_google_sheets

click node_data_provider "https://github.com/as1605/mf-screener-ai/blob/main/src/mf_data_provider.py"
click node_nav_cache "https://github.com/as1605/mf-screener-ai/blob/main/src/mf_data_provider.py"
click node_strategies "https://github.com/as1605/mf-screener-ai/tree/main/src/algorithms"
click node_grok_engine "https://github.com/as1605/mf-screener-ai/blob/main/src/algorithms/grok_engine.py"
click node_model_scores "https://github.com/as1605/mf-screener-ai/tree/main/results"
click node_results_compiler "https://github.com/as1605/mf-screener-ai/blob/main/src/compile_results.py"
click node_run_orchestrator "https://github.com/as1605/mf-screener-ai/blob/main/run.py"
click node_rank_compiler "https://github.com/as1605/mf-screener-ai/blob/main/src/compile_ranks.py"
click node_xirr_compiler "https://github.com/as1605/mf-screener-ai/blob/main/src/compile_xirr.py"
click node_rank_files "https://github.com/as1605/mf-screener-ai/tree/main/results"
click node_sheet_publisher "https://github.com/as1605/mf-screener-ai/blob/main/src/publish_sheet.py"
click node_focused_experiment "https://github.com/as1605/mf-screener-ai/blob/main/src/experiments/focused.py"
click node_returns_experiment "https://github.com/as1605/mf-screener-ai/blob/main/src/experiments/returns.py"
click node_sif_experiment "https://github.com/as1605/mf-screener-ai/blob/main/src/experiments/sif.py"
click node_statistics "https://github.com/as1605/mf-screener-ai/blob/main/src/generate_statistics.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_data_provider,node_nav_cache toneBlue
class node_strategies,node_grok_engine,node_model_scores,node_google_sheets toneAmber
class node_xirr_compiler,node_focused_experiment,node_returns_experiment,node_sif_experiment,node_statistics,node_ticker toneMint
class node_results_compiler,node_run_orchestrator,node_rank_compiler,node_rank_files,node_sheet_publisher toneRose
class node_investor toneIndigo
```

## Components

### Fund data

- [Fund data provider](https://github.com/as1605/mf-screener-ai/blob/main/src/mf_data_provider.py): `src/mf_data_provider.py`
- [Cached NAV and holdings](https://github.com/as1605/mf-screener-ai/blob/main/src/mf_data_provider.py): `src/mf_data_provider.py`

### Scoring

- [Sector scoring strategies](https://github.com/as1605/mf-screener-ai/tree/main/src/algorithms): `src/algorithms`
- [Grok scoring engine](https://github.com/as1605/mf-screener-ai/blob/main/src/algorithms/grok_engine.py): `src/algorithms/grok_engine.py`
- [Model score CSVs](https://github.com/as1605/mf-screener-ai/tree/main/results): `results`

### Experiments and evaluation

- [Strategy XIRR evaluator](https://github.com/as1605/mf-screener-ai/blob/main/src/compile_xirr.py): `src/compile_xirr.py`
- [Holdings and returns snapshot](https://github.com/as1605/mf-screener-ai/blob/main/src/experiments/focused.py): `src/experiments/focused.py`
- [Point-to-point returns](https://github.com/as1605/mf-screener-ai/blob/main/src/experiments/returns.py): `src/experiments/returns.py`
- [SIF experiment](https://github.com/as1605/mf-screener-ai/blob/main/src/experiments/sif.py): `src/experiments/sif.py`
- [Fund statistics](https://github.com/as1605/mf-screener-ai/blob/main/src/generate_statistics.py): `src/generate_statistics.py`

### Rankings and publishing

- [Consensus score compiler](https://github.com/as1605/mf-screener-ai/blob/main/src/compile_results.py): `src/compile_results.py`
- [Compile and publish runner](https://github.com/as1605/mf-screener-ai/blob/main/run.py): `run.py`
- [Rank history compiler](https://github.com/as1605/mf-screener-ai/blob/main/src/compile_ranks.py): `src/compile_ranks.py`
- [Compiled rankings](https://github.com/as1605/mf-screener-ai/tree/main/results): `results`
- [Google Sheets publisher](https://github.com/as1605/mf-screener-ai/blob/main/src/publish_sheet.py): `src/publish_sheet.py`

### Other components

- **Investor or operator**
- **Tickertape API**
- **Google Sheets**

## Connections

- Fund data provider → Tickertape API: fetches data (evidence: `README.md`)
- Fund data provider → Cached NAV and holdings: caches data (evidence: `src/mf_data_provider.py`)
- Sector scoring strategies → Fund data provider: reads fund data (evidence: `src/algorithms/Mid Cap_Claude.py`)
- Grok scoring engine → Fund data provider: reads fund data (evidence: `src/algorithms/grok_engine.py`)
- Sector scoring strategies → Model score CSVs: writes scores (evidence: `README.md`)
- Grok scoring engine → Model score CSVs: writes scores
- Investor or operator → Compile and publish runner: runs compilation (evidence: `run.py`)
- Compile and publish runner → Consensus score compiler: calls compiler (evidence: `run.py`)
- Compile and publish runner → Google Sheets publisher: calls publisher (evidence: `run.py`)
- Compile and publish runner → Rank history compiler: optionally calls (evidence: `run.py`)
- Consensus score compiler → Model score CSVs: reads model scores (evidence: `src/compile_results.py`)
- Consensus score compiler → Compiled rankings: writes composites
- Rank history compiler → Strategy XIRR evaluator: calls evaluator (evidence: `src/compile_ranks.py`)
- Rank history compiler → Compiled rankings: writes rank history (evidence: `src/compile_ranks.py`)
- Strategy XIRR evaluator → Fund data provider: fetches NAV (evidence: `src/compile_xirr.py`)
- Strategy XIRR evaluator → Compiled rankings: writes XIRR scores (evidence: `src/compile_xirr.py`)
- Google Sheets publisher → Google Sheets: publishes worksheets (evidence: `README.md`)
- Holdings and returns snapshot → Fund data provider: reads fund data (evidence: `src/experiments/focused.py`)
- Point-to-point returns → Fund data provider: reads NAV data (evidence: `src/experiments/returns.py`)
- SIF experiment → Fund data provider: uses provider (evidence: `src/experiments/sif.py`)
- Fund statistics → Fund data provider: uses provider (evidence: `src/generate_statistics.py`)
- Investor or operator → Google Sheets: views live ranks (evidence: `README.md`)
