# jaypatel1511/nmtc-mapper architecture

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

- Interactive diagram: https://gitdiagram.com/jaypatel1511/nmtc-mapper
- Repository: https://github.com/jaypatel1511/nmtc-mapper

## Overview

nmtc-mapper turns addresses or tract IDs into NMTC eligibility and distress results, with explicit indeterminate outcomes; it also reports Opportunity Zone 1.0 and OZ 2.0 statuses. The main path is mapper input, optional Census geocoding, tract lookup and result enrichment. Batch enrichment, offline sample data, and summary counts are additional documented capabilities. Source excerpts establish the mapper’s use of geocoding and eligibility logic; some dataset-loading and OZ 2.0 details are documented in the README but their internal call paths were not fully sampled.

Main entry points: [`nmtcmapper/mapper.py`](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/mapper.py) (NMTC mapper), [`nmtcmapper/eligibility/checker.py`](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/eligibility/checker.py) (Tract eligibility check), [`nmtcmapper/data/loader.py`](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/data/loader.py) (Fund and OZ data), [`nmtcmapper/geocoder/census.py`](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/geocoder/census.py) (Census geocoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public API"]
  node_mapper["NMTC mapper<br/>[mapper.py]"]
  node_batch["Batch enrichment<br/>[mapper.py]"]
  node_summary["Summary counts<br/>[mapper.py]"]
end

subgraph group_data["Data and rules"]
  node_fund_data[("Fund and OZ data<br/>[loader.py]")]
  node_sample_data[("Sample dataset<br/>[loader.py]")]
  node_rules["Schema and thresholds<br/>[schema.py]"]
end

subgraph group_geo["Geocoding"]
  node_census_geocoder["Census geocoder<br/>[census.py]"]
end

subgraph group_results["Eligibility results"]
  node_checker["Tract eligibility check<br/>[checker.py]"]
  node_result["Eligibility result<br/>[checker.py]"]
end

node_caller(("Application caller"))
node_census_service["Census Bureau API"]
node_cdfi[("CDFI Fund data")]
node_treasury[("Treasury OZ 2.0 data")]

node_caller -->|"provides input"| node_mapper
node_mapper -->|"geocodes address"| node_census_geocoder
node_census_geocoder -->|"requests tract"| node_census_service
node_mapper -->|"checks tract"| node_checker
node_checker -->|"uses definitions"| node_rules
node_mapper -->|"loads datasets"| node_fund_data
node_fund_data -->|"downloads eligibility"| node_cdfi
node_fund_data -->|"loads OZ 2.0"| node_treasury
node_mapper -->|"offers sample mode"| node_sample_data
node_mapper -->|"enriches frame"| node_batch
node_batch -->|"geocodes addresses"| node_census_geocoder
node_batch -->|"checks tract rows"| node_checker
node_checker -->|"produces result"| node_result
node_mapper -->|"counts results"| node_summary
node_mapper -->|"returns results"| node_caller

click node_mapper "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/mapper.py"
click node_batch "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/mapper.py"
click node_summary "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/mapper.py"
click node_fund_data "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/data/loader.py"
click node_sample_data "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/data/loader.py"
click node_rules "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/data/schema.py"
click node_census_geocoder "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/geocoder/census.py"
click node_checker "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/eligibility/checker.py"
click node_result "https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/eligibility/checker.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_mapper,node_batch,node_summary toneBlue
class node_fund_data,node_sample_data,node_rules,node_cdfi,node_treasury toneAmber
class node_census_geocoder,node_census_service toneMint
class node_checker,node_result toneRose
class node_caller toneIndigo
```

## Components

### Public API

- [NMTC mapper](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/mapper.py): `nmtcmapper/mapper.py`
- [Batch enrichment](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/mapper.py): `nmtcmapper/mapper.py`
- [Summary counts](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/mapper.py): `nmtcmapper/mapper.py`

### Data and rules

- [Fund and OZ data](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/data/loader.py): `nmtcmapper/data/loader.py`
- [Sample dataset](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/data/loader.py): `nmtcmapper/data/loader.py`
- [Schema and thresholds](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/data/schema.py): `nmtcmapper/data/schema.py`

### Geocoding

- [Census geocoder](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/geocoder/census.py): `nmtcmapper/geocoder/census.py`

### Eligibility results

- [Tract eligibility check](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/eligibility/checker.py): `nmtcmapper/eligibility/checker.py`
- [Eligibility result](https://github.com/jaypatel1511/nmtc-mapper/blob/main/nmtcmapper/eligibility/checker.py): `nmtcmapper/eligibility/checker.py`

### Other components

- **Application caller**
- **Census Bureau API**
- **CDFI Fund data**
- **Treasury OZ 2.0 data**

## Connections

- Application caller → NMTC mapper: provides input (evidence: `README.md`)
- NMTC mapper → Census geocoder: geocodes address (evidence: `nmtcmapper/mapper.py`)
- Census geocoder → Census Bureau API: requests tract (evidence: `README.md`)
- NMTC mapper → Tract eligibility check: checks tract (evidence: `nmtcmapper/mapper.py`)
- Tract eligibility check → Schema and thresholds: uses definitions (evidence: `nmtcmapper/eligibility/checker.py`)
- NMTC mapper → Fund and OZ data: loads datasets (evidence: `README.md`)
- Fund and OZ data → CDFI Fund data: downloads eligibility (evidence: `README.md`)
- Fund and OZ data → Treasury OZ 2.0 data: loads OZ 2.0 (evidence: `README.md`)
- NMTC mapper → Sample dataset: offers sample mode (evidence: `README.md`)
- NMTC mapper → Batch enrichment: enriches frame (evidence: `README.md`)
- Batch enrichment → Census geocoder: geocodes addresses (evidence: `README.md`)
- Batch enrichment → Tract eligibility check: checks tract rows (evidence: `nmtcmapper/mapper.py`)
- Tract eligibility check → Eligibility result: produces result (evidence: `nmtcmapper/eligibility/checker.py`)
- NMTC mapper → Summary counts: counts results (evidence: `README.md`)
- NMTC mapper → Application caller: returns results (evidence: `README.md`)
