# code-with-zoro/nearbuy-hyperlocal-product-discovery-platform architecture

> Architecture diagram of the GitHub repository code-with-zoro/nearbuy-hyperlocal-product-discovery-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform
- Repository: https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform

## Overview

HyperLocal Inventory is a microservices backend for discovering products from nearby vendors. The main workflow starts with a user search: Search Service requests nearby vendor IDs from Location Service, queries Inventory Service for matching products, and returns a limited, deduplicated result. Users and vendors can also sign up or log in, manage locations, and maintain stock. The gateway provides the documented request-routing and JWT/rate-limiting boundary, with Eureka supporting service discovery. Edges reflect excerpts or README statements; some service boundaries are documented but their routing configuration was not sampled.

Main entry points: [`API-Gateway/src/main/java/com/Hyperlocal_Inventory/API_Gateway/ApiGatewayApplication.java`](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/API-Gateway/src/main/java/com/Hyperlocal_Inventory/API_Gateway/ApiGatewayApplication.java) (API Gateway), [`User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/services/UserEntryService.java`](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/services/UserEntryService.java) (User account service), [`Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/services/SearchServices.java`](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/services/SearchServices.java) (Search orchestration), [`User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/controllers/PublicController.java`](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/controllers/PublicController.java) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_edge["Gateway and discovery"]
  node_gateway["API Gateway"]
  node_rate["Rate limiting"]
  node_registry["Eureka registry"]
end

subgraph group_identity["Identity and access"]
  node_authapi["Auth endpoints"]
  node_authlogic["User account service"]
  node_userstore[("User records")]
  node_jwt["JWT utilities<br/>[JwtUtil.java]"]
  node_vendoragg["Vendor inventory view"]
  node_invclient["Auth inventory client"]
end

subgraph group_catalog["Inventory management"]
  node_productapi["Product endpoints"]
  node_productlogic["Product management"]
  node_stocklogic["Search and sales<br/>[SearchService.java]"]
  node_productstore[("Product records")]
end

subgraph group_geo["Location services"]
  node_locationapi["Location endpoints"]
  node_locationlogic["Location and proximity"]
  node_locationstore[("Location records")]
end

subgraph group_discovery["Product discovery"]
  node_searchapi["Search endpoint"]
  node_searchlogic["Search orchestration"]
  node_searchloc["Location client"]
  node_searchinv["Inventory client"]
end

node_client(("Client"))

node_client -->|"sends requests"| node_gateway
node_gateway -.->|"rate limits"| node_rate
node_gateway -.->|"discovers services"| node_registry
node_gateway -.->|"routes requests"| node_authapi
node_gateway -.->|"routes requests"| node_searchapi
node_authapi -->|"delegates signup"| node_authlogic
node_authlogic -->|"reads and writes"| node_userstore
node_authlogic -->|"generates token"| node_jwt
node_vendoragg -->|"requests products"| node_invclient
node_invclient -.->|"fetches inventory"| node_productapi
node_productapi -->|"delegates operations"| node_productlogic
node_productlogic -->|"reads and writes"| node_productstore
node_stocklogic -->|"searches and updates"| node_productstore
node_locationapi -->|"delegates location"| node_locationlogic
node_locationlogic -->|"queries locations"| node_locationstore
node_searchapi -.->|"handles search"| node_searchlogic
node_searchlogic -->|"requests nearby vendors"| node_searchloc
node_searchlogic -->|"queries products"| node_searchinv
node_searchloc -.->|"gets vendor IDs"| node_locationapi
node_searchinv -.->|"searches inventory"| node_stocklogic

