GeoNutria

Overview

GeoNutria is a monorepo containing three deployable units and the infrastructure that joins them. A single FastAPI service owns all business logic, model inference, and device communication; both user-facing clients are thin consumers of its REST API.

What the platform does

• IoT monitoring — live sensor readings per device, historical charts, weather overlay, and a manual-entry lab for users without hardware.
• Plant diagnosis — leaf disease classification, palm disease segmentation and classification, soil type classification, and aerial palm-tree counting, all from local model weights.
• Advisory — crop recommendation, yield prediction, and a conversational agronomy assistant backed by a local Gemma model with hosted-LLM fallback.
• Satellite analysis — field imagery analysis rendered to plots under static/satellite_plots.
• Device control — bind a device, publish switch/value commands, read back reported state, and push firmware over the air.
• Accounts — OTP and Google registration, credit-metered features, team credit pooling, billing receipts, PDF reports, and live support chat.

Architecture

Everything the user sees arrives through one nginx instance on the host. Everything a device says arrives through a broker the backend subscribes to. These are two separate paths that meet only in the database and in memory.

Request path

The host nginx terminates TLS for app.geonutria.ai and splits traffic: the site root proxies to the frontend container, and /api proxies to the backend with the prefix stripped. That prefix-stripping is the single most important deployment fact in the system, and it has one consequence worth internalising:

Two brokers

The compose file configures two distinct MQTT endpoints, and they serve different purposes:

The live telemetry and control path runs entirely over the external broker. The local mosquitto service is started and available but is not what iot_manager binds to.

Repository layout

Backend service

Application lifecycle

main.py builds the FastAPI app and wires two startup concerns that dominate the service's resource profile:

1. Model loading. model_manager.load_all_models() pulls every PyTorch, YOLO, joblib and XGBoost artefact into RAM synchronously. The first request is fast; the first boot is not.
2. IoT thread. start_iot_thread() restores the latest reading per device from the database into the in-memory store, starts the MQTT subscriber on a daemon thread running loop_forever(), starts the publisher client on loop_start(), and schedules a 30-minute APScheduler job that persists the in-memory snapshot back to the database.

Shutdown calls model_manager.unload_all_models(). This is deliberate — without it PyTorch leaves pt_main_thread processes resident.

Middleware

• SecurityHeadersMiddleware — sets a Content-Security-Policy on every response, permitting self plus Google Fonts for styles and fonts, and data:/blob: for images and media. Note it allows unsafe-eval and unsafe-inline for scripts, which is what the CRA bundle requires.
• CORS — an explicit origin allowlist covering localhost development ports and a legacy IP. The production domain is absent, which is correct: the browser reaches the API same-origin through nginx, so no preflight occurs. The mobile app is a native client and is not subject to CORS at all.

Static mounts

Services

API reference

All paths are relative to https://app.geonutria.ai/api. Unless noted, the caller identifies itself with a user_id query parameter (GET/DELETE) or body field (POST/PUT) — see Auth & permissions.

auth

iot

my-devices recent

models — inference

ai & new_ai — assistants

assets, profile, support, admin

Authentication & permissions

How a session works today

POST /login looks the user up by email, verifies the password against a bcrypt hash, refuses unverified accounts, and returns a payload containing user_id, credit balances, and a token field. That token is the literal string user_token_ followed by the user's id.

Roles

users.role is an enum with three values:

Credits and feature metering

Metered features call verify_credits_and_permission(user_id, feature_name, db, cost) before doing any work. The resolution order is:

1. If the user is Admin, return immediately — no charge, no permission check.
2. Join system_features to user_permissions to find this user's access_state and effective cost (custom_credit_cost, else default_credit_cost). With no row, default to credit_based at the caller's suggested cost.
3. blocked raises 403. unlimited passes free. credit_based continues.
4. If personal ai_credits cover the cost, deduct and commit.
5. Otherwise compute the deficit and try to draw it from a team's shared_credits (selected FOR UPDATE), zeroing the personal balance. If no team can cover it, raise 402.

Device access

Device visibility is the union of ownership (devices.user_id) and explicit grants in the user_device_access join table, which an admin manages. The My Devices router enforces this in _assert_access, with an owner_only flag for destructive operations like unbinding.

Database

MySQL 8, schema geonutria_db, running on the host rather than in a container. The backend reaches it through the Docker alias host.docker.internal:3306.

Core tables

Schema drift

The dump also contains a set of dim_* tables (dim_glaccount, dim_item, dim_site, dim_storeroom, dim_transactiontype, dim_vendor) forming an inventory star schema that no application code references — apparently legacy or from a different project sharing the database.

Migration scripts

