# mohithbs-stack/resolvent architecture

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

- Interactive diagram: https://gitdiagram.com/mohithbs-stack/resolvent
- Repository: https://github.com/mohithbs-stack/resolvent

## Overview

This repository provides an end-to-end business entity resolution challenge solution: it ingests three noisy business-record sources, generates candidate pairs, scores likely matches, and packages matches plus the candidate audit trail. It also supports held-out F0.5 evaluation and a dashboard-data export path. The sampled orchestration excerpt is incomplete, so links between pipeline stages reflect the documented stage sequence; dashboard rendering details are not evident from the sampled source.

Main entry points: [`code/business_entity_resolution/run_pipeline.py`](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/run_pipeline.py) (Pipeline orchestrator), [`code/business_entity_resolution/src/blocking/candidate_gen.py`](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/blocking/candidate_gen.py) (Candidate blocking), [`code/business_entity_resolution/src/features/similarity.py`](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/features/similarity.py) (Similarity features), [`code/business_entity_resolution/src/matching/predict.py`](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/matching/predict.py) (Score & threshold)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Resolution Workflow"]
  node_pipeline["Pipeline orchestrator<br/>[run_pipeline.py]"]
  node_ingest["Load &amp; normalize<br/>[load_normalize.py]"]
  node_block["Candidate blocking<br/>[candidate_gen.py]"]
end

subgraph group_modeling["Matching Model"]
  node_features["Similarity features<br/>[similarity.py]"]
  node_train["Train matcher<br/>[train.py]"]
  node_model["LightGBM model<br/>[lgbm_matcher.txt]"]
  node_predict["Score &amp; threshold<br/>[predict.py]"]
end

subgraph group_quality["Evaluation &amp; Reporting"]
  node_evaluate["F0.5 validation<br/>[score_f05.py]"]
  node_dashboard_export["Dashboard data export"]
  node_dashboard["Dashboard<br/>[index.html]"]
end

subgraph group_delivery["Submission Outputs"]
  node_package["Package outputs<br/>[package.py]"]
  node_results["Submission TSVs"]
end

node_operator(("Challenge operator"))
node_source_data["Source TSVs"]

node_operator -->|"runs"| node_pipeline
node_source_data -->|"supplies"| node_pipeline
node_pipeline -->|"loads data"| node_ingest
node_pipeline -->|"generates candidates"| node_block
node_pipeline -->|"builds features"| node_features
node_pipeline -->|"trains matcher"| node_train
node_pipeline -->|"runs inference"| node_predict
node_ingest -->|"normalized records"| node_block
node_block -->|"candidate pairs"| node_features
node_features -->|"training features"| node_train
node_train -->|"saves model"| node_model
node_features -->|"inference features"| node_predict
node_model -->|"scores with"| node_predict
node_predict -->|"match sets"| node_package
node_block -->|"candidate sets"| node_package
node_package -->|"writes TSVs"| node_results
node_evaluate -.->|"provides scoring"| node_dashboard_export
node_model -.->|"feature importances"| node_dashboard_export
node_dashboard_export -->|"exports dashboard data"| node_dashboard

click node_pipeline "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/run_pipeline.py"
click node_ingest "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/ingest/load_normalize.py"
click node_block "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/blocking/candidate_gen.py"
click node_features "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/features/similarity.py"
click node_train "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/matching/train.py"
click node_model "https://github.com/mohithbs-stack/resolvent/blob/main/models/lgbm_matcher.txt"
click node_predict "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/matching/predict.py"
click node_evaluate "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/evaluate/score_f05.py"
click node_dashboard_export "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/export_dashboard_data.py"
click node_dashboard "https://github.com/mohithbs-stack/resolvent/blob/main/dashboard/index.html"
click node_package "https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/submit/package.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_pipeline,node_ingest,node_block toneBlue
class node_features,node_train,node_model,node_predict toneAmber
class node_evaluate,node_dashboard_export,node_dashboard toneMint
class node_package,node_results toneRose
class node_operator,node_source_data toneIndigo
```

## Components

### Resolution Workflow

- [Pipeline orchestrator](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/run_pipeline.py): `code/business_entity_resolution/run_pipeline.py`
- [Load & normalize](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/ingest/load_normalize.py): `code/business_entity_resolution/src/ingest/load_normalize.py`
- [Candidate blocking](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/blocking/candidate_gen.py): `code/business_entity_resolution/src/blocking/candidate_gen.py`

### Matching Model

- [Similarity features](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/features/similarity.py): `code/business_entity_resolution/src/features/similarity.py`
- [Train matcher](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/matching/train.py): `code/business_entity_resolution/src/matching/train.py`
- [LightGBM model](https://github.com/mohithbs-stack/resolvent/blob/main/models/lgbm_matcher.txt): `models/lgbm_matcher.txt`
- [Score & threshold](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/matching/predict.py): `code/business_entity_resolution/src/matching/predict.py`

### Evaluation & Reporting

- [F0.5 validation](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/evaluate/score_f05.py): `code/business_entity_resolution/src/evaluate/score_f05.py`
- [Dashboard data export](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/export_dashboard_data.py): `code/business_entity_resolution/export_dashboard_data.py`
- [Dashboard](https://github.com/mohithbs-stack/resolvent/blob/main/dashboard/index.html): `dashboard/index.html`

### Submission Outputs

- [Package outputs](https://github.com/mohithbs-stack/resolvent/blob/main/code/business_entity_resolution/src/submit/package.py): `code/business_entity_resolution/src/submit/package.py`
- **Submission TSVs**

### Other components

- **Challenge operator**
- **Source TSVs**

## Connections

- Challenge operator → Pipeline orchestrator: runs
- Source TSVs → Pipeline orchestrator: supplies
- Pipeline orchestrator → Load & normalize: loads data
- Pipeline orchestrator → Candidate blocking: generates candidates
- Pipeline orchestrator → Similarity features: builds features
- Pipeline orchestrator → Train matcher: trains matcher
- Pipeline orchestrator → Score & threshold: runs inference
- Load & normalize → Candidate blocking: normalized records
- Candidate blocking → Similarity features: candidate pairs
- Similarity features → Train matcher: training features
- Train matcher → LightGBM model: saves model
- Similarity features → Score & threshold: inference features
- LightGBM model → Score & threshold: scores with
- Score & threshold → Package outputs: match sets
- Candidate blocking → Package outputs: candidate sets
- Package outputs → Submission TSVs: writes TSVs
- F0.5 validation → Dashboard data export: provides scoring
- LightGBM model → Dashboard data export: feature importances
- Dashboard data export → Dashboard: exports dashboard data