# mohanramasamy2005-eng/ai-pcba-board-detection architecture

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

- Interactive diagram: https://gitdiagram.com/mohanramasamy2005-eng/ai-pcba-board-detection
- Repository: https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection

## Overview

#### Purpose and entry points
This repository is an electronic-component/PCBA visual-inspection system built around YOLOv8 object detection. It supports interactive webcam inference, HTTP image prediction, model training, PostgreSQL detection logging, and a Streamlit monitoring view.

Primary launch points are:
- Webcam detector: `app/main.py`
- FastAPI service: `app/api.py`
- Training workflow: `train.py`
- Monitoring UI: `dashboard.py`

#### Model assets and inference boundary
YOLOv8 is the central ML runtime. The repository includes a PyTorch base/model artifact and an ONNX artifact:
- `yolov8n.pt`
- `yolov8n.onnx`
- `models/.gitkeep`

Inference-facing applications are expected to load an exported ONNX model (the README describes `models/best.onnx` as the trained output). ONNX forms the portability/efficient-inference boundary; PyTorch/Ultralytics is used for training and potentially local model handling.

#### Real-time inspection path
`app/main.py` is the local operational path for live quality inspection. It captures frames from a webcam through OpenCV, runs detector inference, and presents detections in real time. This path is intended for operator-facing manufacturing inspection rather than serving HTTP clients.

Relevant path:
- `app/main.py`

#### REST prediction service
`app/api.py` exposes the FastAPI application, with `POST /predict` accepting an uploaded image. The API boundary converts multipart image input into model inference results suitable for integration with external manufacturing or quality-control systems.

Relevant path:
- `app/api.py`

The service is run with Uvicorn (`uvicorn app.api:app`), binding application logic to an ASGI server/runtime.

#### Training and dataset contract
`train.py` drives YOLOv8 detector training. Dataset layout, split locations, class count, and labels are defined by:
- `train.py`
- `data/data.yaml`

The documented detection taxonomy has five classes: `OK`, `Missing_Part`, `Scratch`, `Bent_Pin`, and `Soldering_Issue`. Training outputs are expected to be exported for deployment, notably as ONNX artifacts consumed by inference paths.

#### Detection persistence and monitoring
Detection events are persisted to PostgreSQL through:
- `log.py`

The expected record contract is timestamp, detected class, and confidence score. `dashboard.py` is a Streamlit application that reads these stored detection records and presents a live-updating monitoring table:
- `dashboard.py`
- `log.py`

This creates a separate observability path: detector/API inference → PostgreSQL log records → Streamlit dashboard.

#### Deployment and infrastructure
The runtime is containerized by:
- `Dockerfile`

Cloud deployment guidance targets Google Cloud Run:
- `gcp_deploy.md`

Material external dependencies are Ultralytics YOLOv8, OpenCV, FastAPI/Uvicorn, PostgreSQL, Streamlit, Docker, and Google Cloud Run. Python dependency resolution is defined in `requirements.txt`.

