# sani-mohibur/tutor-marketplace-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/sani-mohibur/tutor-marketplace-frontend
- Repository: https://github.com/sani-mohibur/tutor-marketplace-frontend

## Overview

1. **Repository shape**
   - This is a **frontend-only Next.js 16 App Router** application for a tutor marketplace.
   - The frontend depends on an external **backend API** for authentication, marketplace data, bookings, payments, reviews, and admin actions.

2. **Top-level route partitioning**
   - `src/app/(client)` contains the main user-facing experience.
   - `src/app/admin` is a separate admin area with its own layout and management pages.
   - Inside `(client)`, the app is further split into `public`, `auth`, and authenticated product areas like `dashboard`, `bookings`, `profile`, `slots`, `tutors`, and `reviews`.

3. **Layout hierarchy**
   - `src/app/layout.tsx` is the root shell for fonts, global styles, theme/provider wiring, and toast notifications.
   - `src/app/(client)/layout.tsx` adds the shared public/client chrome such as navbar and footer.
   - `src/app/admin/layout.tsx` isolates the admin UI boundary.
   - Some sections also have their own local layouts, especially auth and role-based areas.

4. **Role-based application model**
   - The UI is organized around three roles: **student**, **tutor**, and **admin**.
   - `dashboard`, `bookings`, and `profile` use **parallel routes** like `@student` and `@tutor` so the same URL space can render different role-specific content.
   - Role constants live in `src/constants/roles.ts`, and the backend session determines which experience is shown.

5. **Authentication boundary**
   - Auth UI lives in `src/components/auth` and routes under `(auth)` cover login, register, forgot password, and reset password.
   - `src/lib/auth-client.ts` configures the frontend side of **better-auth**.
   - The actual session state is backend-managed via **HTTP-only cookies**, so the frontend is mostly a client and presentation layer for auth flows.

6. **Marketplace discovery flow**
   - The landing page and tutor discovery pages are built from components under `src/components/home` and `src/components/tutors`.
   - The home page highlights featured tutors and categories, while `/tutors` supports browsing, filtering, and tutor detail views.
   - This is a key server-to-client data path: the frontend renders marketplace content, but the backend supplies the tutor and category data.

7. **Booking and availability subsystem**
   - `src/components/slots` and the `/slots` routes handle tutor availability creation and listing.
   - `src/components/bookings` covers student and tutor booking views, including status-specific lists and cards.
   - The booking flow is role-aware: tutors publish slots, students book them, and booking state is then surfaced in dashboards and booking pages.

8. **Payments and Stripe Checkout**
   - Payment handling is a major external integration.
   - Tutors can mark slots as `cash`, `stripe`, or `both`, which changes how the booking/payment flow behaves.
   - The frontend triggers Stripe Checkout through the backend, then receives the user back on `/payment-success` or `/payment-cancel`.
   - The success page is not just confirmation UI; it also displays receipt details and supports receipt download.

9. **Profile and image handling**
   - Profile editing is split by role under `src/components/profile/student` and `src/components/profile/tutor`.
   - Profile images are uploaded to **Cloudinary** and displayed through Next.js image optimization.
   - `next.config.ts` is architecturally important because it allows remote images from `res.cloudinary.com`.

10. **Admin console**
   - `src/app/admin` is a separate operational area for platform staff.
   - The admin pages manage users, bookings, tutor verifications, categories, featured tutors, and availabilities.
   - This is a distinct boundary from the customer-facing marketplace and is protected by role-based access.

11. **Shared UI and design system**
   - The app uses **shadcn/ui** primitives in `src/components/ui` plus custom feature components elsewhere.
   - `src/context/ThemeContext.tsx` provides the dark/light theme behavior across the app.
   - Shared building blocks like pagination, dialogs, nav, footer, and mobile drawer components are centralized so the product surfaces stay consistent.

12. **External service and deployment boundaries**
   - The frontend talks to the backend through environment-configured URLs, with the README describing API proxying/rewrite behavior to avoid CORS issues.
   - The app is deployed on **Vercel**, while the backend runs separately.
   - Runtime-sensitive configuration includes backend API URL, frontend base URL, and the Stripe publishable key.

13. **How to think about the data flow**
   - User interaction starts in the Next.js route/component layer.
   - Forms and action buttons call the auth client or backend API.
   - The backend owns durable state: sessions, bookings, slots, payments, reviews, profile image metadata, and admin changes.
   - The frontend renders the returned state into role-specific screens and redirects users through payment/auth flows where needed.

