# korepupavankumar/business-entity-resolution architecture

> Architecture diagram of the GitHub repository korepupavankumar/business-entity-resolution, 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/korepupavankumar/business-entity-resolution
- Repository: https://github.com/korepupavankumar/business-entity-resolution

## Overview

This is a business-entity resolution application: it trains a classifier from labeled records and then matches Source 1 entities against Sources 2 and 3. The main run is orchestrated by `pipeline.py`: load and normalize records, generate candidates, train or apply the model, and write candidate and match files. Training also builds labeled feature pairs using ground truth; prediction scores candidate pairs against a threshold. The README provides only the product name, so feature details and links here are based on the sampled source; unsampled subsystem wiring is omitted.

Main entry points: [`pipeline.py`](https://github.com/korepupavankumar/business-entity-resolution/blob/main/pipeline.py) (Workflow runner), [`train_model.py`](https://github.com/korepupavankumar/business-entity-resolution/blob/main/train_model.py) (Classifier training), [`predict.py`](https://github.com/korepupavankumar/business-entity-resolution/blob/main/predict.py) (Candidate scoring), [`blocking.py`](https://github.com/korepupavankumar/business-entity-resolution/blob/main/blocking.py) (Candidate blocking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Run orchestration"]
  node_pipeline["Workflow runner<br/>[pipeline.py]"]
end

subgraph group_matching["Matching stages"]
  node_normalization["Record normalization<br/>[normalization.py]"]
  node_blocking["Candidate blocking<br/>[blocking.py]"]
  node_blocking_db[("Blocking index<br/>[blocking.py]")]
  node_predict["Candidate scoring<br/>[predict.py]"]
end

subgraph group_learning["Model training"]
  node_train["Classifier training<br/>[train_model.py]"]
  node_features["Pair features<br/>[features.py]"]
  node_model_artifact["Trained model"]
end

subgraph group_io["Data and evaluation"]
  node_loader["TSV loader<br/>[data_loader.py]"]
  node_ground_truth["Ground-truth mapping<br/>[ground_truth.py]"]
  node_evaluate["Match evaluation<br/>[evaluate.py]"]
  node_writer["Result writer<br/>[output_writer.py]"]
end

node_user(("Operator"))
node_training_data["Training TSVs"]
node_test_data["Test TSVs"]
node_output_files["Output TSVs"]

node_user -->|"starts run"| node_pipeline
node_training_data -->|"provides records"| node_loader
node_test_data -->|"provides records"| node_loader
node_pipeline -->|"loads data"| node_loader
node_pipeline -->|"normalizes records"| node_normalization
node_pipeline -->|"generates candidates"| node_blocking
node_blocking -->|"reads and writes"| node_blocking_db
node_pipeline -->|"maps labels"| node_ground_truth
node_pipeline -->|"trains classifier"| node_train
node_train -->|"builds pair features"| node_features
node_train -->|"uses labels"| node_ground_truth
node_train -->|"builds source indexes"| node_blocking
node_train -->|"saves model"| node_model_artifact
node_pipeline -->|"loads model"| node_model_artifact
node_pipeline -->|"scores candidates"| node_predict
node_predict -->|"computes features"| node_features
node_predict -->|"scores with model"| node_model_artifact
node_pipeline -->|"evaluates blocking"| node_evaluate
node_pipeline -->|"writes results"| node_writer
node_writer -->|"writes TSVs"| node_output_files

click node_pipeline "https://github.com/korepupavankumar/business-entity-resolution/blob/main/pipeline.py"
click node_loader "https://github.com/korepupavankumar/business-entity-resolution/blob/main/data_loader.py"
click node_normalization "https://github.com/korepupavankumar/business-entity-resolution/blob/main/normalization.py"
click node_blocking "https://github.com/korepupavankumar/business-entity-resolution/blob/main/blocking.py"
click node_blocking_db "https://github.com/korepupavankumar/business-entity-resolution/blob/main/blocking.py"
click node_ground_truth "https://github.com/korepupavankumar/business-entity-resolution/blob/main/ground_truth.py"
click node_train "https://github.com/korepupavankumar/business-entity-resolution/blob/main/train_model.py"
click node_features "https://github.com/korepupavankumar/business-entity-resolution/blob/main/features.py"
click node_predict "https://github.com/korepupavankumar/business-entity-resolution/blob/main/predict.py"
click node_evaluate "https://github.com/korepupavankumar/business-entity-resolution/blob/main/evaluate.py"
click node_writer "https://github.com/korepupavankumar/business-entity-resolution/blob/main/output_writer.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 toneBlue
class node_normalization,node_blocking,node_blocking_db,node_predict toneAmber
class node_train,node_features,node_model_artifact toneMint
class node_loader,node_ground_truth,node_evaluate,node_writer toneRose
class node_user,node_training_data,node_test_data,node_output_files toneIndigo
```

## Components

### Run orchestration

- [Workflow runner](https://github.com/korepupavankumar/business-entity-resolution/blob/main/pipeline.py): `pipeline.py`

### Matching stages

- [Record normalization](https://github.com/korepupavankumar/business-entity-resolution/blob/main/normalization.py): `normalization.py`
- [Candidate blocking](https://github.com/korepupavankumar/business-entity-resolution/blob/main/blocking.py): `blocking.py`
- [Blocking index](https://github.com/korepupavankumar/business-entity-resolution/blob/main/blocking.py): `blocking.py`
- [Candidate scoring](https://github.com/korepupavankumar/business-entity-resolution/blob/main/predict.py): `predict.py`

### Model training

- [Classifier training](https://github.com/korepupavankumar/business-entity-resolution/blob/main/train_model.py): `train_model.py`
- [Pair features](https://github.com/korepupavankumar/business-entity-resolution/blob/main/features.py): `features.py`
- **Trained model**

### Data and evaluation

- [TSV loader](https://github.com/korepupavankumar/business-entity-resolution/blob/main/data_loader.py): `data_loader.py`
- [Ground-truth mapping](https://github.com/korepupavankumar/business-entity-resolution/blob/main/ground_truth.py): `ground_truth.py`
- [Match evaluation](https://github.com/korepupavankumar/business-entity-resolution/blob/main/evaluate.py): `evaluate.py`
- [Result writer](https://github.com/korepupavankumar/business-entity-resolution/blob/main/output_writer.py): `output_writer.py`

### Other components

- **Operator**
- **Training TSVs**
- **Test TSVs**
- **Output TSVs**

## Connections

- Operator → Workflow runner: starts run
- Training TSVs → TSV loader: provides records
- Test TSVs → TSV loader: provides records
- Workflow runner → TSV loader: loads data
- Workflow runner → Record normalization: normalizes records
- Workflow runner → Candidate blocking: generates candidates
- Candidate blocking → Blocking index: reads and writes
- Workflow runner → Ground-truth mapping: maps labels
- Workflow runner → Classifier training: trains classifier
- Classifier training → Pair features: builds pair features
- Classifier training → Ground-truth mapping: uses labels
- Classifier training → Candidate blocking: builds source indexes
- Classifier training → Trained model: saves model
- Workflow runner → Trained model: loads model
- Workflow runner → Candidate scoring: scores candidates
- Candidate scoring → Pair features: computes features
- Candidate scoring → Trained model: scores with model
- Workflow runner → Match evaluation: evaluates blocking
- Workflow runner → Result writer: writes results
- Result writer → Output TSVs: writes TSVs