# shiv2077/retina architecture

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

- Interactive diagram: https://gitdiagram.com/shiv2077/retina
- Repository: https://github.com/shiv2077/retina

## Overview

RETINA is an industrial image-inspection service. An operator or production line submits an image, optionally declaring its product; the API stores it and queues work, and the worker routes it through product identification when needed, PatchCore scoring, and conditional VLM refinement. Results and uncertain cases are surfaced for operator labeling, whose examples can inform later refinements. The README documents these stages; sampled worker and API excerpts support the orchestration and persistence links. Other research model implementations in the tree are not shown as part of this documented production workflow.

Main entry points: [`worker/src/retina_worker/worker.py`](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/worker.py) (Job orchestrator), [`frontend/src/lib/api.ts`](https://github.com/shiv2077/retina/blob/main/frontend/src/lib/api.ts) (API client), [`api/main.py`](https://github.com/shiv2077/retina/blob/main/api/main.py) (Submission and label API), [`frontend/src/app/submit/page.tsx`](https://github.com/shiv2077/retina/blob/main/frontend/src/app/submit/page.tsx) (Submit image)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operator interface"]
  node_submit_page["Submit image<br/>[page.tsx]"]
  node_results_page["View results<br/>[page.tsx]"]
  node_label_page["Label samples<br/>[page.tsx]"]
  node_performance_page["Model performance<br/>[page.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_service["Submission and feedback API"]
  node_api["Submission and label API<br/>[main.py]"]
  node_image_store[("Content-addressed images<br/>[main.py]")]
end

subgraph group_inference["Inference pipeline"]
  node_worker["Job orchestrator<br/>[worker.py]"]
  node_product_id["Product identification<br/>[vlm_router.py]"]
  node_registry["PatchCore registry"]
  node_patchcore["PatchCore scoring<br/>[worker.py]"]
  node_stage2["Stage 2 refiner<br/>[vlm_router.py]"]
  node_describe["Defect description<br/>[vlm_router.py]"]
  node_zero_shot["Zero-shot fallback<br/>[vlm_router.py]"]
end

subgraph group_state["Job and label state"]
  node_redis[("Redis streams and hashes")]
  node_redis_client["Redis access<br/>[redis_client.py]"]
end

node_operator(("Operator / line"))
node_openai["OpenAI models"]

node_operator -->|"submits image"| node_submit_page
node_operator -->|"checks result"| node_results_page
node_operator -->|"labels sample"| node_label_page
node_submit_page -->|"sends submission"| node_api_client
node_results_page -->|"polls result"| node_api_client
node_label_page -->|"fetches / submits labels"| node_api_client
node_performance_page -.->|"requests metrics"| node_api_client
node_api_client -->|"calls endpoints"| node_api
node_api -->|"writes / serves bytes"| node_image_store
node_api -->|"queues jobs; reads and writes state"| node_redis
node_worker -->|"consumes jobs; persists outcomes"| node_redis_client
node_redis_client -->|"reads / writes"| node_redis
node_worker -->|"loads image bytes"| node_image_store
node_worker -->|"identifies when class absent"| node_product_id
node_worker -->|"loads category model"| node_registry
node_registry -->|"provides model"| node_patchcore
node_worker -->|"scores image"| node_patchcore
node_worker -->|"refines score-band cases"| node_stage2
node_worker -->|"describes confirmed anomalies"| node_describe
node_worker -->|"handles missing checkpoint"| node_zero_shot
node_product_id -.->|"calls model"| node_openai
node_stage2 -.->|"calls model"| node_openai
node_describe -.->|"calls model"| node_openai
node_zero_shot -.->|"calls model"| node_openai

click node_submit_page "https://github.com/shiv2077/retina/blob/main/frontend/src/app/submit/page.tsx"
click node_results_page "https://github.com/shiv2077/retina/blob/main/frontend/src/app/results/page.tsx"
click node_label_page "https://github.com/shiv2077/retina/blob/main/frontend/src/app/label/page.tsx"
click node_performance_page "https://github.com/shiv2077/retina/blob/main/frontend/src/app/model-performance/page.tsx"
click node_api_client "https://github.com/shiv2077/retina/blob/main/frontend/src/lib/api.ts"
click node_api "https://github.com/shiv2077/retina/blob/main/api/main.py"
click node_image_store "https://github.com/shiv2077/retina/blob/main/api/main.py"
click node_worker "https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/worker.py"
click node_product_id "https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/vlm_router.py"
click node_registry "https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/patchcore_registry.py"
click node_patchcore "https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/worker.py"
click node_stage2 "https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/vlm_router.py"
click node_describe "https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/vlm_router.py"
click node_zero_shot "https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/vlm_router.py"
click node_redis_client "https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/redis_client.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_submit_page,node_results_page,node_label_page,node_performance_page,node_api_client toneBlue
class node_api,node_image_store toneAmber
class node_worker,node_product_id,node_registry,node_patchcore,node_stage2,node_describe,node_zero_shot toneMint
class node_redis,node_redis_client toneRose
class node_operator,node_openai toneIndigo
```

## Components

### Operator interface

- [Submit image](https://github.com/shiv2077/retina/blob/main/frontend/src/app/submit/page.tsx): `frontend/src/app/submit/page.tsx`
- [View results](https://github.com/shiv2077/retina/blob/main/frontend/src/app/results/page.tsx): `frontend/src/app/results/page.tsx`
- [Label samples](https://github.com/shiv2077/retina/blob/main/frontend/src/app/label/page.tsx): `frontend/src/app/label/page.tsx`
- [Model performance](https://github.com/shiv2077/retina/blob/main/frontend/src/app/model-performance/page.tsx): `frontend/src/app/model-performance/page.tsx`
- [API client](https://github.com/shiv2077/retina/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Submission and feedback API

- [Submission and label API](https://github.com/shiv2077/retina/blob/main/api/main.py): `api/main.py`
- [Content-addressed images](https://github.com/shiv2077/retina/blob/main/api/main.py): `api/main.py`

### Inference pipeline

- [Job orchestrator](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/worker.py): `worker/src/retina_worker/worker.py`
- [Product identification](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/vlm_router.py): `worker/src/retina_worker/models/vlm_router.py`
- [PatchCore registry](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/patchcore_registry.py): `worker/src/retina_worker/models/patchcore_registry.py`
- [PatchCore scoring](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/worker.py): `worker/src/retina_worker/worker.py`
- [Stage 2 refiner](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/vlm_router.py): `worker/src/retina_worker/models/vlm_router.py`
- [Defect description](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/vlm_router.py): `worker/src/retina_worker/models/vlm_router.py`
- [Zero-shot fallback](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/models/vlm_router.py): `worker/src/retina_worker/models/vlm_router.py`

### Job and label state

- **Redis streams and hashes**
- [Redis access](https://github.com/shiv2077/retina/blob/main/worker/src/retina_worker/redis_client.py): `worker/src/retina_worker/redis_client.py`

### Other components

- **Operator / line**
- **OpenAI models**

## Connections

- Operator / line → Submit image: submits image
- Operator / line → View results: checks result
- Operator / line → Label samples: labels sample
- Submit image → API client: sends submission
- View results → API client: polls result
- Label samples → API client: fetches / submits labels
- Model performance → API client: requests metrics
- API client → Submission and label API: calls endpoints
- Submission and label API → Content-addressed images: writes / serves bytes
- Submission and label API → Redis streams and hashes: queues jobs; reads and writes state
- Job orchestrator → Redis access: consumes jobs; persists outcomes
- Redis access → Redis streams and hashes: reads / writes
- Job orchestrator → Content-addressed images: loads image bytes
- Job orchestrator → Product identification: identifies when class absent
- Job orchestrator → PatchCore registry: loads category model
- PatchCore registry → PatchCore scoring: provides model
- Job orchestrator → PatchCore scoring: scores image
- Job orchestrator → Stage 2 refiner: refines score-band cases
- Job orchestrator → Defect description: describes confirmed anomalies
- Job orchestrator → Zero-shot fallback: handles missing checkpoint
- Product identification → OpenAI models: calls model
- Stage 2 refiner → OpenAI models: calls model
- Defect description → OpenAI models: calls model
- Zero-shot fallback → OpenAI models: calls model