IoT & MQTT layer

The backend keeps a live picture of every device in memory and only writes to disk twice an hour. Read paths hit RAM; the database is the durable log, not the source of truth for "now".

Inbound telemetry

Each device row carries mqtt_topics, a JSON array of topic roots. On connect the subscriber reads every device's topics from the database and subscribes to {topic}/#, keeping a topic_to_device map. subscribe_topic() lets a newly bound or edited device start being monitored without restarting the service.

Incoming messages are keyed by the last path segment of the topic, mapped to canonical field names:

Anything whose suffix is not in that map is discarded. Payloads are parsed as floats, so a non-numeric message on a sensor topic is logged and dropped.

Persistence and weather fallback

Every 30 minutes the scheduler snapshots the in-memory store and, per device, calls _apply_weather_fallback_and_log: if the device has coordinates it fetches Open-Meteo, always logs a six-value weather row, and substitutes API temperature and humidity wherever the sensor reported exactly zero. The adjusted values are then inserted into iot_readings.

Outbound control

Control endpoints live in devices.control_topics as a JSON array. Each entry describes one control:

{
  "label":        "Irrigation pump",
  "topic":        "farm101/pump/set",     // device subscribes here
  "state_topic":  "farm101/pump/state",   // device reports here (optional)
  "type":         "switch",               // or "value"
  "on_payload":   "1",
  "off_payload":  "0",
  "min": 0, "max": 100, "unit": "%"
}

POST /my-devices/{id}/publish validates the requested topic against that device's registered control topics plus its OTA topic, and refuses anything else with a 400. Publishing itself goes through the persistent IoTPublisher at QoS 1, so broker credentials never leave the server.

State feedback

A control may declare a state_topic. The backend subscribes to it exactly — no wildcard — and stores raw payloads verbatim in ControlStateStore. This check runs at the very top of the message handler, before the numeric sensor parsing, because feedback payloads like ON are not floats.

The app polls /my-devices/states every 5 seconds, but only while at least one control declares a state topic, and re-checks 800 ms after any publish. The switch shows the device's reported position; the user's toggle is an optimistic guess displayed only until the device confirms, and is dropped immediately if the publish fails.

OTA firmware

Admins upload a binary to POST /my-devices/{id}/firmware. It is stored under static/firmware/{device_id}/ with a UUID filename, the version and OTA topic are persisted, and a command is published to the device's OTA topic:

{"url": "https://app.geonutria.ai/api/static/firmware/12/<uuid>.bin", "version": "1.4.2"}

The device is expected to subscribe to that topic, download the URL, and flash. The absolute URL is built from PUBLIC_BASE_URL, which must include the /api prefix or devices will receive an unreachable link.

Machine-learning models

All inference is local. ModelManager is a singleton loaded once at startup; nothing is fetched at request time.

Model definitions for the PyTorch networks (ResNet9, CustomCNN, ImageClassificationBase) live in services/models_def.py — required because the checkpoints are loaded with weights_only=False and need the class definitions present.

Language models

The agronomy assistant runs against a local Ollama container serving a quantised Gemma model. A hosted fallback path exists through OpenRouter/OpenAI, with config.fallback_api_keys assembling an ordered, de-duplicated key list from AI_API_KEYS, OPENROUTER_API_KEY and OPENAI_API_KEY so exhausted keys can rotate.

Web dashboard

Create React App, built to a static bundle at image build time with REACT_APP_API_URL=/api and served by nginx inside the frontend container.

Views

Shared UI lives in components/ui — GaugeChart, IoTMap, SensorCard, SatelliteImage, MapLocationPicker, MarkdownText, Toast. Cross-cutting widgets include OnboardingWizard, PaywallPopup, PaymentCheckout, SupportChatWidget, ExportReportModal and HelpGuideModal. All HTTP goes through services/apiService.js; services/translationService.js handles localisation.

Mobile app

Flutter, Dart SDK ^3.11.5, 85 source files. Full farmer-facing parity with the dashboard excluding the admin panel — the one admin endpoint it uses is payment receipt upload for billing.

Stack

Structure

Each feature follows the same three-layer split: data/ for models and repositories, bloc/ for Cubits, ui/ for screens and widgets.

Configuration

Env exposes compile-time constants overridable with --dart-define: API_BASE_URL, STATIC_BASE_URL, WS_BASE_URL and GOOGLE_SERVER_CLIENT_ID. All default to the production /api origin. Env.resolveMedia() turns the relative paths the API returns into absolute URLs.

Startup

main.dart renders immediately and runs bootstrap after first paint, with a timeout on each step. This is deliberate: a hanging secure-storage read on some devices would otherwise freeze the launch screen indefinitely. Auth always resolves to a terminal state — login or home.

