# norsaje/cosmo_track architecture

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

- Interactive diagram: https://gitdiagram.com/norsaje/cosmo_track
- Repository: https://github.com/norsaje/cosmo_track

## Overview

cosmo_track is a field-level vegetation-monitoring service: a user authenticates, selects or draws a polygon, binds it to an available observation series, submits an analysis, then polls its job and views reconstructed NDVI, uncertainty and anomaly explanations. The API validates and queues work; a Celery worker fetches fixture-backed series, reconstructs them and stores analysis results for retrieval. The graph also preserves the documented polygon, session, job-status, export and anomaly capabilities. Source excerpts establish key worker and reconstruction calls; some route and DL details are documented or represented only by their exact enclosing directory paths.

Main entry points: [`apps/worker/tasks.py`](https://github.com/norsaje/cosmo_track/blob/main/apps/worker/tasks.py) (Celery worker), [`apps/api/routes/analyses.py`](https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/analyses.py) (Analysis routes), [`apps/api/main.py`](https://github.com/norsaje/cosmo_track/blob/main/apps/api/main.py) (FastAPI entry), [`apps/db/models.py`](https://github.com/norsaje/cosmo_track/blob/main/apps/db/models.py) (PostGIS records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity"]
  node_auth_routes["Auth routes<br/>[auth.py]"]
  node_identity_client["Identity client<br/>[braining_id.py]"]
  node_sessions["Session handling<br/>[sessions.py]"]
end

subgraph group_api["API and records"]
  node_api_main["FastAPI entry<br/>[main.py]"]
  node_polygon_routes["Polygon routes<br/>[polygons.py]"]
  node_analysis_routes["Analysis routes<br/>[analyses.py]"]
  node_job_routes["Job status<br/>[jobs.py]"]
  node_api_schemas["API schemas<br/>[analyses.py]"]
  node_job_states["Job state contract<br/>[jobs.py]"]
  node_database[("PostGIS records<br/>[models.py]")]
end

subgraph group_processing["Analysis processing"]
  node_worker["Celery worker<br/>[tasks.py]"]
  node_fixture["Series provider<br/>[fixture.py]"]
  node_orchestrator["Analysis orchestration<br/>[orchestrator.py]"]
  node_reconstructor["Reconstructor<br/>[reconstructor.py]"]
  node_inference["NDVI inference<br/>[inference.py]"]
  node_features["Feature builder<br/>[builder.py]"]
  node_bundle["Model bundle<br/>[bundle.py]"]
  node_model_package["Mounted ML package"]
end

subgraph group_anomalies["Anomaly insights"]
  node_baseline_anomaly["Baseline anomalies<br/>[baseline.py]"]
  node_advanced_anomaly["Advanced anomaly analysis<br/>[advanced.py]"]
  node_event_explanations["Events and explanations<br/>[events.py]"]
end

node_user(("Field user"))
node_braining["Braining ID"]
node_redis["Redis broker"]

node_user -->|"uses API"| node_api_main
node_api_main -->|"registers"| node_auth_routes
node_api_main -->|"registers"| node_polygon_routes
node_api_main -->|"registers"| node_analysis_routes
node_api_main -->|"registers"| node_job_routes
node_auth_routes -->|"verifies identity"| node_identity_client
node_identity_client -->|"requests codes"| node_braining
node_auth_routes -->|"issues sessions"| node_sessions
node_auth_routes -->|"persists users"| node_database
node_polygon_routes -->|"stores polygons"| node_database
node_analysis_routes -->|"validates requests"| node_api_schemas
node_analysis_routes -->|"creates analyses"| node_database
node_analysis_routes -->|"queues job"| node_redis
node_analysis_routes -->|"dispatches task"| node_worker
node_worker -->|"updates stages"| node_job_states
node_worker -->|"stores outcomes"| node_database
node_job_routes -->|"reads progress"| node_database
node_worker -->|"fetches series"| node_fixture
node_worker -->|"runs analysis"| node_orchestrator
node_orchestrator -->|"reconstructs series"| node_reconstructor
node_reconstructor -->|"delegates inference"| node_inference
node_inference -->|"builds features"| node_features
node_inference -->|"uses bundle"| node_bundle
node_worker -->|"loads mounted model"| node_model_package
node_worker -->|"computes events"| node_baseline_anomaly
node_baseline_anomaly -.->|"optional analysis"| node_advanced_anomaly
node_advanced_anomaly -->|"uses event helpers"| node_event_explanations
node_analysis_routes -.->|"serves anomalies"| node_baseline_anomaly

click node_auth_routes "https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/auth.py"
click node_identity_client "https://github.com/norsaje/cosmo_track/blob/main/apps/auth/braining_id.py"
click node_sessions "https://github.com/norsaje/cosmo_track/blob/main/apps/auth/sessions.py"
click node_api_main "https://github.com/norsaje/cosmo_track/blob/main/apps/api/main.py"
click node_polygon_routes "https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/polygons.py"
click node_analysis_routes "https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/analyses.py"
click node_job_routes "https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/jobs.py"
click node_api_schemas "https://github.com/norsaje/cosmo_track/blob/main/apps/api/schemas/analyses.py"
click node_job_states "https://github.com/norsaje/cosmo_track/blob/main/apps/api/schemas/jobs.py"
click node_database "https://github.com/norsaje/cosmo_track/blob/main/apps/db/models.py"
click node_worker "https://github.com/norsaje/cosmo_track/blob/main/apps/worker/tasks.py"
click node_fixture "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/providers/fixture.py"
click node_orchestrator "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/service/orchestrator.py"
click node_reconstructor "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/service/reconstructor.py"
click node_inference "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/inference.py"
click node_features "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/features/builder.py"
click node_bundle "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/models/bundle.py"
click node_model_package "https://github.com/norsaje/cosmo_track/tree/main/model/ndvi"
click node_baseline_anomaly "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/anomalies/baseline.py"
click node_advanced_anomaly "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/anomalies/advanced.py"
click node_event_explanations "https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/anomalies/events.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_auth_routes,node_identity_client,node_sessions,node_user toneBlue
class node_api_main,node_polygon_routes,node_analysis_routes,node_job_routes,node_api_schemas,node_job_states,node_database,node_redis toneAmber
class node_worker,node_fixture,node_orchestrator,node_reconstructor,node_inference,node_features,node_bundle,node_model_package toneMint
class node_baseline_anomaly,node_advanced_anomaly,node_event_explanations toneRose
class node_braining toneIndigo
```

## Components

### Identity

- [Auth routes](https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/auth.py): `apps/api/routes/auth.py`
- [Identity client](https://github.com/norsaje/cosmo_track/blob/main/apps/auth/braining_id.py): `apps/auth/braining_id.py`
- [Session handling](https://github.com/norsaje/cosmo_track/blob/main/apps/auth/sessions.py): `apps/auth/sessions.py`

### API and records

- [FastAPI entry](https://github.com/norsaje/cosmo_track/blob/main/apps/api/main.py): `apps/api/main.py`
- [Polygon routes](https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/polygons.py): `apps/api/routes/polygons.py`
- [Analysis routes](https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/analyses.py): `apps/api/routes/analyses.py`
- [Job status](https://github.com/norsaje/cosmo_track/blob/main/apps/api/routes/jobs.py): `apps/api/routes/jobs.py`
- [API schemas](https://github.com/norsaje/cosmo_track/blob/main/apps/api/schemas/analyses.py): `apps/api/schemas/analyses.py`
- [Job state contract](https://github.com/norsaje/cosmo_track/blob/main/apps/api/schemas/jobs.py): `apps/api/schemas/jobs.py`
- [PostGIS records](https://github.com/norsaje/cosmo_track/blob/main/apps/db/models.py): `apps/db/models.py`

### Analysis processing

- [Celery worker](https://github.com/norsaje/cosmo_track/blob/main/apps/worker/tasks.py): `apps/worker/tasks.py`
- [Series provider](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/providers/fixture.py): `src/veg_recovery/providers/fixture.py`
- [Analysis orchestration](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/service/orchestrator.py): `src/veg_recovery/service/orchestrator.py`
- [Reconstructor](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/service/reconstructor.py): `src/veg_recovery/service/reconstructor.py`
- [NDVI inference](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/inference.py): `src/veg_recovery/inference.py`
- [Feature builder](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/features/builder.py): `src/veg_recovery/features/builder.py`
- [Model bundle](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/models/bundle.py): `src/veg_recovery/models/bundle.py`
- [Mounted ML package](https://github.com/norsaje/cosmo_track/tree/main/model/ndvi): `model/ndvi`

### Anomaly insights

- [Baseline anomalies](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/anomalies/baseline.py): `src/veg_recovery/anomalies/baseline.py`
- [Advanced anomaly analysis](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/anomalies/advanced.py): `src/veg_recovery/anomalies/advanced.py`
- [Events and explanations](https://github.com/norsaje/cosmo_track/blob/main/src/veg_recovery/anomalies/events.py): `src/veg_recovery/anomalies/events.py`

### Other components

- **Field user**
- **Braining ID**
- **Redis broker**

## Connections

- Field user → FastAPI entry: uses API
- FastAPI entry → Auth routes: registers (evidence: `apps/api/main.py`)
- FastAPI entry → Polygon routes: registers (evidence: `apps/api/main.py`)
- FastAPI entry → Analysis routes: registers (evidence: `apps/api/main.py`)
- FastAPI entry → Job status: registers (evidence: `apps/api/main.py`)
- Auth routes → Identity client: verifies identity (evidence: `apps/api/routes/auth.py`)
- Identity client → Braining ID: requests codes
- Auth routes → Session handling: issues sessions (evidence: `apps/api/routes/auth.py`)
- Auth routes → PostGIS records: persists users (evidence: `apps/api/routes/auth.py`)
- Polygon routes → PostGIS records: stores polygons
- Analysis routes → API schemas: validates requests (evidence: `apps/api/routes/analyses.py`)
- Analysis routes → PostGIS records: creates analyses (evidence: `apps/api/routes/analyses.py`)
- Analysis routes → Redis broker: queues job
- Analysis routes → Celery worker: dispatches task (evidence: `apps/api/routes/analyses.py`)
- Celery worker → Job state contract: updates stages (evidence: `apps/worker/tasks.py`)
- Celery worker → PostGIS records: stores outcomes (evidence: `apps/worker/tasks.py`)
- Job status → PostGIS records: reads progress
- Celery worker → Series provider: fetches series (evidence: `apps/worker/tasks.py`)
- Celery worker → Analysis orchestration: runs analysis (evidence: `apps/worker/tasks.py`)
- Analysis orchestration → Reconstructor: reconstructs series (evidence: `src/veg_recovery/service/orchestrator.py`)
- Reconstructor → NDVI inference: delegates inference
- NDVI inference → Feature builder: builds features (evidence: `src/veg_recovery/inference.py`)
- NDVI inference → Model bundle: uses bundle (evidence: `src/veg_recovery/inference.py`)
- Celery worker → Mounted ML package: loads mounted model
- Celery worker → Baseline anomalies: computes events (evidence: `apps/worker/tasks.py`)
- Baseline anomalies → Advanced anomaly analysis: optional analysis
- Advanced anomaly analysis → Events and explanations: uses event helpers (evidence: `src/veg_recovery/anomalies/advanced.py`)
- Analysis routes → Baseline anomalies: serves anomalies
