# jay2323-tech/amazon-ml-challenge-2026 architecture

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

- Interactive diagram: https://gitdiagram.com/jay2323-tech/amazon-ml-challenge-2026
- Repository: https://github.com/jay2323-tech/amazon-ml-challenge-2026

## Overview

This repository is a starter scaffold for a business entity-resolution challenge, not a complete matching application. The README defines the intended workflow—generate candidates, score them, and emit matches and candidates—but the blocking, feature, model, and submission packages contain no sampled implementation. The graph separates that documented workflow from the implemented normalization, evaluation, split-generation, EDA, and submission-validation utilities; links between unsampled pipeline stages are therefore documented rather than code-verified.

Main entry points: [`utils/validate_submission.py`](https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/utils/validate_submission.py) (Submission validator), [`code/business_entity_resolution/src/evaluation/make_split.py`](https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/evaluation/make_split.py) (Validation split), [`code/business_entity_resolution/src/blocking`](https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/blocking) (Candidate blocking), [`code/business_entity_resolution/src/evaluation/f05.py`](https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/evaluation/f05.py) (F0.5 scoring)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Matching workflow"]
  node_records["Source records"]
  node_normalize["Text normalization<br/>[normalize.py]"]
  node_blocking["Candidate blocking"]
  node_features["Match features"]
  node_model["Match model"]
  node_submission_writer["Submission output"]
  node_candidate_file["Candidate pairs"]
  node_matching_file["Matching results"]
end

subgraph group_utilities["Data and evaluation"]
  node_eda["Dataset analysis<br/>[eda.py]"]
  node_split["Validation split<br/>[make_split.py]"]
  node_split_ids["Split ID files"]
  node_f05["F0.5 scoring<br/>[f05.py]"]
  node_ground_truth["Training labels"]
  node_predictions["Predictions"]
end

subgraph group_submission["Submission checks"]
  node_validator["Submission validator"]
  node_test_data["Test records"]
end

node_team(("Solution author"))

node_team -.->|"provides"| node_records
node_records -.->|"normalizes"| node_normalize
node_records -.->|"blocks"| node_blocking
node_blocking -.->|"writes candidates"| node_candidate_file
node_blocking -.->|"selects pairs"| node_features
node_features -.->|"scores pairs"| node_model
node_model -.->|"produces matches"| node_submission_writer
node_submission_writer -.->|"writes results"| node_matching_file
node_team -->|"runs"| node_eda
node_eda -->|"reads"| node_records
node_team -->|"runs"| node_split
node_split -->|"reads Source 1"| node_records
node_split -->|"reads labels"| node_ground_truth
node_split -->|"writes IDs"| node_split_ids
node_team -->|"runs"| node_f05
node_f05 -->|"reads"| node_ground_truth
node_f05 -->|"reads"| node_predictions
node_team -->|"runs"| node_validator
node_validator -->|"reads Source 1"| node_test_data
node_validator -->|"checks"| node_matching_file
node_validator -->|"checks optionally"| node_candidate_file
node_test_data -->|"checks IDs optionally"| node_validator

click node_normalize "https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/preprocessing/normalize.py"
click node_blocking "https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/blocking"
click node_features "https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/features"
click node_model "https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/models"
click node_submission_writer "https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/submission"
click node_eda "https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/eda.py"
click node_split "https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/evaluation/make_split.py"
click node_split_ids "https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/splits"
click node_f05 "https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/evaluation/f05.py"
click node_validator "https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/utils/validate_submission.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_records,node_normalize,node_blocking,node_features,node_model,node_submission_writer,node_candidate_file,node_matching_file toneBlue
class node_eda,node_split,node_split_ids,node_f05,node_ground_truth,node_predictions toneAmber
class node_validator,node_test_data toneMint
class node_team toneIndigo
```

## Components

### Matching workflow

- **Source records**
- [Text normalization](https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/preprocessing/normalize.py): `code/business_entity_resolution/src/preprocessing/normalize.py`
- [Candidate blocking](https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/blocking): `code/business_entity_resolution/src/blocking`
- [Match features](https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/features): `code/business_entity_resolution/src/features`
- [Match model](https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/models): `code/business_entity_resolution/src/models`
- [Submission output](https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/src/submission): `code/business_entity_resolution/src/submission`
- **Candidate pairs**
- **Matching results**

### Data and evaluation

- [Dataset analysis](https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/eda.py): `code/business_entity_resolution/src/eda.py`
- [Validation split](https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/evaluation/make_split.py): `code/business_entity_resolution/src/evaluation/make_split.py`
- [Split ID files](https://github.com/jay2323-tech/amazon-ml-challenge-2026/tree/main/code/business_entity_resolution/splits): `code/business_entity_resolution/splits`
- [F0.5 scoring](https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/code/business_entity_resolution/src/evaluation/f05.py): `code/business_entity_resolution/src/evaluation/f05.py`
- **Training labels**
- **Predictions**

### Submission checks

- [Submission validator](https://github.com/jay2323-tech/amazon-ml-challenge-2026/blob/main/utils/validate_submission.py): `utils/validate_submission.py`
- **Test records**

### Other components

- **Solution author**

## Connections

- Solution author → Source records: provides
- Source records → Text normalization: normalizes
- Source records → Candidate blocking: blocks
- Candidate blocking → Candidate pairs: writes candidates
- Candidate blocking → Match features: selects pairs
- Match features → Match model: scores pairs
- Match model → Submission output: produces matches
- Submission output → Matching results: writes results
- Solution author → Dataset analysis: runs
- Dataset analysis → Source records: reads
- Solution author → Validation split: runs
- Validation split → Source records: reads Source 1
- Validation split → Training labels: reads labels
- Validation split → Split ID files: writes IDs
- Solution author → F0.5 scoring: runs
- F0.5 scoring → Training labels: reads
- F0.5 scoring → Predictions: reads
- Solution author → Submission validator: runs
- Submission validator → Test records: reads Source 1
- Submission validator → Matching results: checks
- Submission validator → Candidate pairs: checks optionally
- Test records → Submission validator: checks IDs optionally