# shanmukht9/quickserve-fe architecture

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

- Interactive diagram: https://gitdiagram.com/shanmukht9/quickserve-fe
- Repository: https://github.com/shanmukht9/quickserve-fe

## Overview

#### Purpose and Entry Points
QuickServe is a Spring Boot backend for a service-ordering workflow: user authentication, catalog/homepage and menu discovery, cart validation, order placement/partner acceptance, and payment processing. Application bootstrap: `src/main/java/com/quickserve/QuickServeApplication.java`. HTTP entry points are controllers under `src/main/java/com/quickserve/presentation/`, notably `OrderController.java`, `PaymentController.java`, and `AuthController.java`.

#### Layered / Ports-and-Adapters Design
The core is structured as presentation → application use cases → domain ports → infrastructure adapters. Domain entities and persistence-independent interfaces define the business boundary in `src/main/java/com/quickserve/domain/entity/Order.java`, `src/main/java/com/quickserve/domain/port/OrderRepositoryPort.java`, and `src/main/java/com/quickserve/domain/port/CatalogRepositoryPort.java`. Implementations bind those ports to JPA, Redis, Firebase, and payment systems.

#### Identity and Request Security
OTP-based onboarding/authentication and JWT refresh are application workflows: `src/main/java/com/quickserve/application/usecase/RequestOtpUseCaseImpl.java`, `src/main/java/com/quickserve/application/usecase/VerifyOtpUseCaseImpl.java`, and `src/main/java/com/quickserve/application/usecase/RefreshTokenUseCaseImpl.java`. Requests traverse JWT security filtering and security configuration before protected controllers: `src/main/java/com/quickserve/infrastructure/security/JwtAuthenticationFilter.java` and `src/main/java/com/quickserve/infrastructure/security/SecurityConfig.java`.

#### Catalog, Homepage, and Cache
Homepage and menu use cases assemble banners, sections, category trees, and offerings through catalog ports: `src/main/java/com/quickserve/application/usecase/GetHomepageUseCaseImpl.java`, `src/main/java/com/quickserve/application/usecase/GetMenuUseCaseImpl.java`, and `src/main/java/com/quickserve/domain/entity/HomepageSkeleton.java`. Redis-backed homepage/offering caches provide a read-performance boundary in `src/main/java/com/quickserve/infrastructure/cache/RedisHomepageCacheAdapter.java` and `src/main/java/com/quickserve/infrastructure/cache/RedisOfferingCacheAdapter.java`. Domain update events drive invalidation/rebuild behavior via `src/main/java/com/quickserve/infrastructure/invalidation/CacheInvalidationListener.java` and `src/main/java/com/quickserve/infrastructure/async/OfferingRebuildService.java`.

#### Order and Partner Dispatch Flow
Cart validation precedes placement, producing validated items and summaries before an order is persisted: `src/main/java/com/quickserve/application/usecase/ValidateCartUseCaseImpl.java`, `src/main/java/com/quickserve/application/usecase/PlaceOrderUseCaseImpl.java`, and `src/main/java/com/quickserve/domain/entity/CartSummary.java`. Partner selection and acceptance are separate state transitions represented by `src/main/java/com/quickserve/application/usecase/SelectPartnerUseCaseImpl.java`, `src/main/java/com/quickserve/application/usecase/OrderAcceptUseCaseImpl.java`, and `src/main/java/com/quickserve/domain/entity/PartnerDispatchEvent.java`. Firebase is the outbound dispatch/notification integration boundary through `src/main/java/com/quickserve/domain/port/FirebaseDispatchPort.java` and `src/main/java/com/quickserve/infrastructure/persistence/adapter/FirebaseAdapter.java`.

#### Payments and Webhooks
Payment-option retrieval, order/payment handling, and Razorpay webhook processing are isolated use cases: `src/main/java/com/quickserve/application/usecase/GetPaymentOptionsUseCaseImpl.java`, `src/main/java/com/quickserve/application/usecase/HandleRazorpayWebhookUseCaseImpl.java`, and `src/main/java/com/quickserve/infrastructure/payment/RazorpayService.java`. External Razorpay callbacks enter through `src/main/java/com/quickserve/presentation/PaymentWebhookController.java`; resulting payment state is persisted through `src/main/java/com/quickserve/domain/port/PaymentRepositoryPort.java`.

