# habib-utsho/b12_conceptual_session_next-js-basic-1 architecture

> Architecture diagram of the GitHub repository habib-utsho/b12_conceptual_session_next-js-basic-1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/habib-utsho/b12_conceptual_session_next-js-basic-1
- Repository: https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** application (`src/app`) with both **UI routes** and **server API routes** in the same repository.
   - The app is split into two major route groups: **public/common pages** and **dashboard pages**, each with its own layout boundary.

2. **Route and layout structure**
   - `src/app/(withCommonLayout)` contains the public-facing pages such as home, about, login/signup, services, reviews, and role-specific entry pages like `adminRoute` and `userRoute`.
   - `src/app/(withDashboardLayout)` contains authenticated dashboard pages, currently centered on `dashboard` and `dashboard/my-bookings`.
   - Each route group has its own `layout.jsx`, indicating a clear separation between the shared public shell and the dashboard shell.

3. **Public-facing product surface**
   - The main user journey appears to revolve around **services discovery, review management, and booking**.
   - `services/page.jsx` and `services/[slug]/page.jsx` represent a listing/detail flow for service browsing.
   - `reviews/page.jsx` and `reviews/create-review/page.jsx` cover review reading and creation.
   - `login`, `signup`, `aboutUs`, and the home page support standard acquisition/onboarding flows.

4. **Dashboard boundary**
   - The dashboard area is separate from the public app and likely expects an authenticated user.
   - `dashboard/my-bookings/page.jsx` suggests users can manage or view their bookings after sign-in.
   - `src/components/shared/DashboardSidebar.jsx` indicates a persistent dashboard navigation component distinct from the public navbar/footer shell.

5. **Client-side state and cross-cutting data**
   - `src/context/user.context.jsx` and `src/context/booking.context.jsx` provide application-wide state for user identity/session and booking-related data.
   - These contexts likely bridge the public UI and dashboard UI, especially for login state, booking actions, and access control decisions.

6. **Service layer as the app’s data access boundary**
   - `src/services/services.service.js`, `reviews.service.js`, and `users.service.js` form a dedicated client/server data access layer.
   - This layer is the main abstraction between React components and backend endpoints, helping keep route components thin and focused on rendering.
   - For an architecture diagram, this is the key “business/data access” tier between UI and API.

7. **API routes and backend responsibilities**
   - The app exposes route handlers under `src/app/api` for `auth`, `reviews`, and `users`.
   - `src/app/api/auth/[...nextauth]/route.js` indicates authentication is handled via **NextAuth** with a catch-all route.
   - `src/app/api/reviews/route.js` and `src/app/api/reviews/[id]/route.js` provide collection and item-level review operations.
   - `src/app/api/users/route.js` handles user-related backend operations.
   - `src/app/api/route.js` suggests a top-level API entry or health/aggregation route.

8. **Persistence and backend integration**
   - `src/lib/dbConnect.js` is the repository’s backend infrastructure entrypoint, implying a database-backed API layer.
   - The exact database isn’t visible from the tree, but `dbConnect` indicates a reusable connection helper used by API handlers.
   - `src/lib/providers/index.js` suggests centralized provider setup, likely for auth/session and other runtime dependencies.

9. **Authentication and route guarding**
   - Authentication is centered on NextAuth and likely coordinated with `src/proxy.js`, which suggests request interception or route protection at the edge/middleware layer.
   - The presence of separate `login`, `signup`, `adminRoute`, and `userRoute` pages implies role-based access or post-login routing.
   - The dashboard layout and proxy together form the main protection boundary for private routes.

10. **Reusable UI building blocks**
   - Shared shell components live in `src/components/shared`, including `Navbar`, `Footer`, `Container`, and `DashboardSidebar`.
   - These are the app’s structural presentation layer and are reused across route groups to keep layout consistent.
   - `services/_component` contains page-local components such as `ServiceCard`, `ServicesSearching`, and `BookingBtn`, showing feature-specific composition inside the services domain.

