# shlokapol2005/soilsense architecture

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

- Interactive diagram: https://gitdiagram.com/shlokapol2005/soilsense
- Repository: https://github.com/shlokapol2005/soilsense

## Overview

1. **High-level shape**
   SoilSense is a 3-tier application: a React/Vite frontend, a Node/Express backend, and a MongoDB database. In addition, there is a Python-based ML training pipeline that produces serialized models consumed by the app.

2. **Frontend boundary**
   The `frontend/` folder is the presentation layer. It uses React with Vite and is organized as a page-based UI with screens for welcome, login/signup, dashboard, soil analysis, weather, calculator, recommendations, and history. `App.jsx` and `main.jsx` are the entry points that wire the page flow and global styling.

3. **Frontend responsibilities**
   The UI appears to handle user interaction, form capture, displaying weather/soil outputs, and presenting recommendation results and history. CSS is split per page, suggesting each route/screen is mostly self-contained rather than sharing a large component library.

4. **Backend boundary**
   The `backend/` folder is the API and data-access layer. The repo tree shows a Node.js service (`server.js`) with Express-style route modules under `routes/`, plus database models under `models/`. This is the main runtime boundary that the frontend talks to over HTTP.

5. **Backend API domains**
   There are two explicit route domains: `authRoutes.js` for user authentication and `weatherRoutes.js` for weather-related operations. That suggests the backend is responsible for both account management and serving weather or prediction-adjacent data to the frontend.

6. **Persistence layer**
   MongoDB is the durable store. The backend includes Mongoose-style models for `User` and `weather`, and the README describes a `prediction_history` collection as well. The data store likely keeps user records, fetched weather snapshots, and historical prediction/recommendation records for later display.

7. **Machine learning subsystem**
   The ML assets live under `backend/models_ml/`, including serialized models for crop recommendation and nutrient-related predictions (`model_N.pkl`, `model_P.pkl`, `model_K.pkl`, `crop_model.pkl`) plus label encoders for district and soil type. This indicates inference is model-file-based rather than an online training service.

8. **Training pipeline**
   `backend/train_models.py` and the CSV datasets show an offline training workflow. The training script likely reads the combined soil/fertilizer dataset, fits the random-forest-based models described in the README, and writes the `.pkl` artifacts used later by the backend.

9. **External weather dependency**
   The system integrates OpenWeatherMap for real-time weather input. That external API is part of the data flow feeding recommendations, especially because temperature is listed as an input and the backend has a dedicated weather route.

10. **Primary data flow**
   A typical request path is: user enters soil/district information in the React UI → frontend calls the backend API → backend fetches/uses weather data if needed → backend loads the ML model artifacts to generate crop/fertilizer recommendations → result is returned to the UI and optionally stored in MongoDB history.

11. **Historical and user-centric flows**
   The presence of history pages and database collections implies a second flow: recommendation results are persisted and later queried for a user’s past analyses. Authentication likely gates access to personalized history and saved data.

12. **Important architectural note**
   The README describes a Flask backend, but the repository tree shows a Node/Express backend as the active server implementation. For an architecture diagram, the safer interpretation is: React frontend → Node/Express API → MongoDB + local ML artifacts, with Python used for model training/offline generation rather than as the main serving runtime.

