# mahimmuradimath7-debug/clarity architecture

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

- Interactive diagram: https://gitdiagram.com/mahimmuradimath7-debug/clarity
- Repository: https://github.com/mahimmuradimath7-debug/clarity

## Overview

CLARITY is a lunar-image co-registration and mapping suite. Users submit image pairs through the Streamlit interface or REST API; the registration orchestrator preprocesses imagery, finds and refines matches, evaluates quality, and produces registered imagery and exports. Separate capabilities support batch work, history, mosaics, crater analysis, and stereo DEM generation. The README documents the product branches; source excerpts and the index establish several internal calls, while unsampled subsystem connections are left out.

Main entry points: [`ui/app.py`](https://github.com/mahimmuradimath7-debug/clarity/blob/main/ui/app.py) (Streamlit UI), [`src/pipeline.py`](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/pipeline.py) (Registration Orchestrator), [`api/worker.py`](https://github.com/mahimmuradimath7-debug/clarity/blob/main/api/worker.py) (Job Worker), [`api/main.py`](https://github.com/mahimmuradimath7-debug/clarity/blob/main/api/main.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_api["REST API<br/>[main.py]"]
  node_api_client["API Client<br/>[api_client.py]"]
end

subgraph group_registration["Registration Core"]
  node_pipeline["Registration Orchestrator<br/>[pipeline.py]"]
  node_preprocessing["Image Preprocessing"]
  node_matching["Feature Matching<br/>[deep_matcher.py]"]
  node_geometry["Match Refinement<br/>[subpixel_refine.py]"]
  node_evaluation["Quality Evaluation<br/>[metrics.py]"]
end

subgraph group_products["Mapping &amp; Analysis"]
  node_batch["Batch Processing<br/>[batch.py]"]
  node_history[("Registration History<br/>[history.py]")]
  node_mosaic["Mosaic Builder<br/>[mosaic.py]"]
  node_dem["Stereo DEM<br/>[dem_builder.py]"]
  node_craters["Crater Detection<br/>[crater_detector.py]"]
end

subgraph group_services["API &amp; Outputs"]
  node_auth["JWT &amp; RBAC<br/>[jwt_handler.py]"]
  node_worker["Job Worker<br/>[worker.py]"]
  node_exports["Registration Exports"]
  node_reports["PDF Reports<br/>[pdf_report.py]"]
end

node_scientist(("Mission User"))

node_scientist -->|"uses"| node_streamlit
node_scientist -->|"submits imagery"| node_api
node_streamlit -->|"requests jobs"| node_api_client
node_api_client -->|"calls REST"| node_api
node_api -.->|"dispatches jobs"| node_worker
node_api -.->|"authenticates users"| node_auth
node_worker -->|"runs registration"| node_pipeline
node_pipeline -->|"preprocesses imagery"| node_preprocessing
node_pipeline -->|"finds matches"| node_matching
node_pipeline -->|"refines matches"| node_geometry
node_pipeline -->|"measures quality"| node_evaluation
node_pipeline -->|"exports artifacts"| node_exports
node_worker -->|"writes artifacts"| node_exports
node_worker -->|"generates reports"| node_reports
node_streamlit -->|"offers batch runs"| node_batch
node_streamlit -->|"shows history"| node_history
node_streamlit -->|"offers mosaics"| node_mosaic
node_streamlit -->|"offers 3D mapping"| node_dem
node_streamlit -->|"offers crater analysis"| node_craters

click node_streamlit "https://github.com/mahimmuradimath7-debug/clarity/blob/main/ui/app.py"
click node_api "https://github.com/mahimmuradimath7-debug/clarity/blob/main/api/main.py"
click node_api_client "https://github.com/mahimmuradimath7-debug/clarity/blob/main/ui/services/api_client.py"
click node_auth "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/auth/jwt_handler.py"
click node_worker "https://github.com/mahimmuradimath7-debug/clarity/blob/main/api/worker.py"
click node_pipeline "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/pipeline.py"
click node_preprocessing "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/preprocess/photometric_correction.py"
click node_matching "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/features/deep_matcher.py"
click node_geometry "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/registration/subpixel_refine.py"
click node_evaluation "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/evaluate/metrics.py"
click node_batch "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/batch.py"
click node_history "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/history.py"
click node_mosaic "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/mosaic.py"
click node_dem "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/features/dem_builder.py"
click node_craters "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/features/crater_detector.py"
click node_exports "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/registration/artifact_exporter.py"
click node_reports "https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/reporting/pdf_report.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_streamlit,node_api,node_api_client,node_scientist toneBlue
class node_pipeline,node_preprocessing,node_matching,node_geometry,node_evaluation toneAmber
class node_batch,node_history,node_mosaic,node_dem,node_craters toneMint
class node_auth,node_worker,node_exports,node_reports toneRose
```

## Components

### User Interfaces

- [Streamlit UI](https://github.com/mahimmuradimath7-debug/clarity/blob/main/ui/app.py): `ui/app.py`
- [REST API](https://github.com/mahimmuradimath7-debug/clarity/blob/main/api/main.py): `api/main.py`
- [API Client](https://github.com/mahimmuradimath7-debug/clarity/blob/main/ui/services/api_client.py): `ui/services/api_client.py`

### Registration Core

- [Registration Orchestrator](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/pipeline.py): `src/pipeline.py`
- [Image Preprocessing](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/preprocess/photometric_correction.py): `src/preprocess/photometric_correction.py`
- [Feature Matching](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/features/deep_matcher.py): `src/features/deep_matcher.py`
- [Match Refinement](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/registration/subpixel_refine.py): `src/registration/subpixel_refine.py`
- [Quality Evaluation](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/evaluate/metrics.py): `src/evaluate/metrics.py`

### Mapping & Analysis

- [Batch Processing](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/batch.py): `src/batch.py`
- [Registration History](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/history.py): `src/history.py`
- [Mosaic Builder](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/mosaic.py): `src/mosaic.py`
- [Stereo DEM](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/features/dem_builder.py): `src/features/dem_builder.py`
- [Crater Detection](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/features/crater_detector.py): `src/features/crater_detector.py`

### API & Outputs

- [JWT & RBAC](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/auth/jwt_handler.py): `src/auth/jwt_handler.py`
- [Job Worker](https://github.com/mahimmuradimath7-debug/clarity/blob/main/api/worker.py): `api/worker.py`
- [Registration Exports](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/registration/artifact_exporter.py): `src/registration/artifact_exporter.py`
- [PDF Reports](https://github.com/mahimmuradimath7-debug/clarity/blob/main/src/reporting/pdf_report.py): `src/reporting/pdf_report.py`

### Other components

- **Mission User**

## Connections

- Mission User → Streamlit UI: uses (evidence: `README.md`)
- Mission User → REST API: submits imagery (evidence: `README.md`)
- Streamlit UI → API Client: requests jobs (evidence: `ui/app.py`)
- API Client → REST API: calls REST (evidence: `ui/services/api_client.py`)
- REST API → Job Worker: dispatches jobs (evidence: `api/main.py`)
- REST API → JWT & RBAC: authenticates users
- Job Worker → Registration Orchestrator: runs registration (evidence: `api/worker.py`)
- Registration Orchestrator → Image Preprocessing: preprocesses imagery (evidence: `src/pipeline.py`)
- Registration Orchestrator → Feature Matching: finds matches (evidence: `src/pipeline.py`)
- Registration Orchestrator → Match Refinement: refines matches (evidence: `src/pipeline.py`)
- Registration Orchestrator → Quality Evaluation: measures quality (evidence: `src/pipeline.py`)
- Registration Orchestrator → Registration Exports: exports artifacts (evidence: `src/pipeline.py`)
- Job Worker → Registration Exports: writes artifacts (evidence: `api/worker.py`)
- Job Worker → PDF Reports: generates reports (evidence: `api/worker.py`)
- Streamlit UI → Batch Processing: offers batch runs (evidence: `README.md`)
- Streamlit UI → Registration History: shows history (evidence: `ui/app.py`)
- Streamlit UI → Mosaic Builder: offers mosaics (evidence: `ui/app.py`)
- Streamlit UI → Stereo DEM: offers 3D mapping (evidence: `ui/app.py`)
- Streamlit UI → Crater Detection: offers crater analysis (evidence: `ui/app.py`)
