# khairullah770/skilled-laborer-updated architecture

> Architecture diagram of the GitHub repository khairullah770/skilled-laborer-updated, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khairullah770/skilled-laborer-updated
- Repository: https://github.com/khairullah770/skilled-laborer-updated

## Overview

1. **System boundary and shape**
   This repo is a three-client, one-backend marketplace: an **Expo React Native mobile app** for customers/laborers/admins, a **Node.js/Express + MongoDB API** with Socket.IO, and a separate **React/Vite admin dashboard**. Most business logic lives in the backend; both UIs are mostly API consumers.

2. **Mobile app as the primary client**
   The root app uses **Expo Router** with route groups for **auth**, **customer**, **laborer**, and **admin** flows. The screen structure is role-driven rather than feature-driven: each role has its own tabs and detail screens, but all of them share the same backend and shared app state.

3. **Mobile shared state and UI layer**
   Cross-cutting mobile concerns are centralized in `context/` and `components/`. `UserContext`, `ThemeContext`, `SocketContext`, and `app/context/BookingsContext.tsx` provide global session, theming, socket, and booking state. `constants/` holds API URLs and static category/laborer data used by multiple screens.

4. **Backend application core**
   The backend is organized in the classic **Express controller/route/model** shape. `server.js` boots the API, connects MongoDB, and also hosts the **Socket.IO** server. `routes/` expose resource endpoints, `controllers/` contain business logic, and `models/` define the Mongo-backed domain objects.

5. **Identity model and access boundaries**
   The repo separates identities by role and collection: **customers** use `Customer`, while **laborers and admins** use `User`. Authentication is JWT-based, with different middleware for customer auth versus protected user/admin auth. This boundary matters because authorization checks depend on role, not just login state.

6. **Booking is the central business workflow**
   `Booking` is the main transactional object tying the platform together. Customers create bookings, laborers accept/decline/start/complete them, and admins can inspect all bookings. Booking status changes drive downstream effects such as notifications, chat activation/deactivation, ratings, and work photo uploads.

7. **Real-time messaging and notifications**
   Chat is modeled as a **chat per booking** with `Chat` and `Message` collections, plus unread counts and an `isActive` flag. Socket.IO is used for live message delivery, read receipts, and inbox updates; each authenticated user joins a personal room. When a job is completed, the chat is intentionally closed so the communication boundary matches the lifecycle of the booking.

8. **Laborer verification and moderation**
   Laborer onboarding includes a verification flow in the mobile app and a review flow in the admin surfaces. The backend stores verification status, history, document images, warnings, and block state in `User`. Admin actions are also written to `AuditLog`, making moderation traceable and not just stateful.

9. **Marketplace catalog and service discovery**
   Categories and subcategories define the service taxonomy, while `ServiceOffering` maps laborers to specific services and prices. Customers browse categories/subcategories to discover laborers; laborers manage their offerings; admins manage the taxonomy. This is the main discovery layer that feeds booking creation.

10. **Admin dashboard as a separate web client**
   `admin-dashboard/` is a standalone React/Vite application with its own routing, layout, and API client. It focuses on operational views: dashboard analytics, user moderation, service/category CRUD, and booking oversight. It uses browser-local auth and is architecturally separate from the mobile app even though it talks to the same backend.

11. **Media uploads and storage**
   Uploaded assets go through backend Multer middleware into `backend/uploads/`. The uploaded content includes profile photos, ID cards, category icons, subcategory images, and work photos. File handling is a backend concern, which keeps the clients thin and ensures size/type enforcement is centralized.

12. **Resilience, data seeding, and quality gates**
   The backend includes Mongo connection retry logic, utility helpers for ratings and notifications, seed scripts for initial data/admin creation, and a substantial Jest test suite covering signup, booking, search, verification, ratings, and authorization. These are not separate runtime subsystems, but they are important for understanding the repo’s operational maturity and the invariants around booking/chat/verification flows.

