# rohan-bhau/grocio architecture

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

- Interactive diagram: https://gitdiagram.com/rohan-bhau/grocio
- Repository: https://github.com/rohan-bhau/grocio

## Overview

1. **Overall shape**
   - This is a role-based grocery ordering and delivery platform built on **Next.js App Router + TypeScript**.
   - The codebase is split into three main user experiences: **customer**, **admin**, and **delivery agent**.

2. **Frontend application structure**
   - UI pages live under `src/app/...`, with separate route areas for `user`, `admin`, and `delivery`.
   - Role-specific layouts (`admin/layout.tsx`, `delivery/layout.tsx`) provide distinct shells/navigation for each dashboard.
   - Shared UI lives in `src/components`, while dashboard-specific composites are in `src/components/dashboards`.

3. **Server/API boundary**
   - Business logic is primarily exposed through **Next.js route handlers** under `src/app/api/...`.
   - The app uses the framework’s built-in server/client split: pages and interactive components on the client, data access and integrations through API routes.

4. **Authentication and authorization**
   - Authentication is handled with **NextAuth** (`src/auth.ts`, `src/app/api/auth/[...nextauth]/route.ts`).
   - Registration is custom (`/api/auth/register`), and user/role lookup is exposed via `/api/me` and `/api/check-for-admin`.
   - `proxy.ts` likely guards routes and enforces access to admin/delivery/user areas based on auth state and role.

5. **Core domain model**
   - The main persistent entities are defined in `src/models`:
     - `user`
     - `grocery`
     - `order`
     - `deliveryAssignment`
     - `message`
   - `src/lib/db.ts` indicates a centralized database connection, likely MongoDB/Mongoose-based given the model structure.

6. **Customer ordering flow**
   - Customers browse groceries, manage a cart, and place orders from `src/app/user/cart`, `checkout`, and order pages.
   - Order lifecycle routes include `/api/user/order`, `/api/user/payment`, `/api/user/my-orders`, `/api/user/get-order/[id]`, and `/api/user/stripe/webhook`.
   - Success/cancel outcomes are surfaced through dedicated pages in `src/app/user/order-success` and `order-cancel`.

7. **Payments**
   - Payment processing is integrated on the backend through a **Stripe webhook** route.
   - This implies orders are finalized/updated server-side from payment events rather than only from the client checkout flow.

8. **Admin subsystem**
   - Admin pages cover grocery CRUD and order oversight: add, view, edit/delete groceries, and manage orders.
   - Corresponding API routes in `src/app/api/admin/...` provide grocery and order management operations.
   - This subsystem is the operational back office for inventory and order status control.

9. **Delivery subsystem**
   - Delivery agents have their own dashboard for assignment requests, active orders, and history.
   - API routes support assignment retrieval/acceptance, current order lookup, and OTP send/verify for delivery confirmation.
   - `src/app/api/socket/update-location` and related delivery pages suggest live delivery progress tracking.

10. **Real-time and messaging**
   - The app has a chat/message subsystem with routes for saving messages, fetching messages, and AI suggestions.
   - `src/lib/socket.ts` and `src/app/api/socket/connect` indicate real-time socket infrastructure.
   - `src/lib/emitEventHandlers.ts` suggests server-emitted events are used to push updates such as location or order state changes.

11. **Media, notification, and support integrations**
   - `src/lib/cloudinary.ts` indicates image/file upload handling, likely for grocery assets.
   - `src/lib/mailer.ts` supports email notifications, probably for registration, OTP, or order events.

12. **Client state and app wiring**
   - Global state is managed with **Redux** (`cartSlice`, `userSlice`, `store.ts`) and exposed through `StoreProvider`.
   - `Provider.tsx` and `InitUser.tsx` suggest the app initializes authenticated user state before rendering protected UI.
   - Hooks like `useGetMe` help synchronize client state with the authenticated server session.

13. **Maps and location-aware UI**
   - Components like `CheckoutMap`, `LiveMap`, and `GeoUpdater` show that location is a first-class part of the product.
   - These likely support delivery tracking, checkout address selection, and real-time courier movement.

14. **Static assets and presentation**
   - Static assets live in `public/assets`, while shared presentation components such as `Navbar`, `Footer`, `HeroSection`, and `CategorySlider` support the marketing/home experience.
   - The root app page is separate from the authenticated dashboards, so the public landing experience is distinct from the operational app.

15. **Key architectural boundary**
   - The most important boundary is between **role-based client dashboards** and **server-side API/domain logic**.
   - The app’s data flow is: client dashboard → API route → database/integrations (Stripe, socket, email, cloud upload) → updated state back to client via fetch/socket/session.

