# pavanchougaladev/clarity-ai architecture

> Architecture diagram of the GitHub repository pavanchougaladev/clarity-ai, 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/pavanchougaladev/clarity-ai
- Repository: https://github.com/pavanchougaladev/clarity-ai

## Overview

CLARITY* is a lunar-image co-registration and analysis platform with a Streamlit client, FastAPI job/API layer, and image-processing engine. Users select or upload imagery, configure a registration, and inspect alignment, quality, and terrain-analysis results. The engine covers ingestion, illumination normalization, matching, geometric refinement, validation, and exports; separate capabilities include crater analysis and DEM generation. Edges are limited to relationships shown in the README or cited source index/excerpts; some documented subsystems have unsampled implementations, so their internal wiring is not inferred.

Main entry points: [`server/src/pipeline.py`](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/pipeline.py) (Registration pipeline), [`server/api/worker.py`](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/api/worker.py) (Registration worker), [`client/services.py`](https://github.com/pavanchougaladev/clarity-ai/blob/main/client/services.py) (Client services), [`client/app.py`](https://github.com/pavanchougaladev/clarity-ai/blob/main/client/app.py) (Streamlit app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Interactive client"]
  node_app["Streamlit app<br/>[app.py]"]
  node_registration_view["Registration studio"]
  node_other_views["Analysis views"]
  node_client_services["Client services<br/>[services.py]"]
  node_api_client["API client<br/>[api_client.py]"]
end

subgraph group_api["REST and jobs"]
  node_api_gateway["FastAPI gateway<br/>[main.py]"]
  node_api_state[("Job state<br/>[state.py]")]
  node_api_routers["API routers"]
  node_worker["Registration worker<br/>[worker.py]"]
end

subgraph group_registration["Registration engine"]
  node_pipeline["Registration pipeline<br/>[pipeline.py]"]
  node_ingest["PDS4 ingestion<br/>[pds4_parser.py]"]
  node_preprocess_router["Preprocess routing<br/>[pipeline_router.py]"]
  node_photometric["Photometric correction"]
  node_shadow["Shadow normalization"]
  node_fusion_matcher["Feature fusion"]
  node_outliers["Outlier filtering"]
  node_refinement["Subpixel refinement<br/>[subpixel_refine.py]"]
  node_quality["Quality evaluation<br/>[quality_gate.py]"]
end

subgraph group_analysis["Terrain and analysis"]
  node_crater["Crater detection<br/>[crater_detector.py]"]
  node_dem["DEM generation<br/>[dem_builder.py]"]
  node_dual_pair["Stereo pair fusion"]
  node_visualization["Result visualization<br/>[visualizations.py]"]
end

subgraph group_support["Access and outputs"]
  node_artifact_export["Artifact export"]
  node_auth["JWT and RBAC<br/>[jwt_handler.py]"]
  node_report["PDF reporting<br/>[pdf_report.py]"]
end

node_user(("Analyst"))
node_external_imagery["Lunar imagery"]

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_registration_view
node_app -->|"routes to"| node_other_views
node_registration_view -->|"requests processing"| node_client_services
node_client_services -->|"runs registration"| node_pipeline
node_client_services -->|"calls detection"| node_crater
node_client_services -->|"calls DEM builder"| node_dem
node_api_client -.->|"sends requests"| node_api_gateway
node_api_gateway -->|"mounts routes"| node_api_routers
node_api_gateway -->|"uses worker"| node_worker
node_worker -->|"updates jobs"| node_api_state
node_worker -->|"runs registration"| node_pipeline
node_worker -->|"exports artifacts"| node_artifact_export
node_worker -->|"generates report"| node_report
node_external_imagery -.->|"provides products"| node_ingest
node_pipeline -->|"routes preprocessing"| node_preprocess_router
node_pipeline -->|"applies correction"| node_photometric
node_pipeline -->|"normalizes shadows"| node_shadow
node_pipeline -->|"matches features"| node_fusion_matcher
node_pipeline -->|"filters matches"| node_outliers
node_pipeline -->|"refines alignment"| node_refinement
node_pipeline -->|"checks quality"| node_quality
node_dual_pair -->|"registers pairs"| node_pipeline
node_dual_pair -->|"builds pair DEMs"| node_dem
node_other_views -.->|"renders results"| node_visualization
node_auth -->|"supports login"| node_api_routers

click node_app "https://github.com/pavanchougaladev/clarity-ai/blob/main/client/app.py"
click node_registration_view "https://github.com/pavanchougaladev/clarity-ai/blob/main/client/views/view_registration.py"
click node_other_views "https://github.com/pavanchougaladev/clarity-ai/tree/main/client/views"
click node_client_services "https://github.com/pavanchougaladev/clarity-ai/blob/main/client/services.py"
click node_api_client "https://github.com/pavanchougaladev/clarity-ai/blob/main/client/api_client.py"
click node_api_gateway "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/api/main.py"
click node_api_state "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/api/state.py"
click node_api_routers "https://github.com/pavanchougaladev/clarity-ai/tree/main/server/api/routers"
click node_worker "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/api/worker.py"
click node_pipeline "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/pipeline.py"
click node_ingest "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/ingest/pds4_parser.py"
click node_preprocess_router "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/preprocess/pipeline_router.py"
click node_photometric "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/preprocess/photometric_correction.py"
click node_shadow "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/preprocess/shadow_normalization.py"
click node_fusion_matcher "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/features/lunar_fusion_matcher.py"
click node_outliers "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/matching/outlier_rejection.py"
click node_refinement "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/registration/subpixel_refine.py"
click node_quality "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/evaluate/quality_gate.py"
click node_artifact_export "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/registration/artifact_exporter.py"
click node_crater "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/features/crater_detector.py"
click node_dem "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/features/dem_builder.py"
click node_dual_pair "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/dual_pair_pipeline.py"
click node_visualization "https://github.com/pavanchougaladev/clarity-ai/blob/main/client/components/visualizations.py"
click node_auth "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/auth/jwt_handler.py"
click node_report "https://github.com/pavanchougaladev/clarity-ai/blob/main/server/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_app,node_registration_view,node_other_views,node_client_services,node_api_client toneBlue
class node_api_gateway,node_api_state,node_api_routers,node_worker toneAmber
class node_pipeline,node_ingest,node_preprocess_router,node_photometric,node_shadow,node_fusion_matcher,node_outliers,node_refinement,node_quality toneMint
class node_crater,node_dem,node_dual_pair,node_visualization toneRose
class node_artifact_export,node_auth,node_report,node_user,node_external_imagery toneIndigo
```

## Components

### Interactive client

- [Streamlit app](https://github.com/pavanchougaladev/clarity-ai/blob/main/client/app.py): `client/app.py`
- [Registration studio](https://github.com/pavanchougaladev/clarity-ai/blob/main/client/views/view_registration.py): `client/views/view_registration.py`
- [Analysis views](https://github.com/pavanchougaladev/clarity-ai/tree/main/client/views): `client/views`
- [Client services](https://github.com/pavanchougaladev/clarity-ai/blob/main/client/services.py): `client/services.py`
- [API client](https://github.com/pavanchougaladev/clarity-ai/blob/main/client/api_client.py): `client/api_client.py`

### REST and jobs

- [FastAPI gateway](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/api/main.py): `server/api/main.py`
- [Job state](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/api/state.py): `server/api/state.py`
- [API routers](https://github.com/pavanchougaladev/clarity-ai/tree/main/server/api/routers): `server/api/routers`
- [Registration worker](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/api/worker.py): `server/api/worker.py`

### Registration engine

- [Registration pipeline](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/pipeline.py): `server/src/pipeline.py`
- [PDS4 ingestion](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/ingest/pds4_parser.py): `server/src/ingest/pds4_parser.py`
- [Preprocess routing](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/preprocess/pipeline_router.py): `server/src/preprocess/pipeline_router.py`
- [Photometric correction](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/preprocess/photometric_correction.py): `server/src/preprocess/photometric_correction.py`
- [Shadow normalization](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/preprocess/shadow_normalization.py): `server/src/preprocess/shadow_normalization.py`
- [Feature fusion](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/features/lunar_fusion_matcher.py): `server/src/features/lunar_fusion_matcher.py`
- [Outlier filtering](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/matching/outlier_rejection.py): `server/src/matching/outlier_rejection.py`
- [Subpixel refinement](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/registration/subpixel_refine.py): `server/src/registration/subpixel_refine.py`
- [Quality evaluation](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/evaluate/quality_gate.py): `server/src/evaluate/quality_gate.py`

### Terrain and analysis

- [Crater detection](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/features/crater_detector.py): `server/src/features/crater_detector.py`
- [DEM generation](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/features/dem_builder.py): `server/src/features/dem_builder.py`
- [Stereo pair fusion](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/dual_pair_pipeline.py): `server/src/dual_pair_pipeline.py`
- [Result visualization](https://github.com/pavanchougaladev/clarity-ai/blob/main/client/components/visualizations.py): `client/components/visualizations.py`

### Access and outputs

- [Artifact export](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/registration/artifact_exporter.py): `server/src/registration/artifact_exporter.py`
- [JWT and RBAC](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/auth/jwt_handler.py): `server/src/auth/jwt_handler.py`
- [PDF reporting](https://github.com/pavanchougaladev/clarity-ai/blob/main/server/src/reporting/pdf_report.py): `server/src/reporting/pdf_report.py`

### Other components

- **Analyst**
- **Lunar imagery**

## Connections

- Analyst → Streamlit app: uses (evidence: `client/app.py`)
- Streamlit app → Registration studio: routes to (evidence: `client/app.py`)
- Streamlit app → Analysis views: routes to (evidence: `client/app.py`)
- Registration studio → Client services: requests processing (evidence: `client/views/view_registration.py`)
- Client services → Registration pipeline: runs registration (evidence: `client/services.py`)
- Client services → Crater detection: calls detection (evidence: `client/services.py`)
- Client services → DEM generation: calls DEM builder (evidence: `client/services.py`)
- API client → FastAPI gateway: sends requests
- FastAPI gateway → API routers: mounts routes (evidence: `server/api/main.py`)
- FastAPI gateway → Registration worker: uses worker (evidence: `server/api/main.py`)
- Registration worker → Job state: updates jobs (evidence: `server/api/worker.py`)
- Registration worker → Registration pipeline: runs registration (evidence: `server/api/worker.py`)
- Registration worker → Artifact export: exports artifacts (evidence: `server/api/worker.py`)
- Registration worker → PDF reporting: generates report (evidence: `server/api/worker.py`)
- Lunar imagery → PDS4 ingestion: provides products
- Registration pipeline → Preprocess routing: routes preprocessing (evidence: `server/src/pipeline.py`)
- Registration pipeline → Photometric correction: applies correction (evidence: `server/src/pipeline.py`)
- Registration pipeline → Shadow normalization: normalizes shadows (evidence: `server/src/pipeline.py`)
- Registration pipeline → Feature fusion: matches features (evidence: `server/src/pipeline.py`)
- Registration pipeline → Outlier filtering: filters matches (evidence: `server/src/pipeline.py`)
- Registration pipeline → Subpixel refinement: refines alignment (evidence: `server/src/pipeline.py`)
- Registration pipeline → Quality evaluation: checks quality (evidence: `server/src/pipeline.py`)
- Stereo pair fusion → Registration pipeline: registers pairs (evidence: `server/src/dual_pair_pipeline.py`)
- Stereo pair fusion → DEM generation: builds pair DEMs (evidence: `server/src/dual_pair_pipeline.py`)
- Analysis views → Result visualization: renders results
- JWT and RBAC → API routers: supports login (evidence: `server/api/routers/auth.py`)
