# selim2066/medistore-msr-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/selim2066/medistore-msr-frontend
- Repository: https://github.com/selim2066/medistore-msr-frontend

## Overview

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: [`src/components/module`](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/components/module) (Feature UI), [`src/app/layout.tsx`](https://github.com/selim2066/medistore-msr-frontend/blob/main/src/app/layout.tsx) (App shell), [`src/app/(dashboardLayout)`](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(dashboardLayout)) (Dashboard area), [`src/app/api`](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/api) (API routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["UI routes"]
  node_app_root["App shell<br/>next app<br/>[layout.tsx]"]
  node_common_layout["Public area<br/>route group"]
  node_customer_layout["Customer area<br/>route group"]
  node_dashboard_layout["Dashboard area<br/>route group"]
  node_shop_pages["Shop pages<br/>commerce pages"]
  node_customer_pages["Customer flows<br/>customer pages"]
  node_seller_pages["Seller tools<br/>seller pages"]
  node_admin_pages["Admin panel<br/>admin pages"]
end

subgraph group_shared["Shared app layer"]
  node_layout_ui["Shell UI<br/>layout components"]
  node_domain_ui["Feature UI<br/>module components"]
  node_ui_primitives["UI kit<br/>design system"]
  node_state_hooks["State & effects<br/>cross-cutting"]
end

subgraph group_data["Data access"]
  node_services["Services<br/>api client"]
  node_actions["Server actions<br/>mutations"]
  node_route_handlers["API routes<br/>route handlers"]
end

subgraph group_external["External systems"]
  node_auth_client["Auth client<br/>[auth-client.ts]"]
  node_cloudinary["Cloudinary<br/>media storage<br/>[cloudinary.ts]"]
  node_backend_api[("Backend API<br/>external backend")]
end

node_app_root -->|"routes"| node_common_layout
node_app_root -->|"routes"| node_customer_layout
node_app_root -->|"routes"| node_dashboard_layout
node_common_layout -->|"contains"| node_shop_pages
node_customer_layout -->|"contains"| node_customer_pages
node_dashboard_layout -->|"contains"| node_seller_pages
node_dashboard_layout -->|"contains"| node_admin_pages
node_app_root -->|"uses"| node_layout_ui
node_app_root -->|"renders"| node_domain_ui
node_domain_ui -->|"builds on"| node_ui_primitives
node_domain_ui -->|"uses"| node_state_hooks
node_customer_pages -->|"cart state"| node_state_hooks
node_services -->|"reads/writes"| node_backend_api
node_actions -->|"mutates"| node_backend_api
node_route_handlers -->|"auth proxy"| node_auth_client
node_route_handlers -->|"proxies"| node_backend_api
node_auth_client -->|"sessions"| node_backend_api
node_domain_ui -->|"queries"| node_services
node_domain_ui -->|"submits"| node_actions
node_domain_ui -->|"special flows"| node_route_handlers
node_domain_ui -->|"uploads"| node_cloudinary
node_state_hooks -->|"cross-cutting"| node_app_root

click node_app_root "https://github.com/selim2066/medistore-msr-frontend/blob/main/src/app/layout.tsx"
click node_common_layout "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(commonLayout)"
click node_customer_layout "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(customerLayout)"
click node_dashboard_layout "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(dashboardLayout)"
click node_shop_pages "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(commonLayout)/shop"
click node_customer_pages "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(customerLayout)"
click node_seller_pages "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(dashboardLayout)/seller"
click node_admin_pages "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(dashboardLayout)/admin"
click node_layout_ui "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/components/layout"
click node_domain_ui "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/components/module"
click node_ui_primitives "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/components/ui"
click node_state_hooks "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/context"
click node_services "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/service"
click node_actions "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/actions"
click node_route_handlers "https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/api"
click node_auth_client "https://github.com/selim2066/medistore-msr-frontend/blob/main/src/lib/auth-client.ts"
click node_cloudinary "https://github.com/selim2066/medistore-msr-frontend/blob/main/src/lib/cloudinary.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_common_layout,node_customer_layout,node_dashboard_layout,node_shop_pages,node_customer_pages,node_seller_pages,node_admin_pages toneBlue
class node_layout_ui,node_domain_ui,node_ui_primitives,node_state_hooks toneAmber
class node_services,node_actions,node_route_handlers toneMint
class node_auth_client,node_cloudinary,node_backend_api toneRose
```

## Components

### UI routes

App Router route groups and pages

- [App shell](https://github.com/selim2066/medistore-msr-frontend/blob/main/src/app/layout.tsx): next app · Global app layout, loading, error, and not-found boundaries · `src/app/layout.tsx`
- [Public area](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(commonLayout)): route group · Public commerce pages for discovery, auth entry, and payment outcomes · `src/app/(commonLayout)`
- [Customer area](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(customerLayout)): route group · Authenticated shopping and account flows · `src/app/(customerLayout)`
- [Dashboard area](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(dashboardLayout)): route group · Protected seller and admin dashboards · `src/app/(dashboardLayout)`
- [Shop pages](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(commonLayout)/shop): commerce pages · Homepage, shop listing, product detail, and payment result routes · `src/app/(commonLayout)/shop`
- [Customer flows](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(customerLayout)): customer pages · Cart, checkout, orders, and profile routes · `src/app/(customerLayout)`
- [Seller tools](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(dashboardLayout)/seller): seller pages · Seller dashboard, medicines, and order management routes · `src/app/(dashboardLayout)/seller`
- [Admin panel](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/(dashboardLayout)/admin): admin pages · Admin dashboard, users, categories, and orders routes · `src/app/(dashboardLayout)/admin`

### Shared app layer

Reusable components, state, hooks, and providers

- [Shell UI](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/components/layout): layout components · Navbar, footer, sidebar, theme toggle, and shared page chrome · `src/components/layout`
- [Feature UI](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/components/module): module components · Home, shop, checkout, auth, orders, profile, chat, seller, and admin components · `src/components/module`
- [UI kit](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/components/ui): design system · Reusable shadcn-style primitives used across the app · `src/components/ui`
- [State & effects](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/context): cross-cutting · Cart, theme, scroll, animation, and GSAP helpers · `src/context`

### Data access

Client services, server actions, and route handlers

- [Services](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/service): api client · Domain service modules for category, medicine, order, payment, review, and user data · `src/service`
- [Server actions](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/actions): mutations · Server-side mutations for category, medicine, order, review, and user workflows · `src/actions`
- [API routes](https://github.com/selim2066/medistore-msr-frontend/tree/main/src/app/api): route handlers · Auth proxy, payment init, and chat endpoints · `src/app/api`

### External systems

Backend and third-party integrations

- [Auth client](https://github.com/selim2066/medistore-msr-frontend/blob/main/src/lib/auth-client.ts): better-auth client · Client-side auth integration and session handling · `src/lib/auth-client.ts`
- [Cloudinary](https://github.com/selim2066/medistore-msr-frontend/blob/main/src/lib/cloudinary.ts): media storage · Image upload and asset storage integration · `src/lib/cloudinary.ts`
- **Backend API**: external backend · Separate Node/Express/PostgreSQL/Prisma commerce backend

## Connections

- 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
