How sani-mohibur/tutor-marketplace-frontend works
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: (client)/layout.tsx Client shell · ui UI primitives · app/layout.tsx Root shell · (auth) Auth flows
Components 28
Client app
User-facing Next.js routes and role-based marketplace flows
- Root shell · Fonts, globals, theme provider, and toasts
src/app/layout.tsx - Client shell · Shared navbar/footer chrome for marketplace routes
src/app/(client)/layout.tsx - Public pages · Marketing and informational pages
src/app/(client)/(public) - Auth flows · Login, register, forgot, and reset password screens
src/app/(client)/(auth) - Dashboard · Student and tutor dashboards via parallel routes
src/app/(client)/dashboard - Bookings · Student and tutor booking views via parallel routes
src/app/(client)/bookings - Profile · Student and tutor profile views and edits
src/app/(client)/profile - Tutors · Tutor browsing and detail pages
src/app/(client)/tutors - Slots · Tutor availability creation and listing
src/app/(client)/slots - Reviews · Review summaries and user feedback views
src/app/(client)/reviews/page.tsx - Payment return · Stripe checkout success and cancel return pages
src/app/(client)/payment-success
Admin area
Operational console for platform staff
- Admin shell · Isolated admin UI boundary
src/app/admin/layout.tsx - Admin pages · Users, bookings, verifications, categories, featured tutors, and availabilities
src/app/admin
Shared UI
Reusable components and design-system primitives
- Layout UI · Navbar, footer, logo, dropdowns, and mobile drawer
src/components/layout - Home UI · Landing page hero, featured tutors, categories, and CTA
src/components/home - Tutor UI · Tutor browsing, filters, cards, and slot tables
src/components/tutors - Booking UI · Student and tutor booking lists, cards, and payment choice
src/components/bookings - Profile UI · Role-specific profile display and edit forms
src/components/profile - Auth UI · Login, register, forgot password, and reset forms
src/components/auth - Admin UI · Admin layout client and table/filter controls
src/components/admin - Theme context · Dark/light theme behavior across the app
src/context/ThemeContext.tsx - UI primitives · Base buttons, dialogs, inputs, selects, tabs, and sonner
src/components/ui - Roles · Student, tutor, and admin role model
src/constants/roles.ts
External services
Backend and third-party integrations
- Auth client · Frontend auth client configuration
src/lib/auth-client.ts - Backend API · Owns sessions, marketplace data, bookings, payments, reviews, and admin mutations
- Stripe · Checkout and payment redirect flow
- Cloudinary · Remote profile image storage and delivery
- HTTP-only cookie · Backend-managed session state surfaced to the frontend
Connections 41
- 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