Main entry points: [`backend/server.js`](https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/server.js) (API server), [`backend/controllers`](https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/controllers) (Controllers), [`app/_layout.tsx`](https://github.com/khairullah770/skilled-laborer-updated/blob/master/app/_layout.tsx) (App shell), [`context/UserContext.tsx`](https://github.com/khairullah770/skilled-laborer-updated/blob/master/context/UserContext.tsx) (Shared state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mobile["Mobile app"]
  node_app_shell["App shell<br/>expo router app<br/>[_layout.tsx]"]
  node_mobile_shared(("Shared state<br/>contexts<br/>[UserContext.tsx]"))
  node_auth_flow["Auth flow<br/>mobile routes"]
  node_customer_flow["Customer flow<br/>mobile routes"]
  node_laborer_flow["Laborer flow<br/>mobile routes"]
  node_admin_flow["Admin flow<br/>mobile routes"]
end

subgraph group_backend["Backend API"]
  node_api_server["API server<br/>express + socket.io<br/>[server.js]"]
  node_db_config(("Mongo connect<br/>db config<br/>[db.js]"))
  node_routes_layer["Routes"]
  node_controllers_layer["Controllers<br/>business logic"]
  node_models_layer["Models"]
  node_middleware_layer["Middleware<br/>auth + upload"]
  node_utils_layer(("Utilities<br/>helpers"))
  node_uploads_store[("Uploads<br/>file storage")]
  node_booking_domain{{"Booking domain<br/>workflow<br/>[Booking.js]"}}
  node_identity_domain{{"Identity domain<br/>roles + auth<br/>[User.js]"}}
  node_messaging_domain{{"Messaging domain<br/>chat + notifications<br/>[Chat.js]"}}
  node_catalog_domain{{"Catalog domain<br/>taxonomy + offerings<br/>[Category.js]"}}
  node_moderation_domain{{"Moderation domain<br/>verification + audit<br/>[AuditLog.js]"}}
end

subgraph group_dashboard["Admin dashboard"]
  node_dashboard_shell["Dashboard shell<br/>react vite app<br/>[App.tsx]"]
  node_dashboard_api(("Dashboard API<br/>web client<br/>[index.ts]"))
  node_dashboard_pages["Admin pages<br/>ops screens<br/>[Dashboard.tsx]"]
end

node_app_shell -->|"routes"| node_auth_flow
node_app_shell -->|"routes"| node_customer_flow
node_app_shell -->|"routes"| node_laborer_flow
node_app_shell -->|"routes"| node_admin_flow
node_mobile_shared -->|"state"| node_auth_flow
node_mobile_shared -->|"state"| node_customer_flow
node_mobile_shared -->|"state"| node_laborer_flow
node_mobile_shared -->|"state"| node_admin_flow
node_auth_flow -->|"auth"| node_api_server
node_customer_flow -->|"api"| node_api_server
node_laborer_flow -->|"api"| node_api_server
node_admin_flow -->|"api"| node_api_server
node_dashboard_shell -->|"uses"| node_dashboard_api
node_dashboard_api -->|"api"| node_api_server
node_api_server -->|"connects"| node_db_config
node_api_server -->|"mounts"| node_routes_layer
node_api_server -->|"uses"| node_middleware_layer
node_api_server -->|"loads"| node_models_layer
node_api_server -->|"writes"| node_uploads_store
node_routes_layer -->|"dispatches"| node_controllers_layer
node_controllers_layer -->|"orchestrates"| node_booking_domain
node_controllers_layer -->|"auth"| node_identity_domain
node_controllers_layer -->|"chat"| node_messaging_domain
node_controllers_layer -->|"catalog"| node_catalog_domain
node_controllers_layer -->|"moderates"| node_moderation_domain
node_controllers_layer -->|"helpers"| node_utils_layer
node_controllers_layer -->|"media"| node_uploads_store
node_booking_domain -->|"opens/closes"| node_messaging_domain
node_booking_domain -->|"roles"| node_identity_domain
node_catalog_domain -->|"feeds"| node_booking_domain
node_moderation_domain -->|"tracks"| node_identity_domain
node_moderation_domain -->|"evidence"| node_uploads_store

click node_app_shell "https://github.com/khairullah770/skilled-laborer-updated/blob/master/app/_layout.tsx"
click node_mobile_shared "https://github.com/khairullah770/skilled-laborer-updated/blob/master/context/UserContext.tsx"
click node_auth_flow "https://github.com/khairullah770/skilled-laborer-updated/tree/master/app/(auth)"
click node_customer_flow "https://github.com/khairullah770/skilled-laborer-updated/tree/master/app/(customer)"
click node_laborer_flow "https://github.com/khairullah770/skilled-laborer-updated/tree/master/app/(laborer)"
click node_admin_flow "https://github.com/khairullah770/skilled-laborer-updated/tree/master/app/(admin)"
click node_api_server "https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/server.js"
click node_db_config "https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/config/db.js"
click node_routes_layer "https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/routes"
click node_controllers_layer "https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/controllers"
click node_models_layer "https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/models"
click node_middleware_layer "https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/middleware"
click node_utils_layer "https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/utils"
click node_uploads_store "https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/uploads"
click node_booking_domain "https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/Booking.js"
click node_identity_domain "https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/User.js"
click node_messaging_domain "https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/Chat.js"
click node_catalog_domain "https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/Category.js"
click node_moderation_domain "https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/AuditLog.js"
click node_dashboard_shell "https://github.com/khairullah770/skilled-laborer-updated/blob/master/admin-dashboard/src/App.tsx"
click node_dashboard_api "https://github.com/khairullah770/skilled-laborer-updated/blob/master/admin-dashboard/src/api/index.ts"
click node_dashboard_pages "https://github.com/khairullah770/skilled-laborer-updated/blob/master/admin-dashboard/src/pages/Dashboard.tsx"

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_shell,node_mobile_shared,node_auth_flow,node_customer_flow,node_laborer_flow,node_admin_flow toneBlue
class node_api_server,node_db_config,node_routes_layer,node_controllers_layer,node_models_layer,node_middleware_layer,node_utils_layer,node_uploads_store,node_booking_domain,node_identity_domain,node_messaging_domain,node_catalog_domain,node_moderation_domain toneAmber
class node_dashboard_shell,node_dashboard_api,node_dashboard_pages toneMint
```

## Components

### Mobile app

Expo Router client with role-based flows and shared state.

- [App shell](https://github.com/khairullah770/skilled-laborer-updated/blob/master/app/_layout.tsx): expo router app · Top-level mobile navigation and route composition. · `app/_layout.tsx`
- [Shared state](https://github.com/khairullah770/skilled-laborer-updated/blob/master/context/UserContext.tsx): contexts · Global user, theme, socket, and booking state used across the mobile app. · `context/UserContext.tsx`
- [Auth flow](https://github.com/khairullah770/skilled-laborer-updated/tree/master/app/(auth)): mobile routes · Signup, login, role selection, and verification entry points. · `app/(auth)`
- [Customer flow](https://github.com/khairullah770/skilled-laborer-updated/tree/master/app/(customer)): mobile routes · Customer tabs and booking, chat, profile, and discovery screens. · `app/(customer)`
- [Laborer flow](https://github.com/khairullah770/skilled-laborer-updated/tree/master/app/(laborer)): mobile routes · Laborer dashboard, jobs, service management, profile, and verification screens. · `app/(laborer)`
- [Admin flow](https://github.com/khairullah770/skilled-laborer-updated/tree/master/app/(admin)): mobile routes · Admin-only mobile surfaces for dashboards, users, and verification review. · `app/(admin)`

### Backend API

Express, MongoDB, Socket.IO, and domain logic.

- [API server](https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/server.js): express + socket.io · Bootstraps HTTP, MongoDB, and real-time messaging. · `backend/server.js`
- [Mongo connect](https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/config/db.js): db config · MongoDB connection and retry setup. · `backend/config/db.js`
- [Routes](https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/routes): express routes · Resource endpoints for bookings, chat, users, categories, services, and dashboards. · `backend/routes`
- [Controllers](https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/controllers): business logic · Request handlers for booking, chat, identity, catalog, and admin operations. · `backend/controllers`
- [Models](https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/models): mongo models · Booking, user, customer, chat, catalog, notification, rating, and audit collections. · `backend/models`
- [Middleware](https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/middleware): auth + upload · JWT guards, customer auth, error handling, and Multer upload processing. · `backend/middleware`
- [Utilities](https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/utils): helpers · Notification and rating helpers used by the backend workflows. · `backend/utils`
- [Uploads](https://github.com/khairullah770/skilled-laborer-updated/tree/master/backend/uploads): file storage · Stored media for profiles, documents, category assets, and work photos. · `backend/uploads`
- [Booking domain](https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/Booking.js): workflow · Core transactional flow linking customers, laborers, chat, ratings, and photos. · `backend/models/Booking.js`
- [Identity domain](https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/User.js): roles + auth · Customer and user identities with role-based authorization boundaries. · `backend/models/User.js`
- [Messaging domain](https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/Chat.js): chat + notifications · Booking-scoped chat, messages, unread state, and live updates. · `backend/models/Chat.js`
- [Catalog domain](https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/Category.js): taxonomy + offerings · Categories, subcategories, and service offerings for discovery and pricing. · `backend/models/Category.js`
- [Moderation domain](https://github.com/khairullah770/skilled-laborer-updated/blob/master/backend/models/AuditLog.js): verification + audit · Laborer verification status, warnings, blocks, and audit trails. · `backend/models/AuditLog.js`

### Admin dashboard

Standalone React/Vite operational console.

- [Dashboard shell](https://github.com/khairullah770/skilled-laborer-updated/blob/master/admin-dashboard/src/App.tsx): react vite app · Standalone web admin client layout and routing. · `admin-dashboard/src/App.tsx`
- [Dashboard API](https://github.com/khairullah770/skilled-laborer-updated/blob/master/admin-dashboard/src/api/index.ts): web client · Browser-side API layer for the admin dashboard. · `admin-dashboard/src/api/index.ts`
- [Admin pages](https://github.com/khairullah770/skilled-laborer-updated/blob/master/admin-dashboard/src/pages/Dashboard.tsx): ops screens · Dashboard, bookings, services, users, and login views. · `admin-dashboard/src/pages/Dashboard.tsx`

## Connections

- App shell → Auth flow: routes · Directs unauthenticated users into auth screens.
- App shell → Customer flow: routes · Hosts customer role navigation.
- App shell → Laborer flow: routes · Hosts laborer role navigation.
- App shell → Admin flow: routes · Hosts admin role navigation.
- Shared state → Auth flow: state · Provides session and theme state to auth screens.
- Shared state → Customer flow: state · Shares booking, socket, and user state with customer screens.
- Shared state → Laborer flow: state · Shares booking, socket, and user state with laborer screens.
- Shared state → Admin flow: state · Shares session and socket state with admin mobile screens.
- Auth flow → API server: auth · Uses backend signup, login, and verification endpoints.
- Customer flow → API server: api · Consumes bookings, chat, catalog, and profile services.
- Laborer flow → API server: api · Consumes jobs, verification, services, and chat services.
- Admin flow → API server: api · Consumes moderation and oversight endpoints.
- Dashboard shell → Dashboard API: uses · The web UI is driven by its client API layer.
- Dashboard API → API server: api · Talks to the shared backend for admin operations.
- API server → Mongo connect: connects · Initializes MongoDB before serving requests.
- API server → Routes: mounts · Registers HTTP route modules.
- API server → Middleware: uses · Applies auth, error, and upload middleware.
- API server → Models: loads · Uses Mongo models across controllers and real-time flows.
- API server → Uploads: writes · Stores uploaded media on disk.
- Routes → Controllers: dispatches · Routes forward requests to controllers.
- Controllers → Booking domain: orchestrates · Booking controllers drive the main marketplace workflow.
- Controllers → Identity domain: auth · Identity and role checks gate protected operations.
- Controllers → Messaging domain: chat · Chat controllers manage booking-linked conversations.
- Controllers → Catalog domain: catalog · Catalog controllers manage discovery and service setup.
- Controllers → Moderation domain: moderates · Admin and verification actions update moderation records.
- Controllers → Utilities: helpers · Uses shared notification and rating helpers.
- Controllers → Uploads: media · Receives and persists uploaded documents and photos.
- Booking domain → Messaging domain: opens/closes · Booking status enables or disables the related chat.
- Booking domain → Identity domain: roles · Customers create bookings; laborers act on them; admins inspect them.
- Catalog domain → Booking domain: feeds · Categories, subcategories, and offerings drive booking creation.
- Moderation domain → Identity domain: tracks · Stores verification state, warnings, and blocks on user records.
- Moderation domain → Uploads: evidence · Relies on uploaded identity and verification documents.
