# aritra39514/quickkart architecture

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

- Interactive diagram: https://gitdiagram.com/aritra39514/quickkart
- Repository: https://github.com/aritra39514/quickkart

## Overview

QuickKart is a campus-hostel commerce and delivery system with role-based student, vendor, delivery-agent, and admin workflows. Students browse products, manage a cart, place and track orders; vendors manage products and order status; delivery agents handle assignments and OTP-confirmed delivery; admins manage users, orders, and inventory. The README documents Kafka-driven order events, load-aware delivery assignment, Redis product caching, MongoDB persistence, and Prometheus metrics. Several frontend and backend subsystems are represented by their listed source paths; only relationships shown in excerpts or documented in the README are connected.

Main entry points: [`frontend/src/api/axios.js`](https://github.com/aritra39514/quickkart/blob/main/frontend/src/api/axios.js) (API client), [`backend/src/main/java/com/quickkart/service/OrderService.java`](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/OrderService.java) (Order lifecycle), [`frontend/src/App.jsx`](https://github.com/aritra39514/quickkart/blob/main/frontend/src/App.jsx) (Role-based routes), [`backend/src/main/java/com/quickkart/service/CartService.java`](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/CartService.java) (Cart management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_app["Role-based routes<br/>[App.jsx]"]
  node_authstate["Auth state<br/>[AuthContext.jsx]"]
  node_http["API client<br/>[axios.js]"]
  node_student["Student shopping<br/>[Home.jsx]"]
  node_studentorders["Cart and orders<br/>[Cart.jsx]"]
  node_vendorui["Vendor operations"]
  node_deliveryui["Delivery dashboard"]
  node_adminui["Admin operations<br/>[AdminDashboard.jsx]"]
end

subgraph group_api["REST API"]
  node_authapi["Auth endpoints"]
  node_cartapi["Cart endpoints"]
  node_productsapi["Product endpoints"]
  node_ordersapi["Order endpoints"]
  node_vendorapi["Vendor endpoints"]
  node_deliveryapi["Delivery endpoints"]
  node_adminapi["Admin endpoints"]
end

subgraph group_commerce["Commerce domain"]
  node_cartservice["Cart management<br/>[CartService.java]"]
  node_productservice["Product catalog"]
  node_orderservice["Order lifecycle<br/>[OrderService.java]"]
  node_adminservice["Admin management<br/>[AdminService.java]"]
end

subgraph group_delivery["Events and delivery"]
  node_publisher["Order event publisher"]
  node_consumer["Order event consumer"]
  node_scheduler["Agent scheduler"]
end

subgraph group_platform["Identity and data"]
  node_authservice["Authentication<br/>[AuthService.java]"]
  node_orderstore[("Order records<br/>[Order.java]")]
  node_productstore[("Product records<br/>[Product.java]")]
  node_userstore[("User records<br/>[User.java]")]
  node_cartstore[("Cart records<br/>[Cart.java]")]
  node_metrics["Prometheus metrics"]
end

node_people(("Campus users"))
node_mongo[("MongoDB")]
node_kafka["Kafka"]
node_redis[("Redis cache")]

node_people -->|"use"| node_app
node_app -->|"provides auth"| node_authstate
node_app -->|"routes"| node_student
node_app -->|"routes"| node_studentorders
node_app -->|"routes"| node_deliveryui
node_app -->|"routes"| node_adminui
node_student -->|"imports"| node_http
node_deliveryui -->|"calls"| node_http
node_vendorui -->|"calls"| node_http
node_app -->|"fetches cart"| node_http
node_http -->|"REST requests"| node_authapi
node_http -->|"REST requests"| node_cartapi
node_http -->|"REST requests"| node_productsapi
node_http -->|"REST requests"| node_ordersapi
node_http -->|"REST requests"| node_vendorapi
node_http -->|"REST requests"| node_deliveryapi
node_http -->|"REST requests"| node_adminapi
node_authapi -->|"delegates"| node_authservice
node_cartapi -->|"delegates"| node_cartservice
node_vendorapi -->|"delegates"| node_productservice
node_vendorapi -->|"delegates"| node_orderservice
node_adminapi -->|"delegates"| node_adminservice
node_adminapi -->|"delegates"| node_orderservice
node_deliveryapi -->|"delegates"| node_orderservice
node_ordersapi -->|"delegates"| node_orderservice
node_authservice -->|"reads and writes"| node_userstore
node_cartservice -->|"reads and writes"| node_cartstore
node_cartservice -->|"reads"| node_productstore
node_cartservice -->|"reads"| node_userstore
node_productservice -->|"reads and writes"| node_productstore
node_orderservice -->|"persists orders"| node_orderstore
node_orderservice -->|"clears cart"| node_cartservice
node_orderservice -->|"publishes events"| node_publisher
node_orderservice -->|"records placement"| node_metrics
node_publisher -->|"publishes"| node_kafka
node_kafka -->|"delivers events"| node_consumer
node_consumer -->|"routes confirmed"| node_scheduler
node_orderstore -->|"stored in"| node_mongo
node_productstore -->|"stored in"| node_mongo
node_userstore -->|"stored in"| node_mongo
node_cartstore -->|"stored in"| node_mongo
node_productservice -->|"caches products"| node_redis
node_metrics -.->|"exposes telemetry"| node_people

click node_app "https://github.com/aritra39514/quickkart/blob/main/frontend/src/App.jsx"
click node_authstate "https://github.com/aritra39514/quickkart/blob/main/frontend/src/context/AuthContext.jsx"
click node_http "https://github.com/aritra39514/quickkart/blob/main/frontend/src/api/axios.js"
click node_student "https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/student/Home.jsx"
click node_studentorders "https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/student/Cart.jsx"
click node_vendorui "https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/admin/InventoryManagement.jsx"
click node_deliveryui "https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/delivery/DeliveryDashboard.jsx"
click node_adminui "https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/admin/AdminDashboard.jsx"
click node_authapi "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/AuthController.java"
click node_cartapi "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/CartController.java"
click node_productsapi "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/ProductController.java"
click node_ordersapi "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/OrderController.java"
click node_vendorapi "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/VendorController.java"
click node_deliveryapi "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/DeliveryController.java"
click node_adminapi "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/AdminController.java"
click node_authservice "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/AuthService.java"
click node_cartservice "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/CartService.java"
click node_productservice "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/ProductService.java"
click node_orderservice "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/OrderService.java"
click node_adminservice "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/AdminService.java"
click node_publisher "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/messaging/OrderEventPublisher.java"
click node_consumer "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/messaging/OrderEventConsumer.java"
click node_scheduler "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/scheduler/DeliveryScheduler.java"
click node_orderstore "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/model/Order.java"
click node_productstore "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/model/Product.java"
click node_userstore "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/model/User.java"
click node_cartstore "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/model/Cart.java"
click node_metrics "https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/config/QuickKartMetrics.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_app,node_authstate,node_http,node_student,node_studentorders,node_vendorui,node_deliveryui,node_adminui,node_people toneBlue
class node_authapi,node_cartapi,node_productsapi,node_ordersapi,node_vendorapi,node_deliveryapi,node_adminapi,node_mongo,node_redis toneAmber
class node_cartservice,node_productservice,node_orderservice,node_adminservice toneMint
class node_publisher,node_consumer,node_scheduler toneRose
class node_authservice,node_orderstore,node_productstore,node_userstore,node_cartstore,node_metrics,node_kafka toneIndigo
```

## Components

### React client

- [Role-based routes](https://github.com/aritra39514/quickkart/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth state](https://github.com/aritra39514/quickkart/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [API client](https://github.com/aritra39514/quickkart/blob/main/frontend/src/api/axios.js): `frontend/src/api/axios.js`
- [Student shopping](https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/student/Home.jsx): `frontend/src/pages/student/Home.jsx`
- [Cart and orders](https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/student/Cart.jsx): `frontend/src/pages/student/Cart.jsx`
- [Vendor operations](https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/admin/InventoryManagement.jsx): `frontend/src/pages/admin/InventoryManagement.jsx`
- [Delivery dashboard](https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/delivery/DeliveryDashboard.jsx): `frontend/src/pages/delivery/DeliveryDashboard.jsx`
- [Admin operations](https://github.com/aritra39514/quickkart/blob/main/frontend/src/pages/admin/AdminDashboard.jsx): `frontend/src/pages/admin/AdminDashboard.jsx`

### REST API

- [Auth endpoints](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/AuthController.java): `backend/src/main/java/com/quickkart/controller/AuthController.java`
- [Cart endpoints](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/CartController.java): `backend/src/main/java/com/quickkart/controller/CartController.java`
- [Product endpoints](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/ProductController.java): `backend/src/main/java/com/quickkart/controller/ProductController.java`
- [Order endpoints](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/OrderController.java): `backend/src/main/java/com/quickkart/controller/OrderController.java`
- [Vendor endpoints](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/VendorController.java): `backend/src/main/java/com/quickkart/controller/VendorController.java`
- [Delivery endpoints](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/DeliveryController.java): `backend/src/main/java/com/quickkart/controller/DeliveryController.java`
- [Admin endpoints](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/controller/AdminController.java): `backend/src/main/java/com/quickkart/controller/AdminController.java`

### Commerce domain

- [Cart management](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/CartService.java): `backend/src/main/java/com/quickkart/service/CartService.java`
- [Product catalog](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/ProductService.java): `backend/src/main/java/com/quickkart/service/ProductService.java`
- [Order lifecycle](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/OrderService.java): `backend/src/main/java/com/quickkart/service/OrderService.java`
- [Admin management](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/AdminService.java): `backend/src/main/java/com/quickkart/service/AdminService.java`

### Events and delivery

- [Order event publisher](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/messaging/OrderEventPublisher.java): `backend/src/main/java/com/quickkart/messaging/OrderEventPublisher.java`
- [Order event consumer](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/messaging/OrderEventConsumer.java): `backend/src/main/java/com/quickkart/messaging/OrderEventConsumer.java`
- [Agent scheduler](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/scheduler/DeliveryScheduler.java): `backend/src/main/java/com/quickkart/scheduler/DeliveryScheduler.java`

### Identity and data

- [Authentication](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/service/AuthService.java): `backend/src/main/java/com/quickkart/service/AuthService.java`
- [Order records](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/model/Order.java): `backend/src/main/java/com/quickkart/model/Order.java`
- [Product records](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/model/Product.java): `backend/src/main/java/com/quickkart/model/Product.java`
- [User records](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/model/User.java): `backend/src/main/java/com/quickkart/model/User.java`
- [Cart records](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/model/Cart.java): `backend/src/main/java/com/quickkart/model/Cart.java`
- [Prometheus metrics](https://github.com/aritra39514/quickkart/blob/main/backend/src/main/java/com/quickkart/config/QuickKartMetrics.java): `backend/src/main/java/com/quickkart/config/QuickKartMetrics.java`

### Other components

- **Campus users**
- **MongoDB**
- **Kafka**
- **Redis cache**

## Connections

- Campus users → Role-based routes: use (evidence: `README.md`)
- Role-based routes → Auth state: provides auth (evidence: `frontend/src/App.jsx`)
- Role-based routes → Student shopping: routes (evidence: `frontend/src/App.jsx`)
- Role-based routes → Cart and orders: routes (evidence: `frontend/src/App.jsx`)
- Role-based routes → Delivery dashboard: routes (evidence: `frontend/src/App.jsx`)
- Role-based routes → Admin operations: routes (evidence: `frontend/src/App.jsx`)
- Student shopping → API client: imports (evidence: `frontend/src/pages/student/Home.jsx`)
- Delivery dashboard → API client: calls (evidence: `frontend/src/pages/delivery/DeliveryDashboard.jsx`)
- Vendor operations → API client: calls (evidence: `frontend/src/pages/admin/InventoryManagement.jsx`)
- Role-based routes → API client: fetches cart (evidence: `frontend/src/App.jsx`)
- API client → Auth endpoints: REST requests (evidence: `README.md`)
- API client → Cart endpoints: REST requests (evidence: `README.md`)
- API client → Product endpoints: REST requests (evidence: `README.md`)
- API client → Order endpoints: REST requests (evidence: `README.md`)
- API client → Vendor endpoints: REST requests (evidence: `README.md`)
- API client → Delivery endpoints: REST requests (evidence: `README.md`)
- API client → Admin endpoints: REST requests (evidence: `README.md`)
- Auth endpoints → Authentication: delegates (evidence: `backend/src/main/java/com/quickkart/controller/AuthController.java`)
- Cart endpoints → Cart management: delegates (evidence: `backend/src/main/java/com/quickkart/controller/CartController.java`)
- Vendor endpoints → Product catalog: delegates (evidence: `backend/src/main/java/com/quickkart/controller/VendorController.java`)
- Vendor endpoints → Order lifecycle: delegates (evidence: `backend/src/main/java/com/quickkart/controller/VendorController.java`)
- Admin endpoints → Admin management: delegates (evidence: `backend/src/main/java/com/quickkart/controller/AdminController.java`)
- Admin endpoints → Order lifecycle: delegates (evidence: `backend/src/main/java/com/quickkart/controller/AdminController.java`)
- Delivery endpoints → Order lifecycle: delegates (evidence: `backend/src/main/java/com/quickkart/controller/DeliveryController.java`)
- Order endpoints → Order lifecycle: delegates
- Authentication → User records: reads and writes (evidence: `backend/src/main/java/com/quickkart/service/AuthService.java`)
- Cart management → Cart records: reads and writes (evidence: `backend/src/main/java/com/quickkart/service/CartService.java`)
- Cart management → Product records: reads (evidence: `backend/src/main/java/com/quickkart/service/CartService.java`)
- Cart management → User records: reads (evidence: `backend/src/main/java/com/quickkart/service/CartService.java`)
- Product catalog → Product records: reads and writes (evidence: `backend/src/main/java/com/quickkart/service/ProductService.java`)
- Order lifecycle → Order records: persists orders (evidence: `backend/src/main/java/com/quickkart/service/OrderService.java`)
- Order lifecycle → Cart management: clears cart (evidence: `backend/src/main/java/com/quickkart/service/OrderService.java`)
- Order lifecycle → Order event publisher: publishes events (evidence: `backend/src/main/java/com/quickkart/service/OrderService.java`)
- Order lifecycle → Prometheus metrics: records placement (evidence: `backend/src/main/java/com/quickkart/service/OrderService.java`)
- Order event publisher → Kafka: publishes (evidence: `README.md`)
- Kafka → Order event consumer: delivers events (evidence: `README.md`)
- Order event consumer → Agent scheduler: routes confirmed (evidence: `README.md`)
- Order records → MongoDB: stored in (evidence: `README.md`)
- Product records → MongoDB: stored in (evidence: `README.md`)
- User records → MongoDB: stored in (evidence: `README.md`)
- Cart records → MongoDB: stored in (evidence: `README.md`)
- Product catalog → Redis cache: caches products (evidence: `README.md`)
- Prometheus metrics → Campus users: exposes telemetry (evidence: `README.md`)
