# ctrl-alt-elite-za/farmable architecture

> Architecture diagram of the GitHub repository ctrl-alt-elite-za/farmable, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ctrl-alt-elite-za/farmable
- Repository: https://github.com/ctrl-alt-elite-za/farmable

## Overview

Farmable is a farmer-focused decision-support application intended to reduce income loss using market prices, weather forecasts, and input costs. The backend is the clearest runtime entry point in the supplied evidence; its domain modules cover farm records, planning, forecasts, diagnosis, and assistant features, with workers handling asynchronous photo and diagnosis processing. The README establishes the product capabilities, while sampled excerpts support only a subset of the connections shown. The mobile tree contains native shells but no sampled application workflow, so it is not mapped as a client implementation.

Main entry points: [`apps/backend/src/farmable_backend/planning/service.py`](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/planning/service.py) (Planning service), [`apps/backend/src/farmable_backend/main.py`](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/main.py) (FastAPI application), [`apps/backend/src/farmable_backend/demo_api/app.py`](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/demo_api/app.py) (Local demo API), [`apps/backend/src/farmable_backend/diagnosis_worker.py`](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/diagnosis_worker.py) (Diagnosis worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Backend API"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_auth["Authentication<br/>[auth.py]"]
  node_demo_api["Local demo API<br/>[app.py]"]
end

subgraph group_farm["Farm Operations"]
  node_records_api["Records API<br/>[records_api.py]"]
  node_records_service["Records service<br/>[records_service.py]"]
  node_models["ORM models<br/>[models.py]"]
  node_database[("Database<br/>[database.py]")]
  node_demo_store[("Demo store<br/>[storage.py]")]
end

subgraph group_decisions["Decision Support"]
  node_planning_api["Planning API<br/>[api.py]"]
  node_planner["Planning service<br/>[service.py]"]
  node_planning_engine["Planning engine<br/>[engine.py]"]
  node_forecast_api["Forecast API<br/>[forecast_api.py]"]
  node_forecast_jobs["Forecast jobs<br/>[forecasts.py]"]
  node_assistant_api["Assistant API<br/>[api.py]"]
  node_assistant_runtime["Assistant runtime<br/>[runtime.py]"]
end

subgraph group_async["Async Processing"]
  node_diagnosis_api["Diagnosis API<br/>[diagnosis_api.py]"]
  node_diagnosis_worker["Diagnosis worker"]
  node_photo_worker["Photo worker<br/>[photo_worker.py]"]
end

subgraph group_integrations["External Integrations"]
  node_integrations["Provider adapters<br/>[registry.py]"]
end

node_farmer(("Farmer"))
node_weather_provider{{"Weather services"}}
node_market_data{{"Market price data"}}
node_crop_health{{"Crop health provider"}}
node_photo_storage[("Photo storage")]

node_farmer -->|"uses API"| node_backend
node_backend -->|"calls auth"| node_auth
node_farmer -.->|"uses demo"| node_demo_api
node_demo_api -->|"reads and writes"| node_demo_store
node_planner -->|"reads forecast state"| node_database
node_planner -.->|"loads cached weather"| node_weather_provider
node_diagnosis_worker -->|"requests diagnosis"| node_crop_health
node_photo_worker -->|"reads and publishes"| node_photo_storage

click node_backend "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/main.py"
click node_auth "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/auth.py"
click node_records_api "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/records_api.py"
click node_records_service "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/records_service.py"
click node_models "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/models.py"
click node_database "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/database.py"
click node_planning_api "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/planning/api.py"
click node_planner "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/planning/service.py"
click node_planning_engine "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/planning/engine.py"
click node_forecast_api "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/forecast_api.py"
click node_forecast_jobs "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/forecasts.py"
click node_assistant_api "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/assistant/api.py"
click node_assistant_runtime "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/assistant/runtime.py"
click node_diagnosis_api "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/diagnosis_api.py"
click node_diagnosis_worker "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/diagnosis_worker.py"
click node_photo_worker "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/photo_worker.py"
click node_integrations "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/integrations/registry.py"
click node_demo_api "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/demo_api/app.py"
click node_demo_store "https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/demo_api/storage.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_backend,node_auth,node_demo_api toneBlue
class node_records_api,node_records_service,node_models,node_database,node_demo_store,node_photo_storage toneAmber
class node_planning_api,node_planner,node_planning_engine,node_forecast_api,node_forecast_jobs,node_assistant_api,node_assistant_runtime toneMint
class node_diagnosis_api,node_diagnosis_worker,node_photo_worker toneRose
class node_integrations,node_farmer,node_weather_provider,node_market_data,node_crop_health toneIndigo
```

## Components

### Backend API

- [FastAPI application](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/main.py): `apps/backend/src/farmable_backend/main.py`
- [Authentication](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/auth.py): `apps/backend/src/farmable_backend/auth.py`
- [Local demo API](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/demo_api/app.py): `apps/backend/src/farmable_backend/demo_api/app.py`

### Farm Operations

- [Records API](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/records_api.py): `apps/backend/src/farmable_backend/records_api.py`
- [Records service](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/records_service.py): `apps/backend/src/farmable_backend/records_service.py`
- [ORM models](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/models.py): `apps/backend/src/farmable_backend/models.py`
- [Database](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/database.py): `apps/backend/src/farmable_backend/database.py`
- [Demo store](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/demo_api/storage.py): `apps/backend/src/farmable_backend/demo_api/storage.py`

### Decision Support

- [Planning API](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/planning/api.py): `apps/backend/src/farmable_backend/planning/api.py`
- [Planning service](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/planning/service.py): `apps/backend/src/farmable_backend/planning/service.py`
- [Planning engine](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/planning/engine.py): `apps/backend/src/farmable_backend/planning/engine.py`
- [Forecast API](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/forecast_api.py): `apps/backend/src/farmable_backend/forecast_api.py`
- [Forecast jobs](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/forecasts.py): `apps/backend/src/farmable_backend/forecasts.py`
- [Assistant API](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/assistant/api.py): `apps/backend/src/farmable_backend/assistant/api.py`
- [Assistant runtime](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/assistant/runtime.py): `apps/backend/src/farmable_backend/assistant/runtime.py`

### Async Processing

- [Diagnosis API](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/diagnosis_api.py): `apps/backend/src/farmable_backend/diagnosis_api.py`
- [Diagnosis worker](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/diagnosis_worker.py): `apps/backend/src/farmable_backend/diagnosis_worker.py`
- [Photo worker](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/photo_worker.py): `apps/backend/src/farmable_backend/photo_worker.py`

### External Integrations

- [Provider adapters](https://github.com/ctrl-alt-elite-za/farmable/blob/main/apps/backend/src/farmable_backend/integrations/registry.py): `apps/backend/src/farmable_backend/integrations/registry.py`

### Other components

- **Farmer**
- **Weather services**
- **Market price data**
- **Crop health provider**
- **Photo storage**

## Connections

- Farmer → FastAPI application: uses API
- FastAPI application → Authentication: calls auth
- Farmer → Local demo API: uses demo
- Local demo API → Demo store: reads and writes
- Planning service → Database: reads forecast state
- Planning service → Weather services: loads cached weather
- Diagnosis worker → Crop health provider: requests diagnosis
- Photo worker → Photo storage: reads and publishes