How omborekar/terraspotter-mapping-the-right-place-to-plant works
1. Overall shape
TerraSpotter is a three-part system: a Spring Boot backend for core business logic and persistence, a React/Vite frontend for the user experience, and a separate Flask ML service for tree recommendation predictions. The backend is the main system of record; the frontend is a thin client; the ML service is an external dependency.
2. Backend boundary and responsibilities
The backend (backend/) owns authentication, user management, land registration, land verification, plantation tracking, reviews, and aggregate stats. Its controllers are split by domain: Auth, ForgotPassword, User, Land, LandVerification, Plantation, and Stats. This is a conventional layered Spring architecture: controller → service → repository → database.
3. Domain model
The backend’s entities show the business concepts explicitly: User, Land, LandImage, LandRecommendation, LandReview, LandVerification, PlantationStart, PlantationCompletion, PlantationCompletionImage, PlantationReview, and PlantationReviewImage. This suggests a workflow where a land parcel is registered, reviewed/verified, matched with recommendations, and then tracked through plantation start/completion and post-planting feedback.
4. Persistence and schema
Data is persisted through Spring Data repositories and initialized via Flyway (backend/src/main/resources/db/migration/V1__init.sql). The repository layer is separated by aggregate, e.g. LandRepository, LandVerificationRepository, PlantationStartRepository, UserRepository, and image/review repositories. The README indicates PostgreSQL is the intended database, with configuration managed in application.properties.
5. Authentication and security
Security is centralized in SecurityConfig with CustomUserDetailsService backing Spring Security user lookup. AuthService, AuthController, SignupRequest, and LoginRequest indicate standard login/signup flows. Password recovery is handled separately by ForgotPasswordController, BrevoEmailService, and OtpStore, which implies email-based OTP reset flow with temporary in-memory OTP state.
6. External storage and media
Image uploads are offloaded to Cloudinary via CloudinaryConfig and CloudinaryService. This is important to the architecture because land images and plantation review/completion images are modeled separately in the database, while the actual binary media is stored externally. The backend therefore manages metadata and references, not file blobs.
7. Land intelligence and recommendation flow
The “smart” part of the platform is centered on land evaluation. LandService, LandRecommendation, and LandVerificationService indicate a pipeline where land attributes and images are captured, then reviewed/verified, and finally used to generate recommendations or readiness status. This is the main bridge between user-submitted land data and the recommendation/plantation workflow.
8. Plantation coordination and showcase
The plantation side is tracked separately from land registration. PlantationStart, PlantationCompletion, and the corresponding image entities model project progress over time. PlantationShowcaseService and PlantationShowcaseDTO suggest a curated view of planting projects for public or community-facing display, distinct from the internal operational records.
9. Stats and reporting
StatsController and StatsService form a read-only aggregation layer for analytics or dashboard metrics. This is likely derived from the transactional domain tables rather than maintained as a separate source of truth, so it acts as a reporting boundary over the core operational data.
10. Frontend application structure
The frontend (frontend/) is a Vite + React app composed of page-like components such as Landing, Browse, SiteDetail, Login, Signup, ForgotPassword, Profile, PlantationForm, Reviewspage, AdminPendingLands, and AdminLandDetail. ProtectedRoute indicates route-level access control on the client, while Navbar, Main, and App.jsx orchestrate navigation and page layout.
11. Frontend-to-backend interaction
The frontend is responsible for user interaction and calls the backend API for auth, land browsing, profile operations, and plantation workflows. frontend/src/lib/utils.js likely centralizes API base URL configuration, which makes the client deployable across environments. The React UI also includes specialized components such as ContributionMap and modal/form components for plantation completion, showing that map-driven land exploration is a major UX path.
12. ML service boundary
The models/ directory is a separate Flask application, not part of the Spring runtime. It loads a pre-trained model from tree_model.pkl and data from data.csv, exposing a /predict endpoint with environmental inputs (temp, rainfall, soil, climate). This service is an external inference engine for species recommendation and is intentionally decoupled from the main app stack.
13. Deployment and packaging
The repo contains independent deployment artifacts for each subsystem: backend/Dockerfile for the Spring app, frontend/vercel.json for frontend hosting, and Python packaging in models/requirements.txt. This supports separate scaling and deployment of the API, UI, and ML inference service.
14. Key system flow to diagram
The most important end-to-end path is: user interacts with the React UI → frontend sends requests to the Spring backend → backend authenticates, persists domain data, stores images in Cloudinary, sends OTP emails via Brevo when needed, and consults the ML service for recommendation predictions → backend returns curated land/plantation data and stats back to the UI. The database remains the authoritative store for all business records except external media and ML model artifacts.
Main entry points: TerraSpoterApplication.java TerraSpoter · Landing.jsx Pages · UserRepository.java Repositories · App.jsx React app
Components 27
Spring backend
System of record for auth, land, plantation, stats, and persistence.
- TerraSpoter · Backend application entrypoint.
backend/src/main/java/com/example/terraspoter/TerraSpoterApplication.java - Security · Central authentication and request security configuration.
backend/src/main/java/com/example/terraspoter/config/SecurityConfig.java - Auth API · Login and signup endpoints.
backend/src/main/java/com/example/terraspoter/controller/AuthController.java - Reset API · Password recovery and OTP reset endpoints.
backend/src/main/java/com/example/terraspoter/controller/ForgotPasswordController.java - Land API · Land registration, browsing, and recommendation endpoints.
backend/src/main/java/com/example/terraspoter/controller/LandController.java - Verify API · Land verification workflow endpoints.
backend/src/main/java/com/example/terraspoter/controller/LandVerificationController.java - Plantation API · Plantation start, completion, review, and showcase endpoints.
backend/src/main/java/com/example/terraspoter/controller/PlantationController.java - Stats API · Read-only aggregate metrics endpoints.
backend/src/main/java/com/example/terraspoter/controller/StatsController.java - User API · User profile and account endpoints.
backend/src/main/java/com/example/terraspoter/controller/UserController.java - Auth svc · Authentication, account access, and user lookup orchestration.
backend/src/main/java/com/example/terraspoter/service/AuthService.java - User details · Spring Security user loading for authenticated principals.
backend/src/main/java/com/example/terraspoter/service/CustomUserDetailsService.java - Land svc · Land lifecycle, recommendation, and domain coordination.
backend/src/main/java/com/example/terraspoter/service/LandService.java - Verify svc · Land verification processing and status updates.
backend/src/main/java/com/example/terraspoter/service/LandVerificationService.java - Showcase svc · Curated plantation view generation.
backend/src/main/java/com/example/terraspoter/service/PlantationShowcaseService.java - Stats svc · Aggregation for reporting and dashboard metrics.
backend/src/main/java/com/example/terraspoter/service/StatsService.java - Media storage · Cloudinary integration for uploaded land and plantation images.
backend/src/main/java/com/example/terraspoter/service/CloudinaryService.java - Email OTP · Brevo email delivery and temporary OTP state for password recovery.
backend/src/main/java/com/example/terraspoter/service/BrevoEmailService.java - Repositories · Persistence access for users, lands, verifications, plantations, and images.
backend/src/main/java/com/example/terraspoter/repository/UserRepository.java - Domain model · Users, lands, reviews, verifications, recommendations, and plantation records.
backend/src/main/java/com/example/terraspoter/model/User.java - PostgreSQL · Primary persistent store initialized by Flyway migrations.
backend/src/main/resources/db/migration/V1__init.sql
React frontend
User-facing client for browsing, forms, profiles, and admin workflows.
- React app · Frontend application shell and routing bootstrap.
frontend/src/App.jsx - Pages · Landing, browse, auth, profile, plantation, and admin screens.
frontend/src/components/Landing.jsx - Shell · Navbar, main layout, and protected route gating.
frontend/src/components/Navbar.jsx - Map UI · Contribution map and plantation completion interactions.
frontend/src/components/ContributionMap.jsx - API utils · Client-side API/base URL and shared helpers.
frontend/src/lib/utils.js
ML service
Separate Flask inference service for tree recommendations.
- Flask app · Standalone prediction service entrypoint.
models/app.py - Tree model · Trained model and prediction logic for species recommendation.
models/model/predict.py
Connections 34
- TerraSpoter → Security: uses · Bootstraps the security layer.
- TerraSpoter → Auth API: hosts · Exposes auth endpoints.
- TerraSpoter → Reset API: hosts · Exposes password reset endpoints.
- TerraSpoter → Land API: hosts · Exposes land endpoints.
- TerraSpoter → Verify API: hosts · Exposes verification endpoints.
- TerraSpoter → Plantation API: hosts · Exposes plantation endpoints.
- TerraSpoter → Stats API: hosts · Exposes stats endpoints.
- TerraSpoter → User API: hosts · Exposes user endpoints.
- Auth API → Auth svc: calls · Delegates login/signup logic.
- Reset API → Email OTP: uses · Sends recovery emails and manages OTP state.
- Auth svc → User details: depends on · Uses Spring Security user lookup.
- Land API → Land svc: calls · Delegates land workflow operations.
- Verify API → Verify svc: calls · Delegates land verification operations.
- Plantation API → Showcase svc: calls · Builds showcase views and plantation responses.
- Stats API → Stats svc: calls · Serves aggregated metrics.
- Land svc → Repositories: persists via · Reads and writes land-related data.
- Verify svc → Repositories: persists via · Updates verification records.
- Showcase svc → Repositories: reads via · Assembles curated plantation data.
- Stats svc → Repositories: aggregates via · Derives metrics from transactional data.
- Repositories → Domain model: maps · Repositories operate on the entity model.
- Repositories → PostgreSQL: stores in · Persists records in PostgreSQL.
- Land svc → Media storage: uploads to · Stores land and related images externally.
- Showcase svc → Media storage: uploads to · Stores plantation media externally.
- React app → Shell: composes · Wires navigation and route protection.
- React app → Pages: renders · Provides page-level screens.
- Pages → Map UI: uses · Shows map-centric land exploration and completion flows.
- React app → API utils: configures · Uses shared API/client helpers.
- React app → Auth API: calls · Sends auth requests to the backend API.
- Pages → Land API: calls · Browses and submits land data.
- Pages → Plantation API: calls · Submits plantation workflow data.
- Pages → User API: calls · Loads profile and account data.
- Pages → Stats API: calls · Loads dashboard metrics where needed.
- Land svc → Flask app: predicts via · Consults the external ML recommendation service.
- Flask app → Tree model: serves · Loads the trained tree recommendation model.