# chameleon-company/planting-optimisation-tool architecture

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

- Interactive diagram: https://gitdiagram.com/chameleon-company/planting-optimisation-tool
- Repository: https://github.com/chameleon-company/planting-optimisation-tool

## Overview

1. This is a monorepo with four main runtime areas: `frontend` (React/Vite SPA), `backend` (FastAPI API + Postgres/PostGIS), `datascience` (offline scoring/modeling library and CLI tools), and `gis` (geospatial processing library). The shared product logic is split across these boundaries rather than concentrated in one service.

2. The user-facing application is the `frontend` React app. It is organized by feature pages such as calculator, species, recommendations, farm management, profile, and admin settings. React hooks wrap API calls and state management, while `AuthContext` and `RequireRole` enforce session and role-based access in the UI.

3. The backend is the main server-side system. FastAPI routers expose APIs for auth, users, farms, species, environmental profiles, recommendations, sapling estimation, global weights, parameters, reporting, batch estimation, soil texture, and AHP-related configuration. This layer is the entry point for the frontend and the orchestration point for domain workflows.

4. Inside the backend, the code is split into `services`, `domains`, `models`, `schemas`, and `routers`. Routers handle HTTP concerns, services implement business logic, domains capture scoring/profile concepts, models map to database tables, and schemas define request/response contracts. This is the core application boundary to draw in an architecture diagram.

5. Persistence is PostgreSQL with PostGIS support. The schema includes farms, users, auth tokens, audit logs, species, parameters, recommendations, global weights, planting estimates, soil pH, soil texture, waterways, and DEM-related spatial data. Alembic migrations manage schema evolution, and the presence of PostGIS indicates spatial queries are a first-class part of the backend.

6. Data ingestion and maintenance are handled by backend scripts. There are importers for farms, boundaries, DEM, waterways, soil pH, soil texture, species, and species parameters, plus setup and replication scripts. These are offline/admin utilities, not request-time APIs, and they feed the same database used by the application.

7. The `datascience` package is a separate analytical subsystem that supports recommendation logic. It contains AHP implementation, exclusion-rule logic, imputation models, suitability scoring, and recommendation orchestration. It also includes notebooks, CLI scripts, and saved model artifacts, which suggests it is used to develop, validate, and generate scoring assets rather than serve live HTTP traffic.

8. The `gis` package is the geospatial computation subsystem. It includes geometry parsing, farm profile extraction, a Google Earth Engine client, slope raster logic, planting point generation, and sapling estimation rules. This package turns farm geometry plus raster/geospatial sources into environmental inputs and planting estimates consumed by the rest of the system.

9. End-to-end, the main flow is: a user enters or manages farm data in the frontend; the backend stores that data and invokes environmental profiling, recommendation, and sapling estimation workflows; GIS and scoring logic produce derived outputs; the backend persists results and returns them to the UI for tables, dashboards, and reports. This is the primary cross-package data flow to show.

10. Reporting and exports are a separate backend capability. The repo includes reporting services and PDF/report-oriented UI pages, so generated outputs are not just API payloads but also human-readable summaries for farmers, field officers, and administrators.

11. Authentication, verification, and auditing are explicit concerns. The backend has auth tokens, user verification, email service support, and audit log tables; the frontend has login/register/reset/verify flows. That makes identity and traceability a distinct subsystem rather than an incidental feature.

12. Operationally, the repository has independent CI workflows for backend, frontend, data science, and GIS, plus Docker and deployment config. That separation mirrors the architecture: each major package can be tested and deployed with its own toolchain while still contributing to the same product.

