# nayakwadis/mftool architecture

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

- Interactive diagram: https://gitdiagram.com/nayakwadis/mftool
- Repository: https://github.com/nayakwadis/mftool

## Overview

1. **What this repository is**
   - `mftool` is a **Python library**, not an application server.
   - Its main job is to fetch and normalize **public mutual fund data in India**: live NAV quotes, bulk quotes, historical NAVs, scheme lookup, and validation of scheme codes.
   - The architecture is centered on a **single importable library API** that talks to external public data sources and returns Python-native structures or DataFrames.

2. **Primary runtime boundary**
   - The key boundary is between **library consumers** and the **external AMFI/public mutual-fund data sources**.
   - Client code calls into `mftool.py`; that code fetches data over the network, parses it, and returns formatted results.
   - There is no separate backend process, database, or message queue in this repo.

3. **Core API module**
   - `mftool.py` is the main entry point and likely contains the public class/function surface used by callers.
   - The README feature list maps directly to this layer: scheme-wise quote lookup, bulk quotes, historical NAVs, scheme search, and scheme-code validation.
   - This module is the orchestration layer that ties together fetching, parsing, cache handling, and result shaping.

4. **Data-fetching and transformation flow**
   - The expected flow is: **input scheme code or search term → fetch remote AMFI data → parse/clean → return as dict / JSON / DataFrame**.
   - The repo explicitly supports multiple output shapes, so one architectural concern is **presentation/serialization** rather than just retrieval.
   - `utils.py` likely hosts shared helpers for parsing, date handling, conversion, and response normalization.

5. **Caching subsystem**
   - `cache.py` and `CACHING_GUIDE.md` indicate a dedicated **local caching layer**.
   - This layer exists to reduce repeated network calls and improve performance for repeated quote/history requests.
   - Architecturally, cache sits between the public API and the remote data source, with tests validating that behavior.

6. **Static reference data**
   - `data/Scheme_codes.txt`, `scheme_codes.json`, and `const.json` are repository-managed data assets used by the library.
   - These files likely support scheme lookup, validation, or mapping between scheme names and codes.
   - This creates an important boundary between **dynamic market data fetched remotely** and **static reference metadata shipped with the package**.

7. **Package and dependency structure**
   - `setup.py`, `requirements.txt`, and `__init__.py` define the library packaging and import surface.
   - The project targets **Python 3.10+** per the README badge.
   - The presence of DataFrame output in the README suggests a dependency on **pandas** or a similar data library, though the exact usage is encapsulated inside the package.

8. **Testing boundary**
   - `tests/mftool_tests.py`, `tests/test_bulk_quotes.py`, `tests/test_caching.py`, and `tests/test_search.py` show that the repo is organized around **behavioral tests for API features**.
   - Tests likely validate response parsing, search correctness, bulk quote handling, and cache semantics.
   - This helps confirm the library’s main seams: network integration, cache behavior, and lookup logic.

9. **Documentation and developer experience**
   - `docs/` with `docs/conf.py`, `docs/index.rst`, and `.readthedocs.yaml` shows that documentation is a first-class part of the project.
   - `CACHING_GUIDE.md` is an additional architecture-oriented usage guide for a nontrivial subsystem.
   - Documentation and examples are important because the library is consumed directly by other Python projects.

10. **Automation and quality tooling**
   - `.github/workflows/codeql-analysis.yml` adds static security/code scanning.
   - This repo also appears ready for public distribution via PyPI and ReadTheDocs.
   - These are supporting layers, not runtime subsystems, but they matter for how the library is maintained and released.

11. **External integration and usage model**
   - The library is designed for downstream use in analytics, automation, and data collection workflows.
   - The external dependency is the live mutual fund data source; the repo itself provides the client-side adapter and local reference data.
   - For an architecture diagram, the key picture is: **consumer application → mftool API → cache/static data → external mutual fund data source → normalized output**.

