# amgharhind/gravsense architecture

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

- Interactive diagram: https://gitdiagram.com/amgharhind/gravsense
- Repository: https://github.com/amgharhind/gravsense

## Overview

GravSense is a server-side construction-debris analysis API with a browser interface. A user uploads a site photo and selects a detection method; the API validates it, obtains a debris mask, optionally runs depth estimation and reference-width calibration in parallel, then computes area and volume and returns metrics plus visualization images. The graph preserves the SegFormer benchmark path and the separate calibration and depth stages. Relationships are based on the sampled API implementation and README; unsampled UI internals are not inferred.

Main entry points: [`gravsense/api/main.py`](https://github.com/amgharhind/gravsense/blob/main/gravsense/api/main.py) (FastAPI analysis), [`gravsense/api/static/index.html`](https://github.com/amgharhind/gravsense/blob/main/gravsense/api/static/index.html) (Upload and results UI), [`gravsense/api/schemas.py`](https://github.com/amgharhind/gravsense/blob/main/gravsense/api/schemas.py) (Analysis response schema), [`gravsense/core/grounded_sam.py`](https://github.com/amgharhind/gravsense/blob/main/gravsense/core/grounded_sam.py) (Grounded SAM detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_webui["Upload and results UI<br/>[index.html]"]
end

subgraph group_orchestration["Analysis API"]
  node_api["FastAPI analysis<br/>[main.py]"]
  node_response["Analysis response schema<br/>[schemas.py]"]
end

subgraph group_inference["Detection and Depth"]
  node_grounded["Grounded SAM detector<br/>[grounded_sam.py]"]
  node_segformer["SegFormer baseline"]
  node_depth["Pile depth estimator<br/>[depth_estimator.py]"]
end

subgraph group_measurement["Calibration and Measurement"]
  node_calibrator["Reference-width calibration<br/>[auto_calibrate.py]"]
  node_volume["Area and volume calculation<br/>[volume.py]"]
end

node_browser(("User browser"))

node_browser -->|"opens"| node_webui
node_webui -->|"submits analysis"| node_api
node_api -->|"serves UI"| node_webui
node_api -->|"dispatches detection"| node_grounded
node_api -->|"dispatches detection"| node_segformer
node_api -->|"estimates depth"| node_depth
node_api -->|"calibrates width"| node_calibrator
node_api -->|"calculates area and volume"| node_volume
node_api -->|"returns schema"| node_response

click node_webui "https://github.com/amgharhind/gravsense/blob/main/gravsense/api/static/index.html"
click node_api "https://github.com/amgharhind/gravsense/blob/main/gravsense/api/main.py"
click node_response "https://github.com/amgharhind/gravsense/blob/main/gravsense/api/schemas.py"
click node_grounded "https://github.com/amgharhind/gravsense/blob/main/gravsense/core/grounded_sam.py"
click node_segformer "https://github.com/amgharhind/gravsense/blob/main/gravsense/core/segformer_detector.py"
click node_depth "https://github.com/amgharhind/gravsense/blob/main/gravsense/core/depth_estimator.py"
click node_calibrator "https://github.com/amgharhind/gravsense/blob/main/gravsense/core/auto_calibrate.py"
click node_volume "https://github.com/amgharhind/gravsense/blob/main/gravsense/core/volume.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_webui,node_browser toneBlue
class node_api,node_response toneAmber
class node_grounded,node_segformer,node_depth toneMint
class node_calibrator,node_volume toneRose
```

## Components

### User Interface

- [Upload and results UI](https://github.com/amgharhind/gravsense/blob/main/gravsense/api/static/index.html): `gravsense/api/static/index.html`

### Analysis API

- [FastAPI analysis](https://github.com/amgharhind/gravsense/blob/main/gravsense/api/main.py): `gravsense/api/main.py`
- [Analysis response schema](https://github.com/amgharhind/gravsense/blob/main/gravsense/api/schemas.py): `gravsense/api/schemas.py`

### Detection and Depth

- [Grounded SAM detector](https://github.com/amgharhind/gravsense/blob/main/gravsense/core/grounded_sam.py): `gravsense/core/grounded_sam.py`
- [SegFormer baseline](https://github.com/amgharhind/gravsense/blob/main/gravsense/core/segformer_detector.py): `gravsense/core/segformer_detector.py`
- [Pile depth estimator](https://github.com/amgharhind/gravsense/blob/main/gravsense/core/depth_estimator.py): `gravsense/core/depth_estimator.py`

### Calibration and Measurement

- [Reference-width calibration](https://github.com/amgharhind/gravsense/blob/main/gravsense/core/auto_calibrate.py): `gravsense/core/auto_calibrate.py`
- [Area and volume calculation](https://github.com/amgharhind/gravsense/blob/main/gravsense/core/volume.py): `gravsense/core/volume.py`

### Other components

- **User browser**

## Connections

- User browser → Upload and results UI: opens (evidence: `README.md`)
- Upload and results UI → FastAPI analysis: submits analysis (evidence: `README.md`)
- FastAPI analysis → Upload and results UI: serves UI (evidence: `gravsense/api/main.py`)
- FastAPI analysis → Grounded SAM detector: dispatches detection (evidence: `gravsense/api/main.py`)
- FastAPI analysis → SegFormer baseline: dispatches detection (evidence: `gravsense/api/main.py`)
- FastAPI analysis → Pile depth estimator: estimates depth (evidence: `gravsense/api/main.py`)
- FastAPI analysis → Reference-width calibration: calibrates width (evidence: `gravsense/api/main.py`)
- FastAPI analysis → Area and volume calculation: calculates area and volume (evidence: `gravsense/api/main.py`)
- FastAPI analysis → Analysis response schema: returns schema (evidence: `gravsense/api/main.py`)