# pratikchetry/satellite-tile-intelligence-api architecture

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

- Interactive diagram: https://gitdiagram.com/pratikchetry/satellite-tile-intelligence-api
- Repository: https://github.com/pratikchetry/satellite-tile-intelligence-api

## Overview

This repository is a CPU-oriented satellite land-use classification API with a reproducible model-training and evaluation workflow. A client submits image bytes to the FastAPI classify endpoint; shared preprocessing and inference produce a class, probabilities, and an uncertainty flag, then the API records an auditable prediction and returns its ID. Training selects a backbone/head and validation-derived threshold for the artifact used at serving time. Evaluation reuses the serving classifier on held-out tiles. The graph follows the shown calls and README-documented capabilities; data-generation directories and unsampled implementations are not inferred.

Main entry points: [`app/main.py`](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/main.py) (FastAPI endpoints), [`app/classifier.py`](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/classifier.py) (Tile classifier), [`scripts/train_head.py`](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/scripts/train_head.py) (Head training and selection), [`app/storage.py`](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/storage.py) (Prediction storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["API serving"]
  node_api["FastAPI endpoints<br/>[main.py]"]
end

subgraph group_inference["Inference"]
  node_classifier["Tile classifier<br/>[classifier.py]"]
  node_preprocessing["Image preprocessing<br/>[preprocessing.py]"]
  node_artifact["Classifier artifact"]
end

subgraph group_development["Model development"]
  node_trainer["Head training and selection<br/>[train_head.py]"]
  node_validation["Threshold selection<br/>[train_head.py]"]
end

subgraph group_audit["Evaluation and audit"]
  node_storage["Prediction storage<br/>[storage.py]"]
  node_sqlite[("SQLite predictions<br/>[storage.py]")]
  node_evaluation["Held-out evaluation<br/>[evaluate.py]"]
  node_labels["Evaluation labels<br/>[eval_labels.csv]"]
end

node_client(("API client"))
node_review(("Human reviewer"))

node_client -->|"submits tile"| node_api
node_api -->|"requests prediction"| node_classifier
node_classifier -->|"preprocesses image"| node_preprocessing
node_classifier -->|"loads model"| node_artifact
node_api -->|"saves prediction"| node_storage
node_storage -->|"writes and reads"| node_sqlite
node_api -->|"checks health"| node_storage
node_trainer -->|"extracts features"| node_preprocessing
node_trainer -->|"sweeps threshold"| node_validation
node_trainer -->|"writes artifact"| node_artifact
node_evaluation -->|"classifies tiles"| node_classifier
node_evaluation -->|"reads labels"| node_labels
node_api -.->|"flags uncertain"| node_review

click node_api "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/main.py"
click node_classifier "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/classifier.py"
click node_preprocessing "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/preprocessing.py"
click node_artifact "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/models/classifier_head.pkl"
click node_storage "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/storage.py"
click node_sqlite "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/storage.py"
click node_trainer "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/scripts/train_head.py"
click node_validation "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/scripts/train_head.py"
click node_evaluation "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/scripts/evaluate.py"
click node_labels "https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/data/eval_labels.csv"

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_api,node_client,node_review toneBlue
class node_classifier,node_preprocessing,node_artifact toneAmber
class node_trainer,node_validation toneMint
class node_storage,node_sqlite,node_evaluation,node_labels toneRose
```

## Components

### API serving

- [FastAPI endpoints](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/main.py): `app/main.py`

### Inference

- [Tile classifier](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/classifier.py): `app/classifier.py`
- [Image preprocessing](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/preprocessing.py): `app/preprocessing.py`
- [Classifier artifact](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/models/classifier_head.pkl): `models/classifier_head.pkl`

### Model development

- [Head training and selection](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/scripts/train_head.py): `scripts/train_head.py`
- [Threshold selection](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/scripts/train_head.py): `scripts/train_head.py`

### Evaluation and audit

- [Prediction storage](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/storage.py): `app/storage.py`
- [SQLite predictions](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/app/storage.py): `app/storage.py`
- [Held-out evaluation](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/scripts/evaluate.py): `scripts/evaluate.py`
- [Evaluation labels](https://github.com/pratikchetry/satellite-tile-intelligence-api/blob/main/data/eval_labels.csv): `data/eval_labels.csv`

### Other components

- **API client**
- **Human reviewer**

## Connections

- API client → FastAPI endpoints: submits tile (evidence: `README.md`)
- FastAPI endpoints → Tile classifier: requests prediction (evidence: `app/main.py`)
- Tile classifier → Image preprocessing: preprocesses image (evidence: `app/classifier.py`)
- Tile classifier → Classifier artifact: loads model (evidence: `app/classifier.py`)
- FastAPI endpoints → Prediction storage: saves prediction (evidence: `app/main.py`)
- Prediction storage → SQLite predictions: writes and reads (evidence: `app/storage.py`)
- FastAPI endpoints → Prediction storage: checks health (evidence: `app/main.py`)
- Head training and selection → Image preprocessing: extracts features (evidence: `scripts/train_head.py`)
- Head training and selection → Threshold selection: sweeps threshold (evidence: `scripts/train_head.py`)
- Head training and selection → Classifier artifact: writes artifact (evidence: `scripts/train_head.py`)
- Held-out evaluation → Tile classifier: classifies tiles (evidence: `scripts/evaluate.py`)
- Held-out evaluation → Evaluation labels: reads labels (evidence: `scripts/evaluate.py`)
- FastAPI endpoints → Human reviewer: flags uncertain (evidence: `README.md`)