#### Persistence, Runtime, and Operations
The service uses Spring Boot/JPA with database schema migration at `src/main/resources/db/migration.sql`; repository adapters map domain models to JPA entities, including `src/main/java/com/quickserve/infrastructure/persistence/adapter/OrderPersistenceAdapter.java` and `src/main/java/com/quickserve/infrastructure/persistence/entity/OrderJpaEntity.java`. Material infrastructure includes Redis, Firebase, Razorpay, AWS SQS configuration, async execution, and scheduled processing: `src/main/java/com/quickserve/config/RedisConfig.java`, `src/main/java/com/quickserve/config/FirebaseConfig.java`, `src/main/java/com/quickserve/config/AwsSqsConfig.java`, and `src/main/java/com/quickserve/infrastructure/batch/NightlyRatingBatchJob.java`. Local container dependencies are indicated by `docker-compose.yml`.

Main entry points: [`src/main/java/com/quickserve/presentation/OrderController.java`](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/presentation/OrderController.java) (REST Controllers), [`src/main/java/com/quickserve/application/usecase/PlaceOrderUseCaseImpl.java`](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/PlaceOrderUseCaseImpl.java) (Order Placement), [`src/main/java/com/quickserve/application/usecase/HandleRazorpayWebhookUseCaseImpl.java`](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/HandleRazorpayWebhookUseCaseImpl.java) (Payment Workflows), [`src/main/java/com/quickserve/application/usecase/GetHomepageUseCaseImpl.java`](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/GetHomepageUseCaseImpl.java) (Homepage & Menu)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["HTTP & Security"]
  node_security["JWT Security<br/>security filter"]
  node_controllers["REST Controllers<br/>HTTP API"]
  node_webhook["Razorpay Webhook<br/>HTTP callback"]
end

subgraph group_application["Application Workflows"]
  node_auth["OTP &amp; Token Workflows<br/>use cases"]
  node_catalog["Homepage &amp; Menu<br/>use cases"]
  node_cart["Cart Validation<br/>use case"]
  node_orders["Order Placement<br/>use case"]
  node_dispatch["Partner Dispatch<br/>use cases"]
  node_payments["Payment Workflows<br/>use cases"]
end

subgraph group_domain["Domain Boundary"]
  node_order_port["Order Repository Port<br/>domain port"]
  node_catalog_port["Catalog Repository Port<br/>domain port"]
  node_payment_port["Payment Repository Port<br/>domain port"]
  node_firebase_port["Firebase Dispatch Port<br/>domain port"]
end

subgraph group_infrastructure["Infrastructure Adapters"]
  node_jpa_orders["Order Persistence Adapter<br/>JPA adapter"]
  node_database[("Relational Database<br/>[migration.sql]")]
  node_redis_cache["Redis Catalog Cache<br/>cache adapter"]
  node_cache_invalidation["Cache Rebuild Pipeline<br/>event listener"]
  node_firebase["Firebase Adapter<br/>dispatch adapter"]
  node_razorpay["Razorpay Service<br/>payment adapter"]
end

node_app{{"Spring Boot App<br/>bootstrap"}}