Main entry points: [`mftool.py`](https://github.com/nayakwadis/mftool/blob/master/mftool.py) (mftool.py), [`cache.py`](https://github.com/nayakwadis/mftool/blob/master/cache.py) (cache.py), [`docs/conf.py`](https://github.com/nayakwadis/mftool/blob/master/docs/conf.py) (docs config), [`utils.py`](https://github.com/nayakwadis/mftool/blob/master/utils.py) (utils.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core library"]
  node_node_mftool["mftool.py<br/>public API<br/>[mftool.py]"]
  node_node_utils["utils.py<br/>helpers<br/>[utils.py]"]
  node_node_cache[("cache.py<br/>cache layer<br/>[cache.py]")]
  node_node_init["__init__.py<br/>package export<br/>[__init__.py]"]
end

subgraph group_group_data["Reference data"]
  node_node_scheme_codes_txt["Scheme codes<br/>reference data<br/>[Scheme_codes.txt]"]
  node_node_scheme_codes_json["scheme_codes.json<br/>reference map<br/>[scheme_codes.json]"]
  node_node_const["const.json<br/>constants<br/>[const.json]"]
end

subgraph group_group_tests["Tests"]
  node_node_test_main["API tests<br/>pytest<br/>[mftool_tests.py]"]
  node_node_test_bulk["Bulk quotes<br/>pytest"]
  node_node_test_cache["Cache tests<br/>pytest<br/>[test_caching.py]"]
  node_node_test_search["Search tests<br/>pytest<br/>[test_search.py]"]
end

subgraph group_group_docs["Docs"]
  node_node_readme["README.md<br/>usage guide<br/>[README.md]"]
  node_node_cache_guide["Caching guide<br/>[CACHING_GUIDE.md]"]
  node_node_docs_conf["docs config<br/>docs build<br/>[conf.py]"]
  node_node_docs_index["docs index<br/>docs page<br/>[index.rst]"]
end

subgraph group_group_maint["Maintenance"]
  node_node_setup["setup.py<br/>packaging<br/>[setup.py]"]
  node_node_requirements["requirements<br/>deps<br/>[requirements.txt]"]
  node_node_docs_reqs["docs deps<br/>[requirements.txt]"]
  node_node_readthedocs[".readthedocs.yaml<br/>docs automation<br/>[.readthedocs.yaml]"]
  node_node_codeql["codeql workflow<br/>ci scan"]
end

node_node_mftool -->|"uses"| node_node_utils
node_node_mftool -->|"uses"| node_node_cache
node_node_mftool -->|"reads"| node_node_scheme_codes_txt
node_node_mftool -->|"reads"| node_node_scheme_codes_json
node_node_mftool -->|"reads"| node_node_const
node_node_cache -->|"uses"| node_node_utils
node_node_init -->|"exports"| node_node_mftool
node_node_test_main -->|"verifies"| node_node_mftool
node_node_test_bulk -->|"verifies"| node_node_mftool
node_node_test_cache -->|"verifies"| node_node_cache
node_node_test_search -->|"verifies"| node_node_mftool
node_node_readme -->|"documents"| node_node_mftool
node_node_cache_guide -->|"documents"| node_node_cache
node_node_docs_conf -->|"builds"| node_node_docs_index
node_node_docs_reqs -->|"supports"| node_node_docs_conf
node_node_readthedocs -->|"builds"| node_node_docs_conf
node_node_setup -->|"depends on"| node_node_requirements
node_node_codeql -->|"scans"| node_node_mftool
node_node_codeql -->|"scans"| node_node_utils

click node_node_mftool "https://github.com/nayakwadis/mftool/blob/master/mftool.py"
click node_node_utils "https://github.com/nayakwadis/mftool/blob/master/utils.py"
click node_node_cache "https://github.com/nayakwadis/mftool/blob/master/cache.py"
click node_node_init "https://github.com/nayakwadis/mftool/blob/master/__init__.py"
click node_node_scheme_codes_txt "https://github.com/nayakwadis/mftool/blob/master/data/Scheme_codes.txt"
click node_node_scheme_codes_json "https://github.com/nayakwadis/mftool/blob/master/scheme_codes.json"
click node_node_const "https://github.com/nayakwadis/mftool/blob/master/const.json"
click node_node_test_main "https://github.com/nayakwadis/mftool/blob/master/tests/mftool_tests.py"
click node_node_test_bulk "https://github.com/nayakwadis/mftool/blob/master/tests/test_bulk_quotes.py"
click node_node_test_cache "https://github.com/nayakwadis/mftool/blob/master/tests/test_caching.py"
click node_node_test_search "https://github.com/nayakwadis/mftool/blob/master/tests/test_search.py"
click node_node_readme "https://github.com/nayakwadis/mftool/blob/master/README.md"
click node_node_cache_guide "https://github.com/nayakwadis/mftool/blob/master/CACHING_GUIDE.md"
click node_node_docs_conf "https://github.com/nayakwadis/mftool/blob/master/docs/conf.py"
click node_node_docs_index "https://github.com/nayakwadis/mftool/blob/master/docs/index.rst"
click node_node_setup "https://github.com/nayakwadis/mftool/blob/master/setup.py"
click node_node_requirements "https://github.com/nayakwadis/mftool/blob/master/requirements.txt"
click node_node_docs_reqs "https://github.com/nayakwadis/mftool/blob/master/docs/requirements.txt"
click node_node_readthedocs "https://github.com/nayakwadis/mftool/blob/master/.readthedocs.yaml"
click node_node_codeql "https://github.com/nayakwadis/mftool/blob/master/.github/workflows/codeql-analysis.yml"

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_node_mftool,node_node_utils,node_node_cache,node_node_init toneBlue
class node_node_scheme_codes_txt,node_node_scheme_codes_json,node_node_const toneAmber
class node_node_test_main,node_node_test_bulk,node_node_test_cache,node_node_test_search toneMint
class node_node_readme,node_node_cache_guide,node_node_docs_conf,node_node_docs_index toneRose
class node_node_setup,node_node_requirements,node_node_docs_reqs,node_node_readthedocs,node_node_codeql toneIndigo
```

## Components

### Core library

Importable API, caching, and shared utilities that power the package.

- [mftool.py](https://github.com/nayakwadis/mftool/blob/master/mftool.py): public API · Main library entry point and orchestration surface for callers. · `mftool.py`
- [utils.py](https://github.com/nayakwadis/mftool/blob/master/utils.py): helpers · Shared parsing, conversion, and normalization helpers. · `utils.py`
- [cache.py](https://github.com/nayakwadis/mftool/blob/master/cache.py): cache layer · Local caching logic to reduce repeated remote fetches. · `cache.py`
- [__init__.py](https://github.com/nayakwadis/mftool/blob/master/__init__.py): package export · Package import surface. · `__init__.py`

### Reference data

Static files shipped with the package for scheme lookup and validation.

- [Scheme codes](https://github.com/nayakwadis/mftool/blob/master/data/Scheme_codes.txt): reference data · Packaged scheme code list used for lookup and validation. · `data/Scheme_codes.txt`
- [scheme_codes.json](https://github.com/nayakwadis/mftool/blob/master/scheme_codes.json): reference map · Structured scheme metadata used by the library. · `scheme_codes.json`
- [const.json](https://github.com/nayakwadis/mftool/blob/master/const.json): constants · Static configuration and mapping values. · `const.json`

### Tests

Behavioral tests around the main library features.

- [API tests](https://github.com/nayakwadis/mftool/blob/master/tests/mftool_tests.py): pytest · Tests for core library behavior and responses. · `tests/mftool_tests.py`
- [Bulk quotes](https://github.com/nayakwadis/mftool/blob/master/tests/test_bulk_quotes.py): pytest · Tests for bulk quote retrieval and formatting. · `tests/test_bulk_quotes.py`
- [Cache tests](https://github.com/nayakwadis/mftool/blob/master/tests/test_caching.py): pytest · Tests covering cache behavior and reuse. · `tests/test_caching.py`
- [Search tests](https://github.com/nayakwadis/mftool/blob/master/tests/test_search.py): pytest · Tests for scheme search and lookup behavior. · `tests/test_search.py`

### Docs

User and developer documentation for the package.

- [README.md](https://github.com/nayakwadis/mftool/blob/master/README.md): usage guide · Primary project overview and API examples. · `README.md`
- [Caching guide](https://github.com/nayakwadis/mftool/blob/master/CACHING_GUIDE.md): guide · Documentation for the caching subsystem. · `CACHING_GUIDE.md`
- [docs config](https://github.com/nayakwadis/mftool/blob/master/docs/conf.py): docs build · Sphinx documentation configuration. · `docs/conf.py`
- [docs index](https://github.com/nayakwadis/mftool/blob/master/docs/index.rst): docs page · Documentation landing page. · `docs/index.rst`

### Maintenance

Packaging and automation files for release, docs, and analysis.

- [setup.py](https://github.com/nayakwadis/mftool/blob/master/setup.py): packaging · Package metadata and install configuration. · `setup.py`
- [requirements](https://github.com/nayakwadis/mftool/blob/master/requirements.txt): deps · Runtime dependency specification. · `requirements.txt`
- [docs deps](https://github.com/nayakwadis/mftool/blob/master/docs/requirements.txt): deps · Documentation build dependencies. · `docs/requirements.txt`
- [.readthedocs.yaml](https://github.com/nayakwadis/mftool/blob/master/.readthedocs.yaml): docs automation · Hosted documentation build configuration. · `.readthedocs.yaml`
- [codeql workflow](https://github.com/nayakwadis/mftool/blob/master/.github/workflows/codeql-analysis.yml): ci scan · Static analysis workflow. · `.github/workflows/codeql-analysis.yml`

## Connections

- mftool.py → utils.py: uses · Core API relies on shared parsing and normalization helpers.
- mftool.py → cache.py: uses · API consults cache before or after remote fetches.
- mftool.py → Scheme codes: reads · Uses packaged scheme code reference data.
- mftool.py → scheme_codes.json: reads · Uses structured scheme metadata for lookup and validation.
- mftool.py → const.json: reads · Consumes static constants and mappings.
- cache.py → utils.py: uses · Cache logic shares normalization and conversion helpers.
- __init__.py → mftool.py: exports · Package import surface exposes the main library entry point.
- API tests → mftool.py: verifies · Covers primary API behavior.
- Bulk quotes → mftool.py: verifies · Covers bulk quote flow.
- Cache tests → cache.py: verifies · Covers cache semantics.
- Search tests → mftool.py: verifies · Covers search and lookup behavior.
- README.md → mftool.py: documents · README explains the main public API.
- Caching guide → cache.py: documents · Guide explains cache usage and behavior.
- docs config → docs index: builds · Sphinx config drives the docs site.
- docs deps → docs config: supports · Documentation build dependencies.
- .readthedocs.yaml → docs config: builds · Hosted docs pipeline uses Sphinx configuration.
- setup.py → requirements: depends on · Packaging references runtime dependencies.
- codeql workflow → mftool.py: scans · Static analysis targets the library code.
- codeql workflow → utils.py: scans · Static analysis includes shared helper code.