# sivaprakash442001/dme-data-matching-engine architecture

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

- Interactive diagram: https://gitdiagram.com/sivaprakash442001/dme-data-matching-engine
- Repository: https://github.com/sivaprakash442001/dme-data-matching-engine

## Overview

This is a web-based entity-resolution engine. Users upload a dataset or enter two strings, select or auto-detect matching types, and receive scored, categorized results with explanations; dataset matches can be filtered and exported. The graph preserves ingestion, normalization, specialized matching, scoring, and the documented interactive UI and multi-column capabilities. Some routes and matcher implementations were only partially sampled, so their connections rely on the SOURCE INDEX references or README statements rather than claims about unseen details.

Main entry points: [`app/matching/engine.py`](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/engine.py) (Matching engine), [`app/web/routes.py`](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/web/routes.py) (API routes), [`app/normalization/cleaner.py`](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/cleaner.py) (Text normalizer), [`app/scoring/scorer.py`](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/scoring/scorer.py) (Score and explanation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_main["FastAPI app<br/>[main.py]"]
  node_routes["API routes<br/>[routes.py]"]
  node_ui["Web dashboard<br/>[app.js]"]
end

subgraph group_ingest["Data handling"]
  node_reader["File reader<br/>[file_reader.py]"]
  node_samples["Sample datasets"]
  node_export["Result exporters<br/>[exporters.py]"]
end

subgraph group_normalize["Normalization"]
  node_cleaner["Text normalizer<br/>[cleaner.py]"]
  node_abbrev["Abbreviation rules<br/>[abbreviations.py]"]
  node_numbers["Number rules<br/>[numbers.py]"]
  node_addressparse["Address parser<br/>[addresses.py]"]
  node_nameparse["Name parser<br/>[names.py]"]
end

subgraph group_match["Matching"]
  node_detector["Type detector<br/>[detector.py]"]
  node_engine["Matching engine<br/>[engine.py]"]
  node_algorithms["Similarity algorithms<br/>[algorithms.py]"]
  node_specialized["Specialized matchers"]
  node_addressmatch["Address matcher<br/>[address.py]"]
  node_companymatch["Company matcher<br/>[company.py]"]
  node_namematch["Person name matcher<br/>[name.py]"]
  node_emailmatch["Email matcher<br/>[email.py]"]
  node_phonematch["Phone matcher<br/>[phone.py]"]
  node_idmatch["ID matcher<br/>[id_code.py]"]
  node_genericmatch["Generic matcher<br/>[generic.py]"]
end

subgraph group_score["Scoring"]
  node_weights["Weight profiles<br/>[weights.py]"]
  node_scorer["Score and explanation<br/>[scorer.py]"]
end

node_user(("User"))

node_user -->|"uses"| node_ui
node_ui -->|"calls API"| node_routes
node_main -->|"mounts routes"| node_routes
node_main -->|"generates samples"| node_samples
node_routes -->|"reads uploads"| node_reader
node_routes -->|"detects types"| node_detector
node_routes -->|"runs matching"| node_engine
node_routes -->|"configures thresholds"| node_scorer
node_routes -->|"exports results"| node_export
node_routes -->|"serves sample data"| node_samples
node_routes -->|"serves dashboard"| node_ui
node_engine -->|"detects values"| node_detector
node_engine -->|"dispatches to"| node_genericmatch
node_engine -->|"dispatches to"| node_addressmatch
node_engine -->|"dispatches to"| node_companymatch
node_engine -->|"dispatches to"| node_namematch
node_engine -->|"dispatches to"| node_emailmatch
node_engine -->|"dispatches to"| node_phonematch
node_engine -->|"dispatches to"| node_idmatch
node_engine -->|"uses scorer"| node_scorer
node_addressmatch -->|"parses addresses"| node_addressparse
node_addressmatch -->|"builds results"| node_scorer
node_companymatch -->|"normalizes text"| node_cleaner
node_companymatch -->|"uses abbreviations"| node_abbrev
node_companymatch -->|"compares strings"| node_algorithms
node_companymatch -->|"gets weights"| node_weights
node_companymatch -->|"builds results"| node_scorer
node_specialized -->|"uses algorithms"| node_algorithms
node_namematch -->|"parses names"| node_nameparse
node_namematch -->|"normalizes text"| node_cleaner
node_namematch -->|"compares strings"| node_algorithms
node_namematch -->|"builds results"| node_scorer
node_emailmatch -->|"normalizes text"| node_cleaner
node_emailmatch -->|"compares strings"| node_algorithms
node_emailmatch -->|"builds results"| node_scorer
node_phonematch -->|"normalizes text"| node_cleaner
node_phonematch -->|"compares strings"| node_algorithms
node_phonematch -->|"builds results"| node_scorer
node_idmatch -->|"normalizes text"| node_cleaner
node_idmatch -->|"compares strings"| node_algorithms
node_idmatch -->|"builds results"| node_scorer
node_genericmatch -->|"normalizes text"| node_cleaner
node_genericmatch -->|"compares strings"| node_algorithms
node_genericmatch -->|"builds results"| node_scorer
node_addressparse -->|"normalizes text"| node_cleaner
node_addressparse -->|"uses abbreviation rules"| node_abbrev
node_nameparse -->|"normalizes names"| node_cleaner
node_cleaner -->|"expands abbreviations"| node_abbrev

click node_main "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/main.py"
click node_routes "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/web/routes.py"
click node_ui "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/web/static/js/app.js"
click node_reader "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/utils/file_reader.py"
click node_samples "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/utils/sample_generator.py"
click node_export "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/utils/exporters.py"
click node_cleaner "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/cleaner.py"
click node_abbrev "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/abbreviations.py"
click node_numbers "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/numbers.py"
click node_addressparse "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/addresses.py"
click node_nameparse "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/names.py"
click node_detector "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/detector.py"
click node_engine "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/engine.py"
click node_algorithms "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/algorithms.py"
click node_specialized "https://github.com/sivaprakash442001/dme-data-matching-engine/tree/main/app/matching"
click node_addressmatch "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/address.py"
click node_companymatch "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/company.py"
click node_namematch "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/name.py"
click node_emailmatch "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/email.py"
click node_phonematch "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/phone.py"
click node_idmatch "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/id_code.py"
click node_genericmatch "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/generic.py"
click node_weights "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/scoring/weights.py"
click node_scorer "https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/scoring/scorer.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_main,node_routes,node_ui,node_user toneBlue
class node_reader,node_samples,node_export toneAmber
class node_cleaner,node_abbrev,node_numbers,node_addressparse,node_nameparse toneMint
class node_detector,node_engine,node_algorithms,node_specialized,node_addressmatch,node_companymatch,node_namematch,node_emailmatch,node_phonematch,node_idmatch,node_genericmatch toneRose
class node_weights,node_scorer toneIndigo
```

## Components

### Web interface

- [FastAPI app](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/main.py): `app/main.py`
- [API routes](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/web/routes.py): `app/web/routes.py`
- [Web dashboard](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/web/static/js/app.js): `app/web/static/js/app.js`

### Data handling

- [File reader](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/utils/file_reader.py): `app/utils/file_reader.py`
- [Sample datasets](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/utils/sample_generator.py): `app/utils/sample_generator.py`
- [Result exporters](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/utils/exporters.py): `app/utils/exporters.py`

### Normalization

- [Text normalizer](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/cleaner.py): `app/normalization/cleaner.py`
- [Abbreviation rules](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/abbreviations.py): `app/normalization/abbreviations.py`
- [Number rules](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/numbers.py): `app/normalization/numbers.py`
- [Address parser](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/addresses.py): `app/normalization/addresses.py`
- [Name parser](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/normalization/names.py): `app/normalization/names.py`

### Matching

- [Type detector](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/detector.py): `app/matching/detector.py`
- [Matching engine](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/engine.py): `app/matching/engine.py`
- [Similarity algorithms](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/algorithms.py): `app/matching/algorithms.py`
- [Specialized matchers](https://github.com/sivaprakash442001/dme-data-matching-engine/tree/main/app/matching): `app/matching`
- [Address matcher](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/address.py): `app/matching/address.py`
- [Company matcher](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/company.py): `app/matching/company.py`
- [Person name matcher](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/name.py): `app/matching/name.py`
- [Email matcher](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/email.py): `app/matching/email.py`
- [Phone matcher](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/phone.py): `app/matching/phone.py`
- [ID matcher](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/id_code.py): `app/matching/id_code.py`
- [Generic matcher](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/matching/generic.py): `app/matching/generic.py`

### Scoring

- [Weight profiles](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/scoring/weights.py): `app/scoring/weights.py`
- [Score and explanation](https://github.com/sivaprakash442001/dme-data-matching-engine/blob/main/app/scoring/scorer.py): `app/scoring/scorer.py`

### Other components

- **User**

## Connections

- User → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → API routes: calls API (evidence: `README.md`)
- FastAPI app → API routes: mounts routes (evidence: `app/main.py`)
- FastAPI app → Sample datasets: generates samples (evidence: `app/main.py`)
- API routes → File reader: reads uploads (evidence: `app/web/routes.py`)
- API routes → Type detector: detects types (evidence: `app/web/routes.py`)
- API routes → Matching engine: runs matching (evidence: `app/web/routes.py`)
- API routes → Score and explanation: configures thresholds (evidence: `app/web/routes.py`)
- API routes → Result exporters: exports results (evidence: `app/web/routes.py`)
- API routes → Sample datasets: serves sample data (evidence: `app/web/routes.py`)
- API routes → Web dashboard: serves dashboard (evidence: `README.md`)
- Matching engine → Type detector: detects values (evidence: `app/matching/engine.py`)
- Matching engine → Generic matcher: dispatches to (evidence: `app/matching/engine.py`)
- Matching engine → Address matcher: dispatches to (evidence: `app/matching/engine.py`)
- Matching engine → Company matcher: dispatches to (evidence: `app/matching/engine.py`)
- Matching engine → Person name matcher: dispatches to (evidence: `app/matching/engine.py`)
- Matching engine → Email matcher: dispatches to (evidence: `app/matching/engine.py`)
- Matching engine → Phone matcher: dispatches to (evidence: `app/matching/engine.py`)
- Matching engine → ID matcher: dispatches to (evidence: `app/matching/engine.py`)
- Matching engine → Score and explanation: uses scorer (evidence: `app/matching/engine.py`)
- Address matcher → Address parser: parses addresses (evidence: `app/matching/address.py`)
- Address matcher → Score and explanation: builds results (evidence: `app/matching/address.py`)
- Company matcher → Text normalizer: normalizes text (evidence: `app/matching/company.py`)
- Company matcher → Abbreviation rules: uses abbreviations (evidence: `app/matching/company.py`)
- Company matcher → Similarity algorithms: compares strings (evidence: `app/matching/company.py`)
- Company matcher → Weight profiles: gets weights (evidence: `app/matching/company.py`)
- Company matcher → Score and explanation: builds results (evidence: `app/matching/company.py`)
- Specialized matchers → Similarity algorithms: uses algorithms (evidence: `app/matching/__init__.py`)
- Person name matcher → Name parser: parses names (evidence: `app/matching/name.py`)
- Person name matcher → Text normalizer: normalizes text (evidence: `app/matching/name.py`)
- Person name matcher → Similarity algorithms: compares strings (evidence: `app/matching/name.py`)
- Person name matcher → Score and explanation: builds results (evidence: `app/matching/name.py`)
- Email matcher → Text normalizer: normalizes text (evidence: `app/matching/email.py`)
- Email matcher → Similarity algorithms: compares strings (evidence: `app/matching/email.py`)
- Email matcher → Score and explanation: builds results (evidence: `app/matching/email.py`)
- Phone matcher → Text normalizer: normalizes text (evidence: `app/matching/phone.py`)
- Phone matcher → Similarity algorithms: compares strings (evidence: `app/matching/phone.py`)
- Phone matcher → Score and explanation: builds results (evidence: `app/matching/phone.py`)
- ID matcher → Text normalizer: normalizes text (evidence: `app/matching/id_code.py`)
- ID matcher → Similarity algorithms: compares strings (evidence: `app/matching/id_code.py`)
- ID matcher → Score and explanation: builds results (evidence: `app/matching/id_code.py`)
- Generic matcher → Text normalizer: normalizes text (evidence: `app/matching/generic.py`)
- Generic matcher → Similarity algorithms: compares strings (evidence: `app/matching/generic.py`)
- Generic matcher → Score and explanation: builds results (evidence: `app/matching/generic.py`)
- Address parser → Text normalizer: normalizes text (evidence: `app/normalization/addresses.py`)
- Address parser → Abbreviation rules: uses abbreviation rules (evidence: `app/normalization/addresses.py`)
- Name parser → Text normalizer: normalizes names (evidence: `app/normalization/names.py`)
- Text normalizer → Abbreviation rules: expands abbreviations (evidence: `app/normalization/cleaner.py`)