click node_gateway "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/API-Gateway/src/main/java/com/Hyperlocal_Inventory/API_Gateway/ApiGatewayApplication.java"
click node_rate "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/API-Gateway/src/main/java/com/Hyperlocal_Inventory/API_Gateway/services/RateLimiterService.java"
click node_registry "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Service-Registry/src/main/java/com/Hyperlocal_Inventory/Service_Registry/ServiceRegistryApplication.java"
click node_authapi "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/controllers/PublicController.java"
click node_authlogic "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/services/UserEntryService.java"
click node_userstore "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/repository/UserEntryRepository.java"
click node_jwt "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/utils/JwtUtil.java"
click node_vendoragg "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/external/aggregation/InventoryAggregationService.java"
click node_invclient "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/external/feginServices/InventoryClient.java"
click node_productapi "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/controllers/ProductEntryController.java"
click node_productlogic "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/service/ProductEntryService.java"
click node_stocklogic "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/service/SearchService.java"
click node_productstore "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/repository/ProductRepository.java"
click node_locationapi "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/controllers/LocationEntryController.java"
click node_locationlogic "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/services/LocationEntryService.java"
click node_locationstore "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/repository/LocationRepository.java"
click node_searchapi "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/controllers/SearchController.java"
click node_searchlogic "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/services/SearchServices.java"
click node_searchloc "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/external/LocationClient.java"
click node_searchinv "https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/external/InventoryClient.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_gateway,node_rate,node_registry,node_client toneBlue
class node_authapi,node_authlogic,node_userstore,node_jwt,node_vendoragg,node_invclient toneAmber
class node_productapi,node_productlogic,node_stocklogic,node_productstore toneMint
class node_locationapi,node_locationlogic,node_locationstore toneRose
class node_searchapi,node_searchlogic,node_searchloc,node_searchinv toneIndigo
```

## Components

### Gateway and discovery

- [API Gateway](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/API-Gateway/src/main/java/com/Hyperlocal_Inventory/API_Gateway/ApiGatewayApplication.java): `API-Gateway/src/main/java/com/Hyperlocal_Inventory/API_Gateway/ApiGatewayApplication.java`
- [Rate limiting](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/API-Gateway/src/main/java/com/Hyperlocal_Inventory/API_Gateway/services/RateLimiterService.java): `API-Gateway/src/main/java/com/Hyperlocal_Inventory/API_Gateway/services/RateLimiterService.java`
- [Eureka registry](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Service-Registry/src/main/java/com/Hyperlocal_Inventory/Service_Registry/ServiceRegistryApplication.java): `Service-Registry/src/main/java/com/Hyperlocal_Inventory/Service_Registry/ServiceRegistryApplication.java`

### Identity and access

- [Auth endpoints](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/controllers/PublicController.java): `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/controllers/PublicController.java`
- [User account service](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/services/UserEntryService.java): `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/services/UserEntryService.java`
- [User records](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/repository/UserEntryRepository.java): `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/repository/UserEntryRepository.java`
- [JWT utilities](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/utils/JwtUtil.java): `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/utils/JwtUtil.java`
- [Vendor inventory view](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/external/aggregation/InventoryAggregationService.java): `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/external/aggregation/InventoryAggregationService.java`
- [Auth inventory client](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/external/feginServices/InventoryClient.java): `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/external/feginServices/InventoryClient.java`

### Inventory management

- [Product endpoints](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/controllers/ProductEntryController.java): `Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/controllers/ProductEntryController.java`
- [Product management](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/service/ProductEntryService.java): `Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/service/ProductEntryService.java`
- [Search and sales](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/service/SearchService.java): `Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/service/SearchService.java`
- [Product records](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/repository/ProductRepository.java): `Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/repository/ProductRepository.java`

### Location services

- [Location endpoints](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/controllers/LocationEntryController.java): `Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/controllers/LocationEntryController.java`
- [Location and proximity](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/services/LocationEntryService.java): `Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/services/LocationEntryService.java`
- [Location records](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/repository/LocationRepository.java): `Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/repository/LocationRepository.java`

### Product discovery

- [Search endpoint](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/controllers/SearchController.java): `Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/controllers/SearchController.java`
- [Search orchestration](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/services/SearchServices.java): `Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/services/SearchServices.java`
- [Location client](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/external/LocationClient.java): `Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/external/LocationClient.java`
- [Inventory client](https://github.com/code-with-zoro/nearbuy-hyperlocal-product-discovery-platform/blob/main/Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/external/InventoryClient.java): `Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/external/InventoryClient.java`

### Other components

- **Client**

## Connections

- Client → API Gateway: sends requests (evidence: `README.md`)
- API Gateway → Rate limiting: rate limits (evidence: `README.md`)
- API Gateway → Eureka registry: discovers services (evidence: `README.md`)
- API Gateway → Auth endpoints: routes requests (evidence: `README.md`)
- API Gateway → Search endpoint: routes requests (evidence: `README.md`)
- Auth endpoints → User account service: delegates signup (evidence: `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/controllers/PublicController.java`)
- User account service → User records: reads and writes (evidence: `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/services/UserEntryService.java`)
- User account service → JWT utilities: generates token (evidence: `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/services/UserEntryService.java`)
- Vendor inventory view → Auth inventory client: requests products (evidence: `User-Auth-Service/src/main/java/com/HyperLocal_Inventory/User_Auth_Service/external/aggregation/InventoryAggregationService.java`)
- Auth inventory client → Product endpoints: fetches inventory
- Product endpoints → Product management: delegates operations (evidence: `Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/controllers/ProductEntryController.java`)
- Product management → Product records: reads and writes (evidence: `Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/service/ProductEntryService.java`)
- Search and sales → Product records: searches and updates (evidence: `Inventory-Service/src/main/java/com/HyperLocal_Inventory/Inventory_Service/service/SearchService.java`)
- Location endpoints → Location and proximity: delegates location (evidence: `Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/controllers/LocationEntryController.java`)
- Location and proximity → Location records: queries locations (evidence: `Loaction-Service/src/main/java/com/HyperLocal_Inventory/Loaction_Service/services/LocationEntryService.java`)
- Search endpoint → Search orchestration: handles search (evidence: `Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/controllers/SearchController.java`)
- Search orchestration → Location client: requests nearby vendors (evidence: `Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/services/SearchServices.java`)
- Search orchestration → Inventory client: queries products (evidence: `Search_Service/src/main/java/com/HyperLocal_Inventory/Search_Service/services/SearchServices.java`)
- Location client → Location endpoints: gets vendor IDs
- Inventory client → Search and sales: searches inventory