# abhishek2586/fasalniti architecture

> Architecture diagram of the GitHub repository abhishek2586/fasalniti, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhishek2586/fasalniti
- Repository: https://github.com/abhishek2586/fasalniti

## Overview

1. **System shape**
   FasalNiti is a three-tier agriculture decision system: a React/Vite client in `src/`, a Node/Express API in `server/`, and a Python ML service in `ml-service/`. The main architectural boundary is: user interaction in the frontend, orchestration and business rules in the backend, and heavy forecasting/calibration in the Python service.

2. **Frontend responsibilities**
   The frontend is organized around user-facing decision pages, not generic CRUD screens. Key pages include `PlantingAdvisorPage`, `HarvestPlannerPage`, `CropRecPage`, `DiseaseDetectPage`, `WeatherIrrigationProfitMarket.jsx`, and `ChatbotPage`. Shared UI lives under `components/`, with app-wide state in `context/`, local behavior hooks in `hooks/`, and translated strings/design tokens in `constants/`.

3. **Frontend-to-backend communication**
   `src/api/agriBackend.js` is the main client for the Node API, while `src/api/claude.js` and `src/api/config.js` indicate additional AI/API wiring. The frontend does not appear to talk directly to MongoDB or the ML service; it calls the backend, which then fans out to external services and the ML microservice.

4. **Backend entry and request boundary**
   `server/server.js` and `server/app.js` are the runtime entry points for the Express app. Routing is split by domain under `server/routes/`, with matching controllers in `server/controllers/`. This is the main API surface for planting, harvest, disease, weather, market, chatbot, satellite, fertilizer, irrigation, crop, profit, auth, and location features.

5. **Business-logic layer**
   The real decision-making is in `server/services/`. The notable core services are `gadi.service.js`, `cropEconomics.service.js`, `priceIntelligence.service.js`, `planting.service.js`, `harvest.service.js`, and `harvestWindow.service.js`. These services likely implement the framework’s decision indices and economic logic, while controllers mainly validate requests and format responses.

6. **Persistence and domain models**
   `server/models/` contains MongoDB-backed entities such as `user.js`, `Market.js`, `HistoricalPrice.js`, `PriceForecast.js`, `PlantingRecommendation.js`, and `DisposalRecommendation.js`. There is also `CropEconomicsConstants.js` and `labels.txt/model.h5`, which suggests the backend includes packaged model assets for classification or inference, likely around disease detection.

7. **Cross-cutting middleware and API safety**
   Authentication and location scoping are handled by middleware in `server/middleware/`, especially `auth.middleware.js` and `location.middleware.js`. `error.middleware.js` centralizes failure handling, and `utils/responseHandler.js` suggests the API uses a consistent response envelope. This boundary matters because many endpoints depend on authenticated user context or farm location.

8. **External integrations**
   The backend is the integration hub for OpenWeather, Groq, and other AI fallbacks. The README also references Hugging Face and Gemini as backup providers, and the tree includes `bhashini.service.js`, which aligns with multilingual speech/translation support. `server/services/location.service.js` and `server/services/weather.service.js` indicate the app also normalizes geospatial and weather inputs before feeding them into recommendations.

9. **Planting and harvest decision flows**
   The two primary product flows are distinct:
   - **Planting**: inputs from soil/location/crop context flow through planting and crop-suitability logic to produce a planting recommendation.
   - **Harvest**: current market prices, decay economics, weather, and disease severity feed harvest planning logic to produce sell/store/dehydrate recommendations.
   The harvest side is more data-intensive because it combines price forecasting, perishability, and processing costs.

10. **ML microservice boundary**
    `ml-service/` is a separate Python service with its own Dockerfile, dependencies, and training script. It is used for computationally expensive forecasting and calibration, including Prophet-based price forecasting and synthetic benchmarking. The backend calls it via `ML_SERVICE_URL`, so the Node layer remains the orchestration point while Python owns the model runtime.

11. **Offline data and benchmarking**
    The `data/synthetic/` directory stores benchmark outputs such as `results.csv`, `scenarios.csv`, and `summary.json`. `ml-service/training/synthetic_benchmark.py` generates these artifacts, which are used to validate the economic value of the decision engine. This is an offline analytics path, separate from the live user-request path.

