# vikhram-s/visual-quality-inspector architecture

> Architecture diagram of the GitHub repository vikhram-s/visual-quality-inspector, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vikhram-s/visual-quality-inspector
- Repository: https://github.com/vikhram-s/visual-quality-inspector

## Overview

This is a full-stack image quality and defect inspection system. A user uploads an image through the React interface; the FastAPI service validates and stores it, invokes feature extraction and ML inference, then returns a score, defect explanations, and a spatial heatmap. Results are persisted for paginated history, individual retrieval, and image access. The repository also includes dataset generation, model training, and synthetic/real-holdout evaluation. Runtime relationships are grounded in the excerpts and README; some model-development wiring is only partially evidenced.

Main entry points: [`backend/main.py`](https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/main.py) (REST API), [`frontend/src/App.jsx`](https://github.com/vikhram-s/visual-quality-inspector/blob/main/frontend/src/App.jsx) (Inspection UI), [`backend/ml_engine.py`](https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/ml_engine.py) (ML inference), [`ml/train.py`](https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/train.py) (Model training)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Inspection interface"]
  node_ui["Inspection UI<br/>[App.jsx]"]
end

subgraph group_service["Analysis service"]
  node_api["REST API<br/>[main.py]"]
  node_contracts["API schemas<br/>[schemas.py]"]
end

subgraph group_vision["Vision and inference"]
  node_engine["ML inference<br/>[ml_engine.py]"]
  node_features["Feature extraction"]
  node_heatmap["Spatial heatmap"]
  node_model["Inference model<br/>[model.joblib]"]
end

subgraph group_records["Result persistence"]
  node_dbconfig["Database session<br/>[database.py]"]
  node_recordsmodel["Analysis record<br/>[models.py]"]
  node_database[("Analysis database")]
  node_uploads[("Uploaded images")]
end

subgraph group_modeldev["Model development"]
  node_generator["Dataset generation"]
  node_training["Model training<br/>[train.py]"]
  node_evaluation["Model evaluation<br/>[evaluate.py]"]
end

node_user(("Inspector"))

node_user -->|"uploads image"| node_ui
node_ui -->|"sends REST request"| node_api
node_api -->|"validates responses"| node_contracts
node_api -->|"invokes analysis"| node_engine
node_engine -->|"extracts features"| node_features
node_engine -->|"loads classifiers"| node_model
node_api -->|"generates heatmap"| node_heatmap
node_api -->|"writes image"| node_uploads
node_api -->|"gets database session"| node_dbconfig
node_recordsmodel -->|"uses ORM base"| node_dbconfig
node_api -->|"creates and queries records"| node_recordsmodel
node_dbconfig -->|"connects to SQLite"| node_database
node_ui -->|"requests history"| node_api
node_generator -.->|"supplies datasets"| node_training
node_training -->|"extracts training features"| node_features
node_training -->|"saves backend artifact"| node_model
node_evaluation -->|"extracts evaluation features"| node_features
node_evaluation -->|"evaluates classifiers"| node_model

click node_ui "https://github.com/vikhram-s/visual-quality-inspector/blob/main/frontend/src/App.jsx"
click node_api "https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/main.py"
click node_contracts "https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/schemas.py"
click node_engine "https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/ml_engine.py"
click node_features "https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/feature_extractor.py"
click node_heatmap "https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/feature_extractor.py"
click node_model "https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/model.joblib"
click node_dbconfig "https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/database.py"
click node_recordsmodel "https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/models.py"
click node_uploads "https://github.com/vikhram-s/visual-quality-inspector/tree/main/backend/uploads"
click node_generator "https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/generate_dataset.py"
click node_training "https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/train.py"
click node_evaluation "https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/evaluate.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_ui toneBlue
class node_api,node_contracts toneAmber
class node_engine,node_features,node_heatmap,node_model toneMint
class node_dbconfig,node_recordsmodel,node_database,node_uploads toneRose
class node_generator,node_training,node_evaluation,node_user toneIndigo
```

## Components

### Inspection interface

- [Inspection UI](https://github.com/vikhram-s/visual-quality-inspector/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Analysis service

- [REST API](https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/main.py): `backend/main.py`
- [API schemas](https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/schemas.py): `backend/schemas.py`

### Vision and inference

- [ML inference](https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/ml_engine.py): `backend/ml_engine.py`
- [Feature extraction](https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/feature_extractor.py): `ml/feature_extractor.py`
- [Spatial heatmap](https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/feature_extractor.py): `ml/feature_extractor.py`
- [Inference model](https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/model.joblib): `backend/model.joblib`

### Result persistence

- [Database session](https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/database.py): `backend/database.py`
- [Analysis record](https://github.com/vikhram-s/visual-quality-inspector/blob/main/backend/models.py): `backend/models.py`
- **Analysis database**
- [Uploaded images](https://github.com/vikhram-s/visual-quality-inspector/tree/main/backend/uploads): `backend/uploads`

### Model development

- [Dataset generation](https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/generate_dataset.py): `ml/generate_dataset.py`
- [Model training](https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/train.py): `ml/train.py`
- [Model evaluation](https://github.com/vikhram-s/visual-quality-inspector/blob/main/ml/evaluate.py): `ml/evaluate.py`

### Other components

- **Inspector**

## Connections

- Inspector → Inspection UI: uploads image (evidence: `README.md`)
- Inspection UI → REST API: sends REST request (evidence: `README.md`)
- REST API → API schemas: validates responses (evidence: `backend/main.py`)
- REST API → ML inference: invokes analysis (evidence: `backend/main.py`)
- ML inference → Feature extraction: extracts features (evidence: `backend/ml_engine.py`)
- ML inference → Inference model: loads classifiers (evidence: `backend/ml_engine.py`)
- REST API → Spatial heatmap: generates heatmap (evidence: `backend/main.py`)
- REST API → Uploaded images: writes image (evidence: `backend/main.py`)
- REST API → Database session: gets database session (evidence: `backend/main.py`)
- Analysis record → Database session: uses ORM base (evidence: `backend/models.py`)
- REST API → Analysis record: creates and queries records (evidence: `backend/main.py`)
- Database session → Analysis database: connects to SQLite (evidence: `README.md`)
- Inspection UI → REST API: requests history (evidence: `README.md`)
- Dataset generation → Model training: supplies datasets
- Model training → Feature extraction: extracts training features (evidence: `ml/train.py`)
- Model training → Inference model: saves backend artifact (evidence: `ml/train.py`)
- Model evaluation → Feature extraction: extracts evaluation features (evidence: `ml/evaluate.py`)
- Model evaluation → Inference model: evaluates classifiers (evidence: `ml/evaluate.py`)
