# samira-shajahan-borsha/events-activities-client architecture

> Architecture diagram of the GitHub repository samira-shajahan-borsha/events-activities-client, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/samira-shajahan-borsha/events-activities-client
- Repository: https://github.com/samira-shajahan-borsha/events-activities-client

## Overview

1. **Overall shape**
   - This is a **Next.js App Router frontend** for an events platform.
   - The repository is organized around **route groups and role-based layouts**, not around a single SPA shell.
   - The main architectural boundary is between **public discovery pages** and **protected dashboard pages**.

2. **Routing and layout boundaries**
   - `src/app/(commonLayout)` contains the **public site**: home, about, events listing, event details, contact, login/register, payment callbacks, and public profiles.
   - `src/app/(dashboardLayout)` contains the **authenticated area**, split further into:
     - `commonProtectedLayout` for shared protected pages,
     - `userDashboardLayout` for regular users,
     - `admin` for admin workflows,
     - `host` for host workflows.
   - This layout split is the clearest architectural boundary in the repo.

3. **Public experience subsystem**
   - Public pages are built from feature modules under `src/components/modules/Home`, `Events`, `EventDetails`, `Contact`, and `Profile`.
   - These pages focus on **event discovery, browsing, and conversion**: search/filtering, event cards, event detail actions, host application, and contact submission.
   - The public layout likely provides the shared navbar/footer and theme controls.

4. **Role-based dashboard subsystem**
   - The dashboard area supports **three personas**: client/user, host, and admin.
   - Shared dashboard chrome lives in `src/components/modules/dashboard` with navbar/sidebar/user menu components.
   - Each role gets its own pages and feature components:
     - user: booked events, profile, password changes,
     - host: create/edit/manage events,
     - admin: user/host/event management.
   - This separation is important for diagramming because role access is not just UI; it is a route-level boundary.

5. **Data access layer**
   - The frontend does not talk directly to backend endpoints inline in pages; it uses a **service layer** under `src/services`.
   - Services are grouped by domain:
     - `auth` for login/register/logout/profile lookup,
     - `event` for event CRUD and search,
     - `ticket` for booking/leave flows,
     - `user` for profile updates and interests,
     - `admin` for moderation actions.
   - This layer is the primary integration point to the external backend API referenced in the README.

6. **Auth and session flow**
   - Authentication is JWT-based with **HTTP-only cookies handled by the backend**.
   - Frontend helpers in `src/lib/auth-utils.ts` and `src/services/auth/tokenHandlers.ts` support token/session checks and auth-aware navigation.
   - Route protection is enforced through the dashboard layout and `src/proxy.ts`, which suggests request-time guarding/redirect behavior for protected routes.
   - Login/logout and registration are first-class flows, with role-aware post-login routing.

7. **Booking and payment flow**
   - Booking is a multi-step cross-system flow: event selection → booking reservation → payment for paid events → confirmation.
   - `src/services/ticket/ticket.ts` handles book/leave/my-bookings actions.
   - Payment has dedicated callback pages under `src/app/(commonLayout)/payment/{success,fail,cancel}` for browser redirects from the payment gateway.
   - The platform integrates with **SSLCommerz sandbox** for payment processing, so the frontend must handle both direct booking and payment-return states.

8. **Event management workflow**
   - Events are created and managed by hosts and admins through `src/services/event/eventManagement.ts` and the event-management components under `src/components/modules/EventsManagement`.
   - Host and admin dashboards share similar CRUD and moderation patterns, but the host side is scoped to their own events while admin has platform-wide oversight.
   - Dynamic event detail routes (`events/[slug]`, `admin/dashboard/edit-event/[slug]`, `host/dashboard/edit-event/[slug]`) show that event identity is slug-based and reused across workflows.

9. **Forms, validation, and UX feedback**
   - Form-heavy areas use **React Hook Form + Zod** via schemas in `src/zod` and helper utilities in `src/lib/zodValidator.ts`.
   - Reusable field/error components and input helpers are centralized in `src/components/shared` and `src/lib/getInputFieldError.ts`.
   - Toasts, dialogs, skeletons, and loaders are shared UI patterns for async states and user feedback rather than page-specific logic.

