# venky4378/pg-finder-microservices architecture

> Architecture diagram of the GitHub repository venky4378/pg-finder-microservices, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/venky4378/pg-finder-microservices
- Repository: https://github.com/venky4378/pg-finder-microservices

## Overview

PG Finder is a microservices platform for hostel discovery and bed-level reservations. The main user journey passes through the gateway, uses the user service for identity, discovers hostel inventory, and books a bed; owners can then manage booking status. Booking events are consumed asynchronously for notifications. The README documents frontend, database-per-service, and service-discovery capabilities, while the tree and sampled code support the service components shown. Some inter-service wiring is documented rather than present in sampled source, so those edges follow the README.

Main entry points: [`api-gateway/src/main/java/com/pgfinder/api_gateway/filter/AuthenticationFilter.java`](https://github.com/venky4378/pg-finder-microservices/blob/master/api-gateway/src/main/java/com/pgfinder/api_gateway/filter/AuthenticationFilter.java) (API gateway), [`booking-service/src/main/java/com/pgfinder/booking_service/ServiceImpl/BookingServiceImpl.java`](https://github.com/venky4378/pg-finder-microservices/blob/master/booking-service/src/main/java/com/pgfinder/booking_service/ServiceImpl/BookingServiceImpl.java) (Booking workflow), [`hostel/src/main/java/com/pgfinder/hostel/controller/HostelController.java`](https://github.com/venky4378/pg-finder-microservices/blob/master/hostel/src/main/java/com/pgfinder/hostel/controller/HostelController.java) (Hostel, room, bed APIs), [`user-service/src/main/java/com/pgfinder/user/controller/AuthController.java`](https://github.com/venky4378/pg-finder-microservices/blob/master/user-service/src/main/java/com/pgfinder/user/controller/AuthController.java) (Registration and login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and discovery"]
  node_gateway["API gateway"]
  node_eureka["Eureka registry"]
end

subgraph group_identity["Identity and access"]
  node_auth["Registration and login"]
  node_user_service["User management"]
  node_jwt["JWT service<br/>[JwtService.java]"]
  node_user_store[("User database")]
end

subgraph group_inventory["Hostel inventory"]
  node_hostel_api["Hostel, room, bed APIs"]
  node_inventory_services["Inventory services"]
  node_hostel_store[("Hostel database")]
end

subgraph group_reservations["Reservations and events"]
  node_booking_api["Booking API"]
  node_booking_logic["Booking workflow"]
  node_booking_store[("Booking database")]
  node_kafka["Kafka booking events"]
  node_notification["Notification consumer"]
end

subgraph group_recommendations["AI discovery"]
  node_ai_api["AI chat API"]
  node_ai_service["Recommendation and RAG"]
end

node_resident(("Resident / Owner"))
node_frontend["React frontend"]
node_gemini["Gemini API"]
node_email_sms["Email / SMS processing"]

node_resident -->|"uses"| node_frontend
node_frontend -->|"HTTP + JWT"| node_gateway
node_gateway -->|"routes auth"| node_auth
node_gateway -->|"routes inventory"| node_hostel_api
node_gateway -->|"routes bookings"| node_booking_api
node_gateway -->|"routes users"| node_user_service
node_gateway -->|"discovers services"| node_eureka
node_auth -->|"reads and writes"| node_user_store
node_auth -->|"generates token"| node_jwt
node_user_service -->|"reads and writes"| node_user_store
node_hostel_api -->|"dispatches"| node_inventory_services
node_inventory_services -->|"reads and writes"| node_hostel_store
node_booking_api -->|"dispatches"| node_booking_logic
node_booking_logic -->|"reads and writes"| node_booking_store
node_booking_logic -->|"validates bed"| node_hostel_api
node_booking_logic -->|"validates user"| node_user_service
node_booking_logic -->|"publishes events"| node_kafka
node_kafka -->|"delivers events"| node_notification
node_notification -.->|"processes notices"| node_email_sms
node_frontend -.->|"sends chat"| node_ai_api
node_ai_api -->|"dispatches"| node_ai_service
node_ai_service -->|"retrieves catalog"| node_hostel_api
node_ai_service -.->|"generates answer"| node_gemini

click node_gateway "https://github.com/venky4378/pg-finder-microservices/blob/master/api-gateway/src/main/java/com/pgfinder/api_gateway/filter/AuthenticationFilter.java"
click node_eureka "https://github.com/venky4378/pg-finder-microservices/blob/master/eureka-server/src/main/java/com/pgfinder/eureka_server/EurekaServerApplication.java"
click node_auth "https://github.com/venky4378/pg-finder-microservices/blob/master/user-service/src/main/java/com/pgfinder/user/controller/AuthController.java"
click node_user_service "https://github.com/venky4378/pg-finder-microservices/blob/master/user-service/src/main/java/com/pgfinder/user/serviceImpl/UserServiceImpl.java"
click node_jwt "https://github.com/venky4378/pg-finder-microservices/blob/master/user-service/src/main/java/com/pgfinder/user/security/JwtService.java"
click node_hostel_api "https://github.com/venky4378/pg-finder-microservices/blob/master/hostel/src/main/java/com/pgfinder/hostel/controller/HostelController.java"
click node_inventory_services "https://github.com/venky4378/pg-finder-microservices/tree/master/hostel/src/main/java/com/pgfinder/hostel/serviceImpl"
click node_booking_api "https://github.com/venky4378/pg-finder-microservices/blob/master/booking-service/src/main/java/com/pgfinder/booking_service/controller/BookingController.java"
click node_booking_logic "https://github.com/venky4378/pg-finder-microservices/blob/master/booking-service/src/main/java/com/pgfinder/booking_service/ServiceImpl/BookingServiceImpl.java"
click node_notification "https://github.com/venky4378/pg-finder-microservices/blob/master/notification-service/notification-service/src/main/java/com/pgfinder/notification/consumer/NotificationConsumer.java"
click node_ai_api "https://github.com/venky4378/pg-finder-microservices/blob/master/ai-service/src/main/java/com/pgfinder/aiservice/controller/AiChatController.java"
click node_ai_service "https://github.com/venky4378/pg-finder-microservices/blob/master/ai-service/src/main/java/com/pgfinder/aiservice/service/AiRecommendationService.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_eureka,node_frontend toneBlue
class node_auth,node_user_service,node_jwt,node_user_store toneAmber
class node_hostel_api,node_inventory_services,node_hostel_store,node_gemini toneMint
class node_booking_api,node_booking_logic,node_booking_store,node_kafka,node_notification toneRose
class node_ai_api,node_ai_service,node_resident,node_email_sms toneIndigo
```

## Components

### Entry and discovery

- [API gateway](https://github.com/venky4378/pg-finder-microservices/blob/master/api-gateway/src/main/java/com/pgfinder/api_gateway/filter/AuthenticationFilter.java): `api-gateway/src/main/java/com/pgfinder/api_gateway/filter/AuthenticationFilter.java`
- [Eureka registry](https://github.com/venky4378/pg-finder-microservices/blob/master/eureka-server/src/main/java/com/pgfinder/eureka_server/EurekaServerApplication.java): `eureka-server/src/main/java/com/pgfinder/eureka_server/EurekaServerApplication.java`

### Identity and access

- [Registration and login](https://github.com/venky4378/pg-finder-microservices/blob/master/user-service/src/main/java/com/pgfinder/user/controller/AuthController.java): `user-service/src/main/java/com/pgfinder/user/controller/AuthController.java`
- [User management](https://github.com/venky4378/pg-finder-microservices/blob/master/user-service/src/main/java/com/pgfinder/user/serviceImpl/UserServiceImpl.java): `user-service/src/main/java/com/pgfinder/user/serviceImpl/UserServiceImpl.java`
- [JWT service](https://github.com/venky4378/pg-finder-microservices/blob/master/user-service/src/main/java/com/pgfinder/user/security/JwtService.java): `user-service/src/main/java/com/pgfinder/user/security/JwtService.java`
- **User database**

### Hostel inventory

- [Hostel, room, bed APIs](https://github.com/venky4378/pg-finder-microservices/blob/master/hostel/src/main/java/com/pgfinder/hostel/controller/HostelController.java): `hostel/src/main/java/com/pgfinder/hostel/controller/HostelController.java`
- [Inventory services](https://github.com/venky4378/pg-finder-microservices/tree/master/hostel/src/main/java/com/pgfinder/hostel/serviceImpl): `hostel/src/main/java/com/pgfinder/hostel/serviceImpl`
- **Hostel database**

### Reservations and events

- [Booking API](https://github.com/venky4378/pg-finder-microservices/blob/master/booking-service/src/main/java/com/pgfinder/booking_service/controller/BookingController.java): `booking-service/src/main/java/com/pgfinder/booking_service/controller/BookingController.java`
- [Booking workflow](https://github.com/venky4378/pg-finder-microservices/blob/master/booking-service/src/main/java/com/pgfinder/booking_service/ServiceImpl/BookingServiceImpl.java): `booking-service/src/main/java/com/pgfinder/booking_service/ServiceImpl/BookingServiceImpl.java`
- **Booking database**
- **Kafka booking events**
- [Notification consumer](https://github.com/venky4378/pg-finder-microservices/blob/master/notification-service/notification-service/src/main/java/com/pgfinder/notification/consumer/NotificationConsumer.java): `notification-service/notification-service/src/main/java/com/pgfinder/notification/consumer/NotificationConsumer.java`

### AI discovery

- [AI chat API](https://github.com/venky4378/pg-finder-microservices/blob/master/ai-service/src/main/java/com/pgfinder/aiservice/controller/AiChatController.java): `ai-service/src/main/java/com/pgfinder/aiservice/controller/AiChatController.java`
- [Recommendation and RAG](https://github.com/venky4378/pg-finder-microservices/blob/master/ai-service/src/main/java/com/pgfinder/aiservice/service/AiRecommendationService.java): `ai-service/src/main/java/com/pgfinder/aiservice/service/AiRecommendationService.java`

### Other components

- **Resident / Owner**
- **React frontend**
- **Gemini API**
- **Email / SMS processing**

## Connections

- Resident / Owner → React frontend: uses
- React frontend → API gateway: HTTP + JWT
- API gateway → Registration and login: routes auth
- API gateway → Hostel, room, bed APIs: routes inventory
- API gateway → Booking API: routes bookings
- API gateway → User management: routes users
- API gateway → Eureka registry: discovers services
- Registration and login → User database: reads and writes
- Registration and login → JWT service: generates token
- User management → User database: reads and writes
- Hostel, room, bed APIs → Inventory services: dispatches
- Inventory services → Hostel database: reads and writes
- Booking API → Booking workflow: dispatches
- Booking workflow → Booking database: reads and writes
- Booking workflow → Hostel, room, bed APIs: validates bed
- Booking workflow → User management: validates user
- Booking workflow → Kafka booking events: publishes events
- Kafka booking events → Notification consumer: delivers events
- Notification consumer → Email / SMS processing: processes notices
- React frontend → AI chat API: sends chat
- AI chat API → Recommendation and RAG: dispatches
- Recommendation and RAG → Hostel, room, bed APIs: retrieves catalog
- Recommendation and RAG → Gemini API: generates answer