# garvitjoshi1/inspectra architecture

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

- Interactive diagram: https://gitdiagram.com/garvitjoshi1/inspectra
- Repository: https://github.com/garvitjoshi1/inspectra

## Overview

#### Purpose and Entry Points
Inspectra is a computer-vision defect-inspection project spanning dataset preparation, model training, evaluation, ONNX export, and local inference deployment. The executable serving surface is `deployment/api.py`, supported by `deployment/inference.py` and `deployment/model_registry.py`. The notebook sequence (`notebooks/01_dataset_inspection.ipynb` through `notebooks/09_deployment.ipynb`) is the primary experiment workflow.

#### Data Preparation and Experiment Workflow
The project uses public industrial-inspection datasets covering cracks, PCB defects, steel defects, bottles, and welding defects. Dataset inspection, cleaning, and preparation are staged in `notebooks/01_dataset_inspection.ipynb`, `notebooks/02_data_cleaning.ipynb`, and `notebooks/03_data_preparation.ipynb`. Cleaning outcomes are persisted in `reports/dataset_cleaning_report.json`, creating a boundary between raw data work and downstream training.

#### Model Families and Training
Two model tracks are evident:
- Object-detection models for bottle and PCB inspection, with baseline and fine-tuned checkpoints under `experiments/bottle/baseline/baseline/weights/best.pt`, `experiments/pcb/baseline/baseline/weights/best.pt`, and `experiments/finetuning/experiment_config.json`.
- A road/defect classification-style ResNet-18 track, with baseline and tuned weights at `models/road/baseline_resnet18.pt` and `models/road/finetuned/resnet18_finetuned.pt`.

Training and fine-tuning are notebook-driven through `notebooks/04_baseline_training.ipynb` and `notebooks/06_fine_tuning.ipynb`; model artifacts are durable experiment outputs rather than dynamically trained by deployment.

#### Evaluation and Release Selection
Baseline, fine-tuned, and final-test results are materialized as CSV/JSON artifacts. Evaluation is performed in `notebooks/05_evaluation.ipynb`, while release-candidate comparison and final validation are recorded in `experiments/final_testing/deployment_candidates.csv`, `experiments/final_testing/final_results.csv`, and `experiments/final_testing/final_results.json`. This forms the selection boundary between experimental weights and deployable models.

#### Export and Model Metadata
Selected models are converted to ONNX for runtime portability via `notebooks/08_model_export.ipynb`. Deployable exports are located at `experiments/exports/bottle/bottle_finetuned.onnx`, `experiments/exports/pcb/pcb_finetuned.onnx`, and `experiments/exports/road/road_resnet18_finetuned.onnx`. `experiments/exports/export_manifest.json` tracks exported artifacts, while `deployment/model_metadata.json` supplies deployment-facing model information.

#### Deployment Runtime
`deployment/api.py` exposes inference operations; `deployment/inference.py` encapsulates model loading, preprocessing, execution, and prediction formatting; `deployment/model_registry.py` resolves available model variants and their metadata/artifact locations. The intended control flow is request/input → API → registry-selected model → inference runtime → structured prediction response. ONNX is the key deployment boundary, separating training-framework checkpoints (`.pt`) from portable inference artifacts (`.onnx`).

#### Infrastructure and External Dependencies
The repository is primarily a local Python ML workflow, with dependencies declared in `requirements.txt` and `pyproject.toml`. It relies on externally sourced Kaggle and Mendeley datasets rather than an in-repo data store. No cloud infrastructure, database, message broker, or frontend is represented in the tree; artifact files and JSON/CSV manifests serve as the project’s persistence and model-governance layer.