Main entry points: [`backend/src/services`](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/services) (Services), [`frontend/src/pages`](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/frontend/src/pages) (Feature Pages), [`datascience/src/app`](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/app) (Scoring App), [`backend/src/routers`](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/routers) (Routers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["UI App<br/>React/Vite SPA<br/>[App.tsx]"]
  node_frontend_auth(("Auth Context<br/>ui auth<br/>[AuthContext.tsx]"))
  node_frontend_features["Feature Pages<br/>ui features"]
  node_frontend_hooks(("API Hooks<br/>ui data"))
  node_frontend_admin["Admin Settings<br/>ui admin"]
end

subgraph group_backend["Backend"]
  node_backend_api["API Server<br/>FastAPI app<br/>[main.py]"]
  node_backend_routers["Routers<br/>http endpoints"]
  node_backend_services["Services<br/>business logic"]
  node_backend_domains{{"Domains<br/>domain rules"}}
  node_backend_models[("Models")]
  node_backend_schemas["Schemas<br/>contracts"]
  node_backend_db[("Postgres/PostGIS<br/>persistence<br/>[database.py]")]
  node_backend_migrations["Migrations<br/>schema evolution"]
  node_backend_scripts["Importers<br/>offline ops"]
end

subgraph group_datascience["Data Science"]
  node_datascience_app["Scoring App<br/>offline analytics"]
  node_datascience_ahp{{"AHP<br/>ranking model"}}
  node_datascience_scoring{{"Suitability Scoring<br/>scoring engine"}}
  node_datascience_imputation{{"Imputation<br/>modeling"}}
end

subgraph group_gis["GIS"]
  node_gis_core{{"GIS Core<br/>geospatial core"}}
  node_gis_sapling{{"Sapling Estimation<br/>geospatial rules"}}
end

node_frontend_app -->|"routes to"| node_frontend_features
node_frontend_features -->|"uses"| node_frontend_hooks
node_frontend_features -->|"guards with"| node_frontend_auth
node_frontend_admin -->|"calls APIs"| node_backend_routers
node_frontend_hooks -->|"requests"| node_backend_routers
node_backend_api -->|"mounts"| node_backend_routers
node_backend_routers -->|"delegates"| node_backend_services
node_backend_services -->|"applies"| node_backend_domains
node_backend_services -->|"reads/writes"| node_backend_models
node_backend_models -->|"maps to"| node_backend_db
node_backend_migrations -->|"evolves"| node_backend_db
node_backend_scripts -->|"loads"| node_backend_db
node_backend_services -->|"uses"| node_gis_core
node_backend_services -->|"uses"| node_gis_sapling
node_backend_services -->|"orchestrates"| node_datascience_app
node_datascience_app -->|"coordinates"| node_datascience_ahp
node_datascience_app -->|"coordinates"| node_datascience_scoring
node_datascience_app -->|"coordinates"| node_datascience_imputation
node_gis_core -->|"feeds"| node_gis_sapling
node_frontend_features -->|"consumes"| node_backend_services

click node_frontend_app "https://github.com/chameleon-company/planting-optimisation-tool/blob/master/frontend/src/App.tsx"
click node_frontend_auth "https://github.com/chameleon-company/planting-optimisation-tool/blob/master/frontend/src/contexts/AuthContext.tsx"
click node_frontend_features "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/frontend/src/pages"
click node_frontend_hooks "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/frontend/src/hooks"
click node_frontend_admin "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/frontend/src/pages/admin/settings"
click node_backend_api "https://github.com/chameleon-company/planting-optimisation-tool/blob/master/backend/src/main.py"
click node_backend_routers "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/routers"
click node_backend_services "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/services"
click node_backend_domains "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/domains"
click node_backend_models "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/models"
click node_backend_schemas "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/schemas"
click node_backend_db "https://github.com/chameleon-company/planting-optimisation-tool/blob/master/backend/src/database.py"
click node_backend_migrations "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/alembic/versions"
click node_backend_scripts "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/scripts"
click node_datascience_app "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/app"
click node_datascience_ahp "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/ahp"
click node_datascience_scoring "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/suitability_scoring"
click node_datascience_imputation "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/imputation"
click node_gis_core "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/gis/core"
click node_gis_sapling "https://github.com/chameleon-company/planting-optimisation-tool/tree/master/gis/sapling_estimation"

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_frontend_app,node_frontend_auth,node_frontend_features,node_frontend_hooks,node_frontend_admin toneBlue
class node_backend_api,node_backend_routers,node_backend_services,node_backend_domains,node_backend_models,node_backend_schemas,node_backend_db,node_backend_migrations,node_backend_scripts toneAmber
class node_datascience_app,node_datascience_ahp,node_datascience_scoring,node_datascience_imputation toneMint
class node_gis_core,node_gis_sapling toneRose
```

## Components

### Frontend

React/Vite user application and UI state.

- [UI App](https://github.com/chameleon-company/planting-optimisation-tool/blob/master/frontend/src/App.tsx): React/Vite SPA · User-facing application shell with routed pages and feature screens. · `frontend/src/App.tsx`
- [Auth Context](https://github.com/chameleon-company/planting-optimisation-tool/blob/master/frontend/src/contexts/AuthContext.tsx): ui auth · Session state and role gating for protected UI flows. · `frontend/src/contexts/AuthContext.tsx`
- [Feature Pages](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/frontend/src/pages): ui features · Calculator, species, recommendations, farm management, profile, and admin pages. · `frontend/src/pages`
- [API Hooks](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/frontend/src/hooks): ui data · Hook layer wrapping backend requests and local state for feature screens. · `frontend/src/hooks`
- [Admin Settings](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/frontend/src/pages/admin/settings): ui admin · AHP, weights, scoring parameters, and rule management screens. · `frontend/src/pages/admin/settings`

### Backend

FastAPI application, persistence, and operational scripts.

- [API Server](https://github.com/chameleon-company/planting-optimisation-tool/blob/master/backend/src/main.py): FastAPI app · HTTP entry point and orchestration layer for product workflows. · `backend/src/main.py`
- [Routers](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/routers): http endpoints · Auth, farms, species, environmental profile, recommendations, sapling estimation, reporting, batch, soil texture, weights, parameters, and AHP endpoints. · `backend/src/routers`
- [Services](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/services): business logic · Core application logic for auth, scoring, profiling, recommendations, reporting, and data maintenance. · `backend/src/services`
- [Domains](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/domains): domain rules · Scoring and workflow concepts such as environmental profile, suitability, survivability, tree growth, and reporting. · `backend/src/domains`
- [Models](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/models): db models · SQLAlchemy table mappings for users, farms, species, recommendations, spatial data, and audit records. · `backend/src/models`
- [Schemas](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/schemas): contracts · Request and response DTOs for API boundaries and nested domain payloads. · `backend/src/schemas`
- [Postgres/PostGIS](https://github.com/chameleon-company/planting-optimisation-tool/blob/master/backend/src/database.py): persistence · Primary database for application data, audit trails, and spatial tables. · `backend/src/database.py`
- [Migrations](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/alembic/versions): schema evolution · Alembic version history and PostGIS/schema changes. · `backend/alembic/versions`
- [Importers](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/backend/src/scripts): offline ops · Data ingestion and maintenance scripts for farms, boundaries, DEM, waterways, soil, and species reference data. · `backend/src/scripts`

### Data Science

Offline scoring, modeling, and recommendation generation.

- [Scoring App](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/app): offline analytics · Orchestration layer for recommendation and scoring workflows. · `datascience/src/app`
- [AHP](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/ahp): ranking model · Analytic Hierarchy Process implementation and weight generation utilities. · `datascience/src/ahp`
- [Suitability Scoring](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/suitability_scoring): scoring engine · Exclusion rules, numeric/categorical scoring, and recommendation logic. · `datascience/src/suitability_scoring`
- [Imputation](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/datascience/src/imputation): modeling · Feature imputation pipeline and learned model artifacts. · `datascience/src/imputation`

### GIS

Geospatial computation and sapling estimation library.

- [GIS Core](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/gis/core): geospatial core · Geometry parsing, farm profile extraction, and external geospatial client integration. · `gis/core`
- [Sapling Estimation](https://github.com/chameleon-company/planting-optimisation-tool/tree/master/gis/sapling_estimation): geospatial rules · Slope, planting point, rotation, and estimation logic for planting outputs. · `gis/sapling_estimation`

## Connections

- UI App → Feature Pages: routes to · The app shell renders feature-specific pages.
- Feature Pages → API Hooks: uses · Pages consume hooks for data access and local state.
- Feature Pages → Auth Context: guards with · Protected pages rely on session and role checks.
- Admin Settings → Routers: calls APIs · Admin screens manage weights, parameters, AHP, and rules through backend endpoints.
- API Hooks → Routers: requests · UI hooks call the API layer for core product flows.
- API Server → Routers: mounts · The server exposes the router collection.
- Routers → Services: delegates · Routers keep HTTP concerns thin and hand work to services.
- Services → Domains: applies · Services orchestrate scoring and profile domain logic.
- Services → Models: reads/writes · Business operations persist via ORM models.
- Models → Postgres/PostGIS: maps to · Models map to PostgreSQL/PostGIS tables.
- Migrations → Postgres/PostGIS: evolves · Alembic migrations manage the database schema.
- Importers → Postgres/PostGIS: loads · Import and maintenance scripts populate shared reference and spatial data.
- Services → GIS Core: uses · Environmental profile workflows depend on geospatial extraction and geometry handling.
- Services → Sapling Estimation: uses · Sapling estimation workflows depend on GIS computations.
- Services → Scoring App: orchestrates · Backend workflows can be driven by offline scoring assets and recommendation logic.
- Scoring App → AHP: coordinates · Recommendation orchestration includes AHP weight computation.
- Scoring App → Suitability Scoring: coordinates · Orchestration runs exclusion and suitability scoring pipelines.
- Scoring App → Imputation: coordinates · Imputation models support scoring and recommendation preparation.
- GIS Core → Sapling Estimation: feeds · Core geospatial extraction supplies inputs to sapling estimation.
- Feature Pages → Services: consumes · User flows present derived results from backend workflows.
