# superzero11/openfarm architecture

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

## Overview

OpenFarm is a self-hostable crop-intelligence platform: farm teams manage organizations, farms, and fields, then inspect satellite indices, weather, soil, alerts, and scouting insights through a web app. The API provides tenant-scoped operations and background jobs; the worker computes observation and intelligence products, while TiTiler serves raster tiles. The README also documents boundary detection, sharing, and rich soil analysis, preserved here at subsystem level. Source excerpts verify API routing, auth, and parts of the index pipeline; other subsystem links are documented by the README or left unverified.

Main entry points: [`services/api/app/main.py`](https://github.com/superzero11/openfarm/blob/main/services/api/app/main.py) (FastAPI application), [`services/api/app/models/tables.py`](https://github.com/superzero11/openfarm/blob/main/services/api/app/models/tables.py) (PostGIS data), [`apps/web/src/app/[locale]/(authenticated)/dashboard/page.tsx`](https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/(authenticated)/dashboard/page.tsx) (OpenFarm web), [`services/api/app/worker.py`](https://github.com/superzero11/openfarm/blob/main/services/api/app/worker.py) (Celery worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["OpenFarm web<br/>[page.tsx]"]
  node_field_ui["Field workspace<br/>[page.tsx]"]
  node_detection_ui["Boundary review<br/>[page.tsx]"]
  node_share_ui["Shared field report<br/>[page.tsx]"]
  node_web_api["Web API client<br/>[api.ts]"]
end

subgraph group_api["API and tenancy"]
  node_api["FastAPI application<br/>[main.py]"]
  node_auth["JWT and org access<br/>[auth.py]"]
  node_orgs["Organizations<br/>[orgs.py]"]
  node_farms_fields["Farms and fields<br/>[fields.py]"]
  node_monitoring["Monitoring API<br/>[monitoring.py]"]
  node_weather_api["Weather API<br/>[weather.py]"]
  node_soil_api["Soil API<br/>[soil.py]"]
  node_alerts_scouting["Alerts and scouting<br/>[alerts.py]"]
  node_detection_api["Detection API<br/>[detection.py]"]
  node_sharing["Share links<br/>[share.py]"]
end

subgraph group_observations["Observation services"]
  node_weather_tasks["Weather ingestion<br/>[weather.py]"]
  node_tiler["TiTiler service<br/>[app.py]"]
  node_stac["Element84 STAC"]
  node_weather_provider["Open-Meteo"]
  node_soil_provider["SoilGrids / POLARIS"]
end

subgraph group_intelligence["Intelligence workflows"]
  node_worker["Celery worker<br/>[worker.py]"]
  node_index_pipeline["Index processing<br/>[pipeline.py]"]
  node_index_tasks["Vegetation indices<br/>[indices.py]"]
  node_soil_tasks["Soil intelligence<br/>[soil.py]"]
  node_detection_tasks["Boundary inference<br/>[detection.py]"]
end

subgraph group_storage["Data and tiles"]
  node_db[("PostGIS data<br/>[tables.py]")]
  node_minio[("COG object storage")]
end

node_farmer(("Farm user"))

node_farmer -->|"uses"| node_webapp
node_webapp -->|"opens fields"| node_field_ui
node_webapp -->|"starts review"| node_detection_ui
node_webapp -->|"opens shared view"| node_share_ui
node_webapp -.->|"requests data"| node_web_api
node_web_api -.->|"calls"| node_api
node_api -->|"applies access"| node_auth
node_api -->|"routes"| node_orgs
node_api -->|"routes"| node_farms_fields
node_api -->|"routes"| node_monitoring
node_api -->|"routes"| node_weather_api
node_api -->|"routes"| node_soil_api
node_api -->|"routes"| node_alerts_scouting
node_api -->|"routes"| node_detection_api
node_api -->|"routes"| node_sharing
node_auth -->|"checks membership"| node_db
node_orgs -->|"reads and writes"| node_db
node_farms_fields -->|"reads and writes"| node_db
node_monitoring -->|"reads data"| node_db
node_weather_api -.->|"reads and writes"| node_db
node_soil_api -->|"reads and writes"| node_db
node_alerts_scouting -->|"reads and writes"| node_db
node_detection_api -->|"reads and writes"| node_db
node_sharing -->|"reads and writes"| node_db
node_farms_fields -->|"queues weather"| node_weather_tasks
node_farms_fields -->|"queues soil"| node_soil_tasks
node_detection_api -->|"dispatches jobs"| node_worker
node_monitoring -->|"queues indices"| node_index_tasks
node_worker -->|"loads tasks"| node_index_tasks
node_worker -->|"loads tasks"| node_weather_tasks
node_worker -->|"loads tasks"| node_soil_tasks
node_worker -.->|"loads tasks"| node_detection_tasks
node_index_tasks -->|"reuses helpers"| node_index_pipeline
node_index_pipeline -->|"searches scenes"| node_stac
node_index_pipeline -->|"writes COGs"| node_minio
node_index_pipeline -.->|"stores statistics"| node_db
node_index_pipeline -.->|"enriches alerts"| node_alerts_scouting
node_weather_tasks -->|"fetches forecasts"| node_weather_provider
node_soil_tasks -->|"ingests profiles"| node_soil_provider
node_soil_api -->|"queues processing"| node_soil_tasks
node_detection_tasks -.->|"uses imagery"| node_stac
node_minio -->|"serves COG tiles"| node_tiler
node_field_ui -.->|"renders layers"| node_tiler
node_share_ui -.->|"loads public report"| node_sharing

click node_webapp "https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/(authenticated)/dashboard/page.tsx"
click node_field_ui "https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/(authenticated)/farms/%5Bid%5D/fields/%5BfieldId%5D/page.tsx"
click node_detection_ui "https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/(authenticated)/farms/%5Bid%5D/detect/page.tsx"
click node_share_ui "https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/share/%5Btoken%5D/page.tsx"
click node_web_api "https://github.com/superzero11/openfarm/blob/main/apps/web/src/lib/api.ts"
click node_api "https://github.com/superzero11/openfarm/blob/main/services/api/app/main.py"
click node_auth "https://github.com/superzero11/openfarm/blob/main/services/api/app/middleware/auth.py"
click node_orgs "https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/orgs.py"
click node_farms_fields "https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/fields.py"
click node_monitoring "https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/monitoring.py"
click node_weather_api "https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/weather.py"
click node_soil_api "https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/soil.py"
click node_alerts_scouting "https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/alerts.py"
click node_detection_api "https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/detection.py"
click node_sharing "https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/share.py"
click node_db "https://github.com/superzero11/openfarm/blob/main/services/api/app/models/tables.py"
click node_worker "https://github.com/superzero11/openfarm/blob/main/services/api/app/worker.py"
click node_index_pipeline "https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/pipeline.py"
click node_index_tasks "https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/indices.py"
click node_soil_tasks "https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/soil.py"
click node_weather_tasks "https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/weather.py"
click node_detection_tasks "https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/detection.py"
click node_tiler "https://github.com/superzero11/openfarm/blob/main/services/tiler/app.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_webapp,node_field_ui,node_detection_ui,node_share_ui,node_web_api,node_farmer toneBlue
class node_api,node_auth,node_orgs,node_farms_fields,node_monitoring,node_weather_api,node_soil_api,node_alerts_scouting,node_detection_api,node_sharing toneAmber
class node_weather_tasks,node_tiler,node_stac,node_weather_provider,node_soil_provider toneMint
class node_worker,node_index_pipeline,node_index_tasks,node_soil_tasks,node_detection_tasks toneRose
class node_db,node_minio toneIndigo
```

## Components

### Web experience

- [OpenFarm web](https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/(authenticated)/dashboard/page.tsx): `apps/web/src/app/[locale]/(authenticated)/dashboard/page.tsx`
- [Field workspace](https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/(authenticated)/farms/%5Bid%5D/fields/%5BfieldId%5D/page.tsx): `apps/web/src/app/[locale]/(authenticated)/farms/[id]/fields/[fieldId]/page.tsx`
- [Boundary review](https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/(authenticated)/farms/%5Bid%5D/detect/page.tsx): `apps/web/src/app/[locale]/(authenticated)/farms/[id]/detect/page.tsx`
- [Shared field report](https://github.com/superzero11/openfarm/blob/main/apps/web/src/app/%5Blocale%5D/share/%5Btoken%5D/page.tsx): `apps/web/src/app/[locale]/share/[token]/page.tsx`
- [Web API client](https://github.com/superzero11/openfarm/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`

### API and tenancy

- [FastAPI application](https://github.com/superzero11/openfarm/blob/main/services/api/app/main.py): `services/api/app/main.py`
- [JWT and org access](https://github.com/superzero11/openfarm/blob/main/services/api/app/middleware/auth.py): `services/api/app/middleware/auth.py`
- [Organizations](https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/orgs.py): `services/api/app/routers/orgs.py`
- [Farms and fields](https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/fields.py): `services/api/app/routers/fields.py`
- [Monitoring API](https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/monitoring.py): `services/api/app/routers/monitoring.py`
- [Weather API](https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/weather.py): `services/api/app/routers/weather.py`
- [Soil API](https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/soil.py): `services/api/app/routers/soil.py`
- [Alerts and scouting](https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/alerts.py): `services/api/app/routers/alerts.py`
- [Detection API](https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/detection.py): `services/api/app/routers/detection.py`
- [Share links](https://github.com/superzero11/openfarm/blob/main/services/api/app/routers/share.py): `services/api/app/routers/share.py`

### Observation services

- [Weather ingestion](https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/weather.py): `services/api/app/tasks/weather.py`
- [TiTiler service](https://github.com/superzero11/openfarm/blob/main/services/tiler/app.py): `services/tiler/app.py`
- **Element84 STAC**
- **Open-Meteo**
- **SoilGrids / POLARIS**

### Intelligence workflows

- [Celery worker](https://github.com/superzero11/openfarm/blob/main/services/api/app/worker.py): `services/api/app/worker.py`
- [Index processing](https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/pipeline.py): `services/api/app/tasks/pipeline.py`
- [Vegetation indices](https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/indices.py): `services/api/app/tasks/indices.py`
- [Soil intelligence](https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/soil.py): `services/api/app/tasks/soil.py`
- [Boundary inference](https://github.com/superzero11/openfarm/blob/main/services/api/app/tasks/detection.py): `services/api/app/tasks/detection.py`

### Data and tiles

- [PostGIS data](https://github.com/superzero11/openfarm/blob/main/services/api/app/models/tables.py): `services/api/app/models/tables.py`
- **COG object storage**

### Other components

- **Farm user**

## Connections

- Farm user → OpenFarm web: uses (evidence: `README.md`)
- OpenFarm web → Field workspace: opens fields (evidence: `README.md`)
- OpenFarm web → Boundary review: starts review (evidence: `README.md`)
- OpenFarm web → Shared field report: opens shared view (evidence: `README.md`)
- OpenFarm web → Web API client: requests data
- Web API client → FastAPI application: calls
- FastAPI application → JWT and org access: applies access (evidence: `services/api/app/main.py`)
- FastAPI application → Organizations: routes (evidence: `services/api/app/main.py`)
- FastAPI application → Farms and fields: routes (evidence: `services/api/app/main.py`)
- FastAPI application → Monitoring API: routes (evidence: `services/api/app/main.py`)
- FastAPI application → Weather API: routes (evidence: `services/api/app/main.py`)
- FastAPI application → Soil API: routes (evidence: `services/api/app/main.py`)
- FastAPI application → Alerts and scouting: routes (evidence: `services/api/app/main.py`)
- FastAPI application → Detection API: routes (evidence: `services/api/app/main.py`)
- FastAPI application → Share links: routes (evidence: `services/api/app/main.py`)
- JWT and org access → PostGIS data: checks membership (evidence: `services/api/app/middleware/auth.py`)
- Organizations → PostGIS data: reads and writes (evidence: `services/api/app/routers/orgs.py`)
- Farms and fields → PostGIS data: reads and writes (evidence: `services/api/app/routers/fields.py`)
- Monitoring API → PostGIS data: reads data (evidence: `services/api/app/routers/monitoring.py`)
- Weather API → PostGIS data: reads and writes
- Soil API → PostGIS data: reads and writes (evidence: `services/api/app/routers/soil.py`)
- Alerts and scouting → PostGIS data: reads and writes (evidence: `services/api/app/routers/alerts.py`)
- Detection API → PostGIS data: reads and writes (evidence: `services/api/app/routers/detection.py`)
- Share links → PostGIS data: reads and writes (evidence: `services/api/app/routers/share.py`)
- Farms and fields → Weather ingestion: queues weather (evidence: `services/api/app/routers/fields.py`)
- Farms and fields → Soil intelligence: queues soil (evidence: `services/api/app/routers/fields.py`)
- Detection API → Celery worker: dispatches jobs (evidence: `services/api/app/routers/detection.py`)
- Monitoring API → Vegetation indices: queues indices (evidence: `services/api/app/routers/monitoring.py`)
- Celery worker → Vegetation indices: loads tasks (evidence: `services/api/app/worker.py`)
- Celery worker → Weather ingestion: loads tasks (evidence: `services/api/app/worker.py`)
- Celery worker → Soil intelligence: loads tasks (evidence: `services/api/app/worker.py`)
- Celery worker → Boundary inference: loads tasks
- Vegetation indices → Index processing: reuses helpers (evidence: `services/api/app/tasks/pipeline.py`)
- Index processing → Element84 STAC: searches scenes (evidence: `README.md`)
- Index processing → COG object storage: writes COGs (evidence: `services/api/app/tasks/pipeline.py`)
- Index processing → PostGIS data: stores statistics (evidence: `services/api/app/tasks/pipeline.py`)
- Index processing → Alerts and scouting: enriches alerts
- Weather ingestion → Open-Meteo: fetches forecasts (evidence: `README.md`)
- Soil intelligence → SoilGrids / POLARIS: ingests profiles (evidence: `README.md`)
- Soil API → Soil intelligence: queues processing (evidence: `services/api/app/routers/soil.py`)
- Boundary inference → Element84 STAC: uses imagery
- COG object storage → TiTiler service: serves COG tiles (evidence: `README.md`)
- Field workspace → TiTiler service: renders layers
- Shared field report → Share links: loads public report
