How gishan152/farmio works
1. Repository shape
- This is a multi-service Farmio platform split into a React frontend and many Spring Boot backend services.
- The backend is organized as a microservice system with shared infrastructure services and several domain services for commerce, logistics, warehousing, payments, waste management, and notifications.
2. Edge layer
- api-gateway is the main entry point for client traffic.
- It contains route definitions, JWT-based security filters, CORS config, and request validation logic.
- In an architecture diagram, almost all browser/API traffic should flow through the gateway rather than directly to domain services.
3. Platform infrastructure
- eureka-server provides service discovery.
- config-server centralizes runtime configuration; it also stores service-specific config files such as configs/product-service.yml.
- The repository includes Docker Compose files and service-specific dev Dockerfiles, so the system is meant to run as a containerized distributed stack.
4. Identity and access control
- auth-service is the identity boundary.
- It manages users, moderators, roles, login/registration, password changes, and activity logs.
- JWT is used across the system, and the auth service ships RSA public/private keys, which implies asymmetric token signing.
- The gateway also has JWT filters, so access control is enforced both at the edge and in the auth service itself.
5. Commerce / crop listing core
- crop-listing-service owns product creation and product ratings for crop listings.
- order-service owns buyer requests, farmer bids, orders, and transport-related order state.
- These two services represent the core marketplace workflow: listing crops, negotiating, placing orders, and tracking fulfillment.
6. Payments and financial state
- payment-service is a dedicated financial service with payment, wallet, transaction, commission, bank details, receipts, reports, and withdrawal flows.
- It integrates with the external PayHere gateway and contains request/response models for PayHere payment initiation and notifications.
- order-service and waste-service both interact with payment-related messages, so payment events are not isolated to a single domain.
7. Waste management workflow
- waste-service manages waste listings, waste requests, requesters, waste agents, and payment-related request handling.
- warehouse-service also participates in waste operations by managing waste agents, warehouse slots, bookings, and storage capacity.
- The docs folder contains multiple waste-request and waste-agent integration docs, indicating this is a major cross-service business flow.
8. Warehousing and logistics
- warehouse-service owns warehouse locations, slots, bookings, stored items, and waste-agent coordination.
- transport-service owns vehicles, routes, loads, and availability scheduling.
- order-service includes transport entities and controllers, showing transport assignment is part of the order lifecycle, not a separate UI-only concern.
9. Notifications and realtime delivery
- notification-service handles notifications, email delivery, WebSocket delivery, scheduling, and event listeners.
- It consumes messages and can push updates to connected clients in realtime.
- This service is the main async user-facing event broadcaster for payment/order/waste events.
10. Analytics and reporting
- analytic-service is a reporting/read-model service with controllers and services for product, order, user, waste, transport, and moderator analytics.
- It appears to aggregate data from other services rather than own primary transactional state.
- In a diagram, place it as a consumer of upstream service data, not as a source of truth.
11. Inter-service communication
- The repo mixes synchronous and asynchronous integration styles:
- Feign clients in services like order-service, waste-service, and payment-service.
- WebClient / RestTemplate in a few services for HTTP calls.
- RabbitMQ in payment/order/waste/notification flows for event-driven updates such as payment confirmation.
- A good diagram should show both request/response links and event/message links, especially around payment confirmation and notification fan-out.
12. Frontend architecture
- frontend is a Vite + React application with role-specific areas for buyer, farmer, warehouse, waste agent, transporter, moderator, and admin.
- It has a central API layer under src/API, shared utilities, route groups, contexts for per-role state, and reusable UI components.
- This frontend is the primary consumer of the gateway and likely switches behavior heavily by role.
13. Persistence and data ownership
- Each backend service owns its own repositories, entities/models, DTOs, and service layer.
- Several services include Flyway or SQL migration resources, and there is a PostgreSQL initialization script under postgres-init.
- The architecture follows service-local persistence rather than a shared monolithic database.
14. Operational boundary and code maturity
- The repo includes multiple hs_err_pid... crash logs, test stubs, and some duplicate/minimal services such as product-service and test-service, which suggests parts of the platform are prototypes, legacy demos, or service experiments.
- docs/ contains detailed flow documents, which are useful for understanding business process boundaries, especially payments and waste management.
Main entry points: api-gateway API Gateway · config-server Config Server · payment-service Payment Service · order-service Order Service
Components 14
Client
User-facing application layer
- Frontend · Role-based web client for buyers, farmers, warehouse staff, waste agents, transporters, moderators, and admins
frontend
Platform
Shared infrastructure and edge services
- API Gateway · Edge entry point with routing, JWT filters, CORS, and request validation
backend/api-gateway - Auth Service · Identity boundary for users, moderators, roles, login, registration, password changes, and activity logs
backend/auth-service - Eureka · Service discovery registry for backend services
backend/eureka-server - Config Server · Centralized runtime configuration source for backend services
backend/config-server - Analytics · Aggregates product, order, user, waste, transport, and moderator analytics
backend/analytic-service
Commerce
Marketplace and core trading workflow
- Crop Listing · Owns crop product creation, edits, and ratings
backend/crop-listing-service - Order Service · Owns buyer requests, farmer bids, orders, and transport state
backend/order-service - Payment Service · Owns payments, wallet, transactions, commission, receipts, reports, withdrawals, and PayHere integration
backend/payment-service
Operations
Warehousing, transport, and waste workflows
- Warehouse Service · Owns warehouses, slots, bookings, stored items, and waste-agent coordination
backend/warehouse-service - Transport Service · Owns vehicles, routes, loads, and availability scheduling
backend/transport-service - Waste Service · Owns waste listings, requests, requesters, waste agents, and payment-linked request handling
backend/waste-service
Messaging
Async notification and event delivery
- Notifications · Handles notifications, email, WebSocket delivery, scheduling, and event listeners
backend/notification-service - Chat Service · Standalone chat service present in the stack but not central to core flows
backend/chat-service
Connections 39
- Frontend → API Gateway: API traffic · Browser and app requests flow through the gateway
- API Gateway → Auth Service: auth · Login, token handling, and protected user flows
- API Gateway → Crop Listing: routes · Marketplace listing traffic is routed through the gateway
- API Gateway → Order Service: routes · Order and negotiation traffic is routed through the gateway
- API Gateway → Payment Service: routes · Payment and wallet traffic is routed through the gateway
- API Gateway → Warehouse Service: routes · Warehouse UI traffic reaches storage services through the gateway
- API Gateway → Transport Service: routes · Transport UI traffic reaches fleet services through the gateway
- API Gateway → Waste Service: routes · Waste management UI traffic reaches waste services through the gateway
- API Gateway → Notifications: routes · Client-facing notification endpoints are exposed at the edge
- API Gateway → Analytics: routes · Dashboard and reporting APIs are proxied at the edge
- Eureka → API Gateway: discover · Gateway discovers backend services via registry
- Eureka → Crop Listing: discover · Service discovery for listing service
- Eureka → Order Service: discover · Service discovery for order service
- Eureka → Payment Service: discover · Service discovery for payment service
- Config Server → API Gateway: config · Centralized configuration for gateway runtime
- Config Server → Auth Service: config · Centralized configuration for auth runtime
- Config Server → Crop Listing: config · Centralized configuration for listing runtime
- Config Server → Order Service: config · Centralized configuration for order runtime
- Config Server → Payment Service: config · Centralized configuration for payment runtime
- Config Server → Warehouse Service: config · Centralized configuration for warehouse runtime
- Config Server → Transport Service: config · Centralized configuration for transport runtime
- Config Server → Waste Service: config · Centralized configuration for waste runtime
- Config Server → Notifications: config · Centralized configuration for notification runtime
- Order Service → Crop Listing: feign · Looks up crop/product data for orders and buyer requests
- Order Service → Payment Service: feign · Initiates and tracks payment-related order actions
- Order Service → Transport Service: links · Order lifecycle includes transport assignment and state
- Payment Service → Notifications: events · Publishes payment/receipt events for user updates
- Payment Service → Order Service: events · Payment confirmation updates order state
- Payment Service → Waste Service: events · Payment confirmation and request payment flows affect waste operations
- Waste Service → Payment Service: client · Waste payment initiation and payment status coordination
- Waste Service → Warehouse Service: coordination · Waste-agent booking and storage coordination
- Notifications → Auth Service: user lookup · Notification delivery needs user/contact context
- Analytics → Crop Listing: read data · Consumes product and pricing data for reporting
- Analytics → Order Service: read data · Consumes order and delivery data for reporting
- Analytics → Payment Service: read data · Consumes payment and transaction data for reporting
- Analytics → Waste Service: read data · Consumes waste workflow data for reporting
- Analytics → Transport Service: read data · Consumes transport data for reporting
- Analytics → Auth Service: read data · Consumes user and moderator data for reporting
- Notifications → Frontend: realtime · WebSocket and email-driven user-facing updates