11. **Loading and not-found handling**
   - Route-level `loading.jsx` files exist for the app root, services, and reviews, showing intentional use of Next.js streaming/loading states.
   - `src/app/not-found.jsx` defines a centralized 404 experience for unresolved routes.
   - This indicates the app is designed with segmented route feedback rather than one global spinner.

12. **Static assets and styling**
   - Static assets are under `src/assets/img` and public assets under `public`.
   - Styling uses the Next.js/PostCSS pipeline (`globals.css`, `postcss.config.mjs`), with project-level lint/config support via `eslint.config.mjs` and `next.config.mjs`.
   - The README confirms a standard Next.js setup with font optimization via `next/font`.

13. **How data likely flows through the app**
   - User interaction starts in route components under `src/app`.
   - Components call into the `src/services/*` layer.
   - Services hit Next.js API route handlers under `src/app/api/*`.
   - API handlers use `dbConnect` and provider setup to talk to persistence/auth infrastructure.
   - Results flow back into contexts and UI components, with dashboard routes consuming authenticated state.

14. **Key architectural boundary to diagram**
   - The most important separation is: **presentation routes/components** → **service/data-access layer** → **API route handlers** → **database/auth infrastructure**.
   - The second major boundary is: **public/common layout** vs **authenticated dashboard layout**.
   - Those two boundaries are the primary organizing principles of the repository.

