# mmbarrys/laterite_comparator architecture

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

- Interactive diagram: https://gitdiagram.com/mmbarrys/laterite_comparator
- Repository: https://github.com/mmbarrys/laterite_comparator

## Overview

This is a laterite grade-control comparator: a user captures a material image, the backend matches it against comparator samples, adjusts the ranking using geology, and returns sample details for presentation. The backend’s analysis handler coordinates image decoding, visual matching, candidate selection, and Supabase lookups. The frontend also contains result, history, and settings screens. Their detailed wiring is not established by the available excerpts, so frontend-to-backend links are marked unverified; some AI implementation files are indexed but unsampled.

Main entry points: [`backend/app/main.py`](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/main.py) (Analysis API), [`backend/app/ai/similarity.py`](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/similarity.py) (Visual candidate search), [`frontend/services/analysis.ts`](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/services/analysis.ts) (Analysis client), [`frontend/services/api.ts`](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/services/api.ts) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Capture and navigation"]
  node_camera["Camera capture<br/>[camera-preview.tsx]"]
  node_camera_hook["Camera state<br/>[useCamera.ts]"]
  node_camera_service["Camera operations<br/>[camera.ts]"]
  node_scan_page["Scan screen<br/>[page.tsx]"]
end

subgraph group_presentation["Results and records"]
  node_result_page["Match result<br/>[page.tsx]"]
  node_history_page["Scan history<br/>[page.tsx]"]
  node_settings_page["App settings<br/>[page.tsx]"]
end

subgraph group_analysis["Analysis workflow"]
  node_analysis_page["Analysis screen<br/>[page.tsx]"]
  node_analysis_service["Analysis client<br/>[analysis.ts]"]
  node_api_service["API client<br/>[api.ts]"]
  node_backend["Analysis API<br/>[main.py]"]
  node_request_schema["Analysis request<br/>[schemas.py]"]
  node_image_input["Image decoding<br/>[image_input.py]"]
  node_settings["Runtime settings<br/>[config.py]"]
end

subgraph group_matching["Visual matching"]
  node_similarity["Visual candidate search<br/>[similarity.py]"]
  node_preprocessing["Scan preprocessing<br/>[preprocessing.py]"]
  node_image_features["Image features<br/>[image_features.py]"]
  node_zone_selection["Zone selection<br/>[zone_selection.py]"]
  node_geology_reranking["Geology reranking"]
end

subgraph group_catalog["Sample data"]
  node_supabase_adapter["Supabase REST access<br/>[supabase_rest.py]"]
  node_supabase[("Supabase catalog and storage")]
end

node_user(("Field user"))

node_user -.->|"captures image"| node_camera
node_camera_hook -->|"uses camera operations"| node_camera_service
node_analysis_page -.->|"submits analysis"| node_analysis_service
node_analysis_service -.->|"uses API client"| node_api_service
node_api_service -.->|"sends scan"| node_backend
node_backend -->|"accepts request"| node_request_schema
node_backend -->|"loads settings"| node_settings
node_backend -->|"decodes image"| node_image_input
node_backend -->|"finds candidates"| node_similarity
node_similarity -->|"preprocesses scan"| node_preprocessing
node_similarity -->|"extracts features"| node_image_features
node_backend -->|"selects zone candidate"| node_zone_selection
node_backend -->|"reranks candidates"| node_geology_reranking
node_backend -->|"fetches sample data"| node_supabase_adapter
node_supabase_adapter -->|"reads catalog; signs image URLs"| node_supabase
node_backend -.->|"returns match payload"| node_result_page
node_user -.->|"views prior scans"| node_history_page
node_user -.->|"opens preferences"| node_settings_page

