# zabedfolio/taskly-client architecture

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

- Interactive diagram: https://gitdiagram.com/zabedfolio/taskly-client
- Repository: https://github.com/zabedfolio/taskly-client

## Overview

1. **What this repo is**
   - This is the **frontend client** for Taskly, built with **Next.js App Router + React**.
   - The actual business backend is a **separate server/API** (shown in the README), so this repo is mostly the presentation layer, route structure, auth client, and API orchestration.

2. **Core application boundary**
   - The main boundary is between:
     - **browser-rendered Next.js pages/components**
     - **API calls to the external backend**
     - a small set of **Next.js API routes** that proxy or handle platform-specific integrations.
   - Most data is fetched through helpers in `src/lib/api/**`, not directly inside page components.

3. **Route structure and persona-based UX**
   - The app is organized around distinct route families:
     - public pages like `/`, `/browse`, `/freelancers`
     - auth pages under `/auth/login` and `/auth/signup`
     - role-specific dashboards under `/dashboard/client`, `/dashboard/freelancer`, and `/dashboard/admin`
     - support/error routes like `/payment-success`, `/success`, `/unauthorized`, and `not-found`
   - This route tree is the main architectural signal: each persona gets its own navigation, layout, and workflows.

4. **Dashboard layouts as the main UI boundary**
   - `src/app/dashboard/layout.jsx` wraps dashboard-wide behavior.
   - Each role has its own layout:
     - `client/layout.jsx`
     - `freelancer/layout.jsx`
     - `admin/layout.jsx`
   - These layouts likely control shared shell behavior such as sidebar navigation, role gating, and page chrome, while individual pages implement task/proposal/settings views.

5. **Public discovery layer**
   - The home and marketplace discovery surfaces are component-driven:
     - `src/components/home/*` powers the landing page with featured tasks, stats, top freelancers, testimonials, and hero sections.
     - `/freelancers` and `/browse` are the main discovery pages for talent and tasks.
   - Shared modal components in `src/components/shared` support deep inspection of freelancers, tasks, and ratings without leaving the listing page.

6. **Role workflows and data flow**
   - **Clients**: post tasks, review proposals, accept bids, and complete payment.
   - **Freelancers**: browse tasks, submit proposals, track active work, and view earnings.
   - **Admins**: verify freelancers, block/unblock users, and audit transactions.
   - These workflows are reflected in the API helper split under `src/lib/api/client`, `freelancer`, `home`, and `admin`, which keeps each persona’s data access isolated.

7. **Authentication and access control**
   - Auth is handled through **Better Auth** integration in `src/lib/auth.js` and `src/lib/auth-client.js`.
   - The auth route handler lives at `src/app/api/auth/[...all]/route.js`, so auth is implemented as a Next.js API endpoint rather than only client-side state.
   - `src/app/unauthorized` and `src/proxy.js` indicate route protection/redirect logic for blocked or unauthorized sessions, with access constrained by role and account status.

8. **Payment and checkout flow**
   - Payment is a distinct subsystem:
     - `/payment/checkout`
     - `/payment-success`
     - `/dashboard/client/payment-success`
     - API route `src/app/api/checkout_sessions/route.js`
   - The frontend delegates payment session creation to the backend/Stripe integration, then uses success routes to finalize the client-side UX after payment confirmation.

9. **File upload / image service boundary**
   - `src/app/api/imagebb/route.js` shows a dedicated integration for image uploads through **ImageBB**.
   - This keeps external upload credentials and request shaping out of the main UI components and gives the app a controlled upload boundary.

10. **State management**
    - The app uses React Contexts instead of a heavy global store:
      - `BookmarkContext`
      - `NotificationContext`
      - `ThemeContext`
    - That suggests the shared client state is limited to UI-centric concerns, while server state is fetched through the API helper layer.

11. **Shared UI primitives**
    - Common components in `src/components/common` and `src/components/shared` act as the reusable presentation layer:
      - navbar/footer/shell/notification bell
      - rating and verification badges
      - task/freelancer detail modals
    - These components are reused across public pages and dashboards, which reduces duplication while keeping the route pages thin.