10. **Shared UI and design system**
   - The repository uses a **shadcn/ui + Radix UI** component layer under `src/components/ui`.
   - Higher-level shared components provide app-specific composition: navbar, footer, filters, pagination, tables, refresh controls, theme toggling, and image upload.
   - This is a strong separation between **primitive UI components** and **domain components**.

11. **Search, filtering, and listing architecture**
   - List-heavy screens such as events, users, hosts, and bookings share a common pattern: search, select filters, clear filters, pagination, and table/grid rendering.
   - `useDebounce` supports event search without noisy API calls.
   - Reusable table and filter components indicate the app is optimized for **data browsing and moderation**, not just static content.

12. **Media and profile handling**
   - Image upload is a dedicated capability, surfaced through `SingleImageUploader`, `use-file-upload`, and user/profile forms.
   - The README and service structure indicate **Cloudinary** is the external media boundary for profile avatars and event images.
   - This makes media a separate integration concern from the core event data API.

13. **Types and domain modeling**
   - `src/types` contains the core domain contracts for users, events, tickets, and dashboards.
   - These types are used to align UI components, service responses, and validation schemas.
   - For an architecture diagram, these types are the shared contract layer between features and API calls.

14. **Error handling and application shell**
   - The app uses Next.js-level global boundaries: `src/app/error.tsx`, `not-found.tsx`, and route-level `loading.tsx` files.
   - This means loading and failure states are handled at the routing layer, not only inside components.
   - `src/app/layout.tsx` and `src/app/globals.css` provide the root shell, global styling, and theme context.

15. **External dependencies that shape the architecture**
   - The architecture is materially shaped by three external systems:
     - the **separate backend API** for auth/data/business rules,
     - **Cloudinary** for images,
     - **SSLCommerz** for payments.
   - Vercel deployment and Next.js server/client rendering affect routing and loading behavior, but the real system boundary is frontend-to-backend plus these two third-party services.

