# nikhi111/greenshelf architecture

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

- Interactive diagram: https://gitdiagram.com/nikhi111/greenshelf
- Repository: https://github.com/nikhi111/greenshelf

## Overview

1. **Overall shape: a single Spring Boot backend monolith**
   GreenSelf is organized as a layered Java/Spring Boot application rather than a set of separate services. The runtime is a REST API server backed by MySQL, with the usual Spring boundaries: controllers at the edge, services for business logic, repositories for persistence, and JPA entities for the domain model.

2. **Primary request entry points are controller-based API modules**
   The API surface is split by domain into `UserController`, `SellerController`, `AdminController`, `ProductController`, `PlantController`, `PaymentController`, `RecommendationController`, and `WebhookController`. This makes the main architectural boundary the HTTP API layer, with each controller owning one functional area of the marketplace.

3. **Business logic is concentrated in service classes**
   The service layer contains the real workflows: user account operations, seller/nursery management, product and inventory handling, order/payment orchestration, admin verification flows, payout handling, and plant recommendations. `CustomUserService` also supports authentication by loading user details for Spring Security.

4. **Persistence is split across domain repositories and JPA entities**
   The data model includes core marketplace entities such as `User`, `Seller`, `Nursery`, `Product`, `Plant`, `Cart`, `Order`, `Payment`, `Inventory`, and related join/detail entities like `CartProduct`, `OrderProduct`, and `InventoryProduct`. Spring Data repositories map each aggregate to the database, which keeps persistence concerns separate from request handling.

5. **Authentication and authorization are JWT-based**
   Security is handled with `SecurityConfig`, `JwtAuthFilter`, `JwtUtil`, and `CustomUserDetails`. The architecture suggests token-based access control around protected endpoints, with CORS explicitly configured for frontend integration. Public browsing endpoints are separated from authenticated user, seller, and admin operations.

6. **Marketplace flow: browse, cart, order, pay**
   The user journey moves through product discovery, cart management, order creation, and payment verification. `Cart`, `Order`, and `Payment` are distinct domain stages, which is important for diagramming because order placement and payment confirmation are not a single step; they are separate backend responsibilities.

7. **Seller and admin workflows form a verification/operations boundary**
   Sellers can register, create nurseries, manage products, and track inventory, while admins verify sellers and nurseries and oversee platform operations. The existence of `SellerRequest`, `SellerRequestStatus`, and admin services indicates a gated onboarding workflow rather than immediate seller activation.

8. **Inventory is treated as a first-class subsystem**
   Inventory is not embedded directly inside product records. Instead, the repo has `Inventory`, `InventoryProduct`, and related repositories, which suggests a layered stock-management model where a nursery or seller’s inventory is tracked separately from the marketplace catalog.

9. **Recommendations are an external-data-driven subsystem**
   The recommendation feature is its own module with `RecommendationController`, `RecommendationService`, and DTOs for weather and ML request/response data. `RestTemplateConfig` implies outbound HTTP calls, likely to fetch weather/location data and feed it into a recommendation engine that returns suitable plants.

10. **Payments integrate with Razorpay and webhooks**
   Payment handling is explicitly isolated in `PaymentController`, `RazorpayConfig`, and `WebhookController`. That separation matters architecturally: synchronous payment verification and asynchronous webhook event handling are both present, and seller payout processing is handled as a related but separate concern.

11. **DTOs are used heavily as the API boundary**
   The `Dto` package is large and covers requests/responses for users, sellers, products, carts, orders, payments, weather, recommendations, and verification flows. This indicates the system avoids exposing entities directly over the wire, which is a clean boundary for a REST backend.

12. **Cross-cutting concerns are centralized**
   Error handling is handled by `GlobalExceptionHandler`, API docs by `OpenApiConfig`, CORS by `CorsConfig`, and external client wiring by `RestTemplateConfig`. These are infrastructure-level modules that support the feature controllers without mixing into business logic.

13. **Testing is layered around controllers and services**
   The test tree includes controller tests and `UserServiceTest`, plus a base Spring Boot test. That matches the layered architecture: integration-style checks around the API surface and focused unit/service tests for core business logic.

14. **Deployment/runtime context**
   The project is Maven-based, runs as a Spring Boot application, and is configured for deployment on Render according to the README. Swagger UI is part of the runtime API documentation, which is useful for understanding the exposed backend contract but does not change the core architecture.

