How selim2066/medistore-msr-frontend works
1. Overall shape
This repository is the frontend for MediStore, built with Next.js 15 App Router and TypeScript. It is structured as a multi-role commerce UI for customers, sellers, and admins, while the actual business backend lives in a separate service (Node/Express/PostgreSQL/Prisma per the README).
2. Route and layout boundaries
The app is split into three major route groups:
- (commonLayout) for public pages like homepage, shop, login/register, about, contact, privacy, and payment result pages.
- (customerLayout) for authenticated customer flows: cart, checkout, orders, and profile.
- (dashboardLayout) for protected dashboards: seller and admin sections.
Each group has its own layout, which is the main architectural boundary for navigation, auth gating, and shared chrome.
3. Public commerce flow
The public side centers on discovery: homepage sections, shop listing, and product detail pages under shop/ and shop/[id]/. The shop area also has local loading/error boundaries, showing that listing and detail data are fetched asynchronously and designed to fail independently without taking down the whole app.
4. Customer purchase flow
The customer journey runs through cart -> checkout -> payment -> order history. Cart state is maintained in a dedicated React context (cart-context.tsx), while checkout is handled by a feature component in components/module/checkout. Payment outcome pages live under /payment/success, /cancel, and /fail, which indicates a redirect-based payment flow with distinct result handling.
5. Seller dashboard flow
Seller features are isolated under seller/ and cover medicine management, order processing, and a dashboard view. The seller medicine UI includes form and delete/update controls, while seller orders include status updates. This is a separate operational area from customer shopping, but still uses the same application shell and shared UI primitives.
6. Admin management flow
Admin functionality is split into users, categories, and platform orders. The admin pages use dedicated client components for richer table-style interactions. This indicates an admin panel focused on moderation and catalog governance rather than commerce checkout.
7. Backend interaction model
The frontend uses a mix of:
- Service modules in src/service/* for API access to domain resources.
- Next.js server actions in src/actions/* for mutations and server-side operations.
- API routes in src/app/api/* for special integrations and proxying.
This separation suggests read/write operations are not all handled the same way: standard domain calls go through services, while sensitive or framework-integrated flows use server actions and route handlers.
8. Authentication boundary
Authentication is handled through better-auth on the client side (lib/auth-client.ts) with a catch-all API route under api/auth/[...path]. The presence of proxy.ts strongly suggests cookie/session forwarding between the Next.js app and the external backend auth system. Role-based access is a key architectural concern because routes are grouped by customer, seller, and admin access.
9. Special integration routes
There are two notable non-CRUD API integrations:
- api/payment/init for starting a payment session.
- api/chat for a chat feature.
These are isolated from normal page rendering, which keeps payment initiation and chat transport separate from the UI layer.
10. Media and asset handling
The app uses Cloudinary (lib/cloudinary.ts) for image upload/storage, likely for medicine and profile assets. Public images live in public/, while feature components such as medicine forms and image galleries indicate that uploaded media is a core part of the product catalog flow.
11. Shared UI and feature composition
The codebase follows a strong component split:
- components/ui contains reusable design-system primitives from shadcn/ui.
- components/layout contains app shell elements like navbar, footer, sidebar, and theme toggle.
- components/module/* contains feature-specific UIs for auth, home, shop, checkout, orders, profile, seller, admin, and chat.
This keeps reusable styling/behavior separate from domain-specific screens.
12. Client state and interaction helpers
Global interaction concerns are kept in small dedicated layers:
- cart-context.tsx for shopping cart state
- ThemeProvider.tsx for dark/light theme
- lenis-context.tsx and animation hooks for smooth scrolling and reveal effects
These are cross-cutting UI concerns, not business logic.
13. Error/loading strategy
Nearly every route segment has local loading.tsx and error.tsx files. Architecturally, this means the app is designed for segment-level resilience: page data can load progressively and fail in isolation without collapsing the entire application.
14. Primary data flow to diagram
The main runtime flow is:
browser UI → Next.js page/component → service or server action → external backend API,
with special branches for auth/session handling, payment initiation, chat, and Cloudinary uploads. The frontend is therefore a presentation and orchestration layer, not the source of truth for commerce data.
15. What to emphasize in an architecture diagram
The diagram should show three top-level UI domains (public, customer, dashboard), a shared component/state layer, and an external backend boundary. The most important external dependencies are the API backend, better-auth session flow, Cloudinary, and the payment integration path.
Main entry points: module Feature UI · layout.tsx App shell · (dashboardLayout) Dashboard area · api API routes
Components 18
UI routes
App Router route groups and pages
- App shell · Global app layout, loading, error, and not-found boundaries
src/app/layout.tsx - Public area · Public commerce pages for discovery, auth entry, and payment outcomes
src/app/(commonLayout) - Customer area · Authenticated shopping and account flows
src/app/(customerLayout) - Dashboard area · Protected seller and admin dashboards
src/app/(dashboardLayout) - Shop pages · Homepage, shop listing, product detail, and payment result routes
src/app/(commonLayout)/shop - Customer flows · Cart, checkout, orders, and profile routes
src/app/(customerLayout) - Seller tools · Seller dashboard, medicines, and order management routes
src/app/(dashboardLayout)/seller - Admin panel · Admin dashboard, users, categories, and orders routes
src/app/(dashboardLayout)/admin
Shared app layer
Reusable components, state, hooks, and providers
- Shell UI · Navbar, footer, sidebar, theme toggle, and shared page chrome
src/components/layout - Feature UI · Home, shop, checkout, auth, orders, profile, chat, seller, and admin components
src/components/module - UI kit · Reusable shadcn-style primitives used across the app
src/components/ui - State & effects · Cart, theme, scroll, animation, and GSAP helpers
src/context
Data access
Client services, server actions, and route handlers
- Services · Domain service modules for category, medicine, order, payment, review, and user data
src/service - Server actions · Server-side mutations for category, medicine, order, review, and user workflows
src/actions - API routes · Auth proxy, payment init, and chat endpoints
src/app/api
External systems
Backend and third-party integrations
- Auth client · Client-side auth integration and session handling
src/lib/auth-client.ts - Cloudinary · Image upload and asset storage integration
src/lib/cloudinary.ts - Backend API · Separate Node/Express/PostgreSQL/Prisma commerce backend
Connections 22
- App shell → Public area: routes · Public pages are mounted under the common route group
- App shell → Customer area: routes · Customer pages are mounted under the customer route group
- App shell → Dashboard area: routes · Seller and admin pages are mounted under the dashboard route group
- Public area → Shop pages: contains · Public commerce discovery and payment result screens
- Customer area → Customer flows: contains · Cart, checkout, order history, and profile screens
- Dashboard area → Seller tools: contains · Seller operational pages
- Dashboard area → Admin panel: contains · Admin governance pages
- App shell → Shell UI: uses · Global chrome and navigation are shared through layout components
- App shell → Feature UI: renders · Pages compose feature-specific modules
- Feature UI → UI kit: builds on · Feature UIs are assembled from reusable primitives
- Feature UI → State & effects: uses · Interactive modules rely on shared client state and effects
- Customer flows → State & effects: cart state · Cart flow is backed by a dedicated React context
- Services → Backend API: reads/writes · Standard domain data access goes to the external backend
- Server actions → Backend API: mutates · Server actions perform protected write operations against backend data
- API routes → Auth client: auth proxy · Auth endpoints forward session and cookie handling
- API routes → Backend API: proxies · Special integrations proxy to the backend or third-party flow
- Auth client → Backend API: sessions · Client auth depends on the external identity backend
- Feature UI → Services: queries · Shop, profile, orders, and dashboard UIs fetch domain data via services
- Feature UI → Server actions: submits · Forms and mutations use server actions for protected writes
- Feature UI → API routes: special flows · Payment initiation, auth, and chat use dedicated route handlers
- Feature UI → Cloudinary: uploads · Media-heavy flows use Cloudinary for images
- State & effects → App shell: cross-cutting · Theme, scroll, and animation behavior is wired through the app shell