rohan-bhau/grocio

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.