# oilycaptain/soilsense-web-admin architecture

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

- Interactive diagram: https://gitdiagram.com/oilycaptain/soilsense-web-admin
- Repository: https://github.com/oilycaptain/soilsense-web-admin

## Overview

SoilSense Admin Web combines a public product landing page, verified administrator sign-in, a Firestore-backed operations portal, and a small HTTP API. The main admin workflow is sign in and verify admin access, then inspect or manage accounts, device ownership and health, support tickets, analytics, audit activity, and saved preferences. Firestore is the operational data source; farmers and technicians use the separate mobile app, and the device is managed rather than operated through this web portal. Some unsampled page-to-data links are supported by the SOURCE INDEX; no mobile or device implementation is included.

Main entry points: [`frontend/src/admin/AdminLayout.jsx`](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/AdminLayout.jsx) (Admin navigation), [`frontend/src/admin/services/adminFirestore.js`](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/services/adminFirestore.js) (Admin data access), [`backend/router.js`](https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/router.js) (Request router), [`frontend/src/App.jsx`](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/App.jsx) (Web app routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public site"]
  node_landing["Landing page<br/>[LandingPage.jsx]"]
  node_app["Web app routes<br/>[App.jsx]"]
end

subgraph group_identity["Admin identity"]
  node_authpages["Sign-in and signup"]
  node_authcontext["Admin session<br/>[AuthContext.jsx]"]
  node_protected["Route protection<br/>[ProtectedRoute.jsx]"]
  node_firebase["Firebase client<br/>[firebase.js]"]
end

subgraph group_portal["Admin operations"]
  node_adminlayout["Admin navigation<br/>[AdminLayout.jsx]"]
  node_dashboard["Dashboard and alerts<br/>[AdminDashboard.jsx]"]
  node_farmers["Farmer management<br/>[Farmers.jsx]"]
  node_devices["Device management<br/>[Devices.jsx]"]
  node_support["Support tickets<br/>[Support.jsx]"]
  node_analytics["Reports analytics"]
  node_activity["Audit activity<br/>[ActivityLog.jsx]"]
  node_settings["Admin settings<br/>[AdminSettings.jsx]"]
  node_preferences["Saved preferences"]
  node_adminfirestore["Admin data access<br/>[adminFirestore.js]"]
end

subgraph group_api["HTTP API"]
  node_server["API server<br/>[server.js]"]
  node_router["Request router<br/>[router.js]"]
  node_authroute["Admin identity route<br/>[auth.js]"]
  node_adminroute["Admin data routes<br/>[adminData.js]"]
  node_deviceroute["Device route<br/>[device.js]"]
  node_healthroute["Health route<br/>[health.js]"]
  node_token["Firebase token check<br/>[firebaseToken.js]"]
end

node_visitor(("Public visitor"))
node_admin(("Administrator"))
node_firestore[("SoilSense Firestore")]
node_identityservice["Firebase Identity"]
node_device(("SoilSense device"))
node_mobile(("Farmer mobile app"))

node_visitor -->|"visits"| node_landing
node_landing -->|"links to signup"| node_app
node_app -->|"routes to"| node_authpages
node_app -->|"routes admin"| node_adminlayout
node_admin -->|"signs in"| node_authpages
node_authpages -->|"uses session"| node_authcontext
node_authcontext -->|"authenticates with"| node_firebase
node_authcontext -->|"checks admin profile"| node_firestore
node_adminlayout -->|"guards portal"| node_protected
node_adminlayout -->|"routes to"| node_dashboard
node_adminlayout -->|"routes to"| node_farmers
node_adminlayout -->|"routes to"| node_devices
node_adminlayout -->|"routes to"| node_support
node_adminlayout -->|"routes to"| node_analytics
node_adminlayout -->|"routes to"| node_activity
node_adminlayout -->|"routes to"| node_settings
node_adminlayout -->|"provides preferences"| node_preferences
node_dashboard -->|"loads operational stats"| node_adminfirestore
node_farmers -->|"manages accounts"| node_adminfirestore
node_devices -->|"manages ownership"| node_adminfirestore
node_support -->|"manages tickets"| node_adminfirestore
node_analytics -->|"loads aggregates"| node_adminfirestore
node_activity -->|"loads audit trail"| node_adminfirestore
node_preferences -->|"reads and saves"| node_adminfirestore
node_settings -->|"uses password reset"| node_firebase
node_adminfirestore -->|"uses Firestore client"| node_firebase
node_adminfirestore -->|"reads and writes"| node_firestore
node_device -.->|"reports device state"| node_firestore
node_mobile -.->|"provides account and scan data"| node_firestore
node_server -->|"dispatches requests"| node_router
node_router -->|"dispatches health"| node_healthroute
node_router -->|"dispatches auth"| node_authroute
node_router -->|"dispatches admin data"| node_adminroute
node_router -->|"dispatches device"| node_deviceroute
node_authroute -->|"requires admin"| node_token
node_adminroute -->|"checks admin token"| node_token
node_token -->|"looks up token"| node_identityservice

click node_landing "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/landing/LandingPage.jsx"
click node_app "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/App.jsx"
click node_authpages "https://github.com/oilycaptain/soilsense-web-admin/tree/main/frontend/src/auth/pages"
click node_authcontext "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/auth/context/AuthContext.jsx"
click node_protected "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/auth/components/ProtectedRoute.jsx"
click node_firebase "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/services/firebase.js"
click node_adminlayout "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/AdminLayout.jsx"
click node_dashboard "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/AdminDashboard.jsx"
click node_farmers "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/Farmers.jsx"
click node_devices "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/Devices.jsx"
click node_support "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/Support.jsx"
click node_analytics "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/ReportsAnalytics.jsx"
click node_activity "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/ActivityLog.jsx"
click node_settings "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/AdminSettings.jsx"
click node_preferences "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/context/AdminPreferencesContext.jsx"
click node_adminfirestore "https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/services/adminFirestore.js"
click node_server "https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/server.js"
click node_router "https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/router.js"
click node_authroute "https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/routes/auth.js"
click node_adminroute "https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/routes/adminData.js"
click node_deviceroute "https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/routes/device.js"
click node_healthroute "https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/routes/health.js"
click node_token "https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/auth/firebaseToken.js"

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_landing,node_app toneBlue
class node_authpages,node_authcontext,node_protected,node_firebase,node_firestore toneAmber
class node_adminlayout,node_dashboard,node_farmers,node_devices,node_support,node_analytics,node_activity,node_settings,node_preferences,node_adminfirestore toneMint
class node_server,node_router,node_authroute,node_adminroute,node_deviceroute,node_healthroute,node_token toneRose
class node_visitor,node_admin,node_identityservice,node_device,node_mobile toneIndigo
```

## Components

### Public site

- [Landing page](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/landing/LandingPage.jsx): `frontend/src/landing/LandingPage.jsx`
- [Web app routes](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`

### Admin identity

- [Sign-in and signup](https://github.com/oilycaptain/soilsense-web-admin/tree/main/frontend/src/auth/pages): `frontend/src/auth/pages`
- [Admin session](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/auth/context/AuthContext.jsx): `frontend/src/auth/context/AuthContext.jsx`
- [Route protection](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/auth/components/ProtectedRoute.jsx): `frontend/src/auth/components/ProtectedRoute.jsx`
- [Firebase client](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/services/firebase.js): `frontend/src/services/firebase.js`

### Admin operations

- [Admin navigation](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/AdminLayout.jsx): `frontend/src/admin/AdminLayout.jsx`
- [Dashboard and alerts](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/AdminDashboard.jsx): `frontend/src/admin/pages/AdminDashboard.jsx`
- [Farmer management](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/Farmers.jsx): `frontend/src/admin/pages/Farmers.jsx`
- [Device management](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/Devices.jsx): `frontend/src/admin/pages/Devices.jsx`
- [Support tickets](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/Support.jsx): `frontend/src/admin/pages/Support.jsx`
- [Reports analytics](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/ReportsAnalytics.jsx): `frontend/src/admin/pages/ReportsAnalytics.jsx`
- [Audit activity](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/ActivityLog.jsx): `frontend/src/admin/pages/ActivityLog.jsx`
- [Admin settings](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/pages/AdminSettings.jsx): `frontend/src/admin/pages/AdminSettings.jsx`
- [Saved preferences](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/context/AdminPreferencesContext.jsx): `frontend/src/admin/context/AdminPreferencesContext.jsx`
- [Admin data access](https://github.com/oilycaptain/soilsense-web-admin/blob/main/frontend/src/admin/services/adminFirestore.js): `frontend/src/admin/services/adminFirestore.js`

### HTTP API

- [API server](https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/server.js): `backend/server.js`
- [Request router](https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/router.js): `backend/router.js`
- [Admin identity route](https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [Admin data routes](https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/routes/adminData.js): `backend/routes/adminData.js`
- [Device route](https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/routes/device.js): `backend/routes/device.js`
- [Health route](https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/routes/health.js): `backend/routes/health.js`
- [Firebase token check](https://github.com/oilycaptain/soilsense-web-admin/blob/main/backend/auth/firebaseToken.js): `backend/auth/firebaseToken.js`

### Other components

- **Public visitor**
- **Administrator**
- **SoilSense Firestore**
- **Firebase Identity**
- **SoilSense device**
- **Farmer mobile app**

## Connections

- Public visitor → Landing page: visits
- Landing page → Web app routes: links to signup (evidence: `frontend/src/landing/LandingPage.jsx`)
- Web app routes → Sign-in and signup: routes to (evidence: `frontend/src/App.jsx`)
- Web app routes → Admin navigation: routes admin (evidence: `frontend/src/App.jsx`)
- Administrator → Sign-in and signup: signs in
- Sign-in and signup → Admin session: uses session (evidence: `frontend/src/auth/pages/Login.jsx`)
- Admin session → Firebase client: authenticates with (evidence: `frontend/src/auth/context/AuthContext.jsx`)
- Admin session → SoilSense Firestore: checks admin profile (evidence: `frontend/src/auth/context/AuthContext.jsx`)
- Admin navigation → Route protection: guards portal (evidence: `frontend/src/App.jsx`)
- Admin navigation → Dashboard and alerts: routes to (evidence: `frontend/src/App.jsx`)
- Admin navigation → Farmer management: routes to (evidence: `frontend/src/App.jsx`)
- Admin navigation → Device management: routes to (evidence: `frontend/src/App.jsx`)
- Admin navigation → Support tickets: routes to (evidence: `frontend/src/App.jsx`)
- Admin navigation → Reports analytics: routes to (evidence: `frontend/src/App.jsx`)
- Admin navigation → Audit activity: routes to (evidence: `frontend/src/App.jsx`)
- Admin navigation → Admin settings: routes to (evidence: `frontend/src/App.jsx`)
- Admin navigation → Saved preferences: provides preferences (evidence: `frontend/src/App.jsx`)
- Dashboard and alerts → Admin data access: loads operational stats (evidence: `frontend/src/admin/pages/AdminDashboard.jsx`)
- Farmer management → Admin data access: manages accounts (evidence: `frontend/src/admin/pages/Farmers.jsx`)
- Device management → Admin data access: manages ownership (evidence: `frontend/src/admin/pages/Devices.jsx`)
- Support tickets → Admin data access: manages tickets (evidence: `frontend/src/admin/pages/Support.jsx`)
- Reports analytics → Admin data access: loads aggregates (evidence: `frontend/src/admin/pages/ReportsAnalytics.jsx`)
- Audit activity → Admin data access: loads audit trail (evidence: `frontend/src/admin/pages/ActivityLog.jsx`)
- Saved preferences → Admin data access: reads and saves (evidence: `frontend/src/admin/context/AdminPreferencesContext.jsx`)
- Admin settings → Firebase client: uses password reset (evidence: `frontend/src/admin/pages/AdminSettings.jsx`)
- Admin data access → Firebase client: uses Firestore client (evidence: `frontend/src/admin/services/adminFirestore.js`)
- Admin data access → SoilSense Firestore: reads and writes (evidence: `frontend/src/admin/services/adminFirestore.js`)
- SoilSense device → SoilSense Firestore: reports device state (evidence: `README.md`)
- Farmer mobile app → SoilSense Firestore: provides account and scan data (evidence: `README.md`)
- API server → Request router: dispatches requests (evidence: `backend/server.js`)
- Request router → Health route: dispatches health (evidence: `backend/router.js`)
- Request router → Admin identity route: dispatches auth (evidence: `backend/router.js`)
- Request router → Admin data routes: dispatches admin data (evidence: `backend/router.js`)
- Request router → Device route: dispatches device (evidence: `backend/router.js`)
- Admin identity route → Firebase token check: requires admin (evidence: `backend/routes/auth.js`)
- Admin data routes → Firebase token check: checks admin token (evidence: `backend/routes/adminData.js`)
- Firebase token check → Firebase Identity: looks up token (evidence: `backend/auth/firebaseToken.js`)