click node_camera "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/components/home/camera-preview.tsx"
click node_camera_hook "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/hooks/useCamera.ts"
click node_camera_service "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/services/camera.ts"
click node_scan_page "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/scan/page.tsx"
click node_analysis_page "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/analysis/page.tsx"
click node_analysis_service "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/services/analysis.ts"
click node_api_service "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/services/api.ts"
click node_backend "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/main.py"
click node_request_schema "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/schemas.py"
click node_image_input "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/image_input.py"
click node_settings "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/config.py"
click node_similarity "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/similarity.py"
click node_preprocessing "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/preprocessing.py"
click node_image_features "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/image_features.py"
click node_zone_selection "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/zone_selection.py"
click node_geology_reranking "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/geology_reranking.py"
click node_supabase_adapter "https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/supabase_rest.py"
click node_result_page "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/result/page.tsx"
click node_history_page "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/history/page.tsx"
click node_settings_page "https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/settings/page.tsx"

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_camera,node_camera_hook,node_camera_service,node_scan_page,node_user toneBlue
class node_result_page,node_history_page,node_settings_page toneAmber
class node_analysis_page,node_analysis_service,node_api_service,node_backend,node_request_schema,node_image_input,node_settings toneMint
class node_similarity,node_preprocessing,node_image_features,node_zone_selection,node_geology_reranking toneRose
class node_supabase_adapter,node_supabase toneIndigo
```

## Components

### Capture and navigation

- [Camera capture](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/components/home/camera-preview.tsx): `frontend/components/home/camera-preview.tsx`
- [Camera state](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/hooks/useCamera.ts): `frontend/hooks/useCamera.ts`
- [Camera operations](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/services/camera.ts): `frontend/services/camera.ts`
- [Scan screen](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/scan/page.tsx): `frontend/app/scan/page.tsx`

### Results and records

- [Match result](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/result/page.tsx): `frontend/app/result/page.tsx`
- [Scan history](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/history/page.tsx): `frontend/app/history/page.tsx`
- [App settings](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/settings/page.tsx): `frontend/app/settings/page.tsx`

### Analysis workflow

- [Analysis screen](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/app/analysis/page.tsx): `frontend/app/analysis/page.tsx`
- [Analysis client](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/services/analysis.ts): `frontend/services/analysis.ts`
- [API client](https://github.com/mmbarrys/laterite_comparator/blob/main/frontend/services/api.ts): `frontend/services/api.ts`
- [Analysis API](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/main.py): `backend/app/main.py`
- [Analysis request](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/schemas.py): `backend/app/schemas.py`
- [Image decoding](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/image_input.py): `backend/app/image_input.py`
- [Runtime settings](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/config.py): `backend/app/config.py`

### Visual matching

- [Visual candidate search](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/similarity.py): `backend/app/ai/similarity.py`
- [Scan preprocessing](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/preprocessing.py): `backend/app/ai/preprocessing.py`
- [Image features](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/image_features.py): `backend/app/ai/image_features.py`
- [Zone selection](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/zone_selection.py): `backend/app/ai/zone_selection.py`
- [Geology reranking](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/ai/geology_reranking.py): `backend/app/ai/geology_reranking.py`

### Sample data

- [Supabase REST access](https://github.com/mmbarrys/laterite_comparator/blob/main/backend/app/supabase_rest.py): `backend/app/supabase_rest.py`
- **Supabase catalog and storage**

### Other components

- **Field user**

## Connections

- Field user → Camera capture: captures image
- Camera state → Camera operations: uses camera operations (evidence: `frontend/hooks/useCamera.ts`)
- Analysis screen → Analysis client: submits analysis
- Analysis client → API client: uses API client
- API client → Analysis API: sends scan
- Analysis API → Analysis request: accepts request (evidence: `backend/app/main.py`)
- Analysis API → Runtime settings: loads settings (evidence: `backend/app/main.py`)
- Analysis API → Image decoding: decodes image (evidence: `backend/app/main.py`)
- Analysis API → Visual candidate search: finds candidates (evidence: `backend/app/main.py`)
- Visual candidate search → Scan preprocessing: preprocesses scan (evidence: `backend/app/ai/similarity.py`)
- Visual candidate search → Image features: extracts features (evidence: `backend/app/ai/similarity.py`)
- Analysis API → Zone selection: selects zone candidate (evidence: `backend/app/main.py`)
- Analysis API → Geology reranking: reranks candidates (evidence: `backend/app/main.py`)
- Analysis API → Supabase REST access: fetches sample data (evidence: `backend/app/main.py`)
- Supabase REST access → Supabase catalog and storage: reads catalog; signs image URLs (evidence: `backend/app/supabase_rest.py`)
- Analysis API → Match result: returns match payload
- Field user → Scan history: views prior scans
- Field user → App settings: opens preferences
