How chameleon-company/planting-optimisation-tool works
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: services Services · pages Feature Pages · app Scoring App · routers Routers
Components 20
Frontend
React/Vite user application and UI state.
- UI App · User-facing application shell with routed pages and feature screens.
frontend/src/App.tsx - Auth Context · Session state and role gating for protected UI flows.
frontend/src/contexts/AuthContext.tsx - Feature Pages · Calculator, species, recommendations, farm management, profile, and admin pages.
frontend/src/pages - API Hooks · Hook layer wrapping backend requests and local state for feature screens.
frontend/src/hooks - Admin Settings · AHP, weights, scoring parameters, and rule management screens.
frontend/src/pages/admin/settings
Backend
FastAPI application, persistence, and operational scripts.
- API Server · HTTP entry point and orchestration layer for product workflows.
backend/src/main.py - Routers · Auth, farms, species, environmental profile, recommendations, sapling estimation, reporting, batch, soil texture, weights, parameters, and AHP endpoints.
backend/src/routers - Services · Core application logic for auth, scoring, profiling, recommendations, reporting, and data maintenance.
backend/src/services - Domains · Scoring and workflow concepts such as environmental profile, suitability, survivability, tree growth, and reporting.
backend/src/domains - Models · SQLAlchemy table mappings for users, farms, species, recommendations, spatial data, and audit records.
backend/src/models - Schemas · Request and response DTOs for API boundaries and nested domain payloads.
backend/src/schemas - Postgres/PostGIS · Primary database for application data, audit trails, and spatial tables.
backend/src/database.py - Migrations · Alembic version history and PostGIS/schema changes.
backend/alembic/versions - Importers · 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 · Orchestration layer for recommendation and scoring workflows.
datascience/src/app - AHP · Analytic Hierarchy Process implementation and weight generation utilities.
datascience/src/ahp - Suitability Scoring · Exclusion rules, numeric/categorical scoring, and recommendation logic.
datascience/src/suitability_scoring - Imputation · Feature imputation pipeline and learned model artifacts.
datascience/src/imputation
GIS
Geospatial computation and sapling estimation library.
- GIS Core · Geometry parsing, farm profile extraction, and external geospatial client integration.
gis/core - Sapling Estimation · Slope, planting point, rotation, and estimation logic for planting outputs.
gis/sapling_estimation
Connections 20
- 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.