12. **Technology and runtime shape**
    - This repo is a **Next.js frontend** with the App Router, using:
      - React for component composition
      - Next.js route handlers for API-adjacent endpoints
      - CSS pipeline files (`globals.css`, `postcss.config.mjs`) for styling
      - ESLint and JS config for code quality and aliasing
    - The backend storage/auth/payment concerns are externalized, so the client architecture is primarily a routed UI plus API orchestration layer.

13. **How to draw the architecture diagram**
    - A good diagram would show:
      - user personas entering through public pages
      - role-based dashboard branches for client/freelancer/admin
      - shared UI components feeding those pages
      - `lib/api` helpers connecting the UI to the external backend
      - Next API routes for auth, checkout, and ImageBB
      - context providers wrapping the React tree for bookmarks, notifications, and theme
      - external dependencies: Better Auth, Stripe, ImageBB, and the separate server API

Main entry points: [`src/lib/api/home/getAllTasks.js`](https://github.com/zabedfolio/taskly-client/blob/main/src/lib/api/home/getAllTasks.js) (API helpers), [`src/components/shared/TaskDetailModal.jsx`](https://github.com/zabedfolio/taskly-client/blob/main/src/components/shared/TaskDetailModal.jsx) (Detail modals), [`src/components/dashboard/DashboardSidebar.jsx`](https://github.com/zabedfolio/taskly-client/blob/main/src/components/dashboard/DashboardSidebar.jsx) (Sidebar), [`src/contexts/BookmarkContext.jsx`](https://github.com/zabedfolio/taskly-client/blob/main/src/contexts/BookmarkContext.jsx) (Contexts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_routes["App routes"]
  node_app_root["App shell<br/>next app<br/>[layout.js]"]
  node_home_page["Home<br/>route page<br/>[page.js]"]
  node_browse_page["Browse<br/>route page<br/>[page.jsx]"]
  node_freelancers_page["Freelancers<br/>route page<br/>[page.jsx]"]
  node_auth_pages["Auth pages<br/>route pages<br/>[page.jsx]"]
  node_dashboard_root["Dashboard shell<br/>layout<br/>[layout.jsx]"]
  node_client_dashboard["Client area<br/>layout+pages<br/>[layout.jsx]"]
  node_freelancer_dashboard["Freelancer area<br/>layout+pages<br/>[layout.jsx]"]
  node_admin_dashboard["Admin area<br/>layout+pages<br/>[layout.jsx]"]
  node_payment_routes["Payment routes<br/>route pages<br/>[page.jsx]"]
  node_special_pages["Status pages<br/>utility routes<br/>[page.jsx]"]
end

subgraph group_ui["UI layer"]
  node_navbar_shell["Navbar<br/>shared ui<br/>[Navbar.jsx]"]
  node_dashboard_sidebar["Sidebar<br/>dashboard ui"]
  node_home_components["Home modules<br/>page sections<br/>[HeroBanner.jsx]"]
  node_shared_modals["Detail modals<br/>shared ui"]
  node_badges["Badges<br/>shared ui<br/>[VerifiedBadge.jsx]"]
end

subgraph group_state["Client state"]
  node_contexts["Contexts<br/>react context"]
end

subgraph group_api["API layer"]
  node_auth_route["Auth handler<br/>route handler<br/>[route.js]"]
  node_checkout_route["Checkout API<br/>route handler<br/>[route.js]"]
  node_image_upload_route["Image upload<br/>route handler<br/>[route.js]"]
  node_api_helpers["API helpers<br/>client api<br/>[getAllTasks.js]"]
  node_auth_client["Auth client<br/>auth lib<br/>[auth-client.js]"]
  node_stripe_lib["Stripe lib<br/>payment lib<br/>[stripe.js]"]
end

subgraph group_external["External services"]
  node_backend_api[("Backend API<br/>external server")]
  node_better_auth[("Better Auth<br/>external auth")]
  node_stripe[("Stripe<br/>external payment")]
  node_imagebb[("ImageBB<br/>external upload")]
end

node_app_root -->|"wraps"| node_contexts
node_app_root -->|"renders"| node_navbar_shell
node_home_page -->|"composes"| node_home_components
node_browse_page -->|"uses"| node_shared_modals
node_freelancers_page -->|"uses"| node_shared_modals
node_auth_pages -->|"authenticates"| node_auth_client
node_dashboard_root -->|"provides"| node_dashboard_sidebar
node_client_dashboard -->|"uses"| node_dashboard_sidebar
node_freelancer_dashboard -->|"uses"| node_dashboard_sidebar
node_admin_dashboard -->|"uses"| node_dashboard_sidebar
node_client_dashboard -->|"fetches"| node_api_helpers
node_freelancer_dashboard -->|"fetches"| node_api_helpers
node_admin_dashboard -->|"fetches"| node_api_helpers
node_payment_routes -->|"starts"| node_checkout_route
node_payment_routes -->|"uses"| node_stripe_lib
node_special_pages -->|"gates"| node_auth_client
node_auth_route -->|"integrates"| node_better_auth
node_checkout_route -->|"integrates"| node_stripe
node_image_upload_route -->|"integrates"| node_imagebb
node_api_helpers -->|"calls"| node_backend_api
node_auth_client -->|"calls"| node_better_auth
node_stripe_lib -->|"calls"| node_stripe
node_contexts -.->|"supports"| node_home_page
node_contexts -.->|"supports"| node_dashboard_root
node_shared_modals -.->|"reads"| node_api_helpers
node_badges -.->|"decorates"| node_shared_modals

click node_app_root "https://github.com/zabedfolio/taskly-client/blob/main/src/app/layout.js"
click node_home_page "https://github.com/zabedfolio/taskly-client/blob/main/src/app/page.js"
click node_browse_page "https://github.com/zabedfolio/taskly-client/blob/main/src/app/browse/page.jsx"
click node_freelancers_page "https://github.com/zabedfolio/taskly-client/blob/main/src/app/freelancers/page.jsx"
click node_auth_pages "https://github.com/zabedfolio/taskly-client/blob/main/src/app/auth/login/page.jsx"
click node_dashboard_root "https://github.com/zabedfolio/taskly-client/blob/main/src/app/dashboard/layout.jsx"
click node_client_dashboard "https://github.com/zabedfolio/taskly-client/blob/main/src/app/dashboard/client/layout.jsx"
click node_freelancer_dashboard "https://github.com/zabedfolio/taskly-client/blob/main/src/app/dashboard/freelancer/layout.jsx"
click node_admin_dashboard "https://github.com/zabedfolio/taskly-client/blob/main/src/app/dashboard/admin/layout.jsx"
click node_payment_routes "https://github.com/zabedfolio/taskly-client/blob/main/src/app/payment/checkout/page.jsx"
click node_special_pages "https://github.com/zabedfolio/taskly-client/blob/main/src/app/unauthorized/page.jsx"
click node_navbar_shell "https://github.com/zabedfolio/taskly-client/blob/main/src/components/common/Navbar.jsx"
click node_dashboard_sidebar "https://github.com/zabedfolio/taskly-client/blob/main/src/components/dashboard/DashboardSidebar.jsx"
click node_home_components "https://github.com/zabedfolio/taskly-client/blob/main/src/components/home/HeroBanner.jsx"
click node_shared_modals "https://github.com/zabedfolio/taskly-client/blob/main/src/components/shared/TaskDetailModal.jsx"
click node_badges "https://github.com/zabedfolio/taskly-client/blob/main/src/components/shared/VerifiedBadge.jsx"
click node_contexts "https://github.com/zabedfolio/taskly-client/blob/main/src/contexts/BookmarkContext.jsx"
click node_auth_route "https://github.com/zabedfolio/taskly-client/blob/main/src/app/api/auth/[...all]/route.js"
click node_checkout_route "https://github.com/zabedfolio/taskly-client/blob/main/src/app/api/checkout_sessions/route.js"
click node_image_upload_route "https://github.com/zabedfolio/taskly-client/blob/main/src/app/api/imagebb/route.js"
click node_api_helpers "https://github.com/zabedfolio/taskly-client/blob/main/src/lib/api/home/getAllTasks.js"
click node_auth_client "https://github.com/zabedfolio/taskly-client/blob/main/src/lib/auth-client.js"
click node_stripe_lib "https://github.com/zabedfolio/taskly-client/blob/main/src/lib/stripe.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_app_root,node_home_page,node_browse_page,node_freelancers_page,node_auth_pages,node_dashboard_root,node_client_dashboard,node_freelancer_dashboard,node_admin_dashboard,node_payment_routes,node_special_pages toneBlue
class node_navbar_shell,node_dashboard_sidebar,node_home_components,node_shared_modals,node_badges toneAmber
class node_contexts toneMint
class node_auth_route,node_checkout_route,node_image_upload_route,node_api_helpers,node_auth_client,node_stripe_lib toneRose
class node_backend_api,node_better_auth,node_stripe,node_imagebb toneIndigo
```

## Components

### App routes

Next.js App Router pages, layouts, and route handlers.

- [App shell](https://github.com/zabedfolio/taskly-client/blob/main/src/app/layout.js): next app · Root layout and global app entry for providers and shell composition. · `src/app/layout.js`
- [Home](https://github.com/zabedfolio/taskly-client/blob/main/src/app/page.js): route page · Public landing page for discovery and onboarding. · `src/app/page.js`
- [Browse](https://github.com/zabedfolio/taskly-client/blob/main/src/app/browse/page.jsx): route page · Public task discovery page. · `src/app/browse/page.jsx`
- [Freelancers](https://github.com/zabedfolio/taskly-client/blob/main/src/app/freelancers/page.jsx): route page · Public freelancer discovery page. · `src/app/freelancers/page.jsx`
- [Auth pages](https://github.com/zabedfolio/taskly-client/blob/main/src/app/auth/login/page.jsx): route pages · Login and signup entry points. · `src/app/auth/login/page.jsx`
- [Dashboard shell](https://github.com/zabedfolio/taskly-client/blob/main/src/app/dashboard/layout.jsx): layout · Shared dashboard boundary for role-specific areas. · `src/app/dashboard/layout.jsx`
- [Client area](https://github.com/zabedfolio/taskly-client/blob/main/src/app/dashboard/client/layout.jsx): layout+pages · Client dashboard shell and task/proposal/payment workflows. · `src/app/dashboard/client/layout.jsx`
- [Freelancer area](https://github.com/zabedfolio/taskly-client/blob/main/src/app/dashboard/freelancer/layout.jsx): layout+pages · Freelancer dashboard shell and work tracking workflows. · `src/app/dashboard/freelancer/layout.jsx`
- [Admin area](https://github.com/zabedfolio/taskly-client/blob/main/src/app/dashboard/admin/layout.jsx): layout+pages · Admin dashboard shell and moderation/ops workflows. · `src/app/dashboard/admin/layout.jsx`
- [Payment routes](https://github.com/zabedfolio/taskly-client/blob/main/src/app/payment/checkout/page.jsx): route pages · Checkout and success pages for payment completion. · `src/app/payment/checkout/page.jsx`
- [Status pages](https://github.com/zabedfolio/taskly-client/blob/main/src/app/unauthorized/page.jsx): utility routes · Success, unauthorized, and not-found handling. · `src/app/unauthorized/page.jsx`

### UI layer

Reusable presentation components used across public pages and dashboards.

- [Navbar](https://github.com/zabedfolio/taskly-client/blob/main/src/components/common/Navbar.jsx): shared ui · Top-level navigation used on public surfaces. · `src/components/common/Navbar.jsx`
- [Sidebar](https://github.com/zabedfolio/taskly-client/blob/main/src/components/dashboard/DashboardSidebar.jsx): dashboard ui · Role-aware dashboard navigation shell. · `src/components/dashboard/DashboardSidebar.jsx`
- [Home modules](https://github.com/zabedfolio/taskly-client/blob/main/src/components/home/HeroBanner.jsx): page sections · Hero, featured tasks, stats, testimonials, and top freelancers. · `src/components/home/HeroBanner.jsx`
- [Detail modals](https://github.com/zabedfolio/taskly-client/blob/main/src/components/shared/TaskDetailModal.jsx): shared ui · Task, freelancer, and rating modal surfaces. · `src/components/shared/TaskDetailModal.jsx`
- [Badges](https://github.com/zabedfolio/taskly-client/blob/main/src/components/shared/VerifiedBadge.jsx): shared ui · Rating and verification presentation primitives. · `src/components/shared/VerifiedBadge.jsx`

### Client state

React context providers for shared UI state.

- [Contexts](https://github.com/zabedfolio/taskly-client/blob/main/src/contexts/BookmarkContext.jsx): react context · Bookmark, notification, and theme providers. · `src/contexts/BookmarkContext.jsx`

### API layer

Client-side API helpers and Next.js route handlers.

- [Auth handler](https://github.com/zabedfolio/taskly-client/blob/main/src/app/api/auth/[...all]/route.js): route handler · Better Auth endpoint mounted as a Next.js API route. · `src/app/api/auth/[...all]/route.js`
- [Checkout API](https://github.com/zabedfolio/taskly-client/blob/main/src/app/api/checkout_sessions/route.js): route handler · Creates payment sessions for checkout flow. · `src/app/api/checkout_sessions/route.js`
- [Image upload](https://github.com/zabedfolio/taskly-client/blob/main/src/app/api/imagebb/route.js): route handler · ImageBB integration boundary for uploads. · `src/app/api/imagebb/route.js`
- [API helpers](https://github.com/zabedfolio/taskly-client/blob/main/src/lib/api/home/getAllTasks.js): client api · Persona-scoped helpers for home, client, freelancer, and admin data. · `src/lib/api/home/getAllTasks.js`
- [Auth client](https://github.com/zabedfolio/taskly-client/blob/main/src/lib/auth-client.js): auth lib · Better Auth client/server integration helpers. · `src/lib/auth-client.js`
- [Stripe lib](https://github.com/zabedfolio/taskly-client/blob/main/src/lib/stripe.js): payment lib · Stripe configuration and payment helper layer. · `src/lib/stripe.js`

### External services

Backend and third-party systems used by the client.

- **Backend API**: external server · Separate Taskly backend that serves business data and actions.
- **Better Auth**: external auth · Authentication provider used by the client.
- **Stripe**: external payment · Payment provider for checkout and confirmation.
- **ImageBB**: external upload · Third-party image upload service.

## Connections

- App shell → Contexts: wraps · Root app composition includes shared client state providers.
- App shell → Navbar: renders · Root-level shell and navigation appear across public surfaces.
- Home → Home modules: composes · Landing page is assembled from modular home sections.
- Browse → Detail modals: uses · Discovery page opens task details in modals.
- Freelancers → Detail modals: uses · Talent discovery page opens freelancer details and ratings.
- Auth pages → Auth client: authenticates · Login and signup rely on the auth client integration.
- Dashboard shell → Sidebar: provides · Shared dashboard shell supplies role navigation.
- Client area → Sidebar: uses · Client area uses the shared dashboard navigation.
- Freelancer area → Sidebar: uses · Freelancer area uses the shared dashboard navigation.
- Admin area → Sidebar: uses · Admin area uses the shared dashboard navigation.
- Client area → API helpers: fetches · Client workflows pull tasks, proposals, and payment data.
- Freelancer area → API helpers: fetches · Freelancer workflows pull tasks, proposals, and stats.
- Admin area → API helpers: fetches · Admin workflows pull moderation and transaction data.
- Payment routes → Checkout API: starts · Checkout UI calls the server route to create payment sessions.
- Payment routes → Stripe lib: uses · Payment pages depend on Stripe client logic.
- Status pages → Auth client: gates · Unauthorized and status handling are tied to auth/session state.
- Auth handler → Better Auth: integrates · Auth endpoint is backed by Better Auth.
- Checkout API → Stripe: integrates · Checkout endpoint creates sessions with Stripe.
- Image upload → ImageBB: integrates · Upload endpoint forwards images to ImageBB.
- API helpers → Backend API: calls · Most app data is fetched from the external Taskly backend.
- Auth client → Better Auth: calls · Client auth helpers communicate with Better Auth.
- Stripe lib → Stripe: calls · Payment helper layer is built around Stripe.
- Contexts → Home: supports · Shared UI state feeds public browsing and saved-item behavior.
- Contexts → Dashboard shell: supports · Contexts are available throughout authenticated dashboard flows.
- Detail modals → API helpers: reads · Detail modals are populated from API-backed entity data.
- Badges → Detail modals: decorates · Rating and verification badges are reused in detail views.