12. **Deployment and packaging**
    The presence of `capacitor.config.json` suggests the frontend can be packaged as a hybrid mobile app, even though the core app is a web frontend. `vercel.json` implies frontend deployment support, while `server/package.json` and `ml-service/requirements.txt` keep backend and ML runtimes isolated. The architecture therefore supports local development as well as split deployment of UI, API, and ML components.

Main entry points: [`server/services/planting.service.js`](https://github.com/abhishek2586/fasalniti/blob/main/server/services/planting.service.js) (Decision services), [`src/App.jsx`](https://github.com/abhishek2586/fasalniti/blob/main/src/App.jsx) (App shell), [`server/app.js`](https://github.com/abhishek2586/fasalniti/blob/main/server/app.js) (Express app), [`src/api/agriBackend.js`](https://github.com/abhishek2586/fasalniti/blob/main/src/api/agriBackend.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_src_app["App shell<br/>react shell<br/>[App.jsx]"]
  node_src_pages["Decision pages<br/>ui pages<br/>[index.jsx]"]
  node_src_chatbot["Chatbot UI<br/>assistant page<br/>[ChatbotPage.jsx]"]
  node_src_state(("App state<br/>context<br/>[AppContext.jsx]"))
  node_src_api["API client<br/>[agriBackend.js]"]
end

subgraph group_backend["Backend API"]
  node_server_entry["Server entry<br/>express bootstrap<br/>[server.js]"]
  node_server_app["Express app<br/>[app.js]"]
  node_server_routes["API routes<br/>route layer<br/>[planting.routes.js]"]
  node_server_ctrls["Controllers"]
  node_server_services["Decision services<br/>business logic"]
  node_server_weather["Weather service<br/>integration<br/>[weather.service.js]"]
  node_server_market["Market service<br/>pricing integration<br/>[market.service.js]"]
  node_server_location["Location service<br/>geo service"]
  node_server_crop["Crop suitability<br/>domain service"]
  node_server_harvest["Harvest logic<br/>decision service<br/>[harvest.service.js]"]
  node_server_econ["Economics"]
  node_server_models[("Mongo models<br/>persistence models<br/>[PriceForecast.js]")]
  node_server_mw["Middleware<br/>[auth.middleware.js]"]
end

subgraph group_ml["ML Service"]
  node_ml_app["ML API<br/>python service<br/>[app.py]"]
  node_ml_bench["Benchmarking<br/>training pipeline"]
end

subgraph group_offline["Offline Data"]
  node_data_synth["Synthetic data<br/>benchmark artifacts<br/>[summary.json]"]
end

node_src_app -->|"renders"| node_src_pages
node_src_app -->|"routes to"| node_src_chatbot
node_src_app -->|"uses"| node_src_state
node_src_pages -->|"calls"| node_src_api
node_src_chatbot -->|"calls"| node_src_api
node_src_api -->|"sends requests to"| node_server_entry
node_server_entry -->|"boots"| node_server_app
node_server_app -->|"applies"| node_server_mw
node_server_app -->|"mounts"| node_server_routes
node_server_routes -->|"delegates to"| node_server_ctrls
node_server_ctrls -->|"orchestrates"| node_server_services
node_server_services -->|"uses"| node_server_weather
node_server_services -->|"uses"| node_server_market
node_server_services -->|"uses"| node_server_location
node_server_services -->|"uses"| node_server_crop
node_server_services -->|"uses"| node_server_harvest
node_server_services -->|"uses"| node_server_econ
node_server_services -->|"persists to"| node_server_models
node_server_services -->|"calls"| node_ml_app
node_ml_app -->|"supports"| node_ml_bench
node_ml_bench -->|"produces"| node_data_synth

click node_src_app "https://github.com/abhishek2586/fasalniti/blob/main/src/App.jsx"
click node_src_pages "https://github.com/abhishek2586/fasalniti/blob/main/src/pages/index.jsx"
click node_src_chatbot "https://github.com/abhishek2586/fasalniti/blob/main/src/pages/ChatbotPage.jsx"
click node_src_state "https://github.com/abhishek2586/fasalniti/blob/main/src/context/AppContext.jsx"
click node_src_api "https://github.com/abhishek2586/fasalniti/blob/main/src/api/agriBackend.js"
click node_server_entry "https://github.com/abhishek2586/fasalniti/blob/main/server/server.js"
click node_server_app "https://github.com/abhishek2586/fasalniti/blob/main/server/app.js"
click node_server_routes "https://github.com/abhishek2586/fasalniti/blob/main/server/routes/planting.routes.js"
click node_server_ctrls "https://github.com/abhishek2586/fasalniti/blob/main/server/controllers/planting.controller.js"
click node_server_services "https://github.com/abhishek2586/fasalniti/blob/main/server/services/planting.service.js"
click node_server_weather "https://github.com/abhishek2586/fasalniti/blob/main/server/services/weather.service.js"
click node_server_market "https://github.com/abhishek2586/fasalniti/blob/main/server/services/market.service.js"
click node_server_location "https://github.com/abhishek2586/fasalniti/blob/main/server/services/location.service.js"
click node_server_crop "https://github.com/abhishek2586/fasalniti/blob/main/server/services/cropSuitability.service.js"
click node_server_harvest "https://github.com/abhishek2586/fasalniti/blob/main/server/services/harvest.service.js"
click node_server_econ "https://github.com/abhishek2586/fasalniti/blob/main/server/services/cropEconomics.service.js"
click node_server_models "https://github.com/abhishek2586/fasalniti/blob/main/server/models/PriceForecast.js"
click node_server_mw "https://github.com/abhishek2586/fasalniti/blob/main/server/middleware/auth.middleware.js"
click node_ml_app "https://github.com/abhishek2586/fasalniti/blob/main/ml-service/app.py"
click node_ml_bench "https://github.com/abhishek2586/fasalniti/blob/main/ml-service/training/synthetic_benchmark.py"
click node_data_synth "https://github.com/abhishek2586/fasalniti/blob/main/data/synthetic/summary.json"

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_src_app,node_src_pages,node_src_chatbot,node_src_state,node_src_api toneBlue
class node_server_entry,node_server_app,node_server_routes,node_server_ctrls,node_server_services,node_server_weather,node_server_market,node_server_location,node_server_crop,node_server_harvest,node_server_econ,node_server_models,node_server_mw toneAmber
class node_ml_app,node_ml_bench toneMint
class node_data_synth toneRose
```

## Components

### Frontend

React/Vite user interface and client-side orchestration.

- [App shell](https://github.com/abhishek2586/fasalniti/blob/main/src/App.jsx): react shell · Top-level frontend application composition and routing. · `src/App.jsx`
- [Decision pages](https://github.com/abhishek2586/fasalniti/blob/main/src/pages/index.jsx): ui pages · Main user-facing planning, detection, and advisory screens. · `src/pages/index.jsx`
- [Chatbot UI](https://github.com/abhishek2586/fasalniti/blob/main/src/pages/ChatbotPage.jsx): assistant page · Frontend conversational assistant entry point. · `src/pages/ChatbotPage.jsx`
- [App state](https://github.com/abhishek2586/fasalniti/blob/main/src/context/AppContext.jsx): context · Global client state for auth and app-wide data. · `src/context/AppContext.jsx`
- [API client](https://github.com/abhishek2586/fasalniti/blob/main/src/api/agriBackend.js): api client · Frontend gateway to the Node backend and AI providers. · `src/api/agriBackend.js`

### Backend API

Express API, business logic, persistence, and integrations.

- [Server entry](https://github.com/abhishek2586/fasalniti/blob/main/server/server.js): express bootstrap · Runtime entry for the Node/Express API. · `server/server.js`
- [Express app](https://github.com/abhishek2586/fasalniti/blob/main/server/app.js): express app · API wiring, middleware, and route registration. · `server/app.js`
- [API routes](https://github.com/abhishek2586/fasalniti/blob/main/server/routes/planting.routes.js): route layer · Domain route surface for agriculture features. · `server/routes/planting.routes.js`
- [Controllers](https://github.com/abhishek2586/fasalniti/blob/main/server/controllers/planting.controller.js): request controllers · Request validation and response shaping for each domain. · `server/controllers/planting.controller.js`
- [Decision services](https://github.com/abhishek2586/fasalniti/blob/main/server/services/planting.service.js): business logic · Core recommendation, forecasting, and orchestration services. · `server/services/planting.service.js`
- [Weather service](https://github.com/abhishek2586/fasalniti/blob/main/server/services/weather.service.js): integration · Weather normalization and weather-driven inputs. · `server/services/weather.service.js`
- [Market service](https://github.com/abhishek2586/fasalniti/blob/main/server/services/market.service.js): pricing integration · Market price intake and price intelligence logic. · `server/services/market.service.js`
- [Location service](https://github.com/abhishek2586/fasalniti/blob/main/server/services/location.service.js): geo service · Farm/location scoping and geospatial normalization. · `server/services/location.service.js`
- [Crop suitability](https://github.com/abhishek2586/fasalniti/blob/main/server/services/cropSuitability.service.js): domain service · Crop and planting suitability rules for advisory flows. · `server/services/cropSuitability.service.js`
- [Harvest logic](https://github.com/abhishek2586/fasalniti/blob/main/server/services/harvest.service.js): decision service · Harvest timing and sell/store/dehydrate recommendation logic. · `server/services/harvest.service.js`
- [Economics](https://github.com/abhishek2586/fasalniti/blob/main/server/services/cropEconomics.service.js): economics service · Crop economics, perishability, and value modeling. · `server/services/cropEconomics.service.js`
- [Mongo models](https://github.com/abhishek2586/fasalniti/blob/main/server/models/PriceForecast.js): persistence models · Mongo-backed domain records and price forecast storage. · `server/models/PriceForecast.js`
- [Middleware](https://github.com/abhishek2586/fasalniti/blob/main/server/middleware/auth.middleware.js): api middleware · Authentication, location scoping, and error handling. · `server/middleware/auth.middleware.js`

### ML Service

Python forecasting and benchmarking service.

- [ML API](https://github.com/abhishek2586/fasalniti/blob/main/ml-service/app.py): python service · Separate Python runtime for forecasting and calibration. · `ml-service/app.py`
- [Benchmarking](https://github.com/abhishek2586/fasalniti/blob/main/ml-service/training/synthetic_benchmark.py): training pipeline · Offline synthetic benchmark generation and evaluation. · `ml-service/training/synthetic_benchmark.py`

### Offline Data

Synthetic benchmark outputs used for evaluation.

- [Synthetic data](https://github.com/abhishek2586/fasalniti/blob/main/data/synthetic/summary.json): benchmark artifacts · Offline benchmark results and scenario outputs. · `data/synthetic/summary.json`

## Connections

- App shell → Decision pages: renders · Top-level app composes the decision pages.
- App shell → Chatbot UI: routes to · App exposes the assistant experience.
- App shell → App state: uses · Shared client state supports auth and session flow.
- Decision pages → API client: calls · Decision screens request backend data and recommendations.
- Chatbot UI → API client: calls · Chat UI uses the API client for assistant requests.
- API client → Server entry: sends requests to · Frontend talks to the Node API boundary.
- Server entry → Express app: boots · Server entry initializes the Express application.
- Express app → Middleware: applies · Middleware handles auth, location, and errors.
- Express app → API routes: mounts · Express app registers domain routes.
- API routes → Controllers: delegates to · Routes hand off request handling to controllers.
- Controllers → Decision services: orchestrates · Controllers invoke business logic services.
- Decision services → Weather service: uses · Decision flows depend on weather inputs.
- Decision services → Market service: uses · Harvest and profit logic depend on market data.
- Decision services → Location service: uses · Recommendations are scoped by location.
- Decision services → Crop suitability: uses · Planting decisions rely on crop suitability rules.
- Decision services → Harvest logic: uses · Harvest recommendation flow is centralized here.
- Decision services → Economics: uses · Economic scoring feeds planning and harvest choices.
- Decision services → Mongo models: persists to · Services store and retrieve domain records.
- Decision services → ML API: calls · Backend offloads forecasting and calibration to Python.
- ML API → Benchmarking: supports · Python service includes offline evaluation tooling.
- Benchmarking → Synthetic data: produces · Benchmark runs generate synthetic result artifacts.