Main entry points: [`frontend/src/App.jsx`](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/App.jsx) (App shell), [`backend/server.js`](https://github.com/shlokapol2005/soilsense/blob/main/backend/server.js) (API server), [`backend/routes/weatherRoutes.js`](https://github.com/shlokapol2005/soilsense/blob/main/backend/routes/weatherRoutes.js) (Weather API), [`backend/train_models.py`](https://github.com/shlokapol2005/soilsense/blob/main/backend/train_models.py) (Training script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_entry["App shell<br/>React entry<br/>[App.jsx]"]
  node_frontend_boot["Main entry<br/>React bootstrap<br/>[main.jsx]"]
  node_welcome["Welcome<br/>page<br/>[WelcomeScreen.jsx]"]
  node_auth["Auth screens<br/>page set<br/>[LoginPage.jsx]"]
  node_dashboard["Dashboard<br/>page<br/>[Dashboard.jsx]"]
  node_soil["Soil analysis<br/>page<br/>[SoilAnalysis.jsx]"]
  node_weather_ui["Weather page<br/>[WeatherPage.jsx]"]
  node_calc["Calculator<br/>page<br/>[CalculatorPage.jsx]"]
  node_recs["Recommendations<br/>page"]
  node_history["History<br/>page<br/>[HistoryPage.jsx]"]
end

subgraph group_backend["Backend"]
  node_server["API server<br/>Node service<br/>[server.js]"]
  node_auth_routes["Auth API<br/>route module<br/>[authRoutes.js]"]
  node_weather_routes["Weather API<br/>route module<br/>[weatherRoutes.js]"]
  node_db_config["DB config<br/>db connector<br/>[db.js]"]
  node_user_model[("User model<br/>Mongoose model<br/>[User.js]")]
  node_weather_model[("Weather model<br/>Mongoose model<br/>[weather.js]")]
  node_mongo[("MongoDB<br/>database")]
end

subgraph group_ml["ML Assets"]
  node_model_store["Model files<br/>serialized ML<br/>[crop_model.pkl]"]
  node_train["Training script<br/>Python pipeline<br/>[train_models.py]"]
  node_datasets["Training data<br/>CSV datasets"]
end

node_openweather(("OpenWeatherMap<br/>external API"))

node_frontend_boot -->|"mounts"| node_frontend_entry
node_frontend_entry -->|"routes to"| node_welcome
node_frontend_entry -->|"routes to"| node_auth
node_frontend_entry -->|"routes to"| node_dashboard
node_frontend_entry -->|"routes to"| node_soil
node_frontend_entry -->|"routes to"| node_weather_ui
node_frontend_entry -->|"routes to"| node_calc
node_frontend_entry -->|"routes to"| node_recs
node_frontend_entry -->|"routes to"| node_history
node_frontend_entry -->|"api calls"| node_server
node_server -->|"mounts"| node_auth_routes
node_server -->|"mounts"| node_weather_routes
node_server -->|"initializes"| node_db_config
node_db_config -->|"connects"| node_mongo
node_auth_routes -->|"uses"| node_user_model
node_weather_routes -->|"uses"| node_weather_model
node_weather_routes -->|"fetches"| node_openweather
node_user_model -->|"stores in"| node_mongo
node_weather_model -->|"stores in"| node_mongo
node_server -->|"loads"| node_model_store
node_train -->|"trains on"| node_datasets
node_train -->|"writes"| node_model_store
node_soil -->|"submits data"| node_server
node_recs -->|"requests results"| node_server
node_history -->|"queries history"| node_server

click node_frontend_entry "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/App.jsx"
click node_frontend_boot "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/main.jsx"
click node_welcome "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/WelcomeScreen.jsx"
click node_auth "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/LoginPage.jsx"
click node_dashboard "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/Dashboard.jsx"
click node_soil "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/SoilAnalysis.jsx"
click node_weather_ui "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/WeatherPage.jsx"
click node_calc "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/CalculatorPage.jsx"
click node_recs "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/Recommendations.jsx"
click node_history "https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/HistoryPage.jsx"
click node_server "https://github.com/shlokapol2005/soilsense/blob/main/backend/server.js"
click node_auth_routes "https://github.com/shlokapol2005/soilsense/blob/main/backend/routes/authRoutes.js"
click node_weather_routes "https://github.com/shlokapol2005/soilsense/blob/main/backend/routes/weatherRoutes.js"
click node_db_config "https://github.com/shlokapol2005/soilsense/blob/main/backend/config/db.js"
click node_user_model "https://github.com/shlokapol2005/soilsense/blob/main/backend/models/User.js"
click node_weather_model "https://github.com/shlokapol2005/soilsense/blob/main/backend/models/weather.js"
click node_model_store "https://github.com/shlokapol2005/soilsense/blob/main/backend/models_ml/crop_model.pkl"
click node_train "https://github.com/shlokapol2005/soilsense/blob/main/backend/train_models.py"
click node_datasets "https://github.com/shlokapol2005/soilsense/blob/main/backend/Crop-and-fertilizer-dataset-combined.csv"

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_entry,node_frontend_boot,node_welcome,node_auth,node_dashboard,node_soil,node_weather_ui,node_calc,node_recs,node_history toneBlue
class node_server,node_auth_routes,node_weather_routes,node_db_config,node_user_model,node_weather_model,node_mongo toneAmber
class node_model_store,node_train,node_datasets toneMint
class node_openweather toneNeutral
```

## Components

### Frontend

React/Vite presentation layer and page flow.

- [App shell](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/App.jsx): React entry · Bootstraps the Vite/React UI and wires global app flow. · `frontend/src/App.jsx`
- [Main entry](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/main.jsx): React bootstrap · Mounts the app into the DOM and applies global styling. · `frontend/src/main.jsx`
- [Welcome](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/WelcomeScreen.jsx): page · Landing screen for first-time navigation. · `frontend/src/pages/WelcomeScreen.jsx`
- [Auth screens](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/LoginPage.jsx): page set · Login and signup UI for account access. · `frontend/src/pages/LoginPage.jsx`
- [Dashboard](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/Dashboard.jsx): page · Main user view that summarizes app state. · `frontend/src/pages/Dashboard.jsx`
- [Soil analysis](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/SoilAnalysis.jsx): page · Captures soil inputs and analysis context. · `frontend/src/pages/SoilAnalysis.jsx`
- [Weather page](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/WeatherPage.jsx): page · Shows weather data used in recommendation flows. · `frontend/src/pages/WeatherPage.jsx`
- [Calculator](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/CalculatorPage.jsx): page · Supports fertilizer or crop-related calculations. · `frontend/src/pages/CalculatorPage.jsx`
- [Recommendations](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/Recommendations.jsx): page · Displays model outputs and suggested crops or inputs. · `frontend/src/pages/Recommendations.jsx`
- [History](https://github.com/shlokapol2005/soilsense/blob/main/frontend/src/pages/HistoryPage.jsx): page · Shows prior analyses and saved prediction results. · `frontend/src/pages/HistoryPage.jsx`

### Backend

Node/Express API, persistence, and orchestration.

- [API server](https://github.com/shlokapol2005/soilsense/blob/main/backend/server.js): Node service · Express server that exposes HTTP endpoints. · `backend/server.js`
- [Auth API](https://github.com/shlokapol2005/soilsense/blob/main/backend/routes/authRoutes.js): route module · Authentication endpoints for signup and login. · `backend/routes/authRoutes.js`
- [Weather API](https://github.com/shlokapol2005/soilsense/blob/main/backend/routes/weatherRoutes.js): route module · Weather and weather-adjacent endpoints. · `backend/routes/weatherRoutes.js`
- [DB config](https://github.com/shlokapol2005/soilsense/blob/main/backend/config/db.js): db connector · MongoDB connection setup for the backend. · `backend/config/db.js`
- [User model](https://github.com/shlokapol2005/soilsense/blob/main/backend/models/User.js): Mongoose model · User account schema and persistence logic. · `backend/models/User.js`
- [Weather model](https://github.com/shlokapol2005/soilsense/blob/main/backend/models/weather.js): Mongoose model · Stored weather snapshot or forecast records. · `backend/models/weather.js`
- **MongoDB**: database · Durable store for users, weather data, and history.

### ML Assets

Offline training inputs and serialized prediction models.

- [Model files](https://github.com/shlokapol2005/soilsense/blob/main/backend/models_ml/crop_model.pkl): serialized ML · Pretrained crop and nutrient prediction artifacts. · `backend/models_ml/crop_model.pkl`
- [Training script](https://github.com/shlokapol2005/soilsense/blob/main/backend/train_models.py): Python pipeline · Offline workflow that fits and writes model artifacts. · `backend/train_models.py`
- [Training data](https://github.com/shlokapol2005/soilsense/blob/main/backend/Crop-and-fertilizer-dataset-combined.csv): CSV datasets · Source tables used to train the prediction models. · `backend/Crop-and-fertilizer-dataset-combined.csv`

### Other components

- **OpenWeatherMap**: external API · External weather provider used for live inputs.

## Connections

- Main entry → App shell: mounts · Bootstraps the app shell into the page.
- App shell → Welcome: routes to · Initial user flow starts at the welcome screen.
- App shell → Auth screens: routes to · Provides login and signup entry points.
- App shell → Dashboard: routes to · Main navigation reaches the dashboard.
- App shell → Soil analysis: routes to · Surfaces soil input and analysis screens.
- App shell → Weather page: routes to · Shows weather-related views.
- App shell → Calculator: routes to · Includes calculator functionality.
- App shell → Recommendations: routes to · Displays recommendation results.
- App shell → History: routes to · Shows past analyses and saved records.
- App shell → API server: api calls · Frontend talks to the backend over HTTP.
- API server → Auth API: mounts · Registers authentication endpoints.
- API server → Weather API: mounts · Registers weather endpoints.
- API server → DB config: initializes · Connects the service to MongoDB.
- DB config → MongoDB: connects · Establishes the database connection.
- Auth API → User model: uses · Auth operations read and write user records.
- Weather API → Weather model: uses · Weather endpoints persist or retrieve weather records.
- Weather API → OpenWeatherMap: fetches · Pulls live weather data from the external provider.
- User model → MongoDB: stores in · User documents live in MongoDB.
- Weather model → MongoDB: stores in · Weather data lives in MongoDB.
- API server → Model files: loads · Backend reads serialized models for inference.
- Training script → Training data: trains on · Offline training consumes the CSV datasets.
- Training script → Model files: writes · Training produces the model artifacts used by the app.
- Soil analysis → API server: submits data · Soil inputs are sent to the API for processing.
- Recommendations → API server: requests results · Recommendation page retrieves predictions and history.
- History → API server: queries history · History page fetches stored past analyses.