# omar-netizen/geoguardian architecture

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

- Interactive diagram: https://gitdiagram.com/omar-netizen/geoguardian
- Repository: https://github.com/omar-netizen/geoguardian

## Overview

GeoGuardian is a two-tier application with a React single-page frontend and a Node/Express backend that orchestrates satellite imagery access, image analysis, persistence, scheduled monitoring, and email alerts.

At a high level, the architecture is split into these main boundaries:

1. Browser UI layer
2. API/server layer
3. Persistence layer
4. External services layer

#### 1) Frontend: React SPA

The `frontend` directory is a client application built with React.

##### Main responsibilities
- Authentication screens and session-gated navigation
- Map-based region selection and coordinate input
- Requesting satellite imagery and analysis from the backend
- Displaying results as cards, charts, comparison views, and time-lapse views
- Managing protected pages via route guards

##### Main frontend pages
- `Home`
- `Login`
- `Register`
- `Dashboard`
- `Monitoring`
- `CompareImages`
- `TimeLapse`
- `AnalysisHistory`

##### Main frontend components
- `NavBar`: global navigation shell
- `PrivateRoute`: client-side access control for authenticated pages
- `MapSelector`: geographic region selection UI
- `CoordinatesConverter`: converts user inputs into bounding-box-style coordinates
- `AnalysisCard`, `AnalysisCharts`, `AnalysisDetail`: visualization of analysis results

##### Frontend-to-backend boundary
The frontend talks to the backend over HTTP using the API base URL in `src/config.js`. It does not directly access satellite providers, the database, or email services. Those are all backend concerns.

#### 2) Backend: Express API server

The `backend` directory is the system’s control plane. `index.js` is the server entry point.

##### Main responsibilities
- Expose REST endpoints for auth, imagery, analysis, monitoring, timelapse, and preferences
- Validate and authorize requests
- Persist domain data in MongoDB
- Retrieve/store image assets through MongoDB GridFS
- Call external imagery APIs
- Run background monitoring jobs
- Trigger email notifications

##### Backend structure pattern
The backend is organized into a typical layered Express structure:

- `routes/`: HTTP endpoint definitions
- `controllers/`: request handling and response shaping
- `services/`: domain logic and integration with external systems
- `models/`: MongoDB/Mongoose domain schemas
- `middleware/`: cross-cutting request concerns such as auth
- `config/`: database and storage wiring

This separation is important architecturally: routes are thin, controllers coordinate request/response flow, services contain the business logic, and models define persisted entities.

#### 3) Core backend subsystems

##### A. Authentication and protected access
Files involved:
- `routes/auth.js`
- `middleware/authMiddleware.js`
- `models/User.js`
- `routes/protected.js`

This subsystem handles user registration, login, and JWT-protected access. The frontend’s `PrivateRoute` works together with backend JWT protection: the browser gates navigation, while the backend enforces actual authorization on sensitive endpoints.

##### B. Satellite imagery acquisition
Files involved:
- `routes/nasa.js`
- `controllers/nasacontroller.js`
- `services/sentinelService.js`
- `services/nasaService.js.backup`

Despite the `nasa` naming, the README and file set indicate the real imagery source is Sentinel Hub / Sentinel-2. This subsystem fetches satellite imagery for a given region and time window, likely based on bounding box and date parameters from the frontend.

The backend is the only place that talks to external imagery providers. This keeps API credentials and provider-specific logic out of the browser.

##### C. Change detection and analysis
Files involved:
- `routes/changeDetection.js`
- `controllers/changeDetectionController.js`
- `services/changeDetectionService.js`
- `models/Analysis.js`
- `models/ImageMeta.js`

This is one of the main application subsystems. It compares two satellite images and derives:
- change severity
- change type
- analysis metadata
- stored analysis history

The likely flow is:
1. Frontend submits two images or two image references plus region/date context.
2. Backend runs image comparison logic in `changeDetectionService`.
3. Results are persisted in `Analysis` and related image metadata records.
4. Frontend renders history and detail views.

This subsystem is the main “AI-powered” value proposition, even if the actual algorithm is pixel-based RGB analysis rather than a large model.

##### D. Time-lapse generation
Files involved:
- `routes/timelapse.js`
- `controllers/timelapseController.js`
- `services/timelapseService.js`

