# gishan152/farmio architecture

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

- Interactive diagram: https://gitdiagram.com/gishan152/farmio
- Repository: https://github.com/gishan152/farmio

## Overview

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: [`backend/api-gateway`](https://github.com/gishan152/farmio/tree/main/backend/api-gateway) (API Gateway), [`backend/config-server`](https://github.com/gishan152/farmio/tree/main/backend/config-server) (Config Server), [`backend/payment-service`](https://github.com/gishan152/farmio/tree/main/backend/payment-service) (Payment Service), [`backend/order-service`](https://github.com/gishan152/farmio/tree/main/backend/order-service) (Order Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_frontend["Frontend<br/>React/Vite UI"]
end

subgraph group_platform["Platform"]
  node_api_gateway["API Gateway<br/>Spring Cloud Gateway"]
  node_auth_service["Auth Service<br/>Spring Boot auth"]
  node_eureka_server(("Eureka<br/>service registry"))
  node_config_server[("Config Server<br/>central config")]
  node_analytic_service["Analytics<br/>read model"]
end

subgraph group_commerce["Commerce"]
  node_crop_listing_service["Crop Listing<br/>product catalog"]
  node_order_service["Order Service<br/>market orders"]
  node_payment_service["Payment Service<br/>financial core"]
end

subgraph group_operations["Operations"]
  node_warehouse_service["Warehouse Service<br/>storage ops"]
  node_transport_service["Transport Service<br/>fleet ops"]
  node_waste_service["Waste Service<br/>waste workflow"]
end

subgraph group_messaging["Messaging"]
  node_notification_service["Notifications<br/>async delivery"]
  node_chat_service["Chat Service<br/>aux service"]
end

node_frontend -->|"API traffic"| node_api_gateway
node_api_gateway -->|"auth"| node_auth_service
node_api_gateway -->|"routes"| node_crop_listing_service
node_api_gateway -->|"routes"| node_order_service
node_api_gateway -->|"routes"| node_payment_service
node_api_gateway -->|"routes"| node_warehouse_service
node_api_gateway -->|"routes"| node_transport_service
node_api_gateway -->|"routes"| node_waste_service
node_api_gateway -->|"routes"| node_notification_service
node_api_gateway -->|"routes"| node_analytic_service
node_eureka_server -.->|"discover"| node_api_gateway
node_eureka_server -.->|"discover"| node_crop_listing_service
node_eureka_server -.->|"discover"| node_order_service
node_eureka_server -.->|"discover"| node_payment_service
node_config_server -.->|"config"| node_api_gateway
node_config_server -.->|"config"| node_auth_service
node_config_server -.->|"config"| node_crop_listing_service
node_config_server -.->|"config"| node_order_service
node_config_server -.->|"config"| node_payment_service
node_config_server -.->|"config"| node_warehouse_service
node_config_server -.->|"config"| node_transport_service
node_config_server -.->|"config"| node_waste_service
node_config_server -.->|"config"| node_notification_service
node_order_service -->|"feign"| node_crop_listing_service
node_order_service -->|"feign"| node_payment_service
node_order_service -->|"links"| node_transport_service
node_payment_service -->|"events"| node_notification_service
node_payment_service -->|"events"| node_order_service
node_payment_service -->|"events"| node_waste_service
node_waste_service -->|"client"| node_payment_service
node_waste_service -->|"coordination"| node_warehouse_service
node_notification_service -->|"user lookup"| node_auth_service
node_analytic_service -->|"read data"| node_crop_listing_service
node_analytic_service -->|"read data"| node_order_service
node_analytic_service -->|"read data"| node_payment_service
node_analytic_service -->|"read data"| node_waste_service
node_analytic_service -->|"read data"| node_transport_service
node_analytic_service -->|"read data"| node_auth_service
node_notification_service -.->|"realtime"| node_frontend

click node_frontend "https://github.com/gishan152/farmio/tree/main/frontend"
click node_api_gateway "https://github.com/gishan152/farmio/tree/main/backend/api-gateway"
click node_auth_service "https://github.com/gishan152/farmio/tree/main/backend/auth-service"
click node_eureka_server "https://github.com/gishan152/farmio/tree/main/backend/eureka-server"
click node_config_server "https://github.com/gishan152/farmio/tree/main/backend/config-server"
click node_crop_listing_service "https://github.com/gishan152/farmio/tree/main/backend/crop-listing-service"
click node_order_service "https://github.com/gishan152/farmio/tree/main/backend/order-service"
click node_payment_service "https://github.com/gishan152/farmio/tree/main/backend/payment-service"
click node_warehouse_service "https://github.com/gishan152/farmio/tree/main/backend/warehouse-service"
click node_transport_service "https://github.com/gishan152/farmio/tree/main/backend/transport-service"
click node_waste_service "https://github.com/gishan152/farmio/tree/main/backend/waste-service"
click node_notification_service "https://github.com/gishan152/farmio/tree/main/backend/notification-service"
click node_analytic_service "https://github.com/gishan152/farmio/tree/main/backend/analytic-service"
click node_chat_service "https://github.com/gishan152/farmio/tree/main/backend/chat-service"

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_frontend toneBlue
class node_api_gateway,node_auth_service,node_eureka_server,node_config_server,node_analytic_service toneAmber
class node_crop_listing_service,node_order_service,node_payment_service toneMint
class node_warehouse_service,node_transport_service,node_waste_service toneRose
class node_notification_service,node_chat_service toneIndigo
```

## Components

### Client

User-facing application layer

- [Frontend](https://github.com/gishan152/farmio/tree/main/frontend): React/Vite UI · Role-based web client for buyers, farmers, warehouse staff, waste agents, transporters, moderators, and admins · `frontend`

### Platform

Shared infrastructure and edge services

- [API Gateway](https://github.com/gishan152/farmio/tree/main/backend/api-gateway): Spring Cloud Gateway · Edge entry point with routing, JWT filters, CORS, and request validation · `backend/api-gateway`
- [Auth Service](https://github.com/gishan152/farmio/tree/main/backend/auth-service): Spring Boot auth · Identity boundary for users, moderators, roles, login, registration, password changes, and activity logs · `backend/auth-service`
- [Eureka](https://github.com/gishan152/farmio/tree/main/backend/eureka-server): service registry · Service discovery registry for backend services · `backend/eureka-server`
- [Config Server](https://github.com/gishan152/farmio/tree/main/backend/config-server): central config · Centralized runtime configuration source for backend services · `backend/config-server`
- [Analytics](https://github.com/gishan152/farmio/tree/main/backend/analytic-service): read model · Aggregates product, order, user, waste, transport, and moderator analytics · `backend/analytic-service`

### Commerce

Marketplace and core trading workflow

- [Crop Listing](https://github.com/gishan152/farmio/tree/main/backend/crop-listing-service): product catalog · Owns crop product creation, edits, and ratings · `backend/crop-listing-service`
- [Order Service](https://github.com/gishan152/farmio/tree/main/backend/order-service): market orders · Owns buyer requests, farmer bids, orders, and transport state · `backend/order-service`
- [Payment Service](https://github.com/gishan152/farmio/tree/main/backend/payment-service): financial core · Owns payments, wallet, transactions, commission, receipts, reports, withdrawals, and PayHere integration · `backend/payment-service`

### Operations

Warehousing, transport, and waste workflows

- [Warehouse Service](https://github.com/gishan152/farmio/tree/main/backend/warehouse-service): storage ops · Owns warehouses, slots, bookings, stored items, and waste-agent coordination · `backend/warehouse-service`
- [Transport Service](https://github.com/gishan152/farmio/tree/main/backend/transport-service): fleet ops · Owns vehicles, routes, loads, and availability scheduling · `backend/transport-service`
- [Waste Service](https://github.com/gishan152/farmio/tree/main/backend/waste-service): waste workflow · Owns waste listings, requests, requesters, waste agents, and payment-linked request handling · `backend/waste-service`

### Messaging

Async notification and event delivery

- [Notifications](https://github.com/gishan152/farmio/tree/main/backend/notification-service): async delivery · Handles notifications, email, WebSocket delivery, scheduling, and event listeners · `backend/notification-service`
- [Chat Service](https://github.com/gishan152/farmio/tree/main/backend/chat-service): aux service · Standalone chat service present in the stack but not central to core flows · `backend/chat-service`

## Connections

- 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