Main entry points: [`src/main/java/com/example/GreenSelf/entity/User.java`](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/entity/User.java) (Domain model), [`src/main/java/com/example/GreenSelf/service/PaymentService.java`](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/PaymentService.java) (Payment service), [`src/main/java/com/example/GreenSelf/config/SecurityConfig.java`](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/config/SecurityConfig.java) (Security), [`src/main/java/com/example/GreenSelf/service/UserService.java`](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/UserService.java) (User service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API layer"]
  node_user_api["Users<br/>controller"]
  node_seller_api["Sellers<br/>controller"]
  node_admin_api["Admin<br/>controller"]
  node_product_api["Products<br/>controller"]
  node_plant_api["Plants<br/>controller"]
  node_payment_api["Payments<br/>controller"]
  node_recommend_api["Recommend<br/>controller"]
  node_webhook_api["Webhook<br/>controller"]
end

subgraph group_core["Core services"]
  node_user_svc["User service<br/>[UserService.java]"]
  node_seller_svc["Seller service<br/>[SellerService.java]"]
  node_admin_svc["Admin service<br/>[AdminService.java]"]
  node_product_svc["Product service"]
  node_payment_svc["Payment service"]
  node_payout_svc["Payout service<br/>[PayoutService.java]"]
  node_rec_svc["Rec service"]
end

subgraph group_data["Persistence"]
  node_user_repo[("User repo<br/>[UserRepo.java]")]
  node_seller_repo[("Seller repo<br/>[SellerRepo.java]")]
  node_product_repo[("Product repo<br/>[ProductRepo.java]")]
  node_order_repo[("Order repo<br/>[OrderRepo.java]")]
  node_payment_repo[("Payment repo<br/>[PaymentRepo.java]")]
  node_inventory_repo[("Inventory repo<br/>[InventoryRepo.java]")]
  node_cart_repo[("Cart repo<br/>[CartRepo.java]")]
  node_entities[("Domain model<br/>entities<br/>[User.java]")]
end

subgraph group_infra["Infrastructure"]
  node_app(("GreenSelf<br/>spring-boot app"))
  node_security["Security<br/>config/filter"]
  node_jwt_filter["JWT filter<br/>[JwtAuthFilter.java]"]
  node_jwt_util["JWT util<br/>[JwtUtil.java]"]
  node_configs["Configs"]
  node_handler["Errors<br/>exception handler"]
end

node_app -->|"boots with"| node_security
node_app -->|"loads"| node_configs
node_app -->|"uses"| node_handler
node_security -->|"includes"| node_jwt_filter
node_security -->|"relies on"| node_jwt_util
node_security -->|"auth via"| node_user_svc
node_user_api -->|"calls"| node_user_svc
node_seller_api -->|"calls"| node_seller_svc
node_admin_api -->|"calls"| node_admin_svc
node_product_api -->|"calls"| node_product_svc
node_plant_api -->|"calls"| node_rec_svc
node_payment_api -->|"calls"| node_payment_svc
node_webhook_api -->|"notifies"| node_payment_svc
node_recommend_api -->|"calls"| node_rec_svc
node_user_svc -->|"persists via"| node_user_repo
node_user_svc -->|"manages"| node_cart_repo
node_seller_svc -->|"persists via"| node_seller_repo
node_seller_svc -->|"updates"| node_inventory_repo
node_admin_svc -->|"verifies"| node_seller_repo
node_product_svc -->|"reads/writes"| node_product_repo
node_product_svc -->|"checks stock"| node_inventory_repo
node_payment_svc -->|"persists via"| node_payment_repo
node_payment_svc -->|"updates"| node_order_repo
node_payment_svc -->|"triggers"| node_payout_svc
node_rec_svc -->|"outbound client"| node_configs
node_cart_repo -->|"maps"| node_entities
node_order_repo -->|"maps"| node_entities
node_payment_repo -->|"maps"| node_entities
node_inventory_repo -->|"maps"| node_entities
node_product_repo -->|"maps"| node_entities
node_seller_repo -->|"maps"| node_entities
node_user_repo -->|"maps"| node_entities

click node_app "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/GreenSelfApplication.java"
click node_user_api "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/UserController.java"
click node_seller_api "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/SellerController.java"
click node_admin_api "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/AdminController.java"
click node_product_api "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/ProductController.java"
click node_plant_api "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/PlantController.java"
click node_payment_api "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/PaymentController.java"
click node_recommend_api "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/RecommendationController.java"
click node_webhook_api "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/WebhookController.java"
click node_user_svc "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/UserService.java"
click node_seller_svc "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/SellerService.java"
click node_admin_svc "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/AdminService.java"
click node_product_svc "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/ProductService.java"
click node_payment_svc "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/PaymentService.java"
click node_payout_svc "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/PayoutService.java"
click node_rec_svc "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/RecommendationService.java"
click node_security "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/config/SecurityConfig.java"
click node_jwt_filter "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/filter/JwtAuthFilter.java"
click node_jwt_util "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/util/JwtUtil.java"
click node_configs "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/config/RazorpayConfig.java"
click node_handler "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/exception/GlobalExceptionHandler.java"
click node_user_repo "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/UserRepo.java"
click node_seller_repo "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/SellerRepo.java"
click node_product_repo "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/ProductRepo.java"
click node_order_repo "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/OrderRepo.java"
click node_payment_repo "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/PaymentRepo.java"
click node_inventory_repo "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/InventoryRepo.java"
click node_cart_repo "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/CartRepo.java"
click node_entities "https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/entity/User.java"

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_user_api,node_seller_api,node_admin_api,node_product_api,node_plant_api,node_payment_api,node_recommend_api,node_webhook_api toneBlue
class node_user_svc,node_seller_svc,node_admin_svc,node_product_svc,node_payment_svc,node_payout_svc,node_rec_svc toneAmber
class node_user_repo,node_seller_repo,node_product_repo,node_order_repo,node_payment_repo,node_inventory_repo,node_cart_repo,node_entities toneMint
class node_app,node_security,node_jwt_filter,node_jwt_util,node_configs,node_handler toneRose
```

## Components

### API layer

HTTP entry points grouped by functional domain

- [Users](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/UserController.java): controller · User account and authentication endpoints · `src/main/java/com/example/GreenSelf/controller/UserController.java`
- [Sellers](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/SellerController.java): controller · Seller onboarding and nursery-facing endpoints · `src/main/java/com/example/GreenSelf/controller/SellerController.java`
- [Admin](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/AdminController.java): controller · Verification and platform operations endpoints · `src/main/java/com/example/GreenSelf/controller/AdminController.java`
- [Products](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/ProductController.java): controller · Catalog and product browsing endpoints · `src/main/java/com/example/GreenSelf/controller/ProductController.java`
- [Plants](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/PlantController.java): controller · Plant data and related browse endpoints · `src/main/java/com/example/GreenSelf/controller/PlantController.java`
- [Payments](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/PaymentController.java): controller · Payment creation and verification endpoints · `src/main/java/com/example/GreenSelf/controller/PaymentController.java`
- [Recommend](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/RecommendationController.java): controller · Plant recommendation endpoints · `src/main/java/com/example/GreenSelf/controller/RecommendationController.java`
- [Webhook](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/controller/WebhookController.java): controller · Asynchronous payment callback handling · `src/main/java/com/example/GreenSelf/controller/WebhookController.java`

### Core services

Business workflows and orchestration

- [User service](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/UserService.java): service · User registration, profile, and cart/order-facing logic · `src/main/java/com/example/GreenSelf/service/UserService.java`
- [Seller service](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/SellerService.java): service · Seller, nursery, and inventory workflows · `src/main/java/com/example/GreenSelf/service/SellerService.java`
- [Admin service](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/AdminService.java): service · Seller verification and admin operations · `src/main/java/com/example/GreenSelf/service/AdminService.java`
- [Product service](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/ProductService.java): service · Catalog and inventory coordination · `src/main/java/com/example/GreenSelf/service/ProductService.java`
- [Payment service](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/PaymentService.java): service · Payment verification and settlement workflows · `src/main/java/com/example/GreenSelf/service/PaymentService.java`
- [Payout service](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/PayoutService.java): service · Seller payout processing · `src/main/java/com/example/GreenSelf/service/PayoutService.java`
- [Rec service](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/service/RecommendationService.java): service · Weather-driven plant recommendations · `src/main/java/com/example/GreenSelf/service/RecommendationService.java`

### Persistence

Entities and repositories backing the monolith

- [User repo](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/UserRepo.java): repository · User persistence gateway · `src/main/java/com/example/GreenSelf/repo/UserRepo.java`
- [Seller repo](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/SellerRepo.java): repository · Seller and request persistence gateway · `src/main/java/com/example/GreenSelf/repo/SellerRepo.java`
- [Product repo](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/ProductRepo.java): repository · Catalog persistence gateway · `src/main/java/com/example/GreenSelf/repo/ProductRepo.java`
- [Order repo](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/OrderRepo.java): repository · Order persistence gateway · `src/main/java/com/example/GreenSelf/repo/OrderRepo.java`
- [Payment repo](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/PaymentRepo.java): repository · Payment persistence gateway · `src/main/java/com/example/GreenSelf/repo/PaymentRepo.java`
- [Inventory repo](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/InventoryRepo.java): repository · Inventory persistence gateway · `src/main/java/com/example/GreenSelf/repo/InventoryRepo.java`
- [Cart repo](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/repo/CartRepo.java): repository · Cart persistence gateway · `src/main/java/com/example/GreenSelf/repo/CartRepo.java`
- [Domain model](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/entity/User.java): entities · Core marketplace entities for users, sellers, products, carts, orders, payments, and inventory · `src/main/java/com/example/GreenSelf/entity/User.java`

### Infrastructure

Security, configuration, and cross-cutting concerns

- [GreenSelf](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/GreenSelfApplication.java): spring-boot app · Application bootstrap for the backend monolith · `src/main/java/com/example/GreenSelf/GreenSelfApplication.java`
- [Security](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/config/SecurityConfig.java): config/filter · JWT auth, Spring Security, and user detail loading · `src/main/java/com/example/GreenSelf/config/SecurityConfig.java`
- [JWT filter](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/filter/JwtAuthFilter.java): filter · Token validation on protected requests · `src/main/java/com/example/GreenSelf/filter/JwtAuthFilter.java`
- [JWT util](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/util/JwtUtil.java): util · Token generation and parsing helpers · `src/main/java/com/example/GreenSelf/util/JwtUtil.java`
- [Configs](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/config/RazorpayConfig.java): config · CORS, OpenAPI, REST client, and Razorpay wiring · `src/main/java/com/example/GreenSelf/config/RazorpayConfig.java`
- [Errors](https://github.com/nikhi111/greenshelf/blob/master/src/main/java/com/example/GreenSelf/exception/GlobalExceptionHandler.java): exception handler · Central API exception translation · `src/main/java/com/example/GreenSelf/exception/GlobalExceptionHandler.java`

## Connections

- GreenSelf → Security: boots with · Application starts through secured web configuration
- GreenSelf → Configs: loads · Bootstraps infrastructure configuration
- GreenSelf → Errors: uses · Centralized exception handling is part of runtime setup
- Security → JWT filter: includes · Security config installs the JWT filter
- Security → JWT util: relies on · Security uses JWT helper utilities
- Security → User service: auth via · Custom user loading supports authentication flows
- Users → User service: calls · User controller delegates account workflows
- Sellers → Seller service: calls · Seller controller delegates seller workflows
- Admin → Admin service: calls · Admin controller delegates verification workflows
- Products → Product service: calls · Product controller delegates catalog workflows
- Plants → Rec service: calls · Plant endpoints support recommendation-related browsing
- Payments → Payment service: calls · Payment controller delegates payment workflows
- Webhook → Payment service: notifies · Webhook callbacks feed asynchronous payment handling
- Recommend → Rec service: calls · Recommendation controller delegates ML/weather workflow
- User service → User repo: persists via · User workflows read and write user data
- User service → Cart repo: manages · User-facing cart logic touches cart storage
- Seller service → Seller repo: persists via · Seller onboarding and management storage
- Seller service → Inventory repo: updates · Seller workflows manage inventory state
- Admin service → Seller repo: verifies · Admin workflows update seller approval state
- Product service → Product repo: reads/writes · Catalog changes flow through product persistence
- Product service → Inventory repo: checks stock · Product availability depends on inventory
- Payment service → Payment repo: persists via · Payment records are stored separately
- Payment service → Order repo: updates · Payment completion advances order state
- Payment service → Payout service: triggers · Seller settlement is handled as a downstream concern
- Rec service → Configs: outbound client · Recommendation workflow uses REST client wiring
- Cart repo → Domain model: maps · Cart persistence is backed by domain entities
- Order repo → Domain model: maps · Order persistence is backed by domain entities
- Payment repo → Domain model: maps · Payment persistence is backed by domain entities
- Inventory repo → Domain model: maps · Inventory persistence is backed by domain entities
- Product repo → Domain model: maps · Product persistence is backed by domain entities
- Seller repo → Domain model: maps · Seller persistence is backed by domain entities
- User repo → Domain model: maps · User persistence is backed by domain entities
