Backend/AI_ROUTE_CONNECTION_AUDIT.md

Backend ↔ AI Route Connection Audit

Last reconciled against current route registrations and view implementations in:

• Backend/config/urls.py
• Backend/*/urls.py
• Backend/*/views.py
• Ai/config/urls.py
• Ai/*/urls.py
• Backend/external_api_adapter/json/ai/index.json

Status Vocabulary

• implemented: route exists and the corresponding backend ↔ AI integration is implemented now
• partially_implemented: route exists, but behavior/readiness is limited or alias-based
• contract_only: mock/spec exists, but no real client-facing implementation is registered
• deprecated: kept for compatibility or aliasing, but not the preferred canonical route
• missing: documented previously, but no route/implementation exists now
• disabled: intentionally not exposed for current developer/public use
• transitional: works now, but still reflects temporary architecture boundaries or compatibility layers

Runtime vs Seed Rule

• seed/bootstrap data stays allowed for local/dev/test/bootstrap flows
• runtime application code must not silently return mock/sample/demo data
• if real data is missing, the contract must surface an explicit empty state or structured failure

Ownership Boundaries

• Backend owns canonical plant catalog records exposed in Backend/plants
• AI farm_data owns the derived farm read-model and canonical AI-side farm ↔ plant assignment path
• Backend farm-alert tracker route is cached snapshot delivery, not live AI on request
• AI crop-simulation routes own live or derived simulation outputs

Source-Of-Truth Matrix

Backend/API contract	Actual route or AI path	Status	Notes
POST /api/rag/chat/	AI only: Ai/rag/urls.py	implemented	Real AI route; not a backend client route
POST /api/farm-alerts/tracker/	Backend/farm_alerts/views.py → cached snapshot response	transitional	Backend route is production-valid, but semantics are cached_snapshot, not live AI inference
POST /api/farm-alerts/timeline/	no backend route	missing	Previously documented incorrectly
GET /api/soil-data/	AI only: Ai/location_data/urls.py	implemented	Exists on AI service, not on backend public routes
POST /api/soil-data/	AI only: Ai/location_data/urls.py	implemented	Exists on AI service, not on backend public routes
GET /api/soil-data/tasks/{task_id}/status/	AI only: Ai/location_data/urls.py	implemented	Exists on AI service, not on backend public routes
POST /api/soil-data/ndvi-health/	real backend route is POST /api/crop-health/ndvi-health/	deprecated	Old path should not be presented as current
POST /api/soile/moisture-heatmap/	AI route; backend canonical alias is POST /api/soil/moisture-heatmap/	implemented	soile/* is AI-facing, soil/* is backend-facing
POST /api/soile/health-summary/	AI route; backend canonical alias is POST /api/soil/summary/	implemented	Same as above
POST /api/soile/anomaly-detection/	AI route; backend canonical alias is POST /api/soil/anomalies/	implemented	Same as above
POST /api/farm-data/	AI route exists; backend uses it for sync	implemented	Internal AI contract; not a backend public endpoint
GET /api/farm-data/{farm_uuid}/detail/	AI route exists: Ai/farm_data/urls.py	implemented	Internal AI service contract
POST /api/farm-data/parameters/	AI route exists: Ai/farm_data/urls.py	implemented	Internal AI service contract
POST /api/weather/farm-card/	backend route exists; AI canonical route also exists	implemented	Backend proxies to weather functionality
POST /api/weather/water-need-prediction/	AI route exists; backend public contract differs	partially_implemented	AI path is real; backend public path is different
POST /api/economy/overview/	backend + AI route exist	implemented	End-to-end connected
GET /api/plants/	AI route exists as Ai/plant/urls.py and backend route exists as GET /api/plants/	implemented	Different services, both real
POST /api/plants/	AI + backend real	implemented	Different services, both real
GET /api/plants/{pk}/	AI + backend real	implemented	Backend is canonical catalog; AI is its own service/snapshot consumer
PUT /api/plants/{pk}/	AI route real; backend route not exposed with PUT	partially_implemented	Real on AI, not mirrored on backend public app
PATCH /api/plants/{pk}/	AI route real; backend route not exposed with PATCH	partially_implemented	Same limitation
DELETE /api/plants/{pk}/	AI route real; backend route not exposed with DELETE	partially_implemented	Same limitation
POST /api/plants/fetch-info/	AI route real	implemented	AI route exists; backend public equivalent is absent
POST /api/pest-disease/detect/	backend alias + AI route real	implemented	Canonical current path
POST /api/pest-disease/risk/	backend alias + AI route real	implemented	Canonical current path
POST /api/pest-disease/risk-summary/	backend alias route exists	implemented	Implemented in backend alias layer
GET /api/irrigation/	backend + AI real	implemented	Canonical list route
POST /api/irrigation/	AI route real; backend route currently list/create mismatch	partially_implemented	Backend public create contract is not yet cleanly reconciled
GET /api/irrigation/{pk}/	AI route real; backend route missing	partially_implemented	Real in AI only
PUT /api/irrigation/{pk}/	AI route real; backend route missing	contract_only	Present in mock/spec and AI service, not a backend public route
PATCH /api/irrigation/{pk}/	AI route real; backend route missing	contract_only	Same
DELETE /api/irrigation/{pk}/	AI route real; backend route missing	contract_only	Same
POST /api/irrigation/recommend/	backend + AI real	implemented	Canonical route
GET /api/irrigation/recommend/{task_id}/status/	mock/spec only	contract_only	No current backend or AI route registration found
POST /api/fertilization/recommend/	backend + AI real	implemented	Canonical route
GET /api/fertilization/recommend/{task_id}/status/	mock/spec only	contract_only	No current route registration found
POST /api/crop-simulation/growth/	AI route real; backend canonical client route is /api/yield-harvest/growth/	deprecated	Real AI route, but backend public source-of-truth remains under yield-harvest/*
GET /api/crop-simulation/growth/{task_id}/status/	AI route real; backend canonical client route is /api/yield-harvest/growth/{task_id}/status/	deprecated	Same
POST /api/crop-simulation/current-farm-chart/	AI route real; backend canonical client route is /api/yield-harvest/current-farm-chart/	deprecated	Same
POST /api/crop-simulation/harvest-prediction/	AI route real; backend canonical client route is /api/yield-harvest/harvest-prediction/	deprecated	Same
POST /api/crop-simulation/yield-prediction/	AI route real; backend canonical client route is /api/yield-harvest/yield-prediction/	deprecated	Same

Response Semantics

• farm-alerts/tracker backend route → cached snapshot
• irrigation/* backend routes → mostly proxy or backend-owned data with AI enrichment
• yield-harvest/* backend routes → proxy to AI plus persisted backend logs for some summaries
• farm-data/* AI routes → AI-owned derived read/write model

Reconciliation Notes

• pest-disease/* is now the real backend alias and AI contract. Older references to pest-detection/analyze as the “real” path are stale.
• farm-alerts/timeline is not a registered backend route and must not be documented as implemented.
• soil-data/*, farm-data/*, and several plants/* routes are real on the AI service, but not backend public routes; docs must distinguish internal AI contracts from backend client APIs.
• crop-simulation/* remains real on AI, while backend public endpoints are exposed under yield-harvest/*.
• task status endpoints for fertilization and irrigation recommendation remain mock/spec-only in Backend/external_api_adapter/json/ai/index.json.
• schema UI endpoints are intentionally disabled in AI; developers should rely on version-controlled audit docs until schema publishing is intentionally re-enabled.

Known Gaps / Follow-up

• Some backend docs still use historical “AI route” wording where “internal AI contract” would be more precise.
• Some dashboard-era docs still need cleanup where old mock fallback language remains.