Main entry points: [`src/models/user.model.ts`](https://github.com/rohan-bhau/grocio/blob/main/src/models/user.model.ts) (Domain models), [`src/app/layout.tsx`](https://github.com/rohan-bhau/grocio/blob/main/src/app/layout.tsx) (App shell), [`src/app/delivery/page.tsx`](https://github.com/rohan-bhau/grocio/blob/main/src/app/delivery/page.tsx) (Delivery UI), [`src/lib/mailer.ts`](https://github.com/rohan-bhau/grocio/blob/main/src/lib/mailer.ts) (Integrations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_app["Public app"]
  node_app_root["App shell<br/>Next.js app<br/>[layout.tsx]"]
  node_landing_page["Home<br/>public page<br/>[page.tsx]"]
  node_auth_pages["Auth pages<br/>auth UI<br/>[page.tsx]"]
end

subgraph group_role_dashboards["Role dashboards"]
  node_user_dashboard["Customer UI<br/>role dashboard<br/>[page.tsx]"]
  node_admin_layout["Admin shell<br/>dashboard layout<br/>[layout.tsx]"]
  node_admin_dashboard["Admin UI<br/>role dashboard<br/>[page.tsx]"]
  node_delivery_layout["Delivery shell<br/>dashboard layout<br/>[layout.tsx]"]
  node_delivery_dashboard["Delivery UI<br/>role dashboard<br/>[page.tsx]"]
end

subgraph group_api_boundary["API boundary"]
  node_auth_routes["Auth API<br/>route handlers<br/>[route.ts]"]
  node_me_api["Me API<br/>route handler<br/>[route.ts]"]
  node_user_orders_api["Customer orders<br/>route handlers<br/>[route.ts]"]
  node_admin_api["Admin API<br/>route handlers<br/>[route.ts]"]
  node_delivery_api["Delivery API<br/>route handlers<br/>[route.ts]"]
  node_chat_api["Chat API<br/>route handlers<br/>[route.ts]"]
  node_socket_api["Socket API<br/>realtime routes<br/>[route.ts]"]
end

subgraph group_shared_core["Shared UI & state"]
  node_store_provider["Store provider<br/>state wiring<br/>[StoreProvider.tsx]"]
  node_client_state["Redux state<br/>client store<br/>[store.ts]"]
  node_shared_components["Shared UI<br/>component library<br/>[Navbar.tsx]"]
end

subgraph group_domain_infra["Domain & infra"]
  node_db_models[("Domain models<br/>mongoose models<br/>[user.model.ts]")]
  node_db_connection[("Database<br/>db connector<br/>[db.ts]")]
  node_integrations{{"Integrations<br/>external services<br/>[mailer.ts]"}}
end

node_app_root -->|"renders"| node_landing_page
node_app_root -->|"hosts"| node_auth_pages
node_app_root -->|"contains"| node_user_dashboard
node_app_root -->|"contains"| node_admin_dashboard
node_app_root -->|"contains"| node_delivery_dashboard
node_admin_layout -->|"wraps"| node_admin_dashboard
node_delivery_layout -->|"wraps"| node_delivery_dashboard
node_user_dashboard -->|"fetches"| node_user_orders_api
node_admin_dashboard -->|"manages"| node_admin_api
node_delivery_dashboard -->|"uses"| node_delivery_api
node_shared_components -->|"uses"| node_store_provider
node_store_provider -->|"provides"| node_client_state
node_auth_routes -->|"reads/writes"| node_db_models
node_me_api -->|"depends on"| node_auth_routes
node_user_orders_api -->|"reads/writes"| node_db_models
node_admin_api -->|"reads/writes"| node_db_models
node_delivery_api -->|"reads/writes"| node_db_models
node_chat_api -->|"reads/writes"| node_db_models
node_socket_api -->|"streams"| node_integrations
node_user_orders_api -->|"integrates"| node_integrations
node_admin_api -->|"integrates"| node_integrations
node_delivery_api -->|"integrates"| node_integrations
node_chat_api -->|"integrates"| node_integrations
node_db_models -->|"uses"| node_db_connection
node_auth_pages -->|"submits to"| node_auth_routes
node_user_dashboard -->|"hydrates"| node_me_api
node_delivery_dashboard -->|"tracks"| node_socket_api
node_user_dashboard -->|"composes"| node_shared_components
node_admin_dashboard -->|"composes"| node_shared_components
node_delivery_dashboard -->|"composes"| node_shared_components

click node_app_root "https://github.com/rohan-bhau/grocio/blob/main/src/app/layout.tsx"
click node_landing_page "https://github.com/rohan-bhau/grocio/blob/main/src/app/page.tsx"
click node_auth_pages "https://github.com/rohan-bhau/grocio/blob/main/src/app/login/page.tsx"
click node_user_dashboard "https://github.com/rohan-bhau/grocio/blob/main/src/app/user/cart/page.tsx"
click node_admin_layout "https://github.com/rohan-bhau/grocio/blob/main/src/app/admin/layout.tsx"
click node_admin_dashboard "https://github.com/rohan-bhau/grocio/blob/main/src/app/admin/page.tsx"
click node_delivery_layout "https://github.com/rohan-bhau/grocio/blob/main/src/app/delivery/layout.tsx"
click node_delivery_dashboard "https://github.com/rohan-bhau/grocio/blob/main/src/app/delivery/page.tsx"
click node_auth_routes "https://github.com/rohan-bhau/grocio/blob/main/src/app/api/auth/[...nextauth]/route.ts"
click node_me_api "https://github.com/rohan-bhau/grocio/blob/main/src/app/api/me/route.ts"
click node_user_orders_api "https://github.com/rohan-bhau/grocio/blob/main/src/app/api/user/order/route.ts"
click node_admin_api "https://github.com/rohan-bhau/grocio/blob/main/src/app/api/admin/add-grocery/route.ts"
click node_delivery_api "https://github.com/rohan-bhau/grocio/blob/main/src/app/api/delivery/get-assignments/route.ts"
click node_chat_api "https://github.com/rohan-bhau/grocio/blob/main/src/app/api/chat/messages/route.ts"
click node_socket_api "https://github.com/rohan-bhau/grocio/blob/main/src/app/api/socket/connect/route.ts"
click node_store_provider "https://github.com/rohan-bhau/grocio/blob/main/src/redux/StoreProvider.tsx"
click node_client_state "https://github.com/rohan-bhau/grocio/blob/main/src/redux/store.ts"
click node_shared_components "https://github.com/rohan-bhau/grocio/blob/main/src/components/Navbar.tsx"
click node_db_models "https://github.com/rohan-bhau/grocio/blob/main/src/models/user.model.ts"
click node_db_connection "https://github.com/rohan-bhau/grocio/blob/main/src/lib/db.ts"
click node_integrations "https://github.com/rohan-bhau/grocio/blob/main/src/lib/mailer.ts"

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_root,node_landing_page,node_auth_pages toneBlue
class node_user_dashboard,node_admin_layout,node_admin_dashboard,node_delivery_layout,node_delivery_dashboard toneAmber
class node_auth_routes,node_me_api,node_user_orders_api,node_admin_api,node_delivery_api,node_chat_api,node_socket_api toneMint
class node_store_provider,node_client_state,node_shared_components toneRose
class node_db_models,node_db_connection,node_integrations toneIndigo
```

## Components

### Public app

Landing and authentication entry points

- [App shell](https://github.com/rohan-bhau/grocio/blob/main/src/app/layout.tsx): Next.js app · Root layout, landing page, and app-wide styling · `src/app/layout.tsx`
- [Home](https://github.com/rohan-bhau/grocio/blob/main/src/app/page.tsx): public page · Public marketing and entry page · `src/app/page.tsx`
- [Auth pages](https://github.com/rohan-bhau/grocio/blob/main/src/app/login/page.tsx): auth UI · Login, register, and unauthorized screens · `src/app/login/page.tsx`

### Role dashboards

Customer, admin, and delivery experiences

- [Customer UI](https://github.com/rohan-bhau/grocio/blob/main/src/app/user/cart/page.tsx): role dashboard · Customer cart, checkout, orders, and tracking · `src/app/user/cart/page.tsx`
- [Admin shell](https://github.com/rohan-bhau/grocio/blob/main/src/app/admin/layout.tsx): dashboard layout · Admin navigation and page shell · `src/app/admin/layout.tsx`
- [Admin UI](https://github.com/rohan-bhau/grocio/blob/main/src/app/admin/page.tsx): role dashboard · Grocery and order management screens · `src/app/admin/page.tsx`
- [Delivery shell](https://github.com/rohan-bhau/grocio/blob/main/src/app/delivery/layout.tsx): dashboard layout · Delivery agent navigation and page shell · `src/app/delivery/layout.tsx`
- [Delivery UI](https://github.com/rohan-bhau/grocio/blob/main/src/app/delivery/page.tsx): role dashboard · Requests, active orders, and history · `src/app/delivery/page.tsx`

### API boundary

Route handlers for auth, domain, and integrations

- [Auth API](https://github.com/rohan-bhau/grocio/blob/main/src/app/api/auth/[...nextauth]/route.ts): route handlers · NextAuth session and custom registration · `src/app/api/auth/[...nextauth]/route.ts`
- [Me API](https://github.com/rohan-bhau/grocio/blob/main/src/app/api/me/route.ts): route handler · Current user and role lookup · `src/app/api/me/route.ts`
- [Customer orders](https://github.com/rohan-bhau/grocio/blob/main/src/app/api/user/order/route.ts): route handlers · Order creation, history, lookup, and payment flow · `src/app/api/user/order/route.ts`
- [Admin API](https://github.com/rohan-bhau/grocio/blob/main/src/app/api/admin/add-grocery/route.ts): route handlers · Grocery CRUD and order status management · `src/app/api/admin/add-grocery/route.ts`
- [Delivery API](https://github.com/rohan-bhau/grocio/blob/main/src/app/api/delivery/get-assignments/route.ts): route handlers · Assignments, current orders, and OTP delivery steps · `src/app/api/delivery/get-assignments/route.ts`
- [Chat API](https://github.com/rohan-bhau/grocio/blob/main/src/app/api/chat/messages/route.ts): route handlers · Message persistence and AI suggestions · `src/app/api/chat/messages/route.ts`
- [Socket API](https://github.com/rohan-bhau/grocio/blob/main/src/app/api/socket/connect/route.ts): realtime routes · Socket connection and live location updates · `src/app/api/socket/connect/route.ts`

### Shared UI & state

Reusable components, providers, and client state

- [Store provider](https://github.com/rohan-bhau/grocio/blob/main/src/redux/StoreProvider.tsx): state wiring · Redux provider and app initialization · `src/redux/StoreProvider.tsx`
- [Redux state](https://github.com/rohan-bhau/grocio/blob/main/src/redux/store.ts): client store · Cart and authenticated user state · `src/redux/store.ts`
- [Shared UI](https://github.com/rohan-bhau/grocio/blob/main/src/components/Navbar.tsx): component library · Reusable UI and dashboard composites · `src/components/Navbar.tsx`

### Domain & infra

Models, persistence, and external integrations

- [Domain models](https://github.com/rohan-bhau/grocio/blob/main/src/models/user.model.ts): mongoose models · User, grocery, order, assignment, and message entities · `src/models/user.model.ts`
- [Database](https://github.com/rohan-bhau/grocio/blob/main/src/lib/db.ts): db connector · Central database connection layer · `src/lib/db.ts`
- [Integrations](https://github.com/rohan-bhau/grocio/blob/main/src/lib/mailer.ts): external services · Stripe, Cloudinary, mailer, and socket/event helpers · `src/lib/mailer.ts`

## Connections

- App shell → Home: renders · Root app presents the public landing experience
- App shell → Auth pages: hosts · Public authentication and error pages live in the app shell
- App shell → Customer UI: contains · Customer routes are mounted under the app router
- App shell → Admin UI: contains · Admin routes are mounted under the app router
- App shell → Delivery UI: contains · Delivery routes are mounted under the app router
- Admin shell → Admin UI: wraps · Admin shell provides dashboard navigation and layout
- Delivery shell → Delivery UI: wraps · Delivery shell provides dashboard navigation and layout
- Customer UI → Customer orders: fetches · Customer UI interacts with order and payment routes
- Admin UI → Admin API: manages · Admin UI drives grocery and order operations
- Delivery UI → Delivery API: uses · Delivery UI retrieves assignments and updates delivery state
- Shared UI → Store provider: uses · Shared client components are rendered inside the provider tree
- Store provider → Redux state: provides · Redux store is exposed to the client app
- Auth API → Domain models: reads/writes · Authentication and registration touch user records
- Me API → Auth API: depends on · Current-user lookup is session-aware
- Customer orders → Domain models: reads/writes · Order and payment endpoints persist order data
- Admin API → Domain models: reads/writes · Admin CRUD and status changes operate on grocery and order data
- Delivery API → Domain models: reads/writes · Delivery assignment and OTP flows use assignment and order data
- Chat API → Domain models: reads/writes · Message routes persist chat content
- Socket API → Integrations: streams · Realtime events and location updates use socket helpers
- Customer orders → Integrations: integrates · Payment webhook and order events depend on Stripe and notifications
- Admin API → Integrations: integrates · Admin workflows may trigger uploads and notifications
- Delivery API → Integrations: integrates · OTP and delivery updates rely on notification and realtime helpers
- Chat API → Integrations: integrates · AI suggestions and chat persistence use external helpers
- Domain models → Database: uses · Models are backed by the central database connection
- Auth pages → Auth API: submits to · Login and registration screens use auth endpoints
- Customer UI → Me API: hydrates · Client state is synchronized from the current-user endpoint
- Delivery UI → Socket API: tracks · Live delivery pages subscribe to location and event updates
- Customer UI → Shared UI: composes · Customer views are built from shared UI pieces
- Admin UI → Shared UI: composes · Admin screens reuse shared dashboard components
- Delivery UI → Shared UI: composes · Delivery screens reuse shared dashboard components