node_app -->|"boots"| node_security
node_security -->|"protects"| node_controllers
node_controllers -->|"auth requests"| node_auth
node_controllers -->|"catalog requests"| node_catalog
node_controllers -->|"cart requests"| node_cart
node_controllers -->|"order requests"| node_orders
node_controllers -->|"payment requests"| node_payments
node_webhook -->|"payment callback"| node_payments
node_cart -->|"validates against"| node_catalog_port
node_orders -->|"persists"| node_order_port
node_orders -->|"initiates dispatch"| node_dispatch
node_dispatch -->|"updates state"| node_order_port
node_dispatch -->|"sends dispatch"| node_firebase_port
node_catalog -->|"reads catalog"| node_catalog_port
node_catalog -->|"uses cached reads"| node_redis_cache
node_payments -->|"persists state"| node_payment_port
node_payments -->|"processes payments"| node_razorpay
node_order_port -->|"implemented by"| node_jpa_orders
node_payment_port -.->|"stored through JPA"| node_jpa_orders
node_jpa_orders -->|"JPA persistence"| node_database
node_catalog_port -.->|"catalog data"| node_database
node_firebase_port -->|"implemented by"| node_firebase
node_cache_invalidation -->|"invalidates and rebuilds"| node_redis_cache
node_orders -.->|"domain updates"| node_cache_invalidation