Main entry points: [`src/app/(client)/layout.tsx`](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/(client)/layout.tsx) (Client shell), [`src/components/ui`](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/ui) (UI primitives), [`src/app/layout.tsx`](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/layout.tsx) (Root shell), [`src/app/(client)/(auth)`](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/(auth)) (Auth flows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_root_shell["Root shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_client_shell["Client shell<br/>App layout<br/>[layout.tsx]"]
  node_public_pages["Public pages<br/>Route group"]
  node_auth_flows["Auth flows<br/>Route group"]
  node_dashboard_area["Dashboard<br/>Role routes"]
  node_bookings_area["Bookings<br/>Role routes"]
  node_profile_area["Profile<br/>Role routes"]
  node_tutors_area["Tutors<br/>Discovery routes"]
  node_slots_area["Slots<br/>Availability routes"]
  node_reviews_page["Reviews<br/>Route<br/>[page.tsx]"]
  node_payment_pages["Payment return<br/>Route pair"]
end

subgraph group_admin["Admin area"]
  node_admin_shell["Admin shell<br/>App layout<br/>[layout.tsx]"]
  node_admin_pages["Admin pages<br/>Management routes"]
end

subgraph group_shared["Shared UI"]
  node_layout_ui["Layout UI<br/>Shared components"]
  node_home_ui["Home UI<br/>Shared components"]
  node_tutor_ui["Tutor UI<br/>Shared components"]
  node_booking_ui["Booking UI<br/>Shared components"]
  node_profile_ui["Profile UI<br/>Shared components"]
  node_auth_ui["Auth UI<br/>Shared components"]
  node_admin_ui["Admin UI<br/>Shared components"]
  node_theme_provider(("Theme context<br/>React context<br/>[ThemeContext.tsx]"))
  node_ui_primitives["UI primitives<br/>shadcn/ui"]
  node_roles["Roles<br/>Constants<br/>[roles.ts]"]
end

subgraph group_external["External services"]
  node_auth_client["Auth client<br/>better-auth<br/>[auth-client.ts]"]
  node_backend_api[("Backend API<br/>External API")]
  node_stripe{{"Stripe<br/>Payments"}}
  node_cloudinary{{"Cloudinary<br/>Image CDN"}}
  node_session_cookie(("HTTP-only cookie<br/>Session boundary"))
end

node_root_shell -->|"wraps"| node_theme_provider
node_root_shell -->|"mounts"| node_layout_ui
node_root_shell -->|"hosts"| node_client_shell
node_root_shell -->|"hosts"| node_admin_shell
node_client_shell -->|"frames"| node_public_pages
node_client_shell -->|"frames"| node_auth_flows
node_client_shell -->|"frames"| node_dashboard_area
node_client_shell -->|"frames"| node_bookings_area
node_client_shell -->|"frames"| node_profile_area
node_client_shell -->|"frames"| node_tutors_area
node_client_shell -->|"frames"| node_slots_area
node_client_shell -->|"frames"| node_reviews_page
node_client_shell -->|"frames"| node_payment_pages
node_admin_shell -->|"frames"| node_admin_pages
node_public_pages -->|"uses"| node_home_ui
node_dashboard_area -->|"branches on"| node_roles
node_dashboard_area -->|"loads"| node_backend_api
node_bookings_area -->|"uses"| node_booking_ui
node_bookings_area -->|"loads"| node_backend_api
node_profile_area -->|"uses"| node_profile_ui
node_profile_area -->|"uploads"| node_cloudinary
node_tutors_area -->|"uses"| node_tutor_ui
node_tutors_area -->|"loads"| node_backend_api
node_slots_area -->|"mutates"| node_backend_api
node_reviews_page -->|"loads"| node_backend_api
node_payment_pages -->|"returns from"| node_stripe
node_payment_pages -->|"confirms"| node_backend_api
node_auth_flows -->|"uses"| node_auth_ui
node_auth_flows -->|"calls"| node_auth_client
node_auth_client -->|"depends on"| node_session_cookie
node_auth_client -->|"authenticates with"| node_backend_api
node_admin_pages -->|"uses"| node_admin_ui
node_admin_pages -->|"mutates"| node_backend_api
node_theme_provider -->|"styles"| node_ui_primitives
node_layout_ui -->|"composes"| node_ui_primitives
node_home_ui -->|"composes"| node_ui_primitives
node_tutor_ui -->|"composes"| node_ui_primitives
node_booking_ui -->|"composes"| node_ui_primitives
node_profile_ui -->|"composes"| node_ui_primitives
node_auth_ui -->|"composes"| node_ui_primitives
node_admin_ui -->|"composes"| node_ui_primitives

click node_root_shell "https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/layout.tsx"
click node_client_shell "https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/(client)/layout.tsx"
click node_admin_shell "https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/admin/layout.tsx"
click node_public_pages "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/(public)"
click node_auth_flows "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/(auth)"
click node_dashboard_area "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/dashboard"
click node_bookings_area "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/bookings"
click node_profile_area "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/profile"
click node_tutors_area "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/tutors"
click node_slots_area "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/slots"
click node_reviews_page "https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/(client)/reviews/page.tsx"
click node_payment_pages "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/payment-success"
click node_admin_pages "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/admin"
click node_layout_ui "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/layout"
click node_home_ui "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/home"
click node_tutor_ui "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/tutors"
click node_booking_ui "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/bookings"
click node_profile_ui "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/profile"
click node_auth_ui "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/auth"
click node_admin_ui "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/admin"
click node_theme_provider "https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/context/ThemeContext.tsx"
click node_ui_primitives "https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/ui"
click node_auth_client "https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/lib/auth-client.ts"
click node_roles "https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/constants/roles.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_root_shell,node_client_shell,node_public_pages,node_auth_flows,node_dashboard_area,node_bookings_area,node_profile_area,node_tutors_area,node_slots_area,node_reviews_page,node_payment_pages toneBlue
class node_admin_shell,node_admin_pages toneAmber
class node_layout_ui,node_home_ui,node_tutor_ui,node_booking_ui,node_profile_ui,node_auth_ui,node_admin_ui,node_theme_provider,node_ui_primitives,node_roles toneMint
class node_auth_client,node_backend_api,node_stripe,node_cloudinary,node_session_cookie toneRose
```

## Components

### Client app

User-facing Next.js routes and role-based marketplace flows

- [Root shell](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/layout.tsx): Next.js layout · Fonts, globals, theme provider, and toasts · `src/app/layout.tsx`
- [Client shell](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/(client)/layout.tsx): App layout · Shared navbar/footer chrome for marketplace routes · `src/app/(client)/layout.tsx`
- [Public pages](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/(public)): Route group · Marketing and informational pages · `src/app/(client)/(public)`
- [Auth flows](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/(auth)): Route group · Login, register, forgot, and reset password screens · `src/app/(client)/(auth)`
- [Dashboard](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/dashboard): Role routes · Student and tutor dashboards via parallel routes · `src/app/(client)/dashboard`
- [Bookings](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/bookings): Role routes · Student and tutor booking views via parallel routes · `src/app/(client)/bookings`
- [Profile](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/profile): Role routes · Student and tutor profile views and edits · `src/app/(client)/profile`
- [Tutors](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/tutors): Discovery routes · Tutor browsing and detail pages · `src/app/(client)/tutors`
- [Slots](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/slots): Availability routes · Tutor availability creation and listing · `src/app/(client)/slots`
- [Reviews](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/(client)/reviews/page.tsx): Route · Review summaries and user feedback views · `src/app/(client)/reviews/page.tsx`
- [Payment return](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/(client)/payment-success): Route pair · Stripe checkout success and cancel return pages · `src/app/(client)/payment-success`

### Admin area

Operational console for platform staff

- [Admin shell](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/app/admin/layout.tsx): App layout · Isolated admin UI boundary · `src/app/admin/layout.tsx`
- [Admin pages](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/app/admin): Management routes · Users, bookings, verifications, categories, featured tutors, and availabilities · `src/app/admin`

### Shared UI

Reusable components and design-system primitives

- [Layout UI](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/layout): Shared components · Navbar, footer, logo, dropdowns, and mobile drawer · `src/components/layout`
- [Home UI](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/home): Shared components · Landing page hero, featured tutors, categories, and CTA · `src/components/home`
- [Tutor UI](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/tutors): Shared components · Tutor browsing, filters, cards, and slot tables · `src/components/tutors`
- [Booking UI](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/bookings): Shared components · Student and tutor booking lists, cards, and payment choice · `src/components/bookings`
- [Profile UI](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/profile): Shared components · Role-specific profile display and edit forms · `src/components/profile`
- [Auth UI](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/auth): Shared components · Login, register, forgot password, and reset forms · `src/components/auth`
- [Admin UI](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/admin): Shared components · Admin layout client and table/filter controls · `src/components/admin`
- [Theme context](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/context/ThemeContext.tsx): React context · Dark/light theme behavior across the app · `src/context/ThemeContext.tsx`
- [UI primitives](https://github.com/sani-mohibur/tutor-marketplace-frontend/tree/main/src/components/ui): shadcn/ui · Base buttons, dialogs, inputs, selects, tabs, and sonner · `src/components/ui`
- [Roles](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/constants/roles.ts): Constants · Student, tutor, and admin role model · `src/constants/roles.ts`

### External services

Backend and third-party integrations

- [Auth client](https://github.com/sani-mohibur/tutor-marketplace-frontend/blob/main/src/lib/auth-client.ts): better-auth · Frontend auth client configuration · `src/lib/auth-client.ts`
- **Backend API**: External API · Owns sessions, marketplace data, bookings, payments, reviews, and admin mutations
- **Stripe**: Payments · Checkout and payment redirect flow
- **Cloudinary**: Image CDN · Remote profile image storage and delivery
- **HTTP-only cookie**: Session boundary · Backend-managed session state surfaced to the frontend

## Connections

- Root shell → Theme context: wraps · Provides app-wide theme state
- Root shell → Layout UI: mounts · Adds global shell pieces and toasts
- Root shell → Client shell: hosts · Renders the client app subtree
- Root shell → Admin shell: hosts · Renders the admin subtree
- Client shell → Public pages: frames · Shares navbar and footer across public pages
- Client shell → Auth flows: frames · Provides shared client chrome where applicable
- Client shell → Dashboard: frames · Shared client layout for role dashboards
- Client shell → Bookings: frames · Shared client layout for booking flows
- Client shell → Profile: frames · Shared client layout for profile flows
- Client shell → Tutors: frames · Shared client layout for marketplace discovery
- Client shell → Slots: frames · Shared client layout for availability flows
- Client shell → Reviews: frames · Shared client layout for review pages
- Client shell → Payment return: frames · Shared client layout for payment return pages
- Admin shell → Admin pages: frames · Admin-specific layout boundary
- Public pages → Home UI: uses · Landing and marketing content
- Dashboard → Roles: branches on · Chooses student or tutor experience
- Dashboard → Backend API: loads · Fetches dashboard state from the backend
- Bookings → Booking UI: uses · Renders booking cards, tabs, and payment choice
- Bookings → Backend API: loads · Reads booking lists and status data
- Profile → Profile UI: uses · Displays and edits role-specific profiles
- Profile → Cloudinary: uploads · Sends profile images to remote storage
- Tutors → Tutor UI: uses · Supports browsing, filters, and tutor detail views
- Tutors → Backend API: loads · Fetches tutors, categories, and availability
- Slots → Backend API: mutates · Creates and lists tutor availability slots
- Reviews → Backend API: loads · Reads review data and analytics
- Payment return → Stripe: returns from · Handles Stripe checkout success and cancel redirects
- Payment return → Backend API: confirms · Fetches receipt and payment details
- Auth flows → Auth UI: uses · Shared authentication forms
- Auth flows → Auth client: calls · Client-side auth flow wiring
- Auth client → HTTP-only cookie: depends on · Session state is maintained by HTTP-only cookies
- Auth client → Backend API: authenticates with · Delegates login and session operations to backend auth
- Admin pages → Admin UI: uses · Admin filters, rows, and layout helpers
- Admin pages → Backend API: mutates · Performs management actions against backend data
- Theme context → UI primitives: styles · Themes shared controls across the app
- Layout UI → UI primitives: composes · Shared navigation and shell elements rely on base primitives
- Home UI → UI primitives: composes · Landing components use shared controls
- Tutor UI → UI primitives: composes · Tutor discovery controls use shared primitives
- Booking UI → UI primitives: composes · Booking views use shared controls and dialogs
- Profile UI → UI primitives: composes · Profile forms and views use shared controls
- Auth UI → UI primitives: composes · Auth forms use shared controls
- Admin UI → UI primitives: composes · Admin tables and filters use shared controls