Navigation

The shell exposes five primary destinations in the bottom bar — Dashboard, My Devices, Leaf Doctor, Satellite, Smart Assistant — with the full feature list in the drawer. Screens are held in an IndexedStack, so state survives tab switches.

My Devices

The device feature is the app's only write path to hardware.

• Bind — register a device with a name, map location, monitored MQTT topics and an optional OTA topic.
• Controls — define switch or value endpoints; each publishes its configured payload and reflects reported state.
• Quick controls — every configured control across all bound devices also renders at the top of the dashboard's Live tab, so acting on hardware never requires navigating into the device screen.
• Firmware — visible only to admins; everyone else sees a read-only version card.

DevicesCubit is provided at the shell rather than inside the devices screen, so the dashboard and My Devices share one device list and one polling timer. DeviceControlTile is the single shared switch/slider widget used by both surfaces.

Deployment

The server runs aaPanel with Docker. The project lives at /www/wwwroot/app.geonutria.ai. Host nginx reverse-proxies the domain to the frontend container and /api to the backend.

Compose services (production)

All four restart always; the backend declares depends_on for ollama and mosquitto. Every service uses extra_hosts: host.docker.internal:host-gateway so containers can reach host MySQL.

Deploying a backend change

Because the monorepo is not version-controlled, backend deployment is a file upload followed by a rebuild. Preserve the directory structure — routers/ files must land in Backend/routers/.

cd /www/wwwroot/app.geonutria.ai
docker compose -f docker-compose.prod.yml up -d --build --no-deps backend

Then run any pending migration inside the container:

docker compose -f docker-compose.prod.yml exec backend python migrate_my_devices.py

Building the mobile app

cd mobile
flutter build apk --debug

Output lands at build/app/outputs/flutter-apk/app-debug.apk. On the current Windows build machine the Android Studio JBR must be selected as JAVA_HOME, and the Dart analyzer needs a raised heap (DART_VM_OPTIONS=--old_gen_heap_size=1024).

Security findings

These are observations from reading the code, ordered by severity. None are theoretical — each is verifiable in the current source.

Critical Unauthenticated identity

Covered in full under Auth & permissions. The login token is a formatted string, never validated; identity is a caller-supplied parameter on every endpoint. Any client can act as any user, including administrators, by supplying a different id. This undermines every other access control in the system.

Critical Secrets committed in the working tree

docker-compose.prod.yml contains the production MySQL password and the MQTT broker password inline as environment values, rather than being read from an untracked .env. They are visible to anyone with repository or filesystem access, and are shipped in every copy of the project.

Additionally, DatabaseBackup.sql sits at the repository root and contains real user records — names, email addresses, phone numbers, and bcrypt password hashes. It should be removed from the tree and stored as an access-controlled backup artefact; the credentials in it should be treated as exposed and rotated.

Moderate Broad script CSP

The security-headers middleware allows unsafe-eval and unsafe-inline for scripts. This is what the CRA bundle needs to run, but it removes most of the XSS mitigation a CSP is there to provide.

Moderate Error responses leak internals

The login handler catches unexpected exceptions and returns traceback.format_exc() in the 500 response body, exposing file paths and library versions to the caller.

Sound What is done well

• Passwords are bcrypt-hashed, and login does not distinguish "no such user" from "wrong password".
• MQTT publishing is server-side only — broker credentials never reach a client — and /publish is restricted to topics the device has actually registered, so it cannot be used as an open relay.
• Firmware OTA is enforced admin-only in the backend, not merely hidden in the app.
• Every query uses SQLAlchemy bound parameters; there is no string-interpolated SQL on user input.
• The broker runs with allow_anonymous false and a password file.

Runbook

Connect and inspect

ssh root@<server-ip>
cd /www/wwwroot/app.geonutria.ai
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs -f --tail=100 backend

Verify the MQTT layer

On boot the backend logs a connection banner and one line per subscribed topic. Look for MQTT Connected, MQTT Publisher connected, and Subscribed to Device N topic: …. A rejection prints the numeric reason code. Unmatched inbound topics log a dropped-message warning, which is the fastest way to spot a device publishing somewhere unexpected.

Common failures

Recommended next steps

1. Replace parameter-based identity with a signed token resolved by a FastAPI dependency.
2. Move the compose secrets into an untracked env file and rotate the exposed credentials; remove the database dump from the tree.
3. Put the monorepo under version control so backend changes are reviewable and reversible.
4. Consolidate the migration scripts into an ordered, idempotent set that can rebuild the schema from scratch.
5. Pin the :latest image tags.