Main entry points: [`src/app/(commonLayout)`](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(commonLayout)) (Public Pages), [`src/app/(dashboardLayout)/admin`](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/admin) (Admin Dashboard), [`src/app/(dashboardLayout)/layout.tsx`](https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/(dashboardLayout)/layout.tsx) (Dashboard Layout), [`src/services/event`](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/event) (Event Service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Router"]
  node_app_root_layout["Root Layout<br/>next layout<br/>[layout.tsx]"]
  node_app_public_layout["Public Layout<br/>route layout<br/>[layout.tsx]"]
  node_app_dashboard_layout["Dashboard Layout<br/>route layout<br/>[layout.tsx]"]
end

subgraph group_public["Public Site"]
  node_public_pages["Public Pages<br/>routes"]
  node_public_event_detail["Event Detail<br/>route page<br/>[page.tsx]"]
  node_public_auth["Auth Pages<br/>route pages"]
  node_public_payment["Payment Return<br/>route pages"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_common["Shared Protected<br/>protected routes"]
  node_dashboard_user["User Dashboard<br/>user routes"]
  node_dashboard_host["Host Dashboard<br/>host routes"]
  node_dashboard_admin["Admin Dashboard<br/>admin routes"]
end

subgraph group_components["UI Modules"]
  node_public_ui["Public Modules<br/>feature UI"]
  node_dashboard_ui["Dashboard UI<br/>chrome UI"]
  node_events_mgmt_ui["Event Management UI<br/>feature UI"]
  node_admin_ui["Admin Tables<br/>moderation UI"]
  node_shared_ui["Shared UI<br/>shared components"]
end

subgraph group_services["Services"]
  node_api_auth["Auth Service<br/>service domain"]
  node_api_events["Event Service<br/>service domain"]
  node_api_tickets["Ticket Service<br/>service domain"]
  node_api_profile["Profile Service<br/>service domain"]
  node_api_admin["Admin Service<br/>service domain"]
end

subgraph group_core["Core"]
  node_core_contracts["Contracts<br/>types"]
  node_core_validation["Validation<br/>zod schemas"]
  node_core_runtime["Runtime Core<br/>helpers"]
end

node_external_backend[("Backend API<br/>external system")]
node_external_cloudinary[("Cloudinary<br/>external system")]
node_external_payment[("SSLCommerz<br/>external system")]

node_app_root_layout -->|"wraps"| node_app_public_layout
node_app_root_layout -->|"wraps"| node_app_dashboard_layout
node_app_public_layout -->|"renders"| node_public_pages
node_app_dashboard_layout -->|"renders"| node_dashboard_common
node_app_dashboard_layout -->|"renders"| node_dashboard_user
node_app_dashboard_layout -->|"renders"| node_dashboard_host
node_app_dashboard_layout -->|"renders"| node_dashboard_admin
node_public_pages -->|"uses"| node_public_ui
node_public_event_detail -->|"uses"| node_public_ui
node_dashboard_user -->|"uses"| node_dashboard_ui
node_dashboard_host -->|"uses"| node_dashboard_ui
node_dashboard_admin -->|"uses"| node_dashboard_ui
node_dashboard_host -->|"uses"| node_events_mgmt_ui
node_dashboard_admin -->|"uses"| node_events_mgmt_ui
node_dashboard_admin -->|"uses"| node_admin_ui
node_public_pages -->|"uses"| node_shared_ui
node_dashboard_common -->|"uses"| node_shared_ui
node_public_pages -->|"calls"| node_api_auth
node_dashboard_common -->|"calls"| node_api_auth
node_public_pages -->|"calls"| node_api_events
node_public_event_detail -->|"calls"| node_api_events
node_dashboard_host -->|"calls"| node_api_events
node_dashboard_admin -->|"calls"| node_api_events
node_dashboard_user -->|"calls"| node_api_tickets
node_public_event_detail -->|"calls"| node_api_tickets
node_dashboard_common -->|"calls"| node_api_profile
node_dashboard_admin -->|"calls"| node_api_admin
node_public_pages -->|"redirects"| node_external_payment
node_public_ui -->|"uploads"| node_external_cloudinary
node_api_auth -->|"integrates"| node_external_backend
node_api_events -->|"integrates"| node_external_backend
node_api_tickets -->|"integrates"| node_external_backend
node_api_profile -->|"integrates"| node_external_backend
node_api_admin -->|"integrates"| node_external_backend
node_core_runtime -->|"guards"| node_app_dashboard_layout
node_core_runtime -->|"supports"| node_api_auth
node_core_validation -->|"validates"| node_public_ui
node_core_contracts -->|"shapes"| node_api_events
node_core_contracts -->|"shapes"| node_api_tickets
node_core_contracts -->|"shapes"| node_api_auth

click node_app_root_layout "https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/layout.tsx"
click node_app_public_layout "https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/(commonLayout)/layout.tsx"
click node_app_dashboard_layout "https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/(dashboardLayout)/layout.tsx"
click node_public_pages "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(commonLayout)"
click node_public_event_detail "https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/(commonLayout)/events/[slug]/page.tsx"
click node_public_auth "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(commonLayout)/(auth)"
click node_public_payment "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(commonLayout)/payment"
click node_dashboard_common "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/(commonProtectedLayout)"
click node_dashboard_user "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/(userDashboardLayout)"
click node_dashboard_host "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/host"
click node_dashboard_admin "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/admin"
click node_public_ui "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/modules"
click node_dashboard_ui "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/modules/dashboard"
click node_events_mgmt_ui "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/modules/EventsManagement"
click node_admin_ui "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/modules/Admin"
click node_shared_ui "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/shared"
click node_api_auth "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/auth"
click node_api_events "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/event"
click node_api_tickets "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/ticket"
click node_api_profile "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/user"
click node_api_admin "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/admin"
click node_core_contracts "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/types"
click node_core_validation "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/zod"
click node_core_runtime "https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/lib"

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_layout,node_app_public_layout,node_app_dashboard_layout toneBlue
class node_public_pages,node_public_event_detail,node_public_auth,node_public_payment toneAmber
class node_dashboard_common,node_dashboard_user,node_dashboard_host,node_dashboard_admin toneMint
class node_public_ui,node_dashboard_ui,node_events_mgmt_ui,node_admin_ui,node_shared_ui toneRose
class node_api_auth,node_api_events,node_api_tickets,node_api_profile,node_api_admin toneIndigo
class node_core_contracts,node_core_validation,node_core_runtime toneTeal
class node_external_backend,node_external_cloudinary,node_external_payment toneNeutral
```

## Components

### App Router

Next.js route groups, layouts, and global shell.

- [Root Layout](https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/layout.tsx): next layout · Global app shell, theme, and metadata. · `src/app/layout.tsx`
- [Public Layout](https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/(commonLayout)/layout.tsx): route layout · Shared shell for public pages. · `src/app/(commonLayout)/layout.tsx`
- [Dashboard Layout](https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/(dashboardLayout)/layout.tsx): route layout · Shared shell for protected areas. · `src/app/(dashboardLayout)/layout.tsx`

### Public Site

Discovery, marketing, auth, and payment-return pages.

- [Public Pages](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(commonLayout)): routes · Home, about, events, contact, auth, profiles, and payment callbacks. · `src/app/(commonLayout)`
- [Event Detail](https://github.com/samira-shajahan-borsha/events-activities-client/blob/development/src/app/(commonLayout)/events/[slug]/page.tsx): route page · Slug-based public event detail view. · `src/app/(commonLayout)/events/[slug]/page.tsx`
- [Auth Pages](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(commonLayout)/(auth)): route pages · Login and registration entry points. · `src/app/(commonLayout)/(auth)`
- [Payment Return](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(commonLayout)/payment): route pages · Success, fail, and cancel redirects from payment flow. · `src/app/(commonLayout)/payment`

### Dashboard

Protected role-based areas for users, hosts, and admins.

- [Shared Protected](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/(commonProtectedLayout)): protected routes · Common protected pages such as profile and password management. · `src/app/(dashboardLayout)/(commonProtectedLayout)`
- [User Dashboard](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/(userDashboardLayout)): user routes · Regular user pages for bookings and personal dashboard. · `src/app/(dashboardLayout)/(userDashboardLayout)`
- [Host Dashboard](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/host): host routes · Host event creation and management pages. · `src/app/(dashboardLayout)/host`
- [Admin Dashboard](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/app/(dashboardLayout)/admin): admin routes · Platform moderation and management pages. · `src/app/(dashboardLayout)/admin`

### UI Modules

Feature components and shared app chrome.

- [Public Modules](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/modules): feature UI · Home, events, details, contact, and profile components. · `src/components/modules`
- [Dashboard UI](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/modules/dashboard): chrome UI · Dashboard navbar, sidebar, and user menu. · `src/components/modules/dashboard`
- [Event Management UI](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/modules/EventsManagement): feature UI · Create/edit forms and tables for event administration. · `src/components/modules/EventsManagement`
- [Admin Tables](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/modules/Admin): moderation UI · Host and user management tables, dialogs, and columns. · `src/components/modules/Admin`
- [Shared UI](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/components/shared): shared components · Navbar, footer, filters, tables, loaders, upload, and toasts. · `src/components/shared`

### Services

Client-side API integration layer by domain.

- [Auth Service](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/auth): service domain · Login, register, logout, profile lookup, and token handling. · `src/services/auth`
- [Event Service](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/event): service domain · Event CRUD, search, and management operations. · `src/services/event`
- [Ticket Service](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/ticket): service domain · Booking, leave, and my-bookings flows. · `src/services/ticket`
- [Profile Service](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/user): service domain · User profile updates and interests. · `src/services/user`
- [Admin Service](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/services/admin): service domain · Administrative moderation actions. · `src/services/admin`

### Core

Shared contracts, validation, hooks, and route guards.

- [Contracts](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/types): types · Shared domain models for users, events, tickets, and dashboards. · `src/types`
- [Validation](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/zod): zod schemas · Form schemas and input validation helpers. · `src/zod`
- [Runtime Core](https://github.com/samira-shajahan-borsha/events-activities-client/tree/development/src/lib): helpers · Auth utilities, route guard proxy, server fetch, and debouncing. · `src/lib`

### Other components

- **Backend API**: external system · Primary data and business-logic backend.
- **Cloudinary**: external system · Image storage and upload boundary.
- **SSLCommerz**: external system · Payment gateway and redirect callbacks.

## Connections

- Root Layout → Public Layout: wraps · Root shell contains the public route group.
- Root Layout → Dashboard Layout: wraps · Root shell contains the protected route group.
- Public Layout → Public Pages: renders · Public layout hosts discovery and conversion pages.
- Dashboard Layout → Shared Protected: renders · Protected layout hosts shared account pages.
- Dashboard Layout → User Dashboard: renders · Protected layout hosts user dashboard routes.
- Dashboard Layout → Host Dashboard: renders · Protected layout hosts host routes.
- Dashboard Layout → Admin Dashboard: renders · Protected layout hosts admin routes.
- Public Pages → Public Modules: uses · Public pages are composed from feature modules.
- Event Detail → Public Modules: uses · Event detail view uses dedicated detail components.
- User Dashboard → Dashboard UI: uses · User dashboard uses shared chrome.
- Host Dashboard → Dashboard UI: uses · Host dashboard uses shared chrome.
- Admin Dashboard → Dashboard UI: uses · Admin dashboard uses shared chrome.
- Host Dashboard → Event Management UI: uses · Host workflows are built on event management components.
- Admin Dashboard → Event Management UI: uses · Admin event workflows reuse event management components.
- Admin Dashboard → Admin Tables: uses · Admin moderation pages use host and user management components.
- Public Pages → Shared UI: uses · Public pages rely on shared navigation, footer, filters, and UI primitives.
- Shared Protected → Shared UI: uses · Protected pages rely on shared table, loader, and menu components.
- Public Pages → Auth Service: calls · Auth pages trigger login and registration flows.
- Shared Protected → Auth Service: calls · Protected account pages load and update profile data.
- Public Pages → Event Service: calls · Discovery pages fetch event listings and details.
- Event Detail → Event Service: calls · Slug detail page loads event data.
- Host Dashboard → Event Service: calls · Host event CRUD uses the event service.
- Admin Dashboard → Event Service: calls · Admin event moderation uses the event service.
- User Dashboard → Ticket Service: calls · User dashboard manages bookings.
- Event Detail → Ticket Service: calls · Event detail drives booking and leave actions.
- Shared Protected → Profile Service: calls · Profile pages update user data and interests.
- Admin Dashboard → Admin Service: calls · Administrative moderation uses admin service.
- Public Pages → SSLCommerz: redirects · Payment callback pages receive gateway returns.
- Public Modules → Cloudinary: uploads · Profile and event imagery are handled through media uploads.
- Auth Service → Backend API: integrates · Auth and session operations are backed by the API.
- Event Service → Backend API: integrates · Event data and search are backed by the API.
- Ticket Service → Backend API: integrates · Booking operations are backed by the API.
- Profile Service → Backend API: integrates · Profile updates are backed by the API.
- Admin Service → Backend API: integrates · Admin actions are backed by the API.
- Runtime Core → Dashboard Layout: guards · Proxy and auth helpers support protected routing.
- Runtime Core → Auth Service: supports · Token handlers and auth utilities support session flow.
- Validation → Public Modules: validates · Form schemas support public and dashboard forms.
- Contracts → Event Service: shapes · Domain types align service payloads.
- Contracts → Ticket Service: shapes · Domain types align booking payloads.
- Contracts → Auth Service: shapes · Domain types align auth/profile payloads.