How khairullah770/skilled-laborer-updated works
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: server.js API server · controllers Controllers · _layout.tsx App shell · UserContext.tsx Shared state
Components 22
Mobile app
Expo Router client with role-based flows and shared state.
- App shell · Top-level mobile navigation and route composition.
app/_layout.tsx - Shared state · Global user, theme, socket, and booking state used across the mobile app.
context/UserContext.tsx - Auth flow · Signup, login, role selection, and verification entry points.
app/(auth) - Customer flow · Customer tabs and booking, chat, profile, and discovery screens.
app/(customer) - Laborer flow · Laborer dashboard, jobs, service management, profile, and verification screens.
app/(laborer) - Admin flow · Admin-only mobile surfaces for dashboards, users, and verification review.
app/(admin)
Backend API
Express, MongoDB, Socket.IO, and domain logic.
- API server · Bootstraps HTTP, MongoDB, and real-time messaging.
backend/server.js - Mongo connect · MongoDB connection and retry setup.
backend/config/db.js - Routes · Resource endpoints for bookings, chat, users, categories, services, and dashboards.
backend/routes - Controllers · Request handlers for booking, chat, identity, catalog, and admin operations.
backend/controllers - Models · Booking, user, customer, chat, catalog, notification, rating, and audit collections.
backend/models - Middleware · JWT guards, customer auth, error handling, and Multer upload processing.
backend/middleware - Utilities · Notification and rating helpers used by the backend workflows.
backend/utils - Uploads · Stored media for profiles, documents, category assets, and work photos.
backend/uploads - Booking domain · Core transactional flow linking customers, laborers, chat, ratings, and photos.
backend/models/Booking.js - Identity domain · Customer and user identities with role-based authorization boundaries.
backend/models/User.js - Messaging domain · Booking-scoped chat, messages, unread state, and live updates.
backend/models/Chat.js - Catalog domain · Categories, subcategories, and service offerings for discovery and pricing.
backend/models/Category.js - Moderation domain · Laborer verification status, warnings, blocks, and audit trails.
backend/models/AuditLog.js
Admin dashboard
Standalone React/Vite operational console.
- Dashboard shell · Standalone web admin client layout and routing.
admin-dashboard/src/App.tsx - Dashboard API · Browser-side API layer for the admin dashboard.
admin-dashboard/src/api/index.ts - Admin pages · Dashboard, bookings, services, users, and login views.
admin-dashboard/src/pages/Dashboard.tsx
Connections 32
- 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.