Main entry points: [`src/app/(withDashboardLayout)/layout.jsx`](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withDashboardLayout)/layout.jsx) (Dashboard Layout), [`src/app/(withCommonLayout)/layout.jsx`](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withCommonLayout)/layout.jsx) (Common Layout), [`src/app/(withCommonLayout)`](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/(withCommonLayout)) (Public Pages), [`src/proxy.js`](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/proxy.js) (Proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public["Public App"]
  node_node_root_layout["Root Layout<br/>app shell<br/>[layout.jsx]"]
  node_node_common_layout["Common Layout<br/>route layout<br/>[layout.jsx]"]
  node_node_public_pages["Public Pages<br/>routes"]
  node_node_services["Services<br/>service browsing"]
  node_node_reviews["Reviews<br/>review flow"]
end

subgraph group_group_dashboard["Dashboard"]
  node_node_dashboard_layout["Dashboard Layout<br/>route layout<br/>[layout.jsx]"]
  node_node_dashboard_home["Dashboard Home<br/>dashboard page<br/>[page.jsx]"]
  node_node_my_bookings["My Bookings<br/>dashboard page<br/>[page.jsx]"]
end

subgraph group_group_api["API Backend"]
  node_node_api_auth["Auth API<br/>nextauth route<br/>[route.js]"]
  node_node_api_reviews["Reviews API<br/>api routes"]
  node_node_api_users["Users API<br/>api route<br/>[route.js]"]
  node_node_api_root["API Root<br/>api entry<br/>[route.js]"]
  node_node_db[("DB Connect<br/>db helper<br/>[dbConnect.js]")]
  node_node_proxy["Proxy<br/>route guard<br/>[proxy.js]"]
end

subgraph group_group_shared["Shared Layer"]
  node_node_providers["Providers<br/>runtime setup<br/>[index.js]"]
  node_node_user_ctx["User Context<br/>app state<br/>[user.context.jsx]"]
  node_node_booking_ctx["Booking Context<br/>app state"]
  node_node_services_api["Services API<br/>data access"]
  node_node_reviews_api["Reviews Service<br/>data access<br/>[reviews.service.js]"]
  node_node_users_api["Users Service<br/>data access<br/>[users.service.js]"]
  node_node_shared_ui["Shared UI<br/>components"]
end

node_node_root_layout -->|"wraps"| node_node_common_layout
node_node_root_layout -->|"wraps"| node_node_dashboard_layout
node_node_common_layout -->|"renders"| node_node_public_pages
node_node_common_layout -->|"renders"| node_node_services
node_node_common_layout -->|"renders"| node_node_reviews
node_node_dashboard_layout -->|"renders"| node_node_dashboard_home
node_node_dashboard_layout -->|"renders"| node_node_my_bookings
node_node_shared_ui -->|"supports"| node_node_common_layout
node_node_shared_ui -->|"supports"| node_node_dashboard_layout
node_node_user_ctx -->|"powers"| node_node_public_pages
node_node_user_ctx -->|"powers"| node_node_dashboard_layout
node_node_booking_ctx -->|"powers"| node_node_services
node_node_booking_ctx -->|"powers"| node_node_my_bookings
node_node_services -->|"calls"| node_node_services_api
node_node_reviews -->|"calls"| node_node_reviews_api
node_node_public_pages -->|"calls"| node_node_users_api
node_node_services_api -->|"requests"| node_node_api_root
node_node_reviews_api -->|"requests"| node_node_api_reviews
node_node_users_api -->|"requests"| node_node_api_users
node_node_api_reviews -->|"uses"| node_node_db
node_node_api_users -->|"uses"| node_node_db
node_node_api_auth -->|"uses"| node_node_providers
node_node_proxy -.->|"guards"| node_node_api_auth
node_node_proxy -.->|"guards"| node_node_dashboard_layout
node_node_proxy -.->|"routes"| node_node_public_pages

click node_node_root_layout "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/layout.jsx"
click node_node_common_layout "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withCommonLayout)/layout.jsx"
click node_node_public_pages "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/(withCommonLayout)"
click node_node_services "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/(withCommonLayout)/services"
click node_node_reviews "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/(withCommonLayout)/reviews"
click node_node_dashboard_layout "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withDashboardLayout)/layout.jsx"
click node_node_dashboard_home "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withDashboardLayout)/dashboard/page.jsx"
click node_node_my_bookings "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withDashboardLayout)/dashboard/my-bookings/page.jsx"
click node_node_api_auth "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/api/auth/[...nextauth]/route.js"
click node_node_api_reviews "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/api/reviews"
click node_node_api_users "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/api/users/route.js"
click node_node_api_root "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/api/route.js"
click node_node_db "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/lib/dbConnect.js"
click node_node_providers "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/lib/providers/index.js"
click node_node_user_ctx "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/context/user.context.jsx"
click node_node_booking_ctx "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/context/booking.context.jsx"
click node_node_services_api "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/services/services.service.js"
click node_node_reviews_api "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/services/reviews.service.js"
click node_node_users_api "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/services/users.service.js"
click node_node_shared_ui "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/components/shared"
click node_node_proxy "https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/proxy.js"

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_node_root_layout,node_node_common_layout,node_node_public_pages,node_node_services,node_node_reviews toneBlue
class node_node_dashboard_layout,node_node_dashboard_home,node_node_my_bookings toneAmber
class node_node_api_auth,node_node_api_reviews,node_node_api_users,node_node_api_root,node_node_db,node_node_proxy toneMint
class node_node_providers,node_node_user_ctx,node_node_booking_ctx,node_node_services_api,node_node_reviews_api,node_node_users_api,node_node_shared_ui toneRose
```

## Components

### Public App

Common layout and public-facing routes

- [Root Layout](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/layout.jsx): app shell · Global app wrapper and shared HTML scaffold · `src/app/layout.jsx`
- [Common Layout](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withCommonLayout)/layout.jsx): route layout · Shared shell for public-facing pages · `src/app/(withCommonLayout)/layout.jsx`
- [Public Pages](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/(withCommonLayout)): routes · Home, about, login, signup, and role entry pages · `src/app/(withCommonLayout)`
- [Services](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/(withCommonLayout)/services): service browsing · Service list and detail flow with local booking actions · `src/app/(withCommonLayout)/services`
- [Reviews](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/(withCommonLayout)/reviews): review flow · Review listing and review creation pages · `src/app/(withCommonLayout)/reviews`

### Dashboard

Authenticated dashboard routes

- [Dashboard Layout](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withDashboardLayout)/layout.jsx): route layout · Authenticated shell for dashboard pages · `src/app/(withDashboardLayout)/layout.jsx`
- [Dashboard Home](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withDashboardLayout)/dashboard/page.jsx): dashboard page · Main dashboard entry page · `src/app/(withDashboardLayout)/dashboard/page.jsx`
- [My Bookings](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/(withDashboardLayout)/dashboard/my-bookings/page.jsx): dashboard page · Booking management area for signed-in users · `src/app/(withDashboardLayout)/dashboard/my-bookings/page.jsx`

### API Backend

Next.js route handlers and backend entrypoints

- [Auth API](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/api/auth/[...nextauth]/route.js): nextauth route · NextAuth authentication handler · `src/app/api/auth/[...nextauth]/route.js`
- [Reviews API](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/app/api/reviews): api routes · Collection and item review endpoints · `src/app/api/reviews`
- [Users API](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/api/users/route.js): api route · User-related backend endpoint · `src/app/api/users/route.js`
- [API Root](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/app/api/route.js): api entry · Top-level API route entrypoint · `src/app/api/route.js`
- [DB Connect](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/lib/dbConnect.js): db helper · Reusable database connection utility · `src/lib/dbConnect.js`
- [Proxy](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/proxy.js): route guard · Edge/interception layer for auth and protected routing · `src/proxy.js`

### Shared Layer

Reusable UI, state, and service abstractions

- [Providers](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/lib/providers/index.js): runtime setup · Central provider and session wiring · `src/lib/providers/index.js`
- [User Context](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/context/user.context.jsx): app state · Global user/session state · `src/context/user.context.jsx`
- [Booking Context](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/context/booking.context.jsx): app state · Global booking-related state · `src/context/booking.context.jsx`
- [Services API](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/services/services.service.js): data access · Client/server abstraction for services data · `src/services/services.service.js`
- [Reviews Service](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/services/reviews.service.js): data access · Client/server abstraction for review data · `src/services/reviews.service.js`
- [Users Service](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/blob/main/src/services/users.service.js): data access · Client/server abstraction for user data · `src/services/users.service.js`
- [Shared UI](https://github.com/habib-utsho/b12_conceptual_session_next-js-basic-1/tree/main/src/components/shared): components · Navbar, footer, container, and dashboard sidebar · `src/components/shared`

## Connections

- Root Layout → Common Layout: wraps · Global app shell contains the common route layout
- Root Layout → Dashboard Layout: wraps · Global app shell contains the dashboard layout
- Common Layout → Public Pages: renders · Public shell hosts common pages
- Common Layout → Services: renders · Public shell includes service browsing
- Common Layout → Reviews: renders · Public shell includes review flows
- Dashboard Layout → Dashboard Home: renders · Dashboard shell hosts main dashboard page
- Dashboard Layout → My Bookings: renders · Dashboard shell hosts booking management
- Shared UI → Common Layout: supports · Shared chrome is used by the public layout
- Shared UI → Dashboard Layout: supports · Shared chrome is used by the dashboard layout
- User Context → Public Pages: powers · User state informs onboarding and access decisions
- User Context → Dashboard Layout: powers · Authenticated state drives dashboard access
- Booking Context → Services: powers · Booking state supports service actions
- Booking Context → My Bookings: powers · Booking state feeds dashboard booking views
- Services → Services API: calls · Service pages use the services data layer
- Reviews → Reviews Service: calls · Review pages use the reviews data layer
- Public Pages → Users Service: calls · Signup/login and role pages depend on user operations
- Services API → API Root: requests · Services data access reaches backend endpoints
- Reviews Service → Reviews API: requests · Reviews data access reaches review endpoints
- Users Service → Users API: requests · Users data access reaches user endpoints
- Reviews API → DB Connect: uses · Review handlers persist through the DB helper
- Users API → DB Connect: uses · User handlers persist through the DB helper
- Auth API → Providers: uses · Auth route relies on centralized provider setup
- Proxy → Auth API: guards · Proxy helps protect and route authenticated flows
- Proxy → Dashboard Layout: guards · Dashboard routes are protected by request interception
- Proxy → Public Pages: routes · Proxy also coordinates role-based public entry pages