How omar-netizen/geoguardian works
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: analysis.js REST routes · App.js App shell · User.js Domain models · sentinelService.js Imagery service
Components 22
React client
Browser-facing SPA for auth, region selection, analysis views, and monitoring.
- App shell · Top-level SPA composition and route wiring.
frontend/src/App.js - Nav bar · Global navigation shell and session-aware links.
frontend/src/components/NavBar.jsx - Auth screens · Login and registration entry points.
frontend/src/pages/Login.jsx - Route guard · Client-side protection for authenticated pages.
frontend/src/components/PrivateRoute.jsx - Dashboard · Primary authenticated landing page.
frontend/src/pages/Dashboard.jsx - Map tools · Region selection and coordinate conversion UI.
frontend/src/components/MapSelector.jsx - Result views · Cards, charts, comparisons, and detail panels for analysis output.
frontend/src/components/AnalysisCharts.jsx - Monitoring UI · User interface for scheduled region monitoring.
frontend/src/pages/Monitoring.jsx - Time-lapse UI · 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 · Backend process bootstrap and server startup.
backend/index.js - REST routes · Endpoint definitions for auth, imagery, analysis, monitoring, timelapse, and preferences.
backend/routes/analysis.js - Auth guard · JWT verification and protected-request enforcement.
backend/middleware/authMiddleware.js - Imagery service · Sentinel imagery retrieval and provider-specific orchestration.
backend/services/sentinelService.js - Change detection · Image comparison and severity/type derivation.
backend/services/changeDetectionService.js - Timelapse service · Collects and prepares frame sequences over a date range.
backend/services/timelapseService.js - Scheduler · Periodic monitoring loop for watched regions.
backend/services/schedulerService.js - Email alerts · 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 · Primary durable store for users, analyses, preferences, and monitoring state.
backend/config/db.js - GridFS · Large image and frame asset storage backed by MongoDB file storage.
backend/config/gridfs.js - Domain models · User, Analysis, ImageMeta, MonitoredRegion, and Preference documents.
backend/models/User.js
External services
Third-party systems used for imagery and notification delivery.
- Sentinel Hub · External satellite imagery provider consumed by the backend.
- SMTP email · Outbound email infrastructure used for notifications.
Connections 28
- 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.