This subsystem creates a sequence of images over time for the same region and returns them in a form the UI can animate or step through. It depends on satellite image retrieval and on stored image/frame metadata. The frontend’s `TimeLapse` page is the presentation layer for this workflow.

##### E. Automated monitoring and scheduling
Files involved:
- `routes/monitoring.js`
- `controllers/monitoringController.js`
- `services/schedulerService.js`
- `models/MonitoredRegion.js`

This subsystem stores user-defined regions that should be checked on a schedule. `schedulerService` suggests background cron-style execution rather than only request/response behavior.

The monitoring flow is:
1. User creates a monitored region from the frontend.
2. Region configuration is stored in MongoDB.
3. The scheduler periodically checks each region.
4. If notable change is found, it can trigger analysis and notifications.

This is a key architectural boundary because it introduces asynchronous background work in addition to interactive API calls.

##### F. Email notifications
Files involved:
- `services/emailService.js`

Email is used as an outbound notification channel, most likely for monitoring alerts and high-severity detections. This is separate from the main request path and likely called by the monitoring or change detection services.

##### G. Preferences
Files involved:
- `routes/preferences.js`
- `models/Preference.js`

This subsystem stores user-specific configuration. In a system like this, preferences are typically tied to alert settings, monitoring frequency, or notification preferences. It acts as user-owned configuration state separate from the core analysis history.

#### 4) Persistence layer

##### MongoDB
Files involved:
- `config/db.js`
- Models in `backend/models/`

MongoDB is the main structured data store for:
- users
- analyses
- monitored regions
- preferences
- image metadata

This is the durable state for authentication, analysis history, and monitoring configuration.

##### GridFS
Files involved:
- `config/gridfs.js`

GridFS is used for large binary assets, likely satellite images and generated frames or comparison artifacts. This is a strong architectural signal: metadata lives in MongoDB collections, while image blobs are stored in MongoDB’s file storage mechanism.

That separation matters for diagramming:
- structured documents in collections
- large image files in GridFS
- references between the two via IDs/metadata records

#### 5) External services and infrastructure

##### Sentinel Hub / Sentinel-2 imagery
The app depends on external satellite imagery APIs. The README mentions Sentinel Hub and Sentinel-2. The backend abstracts this provider behind the imagery service/controller stack.

##### Email SMTP
`emailService` and the README’s Gmail setup indicate outbound email is part of the architecture. This is likely configured with app passwords / SMTP credentials.

##### JWT authentication
JWT is used for stateless auth tokens between frontend and backend.

##### Deployment targets
The README indicates:
- Frontend deployed on Vercel
- Backend deployed on Render
- Database hosted on MongoDB Atlas

For architecture diagrams, this means the frontend and backend are independently deployed, with the backend reaching out to both MongoDB Atlas and external APIs.

#### 6) Important data flows

##### User authentication flow
1. User opens React app.
2. User registers or logs in through auth screens.
3. Backend validates credentials, hashes passwords, issues JWT.
4. Frontend stores and uses the token for protected API calls.
5. `PrivateRoute` gates access to authenticated pages.

##### Imagery retrieval flow
1. User chooses region/date parameters in the UI.
2. Frontend sends request to backend imagery endpoint.
3. Backend calls Sentinel imagery service.
4. Retrieved image or metadata is stored/referenced through MongoDB/GridFS.
5. Backend returns image references or URLs to the frontend.

##### Change detection flow
1. User selects two dates or two images for comparison.
2. Backend pulls the required imagery.
3. `changeDetectionService` computes differences and severity.
4. Results are saved in `Analysis`.
5. Frontend renders charts, details, and comparison visuals.

##### Time-lapse flow
1. User requests a time-lapse for a region and date range.
2. Backend gathers frames from satellite data.
3. `timelapseService` prepares the sequence.
4. Frontend displays the animation or frame list.

##### Automated monitoring flow
1. User creates a monitored region and schedule.
2. Region is persisted in MongoDB.
3. `schedulerService` periodically checks all active regions.
4. If change exceeds a threshold, backend performs analysis.
5. `emailService` sends alert notifications.

#### 7) Architectural boundaries to show in a diagram

If you draw this repository, the main boxes should be:

- **React client**
  - UI, routing, map tools, charts, auth screens
- **Express API**
  - route layer, controllers, services, middleware
- **MongoDB**
  - user/config/analysis/monitoring state
- **GridFS**
  - satellite imagery and generated image assets
- **Sentinel Hub / external satellite provider**
  - imagery source
- **Email service / SMTP**
  - notification delivery
- **Scheduler / cron worker**
  - background monitoring loop

#### 8) Summary of the system shape

GeoGuardian is not just a CRUD app; it is a hybrid of:
- interactive geospatial UI
- authenticated API backend
- image-processing pipeline
- scheduled background monitoring
- alerting system

The key architectural idea is that the frontend is only a presentation and interaction layer, while the backend centralizes all sensitive integrations and all heavy lifting: satellite retrieval, image analysis, persistence, scheduling, and notifications.

Main entry points: [`backend/routes/analysis.js`](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/routes/analysis.js) (REST routes), [`frontend/src/App.js`](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/App.js) (App shell), [`backend/models/User.js`](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/models/User.js) (Domain models), [`backend/services/sentinelService.js`](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/services/sentinelService.js) (Imagery service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "React client"
  frontend_app["App shell<br/>react entry<br/>[App.js]"]
  frontend_nav["Nav bar<br/>layout component<br/>[NavBar.jsx]"]
  frontend_auth["Auth screens<br/>pages<br/>[Login.jsx]"]
  frontend_private{{"Route guard<br/>access control<br/>[PrivateRoute.jsx]"}}
  frontend_dashboard["Dashboard<br/>workspace page<br/>[Dashboard.jsx]"]
  frontend_geo["Map tools<br/>geo inputs<br/>[MapSelector.jsx]"]
  frontend_views["Result views<br/>visualization<br/>[AnalysisCharts.jsx]"]
  frontend_monitoring["Monitoring UI<br/>page<br/>[Monitoring.jsx]"]
  frontend_timelapse["Time-lapse UI<br/>page<br/>[TimeLapse.jsx]"]
end

subgraph "Express API"
  api_entry["Server entry<br/>express app<br/>[index.js]"]
  api_routes["REST routes<br/>http layer<br/>[analysis.js]"]
  api_auth{{"Auth guard<br/>middleware<br/>[authMiddleware.js]"}}
  api_img["Imagery service<br/>provider adapter<br/>[sentinelService.js]"]
  api_change["Change detection<br/>analysis service"]
  api_time["Timelapse service<br/>sequence builder"]
  api_sched(("Scheduler<br/>background job"))
  api_mail["Email alerts<br/>notification service<br/>[emailService.js]"]
end

subgraph "Persistence"
  db_main[("MongoDB<br/>document store<br/>[db.js]")]
  db_gridfs[("GridFS<br/>binary store<br/>[gridfs.js]")]
  model_core["Domain models<br/>schemas<br/>[User.js]"]
end

subgraph "External services"
  ext_satellite(("Sentinel Hub<br/>imagery API"))
  ext_smtp(("SMTP email<br/>mail relay"))
end

frontend_app -->|"composes"| frontend_nav
frontend_app -->|"routes via"| frontend_private
frontend_app -->|"shows"| frontend_auth
frontend_app -->|"opens"| frontend_dashboard
frontend_app -->|"collects region"| frontend_geo
frontend_app -->|"renders results"| frontend_views
frontend_app -->|"manages alerts"| frontend_monitoring
frontend_app -->|"plays sequence"| frontend_timelapse
frontend_geo -->|"calls API"| api_routes
frontend_auth -->|"auth requests"| api_routes
frontend_views -->|"fetches analysis"| api_routes
frontend_monitoring -->|"configures monitoring"| api_routes
frontend_timelapse -->|"requests frames"| api_routes
api_entry -->|"mounts"| api_routes
api_routes -->|"protects"| api_auth
api_routes -->|"retrieves imagery"| api_img
api_routes -->|"detects change"| api_change
api_routes -->|"builds timelapse"| api_time
api_routes -->|"registers jobs"| api_sched
api_sched -->|"sends alerts"| api_mail
api_change -->|"stores analysis"| model_core
api_sched -->|"reads regions"| model_core
api_img -->|"fetches data"| ext_satellite
api_mail -->|"delivers mail"| ext_smtp
model_core -->|"persists in"| db_main
model_core -->|"references files"| db_gridfs
api_change -->|"consumes imagery"| api_img
api_time -->|"collects frames"| api_img

click frontend_app "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/App.js"
click frontend_nav "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/components/NavBar.jsx"
click frontend_auth "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/pages/Login.jsx"
click frontend_private "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/components/PrivateRoute.jsx"
click frontend_dashboard "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/pages/Dashboard.jsx"
click frontend_geo "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/components/MapSelector.jsx"
click frontend_views "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/components/AnalysisCharts.jsx"
click frontend_monitoring "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/pages/Monitoring.jsx"
click frontend_timelapse "https://github.com/omar-netizen/geoguardian/blob/main/frontend/src/pages/TimeLapse.jsx"
click api_entry "https://github.com/omar-netizen/geoguardian/blob/main/backend/index.js"
click api_routes "https://github.com/omar-netizen/geoguardian/blob/main/backend/routes/analysis.js"
click api_auth "https://github.com/omar-netizen/geoguardian/blob/main/backend/middleware/authMiddleware.js"
click api_img "https://github.com/omar-netizen/geoguardian/blob/main/backend/services/sentinelService.js"
click api_change "https://github.com/omar-netizen/geoguardian/blob/main/backend/services/changeDetectionService.js"
click api_time "https://github.com/omar-netizen/geoguardian/blob/main/backend/services/timelapseService.js"
click api_sched "https://github.com/omar-netizen/geoguardian/blob/main/backend/services/schedulerService.js"
click api_mail "https://github.com/omar-netizen/geoguardian/blob/main/backend/services/emailService.js"
click db_main "https://github.com/omar-netizen/geoguardian/blob/main/backend/config/db.js"
click db_gridfs "https://github.com/omar-netizen/geoguardian/blob/main/backend/config/gridfs.js"
click model_core "https://github.com/omar-netizen/geoguardian/blob/main/backend/models/User.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 frontend_app,frontend_nav,frontend_auth,frontend_private,frontend_dashboard,frontend_geo,frontend_views,frontend_monitoring,frontend_timelapse toneBlue
class api_entry,api_routes,api_auth,api_img,api_change,api_time,api_sched,api_mail toneAmber
class db_main,db_gridfs,model_core toneMint
class ext_satellite,ext_smtp toneRose
```

## Components

### React client

Browser-facing SPA for auth, region selection, analysis views, and monitoring.

- [App shell](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/App.js): react entry · Top-level SPA composition and route wiring. · `frontend/src/App.js`
- [Nav bar](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/components/NavBar.jsx): layout component · Global navigation shell and session-aware links. · `frontend/src/components/NavBar.jsx`
- [Auth screens](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/pages/Login.jsx): pages · Login and registration entry points. · `frontend/src/pages/Login.jsx`
- [Route guard](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/components/PrivateRoute.jsx): access control · Client-side protection for authenticated pages. · `frontend/src/components/PrivateRoute.jsx`
- [Dashboard](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/pages/Dashboard.jsx): workspace page · Primary authenticated landing page. · `frontend/src/pages/Dashboard.jsx`
- [Map tools](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/components/MapSelector.jsx): geo inputs · Region selection and coordinate conversion UI. · `frontend/src/components/MapSelector.jsx`
- [Result views](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/components/AnalysisCharts.jsx): visualization · Cards, charts, comparisons, and detail panels for analysis output. · `frontend/src/components/AnalysisCharts.jsx`
- [Monitoring UI](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/pages/Monitoring.jsx): page · User interface for scheduled region monitoring. · `frontend/src/pages/Monitoring.jsx`
- [Time-lapse UI](https://github.com/omar-netizen/geoguardian/blob/HEAD/frontend/src/pages/TimeLapse.jsx): page · Frame-based playback and inspection of regional change over time. · `frontend/src/pages/TimeLapse.jsx`

### Express API

Server-side control plane for auth, imagery, analysis, monitoring, and alerts.

- [Server entry](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/index.js): express app · Backend process bootstrap and server startup. · `backend/index.js`
- [REST routes](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/routes/analysis.js): http layer · Endpoint definitions for auth, imagery, analysis, monitoring, timelapse, and preferences. · `backend/routes/analysis.js`
- [Auth guard](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/middleware/authMiddleware.js): middleware · JWT verification and protected-request enforcement. · `backend/middleware/authMiddleware.js`
- [Imagery service](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/services/sentinelService.js): provider adapter · Sentinel imagery retrieval and provider-specific orchestration. · `backend/services/sentinelService.js`
- [Change detection](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/services/changeDetectionService.js): analysis service · Image comparison and severity/type derivation. · `backend/services/changeDetectionService.js`
- [Timelapse service](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/services/timelapseService.js): sequence builder · Collects and prepares frame sequences over a date range. · `backend/services/timelapseService.js`
- [Scheduler](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/services/schedulerService.js): background job · Periodic monitoring loop for watched regions. · `backend/services/schedulerService.js`
- [Email alerts](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/services/emailService.js): notification service · Outbound email delivery for monitoring and high-severity events. · `backend/services/emailService.js`

### Persistence

MongoDB collections and GridFS storage for structured state and image assets.

- [MongoDB](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/config/db.js): document store · Primary durable store for users, analyses, preferences, and monitoring state. · `backend/config/db.js`
- [GridFS](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/config/gridfs.js): binary store · Large image and frame asset storage backed by MongoDB file storage. · `backend/config/gridfs.js`
- [Domain models](https://github.com/omar-netizen/geoguardian/blob/HEAD/backend/models/User.js): schemas · User, Analysis, ImageMeta, MonitoredRegion, and Preference documents. · `backend/models/User.js`

### External services

Third-party systems used for imagery and notification delivery.

- **Sentinel Hub**: imagery API · External satellite imagery provider consumed by the backend.
- **SMTP email**: mail relay · Outbound email infrastructure used for notifications.

## Connections

- App shell → Nav bar: composes · The SPA shell renders global navigation.
- App shell → Route guard: routes via · Authenticated pages are wrapped in client-side access control.
- App shell → Auth screens: shows · Unauthenticated access leads to login and registration screens.
- App shell → Dashboard: opens · Authenticated users land in the main workspace.
- App shell → Map tools: collects region · The UI captures bounding boxes and coordinates.
- App shell → Result views: renders results · Analysis output is presented through cards, charts, and detail views.
- App shell → Monitoring UI: manages alerts · Users configure scheduled region checks from the client.
- App shell → Time-lapse UI: plays sequence · The client displays time-based image sequences.
- Map tools → REST routes: calls API · Region and coordinate input is sent to backend endpoints.
- Auth screens → REST routes: auth requests · Login and registration submit to the REST API.
- Result views → REST routes: fetches analysis · Visualization components read analysis and history data from the server.
- Monitoring UI → REST routes: configures monitoring · Monitoring pages create and update watched regions.
- Time-lapse UI → REST routes: requests frames · Time-lapse views load image sequences from the server.
- Server entry → REST routes: mounts · The server bootstraps and exposes the route layer.
- REST routes → Auth guard: protects · Sensitive endpoints rely on JWT verification.
- REST routes → Imagery service: retrieves imagery · Imagery endpoints delegate to the satellite provider adapter.
- REST routes → Change detection: detects change · Comparison endpoints invoke image-difference analysis.
- REST routes → Timelapse service: builds timelapse · Timelapse endpoints assemble ordered image frames.
- REST routes → Scheduler: registers jobs · Monitoring endpoints feed the background scheduler.
- Scheduler → Email alerts: sends alerts · Scheduler-triggered checks can emit notifications.
- Change detection → Domain models: stores analysis · Results are persisted in analysis and metadata documents.
- Scheduler → Domain models: reads regions · The scheduler loads monitored region definitions and preferences.
- Imagery service → Sentinel Hub: fetches data · The backend is the only component that talks to imagery providers.
- Email alerts → SMTP email: delivers mail · Notification messages are relayed through outbound email infrastructure.
- Domain models → MongoDB: persists in · Application documents are stored in MongoDB collections.
- Domain models → GridFS: references files · Image metadata points to large assets stored in GridFS.
- Change detection → Imagery service: consumes imagery · Change detection depends on retrieved satellite images.
- Timelapse service → Imagery service: collects frames · Time-lapse generation pulls image samples from the imagery service.