click node_app "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/QuickServeApplication.java"
click node_security "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/security/JwtAuthenticationFilter.java"
click node_controllers "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/presentation/OrderController.java"
click node_webhook "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/presentation/PaymentWebhookController.java"
click node_auth "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/VerifyOtpUseCaseImpl.java"
click node_catalog "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/GetHomepageUseCaseImpl.java"
click node_cart "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/ValidateCartUseCaseImpl.java"
click node_orders "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/PlaceOrderUseCaseImpl.java"
click node_dispatch "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/SelectPartnerUseCaseImpl.java"
click node_payments "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/HandleRazorpayWebhookUseCaseImpl.java"
click node_order_port "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/domain/port/OrderRepositoryPort.java"
click node_catalog_port "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/domain/port/CatalogRepositoryPort.java"
click node_payment_port "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/domain/port/PaymentRepositoryPort.java"
click node_firebase_port "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/domain/port/FirebaseDispatchPort.java"
click node_jpa_orders "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/persistence/adapter/OrderPersistenceAdapter.java"
click node_database "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/resources/db/migration.sql"
click node_redis_cache "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/cache/RedisHomepageCacheAdapter.java"
click node_cache_invalidation "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/invalidation/CacheInvalidationListener.java"
click node_firebase "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/persistence/adapter/FirebaseAdapter.java"
click node_razorpay "https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/payment/RazorpayService.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_security,node_controllers,node_webhook toneBlue
class node_auth,node_catalog,node_cart,node_orders,node_dispatch,node_payments toneAmber
class node_order_port,node_catalog_port,node_payment_port,node_firebase_port toneMint
class node_jpa_orders,node_database,node_redis_cache,node_cache_invalidation,node_firebase,node_razorpay toneRose
class node_app toneNeutral
```

## Components

### HTTP & Security

- [JWT Security](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/security/JwtAuthenticationFilter.java): security filter · `src/main/java/com/quickserve/infrastructure/security/JwtAuthenticationFilter.java`
- [REST Controllers](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/presentation/OrderController.java): HTTP API · Auth, order, payment, catalog endpoints. · `src/main/java/com/quickserve/presentation/OrderController.java`
- [Razorpay Webhook](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/presentation/PaymentWebhookController.java): HTTP callback · `src/main/java/com/quickserve/presentation/PaymentWebhookController.java`

### Application Workflows

- [OTP & Token Workflows](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/VerifyOtpUseCaseImpl.java): use cases · `src/main/java/com/quickserve/application/usecase/VerifyOtpUseCaseImpl.java`
- [Homepage & Menu](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/GetHomepageUseCaseImpl.java): use cases · `src/main/java/com/quickserve/application/usecase/GetHomepageUseCaseImpl.java`
- [Cart Validation](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/ValidateCartUseCaseImpl.java): use case · `src/main/java/com/quickserve/application/usecase/ValidateCartUseCaseImpl.java`
- [Order Placement](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/PlaceOrderUseCaseImpl.java): use case · Persists orders after validated cart summaries. · `src/main/java/com/quickserve/application/usecase/PlaceOrderUseCaseImpl.java`
- [Partner Dispatch](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/SelectPartnerUseCaseImpl.java): use cases · Selects and records partner acceptance. · `src/main/java/com/quickserve/application/usecase/SelectPartnerUseCaseImpl.java`
- [Payment Workflows](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/application/usecase/HandleRazorpayWebhookUseCaseImpl.java): use cases · Payment options and webhook state handling. · `src/main/java/com/quickserve/application/usecase/HandleRazorpayWebhookUseCaseImpl.java`

### Domain Boundary

- [Order Repository Port](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/domain/port/OrderRepositoryPort.java): domain port · `src/main/java/com/quickserve/domain/port/OrderRepositoryPort.java`
- [Catalog Repository Port](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/domain/port/CatalogRepositoryPort.java): domain port · `src/main/java/com/quickserve/domain/port/CatalogRepositoryPort.java`
- [Payment Repository Port](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/domain/port/PaymentRepositoryPort.java): domain port · `src/main/java/com/quickserve/domain/port/PaymentRepositoryPort.java`
- [Firebase Dispatch Port](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/domain/port/FirebaseDispatchPort.java): domain port · `src/main/java/com/quickserve/domain/port/FirebaseDispatchPort.java`

### Infrastructure Adapters

- [Order Persistence Adapter](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/persistence/adapter/OrderPersistenceAdapter.java): JPA adapter · `src/main/java/com/quickserve/infrastructure/persistence/adapter/OrderPersistenceAdapter.java`
- [Relational Database](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/resources/db/migration.sql): database · Schema is managed by migration.sql. · `src/main/resources/db/migration.sql`
- [Redis Catalog Cache](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/cache/RedisHomepageCacheAdapter.java): cache adapter · Caches homepage and offering reads. · `src/main/java/com/quickserve/infrastructure/cache/RedisHomepageCacheAdapter.java`
- [Cache Rebuild Pipeline](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/invalidation/CacheInvalidationListener.java): event listener · Invalidates and asynchronously rebuilds offerings. · `src/main/java/com/quickserve/infrastructure/invalidation/CacheInvalidationListener.java`
- [Firebase Adapter](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/persistence/adapter/FirebaseAdapter.java): dispatch adapter · `src/main/java/com/quickserve/infrastructure/persistence/adapter/FirebaseAdapter.java`
- [Razorpay Service](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/infrastructure/payment/RazorpayService.java): payment adapter · `src/main/java/com/quickserve/infrastructure/payment/RazorpayService.java`

### Other components

- [Spring Boot App](https://github.com/shanmukht9/quickserve-fe/blob/master/src/main/java/com/quickserve/QuickServeApplication.java): bootstrap · `src/main/java/com/quickserve/QuickServeApplication.java`

## Connections

- Spring Boot App → JWT Security: boots
- JWT Security → REST Controllers: protects
- REST Controllers → OTP & Token Workflows: auth requests
- REST Controllers → Homepage & Menu: catalog requests
- REST Controllers → Cart Validation: cart requests
- REST Controllers → Order Placement: order requests
- REST Controllers → Payment Workflows: payment requests
- Razorpay Webhook → Payment Workflows: payment callback
- Cart Validation → Catalog Repository Port: validates against
- Order Placement → Order Repository Port: persists
- Order Placement → Partner Dispatch: initiates dispatch
- Partner Dispatch → Order Repository Port: updates state
- Partner Dispatch → Firebase Dispatch Port: sends dispatch
- Homepage & Menu → Catalog Repository Port: reads catalog
- Homepage & Menu → Redis Catalog Cache: uses cached reads
- Payment Workflows → Payment Repository Port: persists state
- Payment Workflows → Razorpay Service: processes payments
- Order Repository Port → Order Persistence Adapter: implemented by
- Payment Repository Port → Order Persistence Adapter: stored through JPA
- Order Persistence Adapter → Relational Database: JPA persistence
- Catalog Repository Port → Relational Database: catalog data
- Firebase Dispatch Port → Firebase Adapter: implemented by
- Cache Rebuild Pipeline → Redis Catalog Cache: invalidates and rebuilds
- Order Placement → Cache Rebuild Pipeline: domain updates