Main entry points: [`app/api.py`](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/app/api.py) (Prediction API), [`train.py`](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/train.py) (Training workflow), [`log.py`](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/log.py) (Detection logger), [`app/main.py`](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/app/main.py) (Live webcam inspection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ml["ML lifecycle"]
  node_dataset["Dataset contract<br/>YOLO dataset config<br/>[data.yaml]"]
  node_trainer["Training workflow<br/>YOLOv8 trainer<br/>[train.py]"]
  node_pytorch_model["PyTorch base model<br/>YOLOv8 weights<br/>[yolov8n.pt]"]
  node_onnx_model["ONNX inference model<br/>portable model artifact<br/>[yolov8n.onnx]"]
end

subgraph group_inference["Inspection interfaces"]
  node_yolo{{"YOLOv8 runtime<br/>Ultralytics inference"}}
  node_webcam_app["Live webcam inspection<br/>OpenCV operator app<br/>[main.py]"]
  node_api["Prediction API<br/>FastAPI service<br/>[api.py]"]
  node_uvicorn{{"ASGI server<br/>Uvicorn runtime"}}
  node_integration_client(("External QC systems<br/>HTTP client"))
end

subgraph group_monitoring["Observability"]
  node_detection_log["Detection logger<br/>persistence adapter<br/>[log.py]"]
  node_postgres[("Detection records<br/>PostgreSQL")]
  node_dashboard["Monitoring dashboard<br/>Streamlit app<br/>[dashboard.py]"]
end

subgraph group_deployment["Deployment"]
  node_container["Container image<br/>Docker build"]
  node_cloud_run{{"Cloud Run<br/>managed deployment target<br/>[gcp_deploy.md]"}}
end

node_dataset -->|"defines training data"| node_trainer
node_pytorch_model -->|"initializes"| node_trainer
node_trainer -->|"exports"| node_onnx_model
node_onnx_model -->|"loaded for inference"| node_yolo
node_webcam_app -->|"submits camera frames"| node_yolo
node_uvicorn -->|"serves"| node_api
node_integration_client -->|"POST /predict image"| node_api
node_api -->|"runs image inference"| node_yolo
node_webcam_app -->|"logs detections"| node_detection_log
node_api -->|"logs predictions"| node_detection_log
node_detection_log -->|"writes records"| node_postgres
node_dashboard -->|"reads detection records"| node_postgres
node_container -.->|"packages service"| node_api
node_container -->|"deployed to"| node_cloud_run

click node_dataset "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/data/data.yaml"
click node_trainer "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/train.py"
click node_pytorch_model "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/yolov8n.pt"
click node_onnx_model "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/yolov8n.onnx"
click node_webcam_app "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/app/main.py"
click node_api "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/app/api.py"
click node_detection_log "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/log.py"
click node_dashboard "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/dashboard.py"
click node_container "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/Dockerfile"
click node_cloud_run "https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/gcp_deploy.md"

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_dataset,node_trainer,node_pytorch_model,node_onnx_model toneBlue
class node_yolo,node_webcam_app,node_api,node_uvicorn,node_integration_client toneAmber
class node_detection_log,node_postgres,node_dashboard toneMint
class node_container,node_cloud_run toneRose
```

## Components

### ML lifecycle

- [Dataset contract](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/data/data.yaml): YOLO dataset config · Defines splits and five defect classes. · `data/data.yaml`
- [Training workflow](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/train.py): YOLOv8 trainer · `train.py`
- [PyTorch base model](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/yolov8n.pt): YOLOv8 weights · `yolov8n.pt`
- [ONNX inference model](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/yolov8n.onnx): portable model artifact · Trained deployment output is expected as models/best.onnx. · `yolov8n.onnx`

### Inspection interfaces

- **YOLOv8 runtime**: Ultralytics inference
- [Live webcam inspection](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/app/main.py): OpenCV operator app · `app/main.py`
- [Prediction API](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/app/api.py): FastAPI service · Accepts uploaded images at POST /predict. · `app/api.py`
- **ASGI server**: Uvicorn runtime
- **External QC systems**: HTTP client

### Observability

- [Detection logger](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/log.py): persistence adapter · Records timestamp, class, and confidence. · `log.py`
- **Detection records**: PostgreSQL
- [Monitoring dashboard](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/dashboard.py): Streamlit app · Shows live-updating detection records. · `dashboard.py`

### Deployment

- [Container image](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/Dockerfile): Docker build · `Dockerfile`
- [Cloud Run](https://github.com/mohanramasamy2005-eng/ai-pcba-board-detection/blob/main/gcp_deploy.md): managed deployment target · `gcp_deploy.md`

## Connections

- Dataset contract → Training workflow: defines training data
- PyTorch base model → Training workflow: initializes
- Training workflow → ONNX inference model: exports
- ONNX inference model → YOLOv8 runtime: loaded for inference
- Live webcam inspection → YOLOv8 runtime: submits camera frames
- ASGI server → Prediction API: serves
- External QC systems → Prediction API: POST /predict image
- Prediction API → YOLOv8 runtime: runs image inference
- Live webcam inspection → Detection logger: logs detections
- Prediction API → Detection logger: logs predictions
- Detection logger → Detection records: writes records
- Monitoring dashboard → Detection records: reads detection records
- Container image → Prediction API: packages service
- Container image → Cloud Run: deployed to