Main entry points: [`experiments/bottle/baseline/baseline/weights/best.pt`](https://github.com/garvitjoshi1/inspectra/blob/main/experiments/bottle/baseline/baseline/weights/best.pt) (Training checkpoints), [`notebooks/08_model_export.ipynb`](https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/08_model_export.ipynb) (ONNX export), [`deployment/model_registry.py`](https://github.com/garvitjoshi1/inspectra/blob/main/deployment/model_registry.py) (Model registry), [`deployment/inference.py`](https://github.com/garvitjoshi1/inspectra/blob/main/deployment/inference.py) (Inference runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiments["Experiment workflow"]
  node_datasets[("Public inspection datasets<br/>external datasets")]
  node_inspection["Dataset inspection<br/>notebook"]
  node_cleaning["Data cleaning<br/>notebook"]
  node_preparation["Data preparation<br/>notebook"]
  node_baseline_training["Baseline training<br/>notebook"]
  node_fine_tuning["Fine-tuning<br/>notebook"]
  node_evaluation["Evaluation<br/>notebook"]
  node_model_export["ONNX export<br/>notebook"]
end

subgraph group_artifacts["Model governance"]
  node_cleaning_report["Cleaning report<br/>JSON report"]
  node_checkpoints["Training checkpoints<br/>PyTorch artifacts<br/>[best.pt]"]
  node_release_results["Release validation results<br/>CSV/JSON results<br/>[final_results.json]"]
  node_onnx_models["Deployable ONNX models<br/>ONNX artifacts"]
  node_export_manifest["Export manifest<br/>JSON manifest"]
end

subgraph group_runtime["Local deployment"]
  node_metadata["Deployment metadata<br/>JSON metadata"]
  node_api{{"Inference API<br/>Python service<br/>[api.py]"}}
  node_registry["Model registry<br/>Python module<br/>[model_registry.py]"]
  node_inference["Inference runtime<br/>Python module<br/>[inference.py]"]
  node_response["Structured prediction<br/>API response"]
end

node_datasets -->|"inspect"| node_inspection
node_inspection -->|"inform"| node_cleaning
node_cleaning -->|"persist"| node_cleaning_report
node_cleaning_report -->|"quality boundary"| node_preparation
node_preparation -->|"prepared data"| node_baseline_training
node_baseline_training -->|"produce baselines"| node_checkpoints
node_checkpoints -->|"initialize"| node_fine_tuning
node_fine_tuning -->|"produce tuned weights"| node_checkpoints
node_checkpoints -->|"evaluate"| node_evaluation
node_evaluation -->|"record results"| node_release_results
node_release_results -->|"select candidates"| node_model_export
node_checkpoints -->|"selected weights"| node_model_export
node_model_export -->|"convert"| node_onnx_models
node_model_export -->|"record exports"| node_export_manifest
node_export_manifest -->|"deployment inventory"| node_metadata
node_api -->|"resolve variant"| node_registry
node_registry -->|"read metadata"| node_metadata
node_registry -->|"locate artifact"| node_onnx_models
node_api -->|"submit input"| node_inference
node_inference -->|"load and execute"| node_onnx_models
node_inference -->|"format prediction"| node_response

click node_inspection "https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/01_dataset_inspection.ipynb"
click node_cleaning "https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/02_data_cleaning.ipynb"
click node_cleaning_report "https://github.com/garvitjoshi1/inspectra/blob/main/reports/dataset_cleaning_report.json"
click node_preparation "https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/03_data_preparation.ipynb"
click node_baseline_training "https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/04_baseline_training.ipynb"
click node_fine_tuning "https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/06_fine_tuning.ipynb"
click node_checkpoints "https://github.com/garvitjoshi1/inspectra/blob/main/experiments/bottle/baseline/baseline/weights/best.pt"
click node_evaluation "https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/05_evaluation.ipynb"
click node_release_results "https://github.com/garvitjoshi1/inspectra/blob/main/experiments/final_testing/final_results.json"
click node_model_export "https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/08_model_export.ipynb"
click node_onnx_models "https://github.com/garvitjoshi1/inspectra/blob/main/experiments/exports/bottle/bottle_finetuned.onnx"
click node_export_manifest "https://github.com/garvitjoshi1/inspectra/blob/main/experiments/exports/export_manifest.json"
click node_metadata "https://github.com/garvitjoshi1/inspectra/blob/main/deployment/model_metadata.json"
click node_api "https://github.com/garvitjoshi1/inspectra/blob/main/deployment/api.py"
click node_registry "https://github.com/garvitjoshi1/inspectra/blob/main/deployment/model_registry.py"
click node_inference "https://github.com/garvitjoshi1/inspectra/blob/main/deployment/inference.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_datasets,node_inspection,node_cleaning,node_preparation,node_baseline_training,node_fine_tuning,node_evaluation,node_model_export toneBlue
class node_cleaning_report,node_checkpoints,node_release_results,node_onnx_models,node_export_manifest toneAmber
class node_metadata,node_api,node_registry,node_inference,node_response toneMint
```

## Components

### Experiment workflow

- **Public inspection datasets**: external datasets · Kaggle and Mendeley sourced defect datasets.
- [Dataset inspection](https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/01_dataset_inspection.ipynb): notebook · `notebooks/01_dataset_inspection.ipynb`
- [Data cleaning](https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/02_data_cleaning.ipynb): notebook · `notebooks/02_data_cleaning.ipynb`
- [Data preparation](https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/03_data_preparation.ipynb): notebook · `notebooks/03_data_preparation.ipynb`
- [Baseline training](https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/04_baseline_training.ipynb): notebook · `notebooks/04_baseline_training.ipynb`
- [Fine-tuning](https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/06_fine_tuning.ipynb): notebook · `notebooks/06_fine_tuning.ipynb`
- [Evaluation](https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/05_evaluation.ipynb): notebook · `notebooks/05_evaluation.ipynb`
- [ONNX export](https://github.com/garvitjoshi1/inspectra/blob/main/notebooks/08_model_export.ipynb): notebook · `notebooks/08_model_export.ipynb`

### Model governance

- [Cleaning report](https://github.com/garvitjoshi1/inspectra/blob/main/reports/dataset_cleaning_report.json): JSON report · Persisted quality boundary for downstream work. · `reports/dataset_cleaning_report.json`
- [Training checkpoints](https://github.com/garvitjoshi1/inspectra/blob/main/experiments/bottle/baseline/baseline/weights/best.pt): PyTorch artifacts · Detection and ResNet-18 baseline and tuned weights. · `experiments/bottle/baseline/baseline/weights/best.pt`
- [Release validation results](https://github.com/garvitjoshi1/inspectra/blob/main/experiments/final_testing/final_results.json): CSV/JSON results · Compares deployment candidates and records final validation. · `experiments/final_testing/final_results.json`
- [Deployable ONNX models](https://github.com/garvitjoshi1/inspectra/blob/main/experiments/exports/bottle/bottle_finetuned.onnx): ONNX artifacts · Portable bottle, PCB, and road model exports. · `experiments/exports/bottle/bottle_finetuned.onnx`
- [Export manifest](https://github.com/garvitjoshi1/inspectra/blob/main/experiments/exports/export_manifest.json): JSON manifest · `experiments/exports/export_manifest.json`

### Local deployment

- [Deployment metadata](https://github.com/garvitjoshi1/inspectra/blob/main/deployment/model_metadata.json): JSON metadata · `deployment/model_metadata.json`
- [Inference API](https://github.com/garvitjoshi1/inspectra/blob/main/deployment/api.py): Python service · Executable local serving surface. · `deployment/api.py`
- [Model registry](https://github.com/garvitjoshi1/inspectra/blob/main/deployment/model_registry.py): Python module · Resolves model variants, metadata, and artifact locations. · `deployment/model_registry.py`
- [Inference runtime](https://github.com/garvitjoshi1/inspectra/blob/main/deployment/inference.py): Python module · Loads ONNX models, preprocesses inputs, executes inference, and formats predictions. · `deployment/inference.py`
- **Structured prediction**: API response

## Connections

- Public inspection datasets → Dataset inspection: inspect
- Dataset inspection → Data cleaning: inform
- Data cleaning → Cleaning report: persist
- Cleaning report → Data preparation: quality boundary
- Data preparation → Baseline training: prepared data
- Baseline training → Training checkpoints: produce baselines
- Training checkpoints → Fine-tuning: initialize
- Fine-tuning → Training checkpoints: produce tuned weights
- Training checkpoints → Evaluation: evaluate
- Evaluation → Release validation results: record results
- Release validation results → ONNX export: select candidates
- Training checkpoints → ONNX export: selected weights
- ONNX export → Deployable ONNX models: convert
- ONNX export → Export manifest: record exports
- Export manifest → Deployment metadata: deployment inventory
- Inference API → Model registry: resolve variant
- Model registry → Deployment metadata: read metadata
- Model registry → Deployable ONNX models: locate artifact
- Inference API → Inference runtime: submit input
- Inference runtime → Deployable ONNX models: load and execute
- Inference runtime → Structured prediction: format prediction