# gismal/to-ai-or-not-to-ai architecture

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

- Interactive diagram: https://gitdiagram.com/gismal/to-ai-or-not-to-ai
- Repository: https://github.com/gismal/to-ai-or-not-to-ai

## Overview

This is an image-origin detection product: browser or API clients submit images and receive a five-label confidence-aware prediction, optionally with a GradCAM heatmap. The principal flow validates uploads, checks the prediction cache, runs ONNX inference, classifies confidence, and logs results. Separate branches cover feedback and human labeling, drift-triggered retraining, browser-extension use, and monitoring. Training and some extension wiring are represented from the README and tree; their implementation details were not sampled, so those links are documented or marked unverified.

Main entry points: [`src/api/inference_routes.py`](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/inference_routes.py) (Inference routes), [`src/main.py`](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/main.py) (FastAPI application), [`src/services/inference_service.py`](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/inference_service.py) (Inference orchestration), [`extension/popup.js`](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/popup.js) (Analysis popup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and inference"]
  node_api_routes["Inference routes"]
  node_validation["Image validation"]
  node_inference["Inference orchestration"]
  node_onnx["ONNX predictor<br/>[inference.py]"]
  node_cache["pHash cache<br/>[cache_service.py]"]
  node_explain["GradCAM explainability"]
  node_api_app["FastAPI application<br/>[main.py]"]
end

subgraph group_data["Data and feedback"]
  node_feedback_routes["Feedback routes<br/>[feedback_routes.py]"]
  node_feedback_service["Feedback handling"]
  node_prediction_logs["Prediction logs"]
  node_feedback_repo["Feedback repository<br/>[feedback_repo.py]"]
  node_postgres[("PostgreSQL data<br/>[database.py]")]
end

subgraph group_mlops["MLOps and monitoring"]
  node_admin_routes["Admin and review routes<br/>[admin_routes.py]"]
  node_retrain_service["Drift detection<br/>[retrain_service.py]"]
  node_worker["Retraining worker<br/>[tasks.py]"]
  node_training["Model training<br/>[train.py]"]
  node_dataset["Dataset preparation<br/>[prepare_dataset.py]"]
  node_metrics["Prometheus metrics<br/>[metrics.py]"]
  node_monitoring["Grafana dashboard"]
end

subgraph group_browser["Browser extension"]
  node_page_scan["Passive page scanning<br/>[content.js]"]
  node_context_menu["Image context menu<br/>[background.js]"]
  node_popup["Analysis popup<br/>[popup.js]"]
  node_extension_results["Result view<br/>[results.js]"]
end

node_client(("Image user"))
node_extension_user(("Website visitor"))

node_client -.->|"submits image"| node_api_app
node_api_app -->|"registers routes"| node_api_routes
node_api_routes -->|"validates upload"| node_validation
node_api_routes -->|"requests prediction"| node_inference
node_inference -->|"checks cache"| node_cache
node_inference -->|"runs inference"| node_onnx
node_api_routes -->|"requests heatmap"| node_explain
node_api_routes -->|"logs predictions"| node_prediction_logs
node_api_routes -->|"registers routes"| node_feedback_routes
node_feedback_routes -->|"submits feedback"| node_feedback_service
node_feedback_service -->|"stores feedback"| node_feedback_repo
node_prediction_logs -.->|"writes logs"| node_postgres
node_feedback_repo -.->|"persists feedback"| node_postgres
node_api_app -->|"registers routes"| node_admin_routes
node_admin_routes -->|"checks drift"| node_retrain_service
node_retrain_service -->|"enqueues retraining"| node_worker
node_worker -.->|"runs training"| node_training
node_dataset -.->|"prepares training data"| node_training
node_api_app -.->|"exposes metrics"| node_metrics
node_metrics -.->|"feeds dashboards"| node_monitoring
node_extension_user -.->|"browses page"| node_page_scan
node_extension_user -.->|"selects image"| node_context_menu
node_page_scan -.->|"requests analysis"| node_api_app
node_context_menu -.->|"opens analysis"| node_popup
node_popup -.->|"requests analysis"| node_api_app
node_popup -.->|"shows results"| node_extension_results

click node_api_routes "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/inference_routes.py"
click node_validation "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/inference_routes.py"
click node_inference "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/inference_service.py"
click node_onnx "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/inference.py"
click node_cache "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/cache_service.py"
click node_explain "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/explainability_service.py"
click node_api_app "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/main.py"
click node_feedback_routes "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/feedback_routes.py"
click node_feedback_service "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/feedback_service.py"
click node_prediction_logs "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/repositories/prediction_log_repository.py"
click node_feedback_repo "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/repositories/feedback_repo.py"
click node_postgres "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/infra/database.py"
click node_admin_routes "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/admin_routes.py"
click node_retrain_service "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/retrain_service.py"
click node_worker "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/worker/tasks.py"
click node_training "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/scripts/train.py"
click node_dataset "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/scripts/prepare_dataset.py"
click node_metrics "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/infra/metrics.py"
click node_page_scan "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/content.js"
click node_context_menu "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/background.js"
click node_popup "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/popup.js"
click node_extension_results "https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/results.js"

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_api_routes,node_validation,node_inference,node_onnx,node_cache,node_explain,node_api_app,node_client toneBlue
class node_feedback_routes,node_feedback_service,node_prediction_logs,node_feedback_repo,node_postgres toneAmber
class node_admin_routes,node_retrain_service,node_worker,node_training,node_dataset,node_metrics,node_monitoring toneMint
class node_page_scan,node_context_menu,node_popup,node_extension_results toneRose
class node_extension_user toneIndigo
```

## Components

### API and inference

- [Inference routes](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/inference_routes.py): `src/api/inference_routes.py`
- [Image validation](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/inference_routes.py): `src/api/inference_routes.py`
- [Inference orchestration](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/inference_service.py): `src/services/inference_service.py`
- [ONNX predictor](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/inference.py): `src/inference.py`
- [pHash cache](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/cache_service.py): `src/services/cache_service.py`
- [GradCAM explainability](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/explainability_service.py): `src/services/explainability_service.py`
- [FastAPI application](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/main.py): `src/main.py`

### Data and feedback

- [Feedback routes](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/feedback_routes.py): `src/api/feedback_routes.py`
- [Feedback handling](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/feedback_service.py): `src/services/feedback_service.py`
- [Prediction logs](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/repositories/prediction_log_repository.py): `src/repositories/prediction_log_repository.py`
- [Feedback repository](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/repositories/feedback_repo.py): `src/repositories/feedback_repo.py`
- [PostgreSQL data](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/infra/database.py): `src/infra/database.py`

### MLOps and monitoring

- [Admin and review routes](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/api/admin_routes.py): `src/api/admin_routes.py`
- [Drift detection](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/services/retrain_service.py): `src/services/retrain_service.py`
- [Retraining worker](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/worker/tasks.py): `src/worker/tasks.py`
- [Model training](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/scripts/train.py): `scripts/train.py`
- [Dataset preparation](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/scripts/prepare_dataset.py): `scripts/prepare_dataset.py`
- [Prometheus metrics](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/src/infra/metrics.py): `src/infra/metrics.py`
- **Grafana dashboard**

### Browser extension

- [Passive page scanning](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/content.js): `extension/content.js`
- [Image context menu](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/background.js): `extension/background.js`
- [Analysis popup](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/popup.js): `extension/popup.js`
- [Result view](https://github.com/gismal/to-ai-or-not-to-ai/blob/main/extension/results.js): `extension/results.js`

### Other components

- **Image user**
- **Website visitor**

## Connections

- Image user → FastAPI application: submits image
- FastAPI application → Inference routes: registers routes (evidence: `src/main.py`)
- Inference routes → Image validation: validates upload (evidence: `src/api/inference_routes.py`)
- Inference routes → Inference orchestration: requests prediction (evidence: `src/api/inference_routes.py`)
- Inference orchestration → pHash cache: checks cache (evidence: `src/services/inference_service.py`)
- Inference orchestration → ONNX predictor: runs inference (evidence: `src/services/inference_service.py`)
- Inference routes → GradCAM explainability: requests heatmap (evidence: `src/api/inference_routes.py`)
- Inference routes → Prediction logs: logs predictions (evidence: `src/api/inference_routes.py`)
- Inference routes → Feedback routes: registers routes (evidence: `src/main.py`)
- Feedback routes → Feedback handling: submits feedback (evidence: `src/api/feedback_routes.py`)
- Feedback handling → Feedback repository: stores feedback (evidence: `src/services/feedback_service.py`)
- Prediction logs → PostgreSQL data: writes logs
- Feedback repository → PostgreSQL data: persists feedback
- FastAPI application → Admin and review routes: registers routes (evidence: `src/main.py`)
- Admin and review routes → Drift detection: checks drift (evidence: `src/api/admin_routes.py`)
- Drift detection → Retraining worker: enqueues retraining (evidence: `src/services/retrain_service.py`)
- Retraining worker → Model training: runs training
- Dataset preparation → Model training: prepares training data
- FastAPI application → Prometheus metrics: exposes metrics
- Prometheus metrics → Grafana dashboard: feeds dashboards
- Website visitor → Passive page scanning: browses page
- Website visitor → Image context menu: selects image
- Passive page scanning → FastAPI application: requests analysis
- Image context menu → Analysis popup: opens analysis
- Analysis popup → FastAPI application: requests analysis
- Analysis popup → Result view: shows results
