# ritu-raj-9262/hirehelper architecture

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

- Interactive diagram: https://gitdiagram.com/ritu-raj-9262/hirehelper
- Repository: https://github.com/ritu-raj-9262/hirehelper

## Overview

HireHelper is a two-tier application split into a Node.js backend and a React frontend, organized as a monorepo.

High-level structure

- The `frontend/` directory contains the user interface built with React and Vite.
- The `backend/` directory contains the API server, domain logic, and persistence layer.
- The root also includes package metadata, suggesting the repo can be managed from the top level, but the application itself is clearly divided into client and server concerns.

Backend architecture

The backend is an Express-style API server centered around `backend/index.js`, with implementation code under `backend/src/`.

Main backend layers:

- `routes/`
  - Defines HTTP endpoints grouped by domain.
  - Separate route modules exist for:
    - authentication
    - OTP verification
    - users
    - tasks
    - task feed
    - requests
- `controllers/`
  - Holds request handlers for each domain area.
  - Controllers mediate between HTTP requests and database/model operations.
- `models/`
  - Contains the persistence models for core entities:
    - `User`
    - `Task`
    - `Request`
    - `AcceptedTask`
    - `Notification`
  - The presence of these model files strongly suggests a MongoDB/Mongoose-style data layer.
- `middleware/`
  - Contains authentication middleware, likely used to protect private routes and attach the current user context.
- `config/`
  - Centralized configuration for:
    - database connection (`db.js`)
    - Cloudinary integration (`cloudinary.js`)
    - file upload handling via Multer (`multer.js`)
- `utils/`
  - Shared utility code for OTP generation, storage, and delivery:
    - OTP creation
    - OTP in-memory store
    - OTP sending

Backend domain boundaries

The backend is organized around a few clear business domains:

1. Authentication and onboarding
   - `authController.js`, `authRoutes.js`
   - `otpController.js`, `otpRoutes.js`
   - Utilities for OTP generation and sending indicate a signup/login flow that uses OTP verification, likely for email or phone verification.
   - `middleware/auth.js` protects authenticated endpoints.

2. User profile management
   - `userController.js`, `userRoutes.js`
   - Includes user-related actions such as profile updates and account-related operations.
   - The frontend includes a `DeleteAccountButton`, which implies account deletion is part of this subsystem.

3. Task management
   - `taskController.js`, `taskRoutes.js`
   - Supports creating, editing, and managing tasks.
   - The backend also has `myTaskController.js` and `getTaskfeedController.js`, indicating separate behavior for:
     - tasks created by the current user
     - tasks visible in a public or filtered task feed

4. Request and assignment workflow
   - `requestController.js`, `requestRoutes.js`
   - `AcceptedTask` and `Request` models show a workflow where users can request to take on a task, and some requests become accepted tasks.
   - This is a distinct business process from raw task creation.

5. Feed and discovery
   - `taskFeedController.js`, `taskFeedRoutes.js`
   - Likely provides browsing/filtering of available tasks for users to discover and request.

6. Notifications
   - `Notification` model suggests the backend records system events such as requests, acceptances, or task updates.
   - The frontend includes a `NotificationBell`, which likely polls or fetches these notifications from the API.

File and media handling

- `config/multer.js` and the `backend/uploads/` directory indicate the backend accepts uploaded files.
- The uploads folder is split into:
  - `profile/` for user profile images
  - `tasks/` for task-related images or attachments
- `config/cloudinary.js` indicates that uploaded files may be stored or mirrored in Cloudinary rather than kept only on the server filesystem.
- This creates a clear boundary between transient upload handling and external asset storage.

Frontend architecture

The frontend is a Vite-based React app under `frontend/src/`.

Main frontend layers:

- `pages/`
  - Top-level screens and routes for the application.
  - Includes:
    - landing and informational pages
    - authentication screens
    - OTP verification
    - task and request management pages
    - profile settings
    - password reset
    - task creation/editing
- `components/`
  - Reusable UI pieces used across pages:
    - task cards
    - request cards
    - request modal
    - sidebar
    - notification bell
    - layout wrapper
    - account deletion button
- `utils/`
  - Routing guards and API helper code.
  - `ProtectedRoute` and `PublicRoute` indicate the frontend distinguishes authenticated vs unauthenticated navigation.
  - `api.js` is the central client-side boundary for talking to the backend.
- `App.jsx`, `main.jsx`
  - Application bootstrap and route composition.
- Styling and theming
  - Tailwind is present via `tailwind.config.js` and `postcss.config.js`.
  - `hirehelper_theme.js`, `App.css`, and `index.css` support consistent styling.

Frontend user flows

The page list reveals the app’s main interaction flows:

- Public onboarding flow
  - `LandingPage`
  - `HowItWorks`
  - `Signup`
  - `Login`
  - `OTPVerification`
  - `ResetPage`

- Authenticated task workflow
  - `feed`
  - `AddTask`
  - `editTask`
  - `MyTasks`
  - `Requests`
  - `MyRequests`

- Account and profile management
  - `ProfileSettings`
  - `DeleteAccountButton` component

- Loading and access control
  - `Loader`
  - `ProtectedRoute`
  - `PublicRoute`

Data flow across the system

1. User enters the frontend
   - Public pages handle first-time access and authentication.
   - Auth state is used to determine whether to render protected or public routes.

2. Authentication and OTP verification
   - User signs up or logs in through the frontend.
   - The frontend calls auth/OTP endpoints via `api.js`.
   - The backend generates and stores OTP data using the utility layer, sends the OTP, and verifies it through the OTP controller/routes.
   - After verification, the backend likely establishes or validates an authenticated session/token, enforced by `auth` middleware on protected routes.

3. Task creation and discovery
   - Authenticated users create tasks in the frontend.
   - The backend stores task data in the `Task` model, optionally handling uploaded files through Multer/Cloudinary.
   - Other users browse the task feed via backend feed routes/controllers.

4. Request and acceptance workflow
   - A user requests a task through the frontend.
   - The backend creates a `Request` record.
   - When a request is accepted, the system transitions into an `AcceptedTask` state.
   - This likely triggers notification creation.

5. My Tasks / My Requests views
   - The frontend has separate screens for:
     - tasks owned by the current user
     - requests the current user has made
   - These map cleanly to backend endpoints that aggregate user-scoped records.

6. Notifications and updates
   - The backend persists notifications.
   - The frontend notification bell provides a compact entry point for unread or recent events.

Important architectural boundaries

- Frontend vs backend
  - The React app does not appear to own business logic; it is a client of the API.
  - The backend is the source of truth for tasks, requests, users, and notifications.

- Authenticated vs public access
  - Protected routes on the frontend mirror backend authentication middleware.
  - This means access control is enforced on both sides of the boundary.

- Domain-separated APIs
  - Authentication, OTP, user profile, task feed, task management, and request handling are split into separate route/controller modules.
  - This helps keep each business process isolated and easier to diagram.

- File handling vs application data
  - Structured domain entities live in the database models.
  - Uploaded assets are handled separately through Multer/Cloudinary and the `uploads/` filesystem area.

Likely deployment/runtime picture

- Backend: Node.js server with Express-style routing, connected to a MongoDB-like database and Cloudinary for media storage.
- Frontend: browser-based React application served as static assets in production and talking to the backend API over HTTP.
- External service dependency: Cloudinary for image/media storage.
- OTP delivery likely depends on an email or messaging provider, though the specific provider is not visible from the file tree alone.

In diagram form, the core architecture is: React UI on the client, an Express API in the middle, MongoDB-style models for persistence, and Cloudinary plus OTP delivery as supporting external services.

Main entry points: [`backend/src/models`](https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/src/models) (Models), [`frontend/src/pages`](https://github.com/ritu-raj-9262/hirehelper/tree/main/frontend/src/pages) (Pages), [`frontend/src/main.jsx`](https://github.com/ritu-raj-9262/hirehelper/blob/main/frontend/src/main.jsx) (React app), [`backend/src/routes`](https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/src/routes) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["HireHelper"]
  node_repo_root["HireHelper<br/>monorepo"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app_entry["React app<br/>Vite/React<br/>[main.jsx]"]
end

subgraph group_backend["Backend"]
  node_backend_entry["API server<br/>Express server<br/>[index.js]"]
end

subgraph group_backend_domain["Backend domains"]
  node_backend_routes["Routes"]
  node_backend_controllers["Controllers<br/>request handlers"]
  node_backend_auth["Auth flow<br/>auth/otp<br/>[authRoutes.js]"]
  node_backend_users["Users<br/>profile/account<br/>[userRoutes.js]"]
  node_backend_tasks["Tasks<br/>task management<br/>[taskRoutes.js]"]
  node_backend_feed["Task feed<br/>discovery<br/>[taskFeedRoutes.js]"]
  node_backend_requests["Requests<br/>workflow<br/>[requestRoutes.js]"]
end

subgraph group_backend_data["Backend data"]
  node_backend_data_models[("Models")]
  node_backend_db["Database<br/>db config<br/>[db.js]"]
  node_backend_media["Media storage<br/>upload/cloudinary<br/>[multer.js]"]
  node_backend_otp["OTP utils<br/>otp helpers<br/>[otp.js]"]
  node_backend_notifications["Notifications<br/>event records<br/>[Notification.js]"]
  node_backend_uploads[("Uploads<br/>file storage")]
  node_backend_auth_mw["Auth middleware<br/>request guard<br/>[auth.js]"]
end

subgraph group_frontend_app["Frontend app"]
  node_frontend_pages["Pages<br/>screens"]
  node_frontend_components["Components"]
  node_frontend_client["API client<br/>routing/auth helpers"]
  node_frontend_theme["Styling<br/>tailwind/css"]
end

node_repo_root -->|"hosts"| node_frontend_app_entry
node_repo_root -->|"hosts"| node_backend_entry
node_frontend_app_entry -->|"renders"| node_frontend_pages
node_frontend_app_entry -->|"uses"| node_frontend_components
node_frontend_app_entry -->|"routes via"| node_frontend_client
node_frontend_app_entry -->|"styles with"| node_frontend_theme
node_frontend_client -->|"calls"| node_backend_entry
node_backend_entry -->|"mounts"| node_backend_routes
node_backend_routes -->|"dispatches to"| node_backend_controllers
node_backend_routes -->|"protects"| node_backend_auth_mw
node_backend_auth -->|"verifies"| node_backend_otp
node_backend_auth -->|"reads/writes"| node_backend_data_models
node_backend_users -->|"reads/writes"| node_backend_data_models
node_backend_tasks -->|"reads/writes"| node_backend_data_models
node_backend_feed -->|"queries"| node_backend_data_models
node_backend_requests -->|"reads/writes"| node_backend_data_models
node_backend_data_models -->|"connects to"| node_backend_db
node_backend_tasks -->|"uploads via"| node_backend_media
node_backend_users -->|"uploads via"| node_backend_media
node_backend_data_models -->|"includes"| node_backend_notifications
node_backend_data_models -->|"stores in"| node_backend_uploads
node_frontend_components -->|"surfaces"| node_backend_notifications
node_frontend_pages -->|"manages"| node_backend_requests
node_frontend_pages -->|"manages"| node_backend_tasks
node_frontend_pages -->|"onboards"| node_backend_auth
node_frontend_pages -->|"updates"| node_backend_users
node_frontend_pages -->|"browses"| node_backend_feed

click node_frontend_app_entry "https://github.com/ritu-raj-9262/hirehelper/blob/main/frontend/src/main.jsx"
click node_frontend_pages "https://github.com/ritu-raj-9262/hirehelper/tree/main/frontend/src/pages"
click node_frontend_components "https://github.com/ritu-raj-9262/hirehelper/tree/main/frontend/src/components"
click node_frontend_client "https://github.com/ritu-raj-9262/hirehelper/tree/main/frontend/src/utils"
click node_frontend_theme "https://github.com/ritu-raj-9262/hirehelper/blob/main/frontend/hirehelper_theme.js"
click node_backend_entry "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/index.js"
click node_backend_routes "https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/src/routes"
click node_backend_controllers "https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/src/controllers"
click node_backend_auth "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/authRoutes.js"
click node_backend_users "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/userRoutes.js"
click node_backend_tasks "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/taskRoutes.js"
click node_backend_feed "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/taskFeedRoutes.js"
click node_backend_requests "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/requestRoutes.js"
click node_backend_data_models "https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/src/models"
click node_backend_db "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/config/db.js"
click node_backend_media "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/config/multer.js"
click node_backend_otp "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/utils/otp.js"
click node_backend_notifications "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/models/Notification.js"
click node_backend_uploads "https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/uploads"
click node_backend_auth_mw "https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/middleware/auth.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_repo_root toneBlue
class node_frontend_app_entry toneAmber
class node_backend_entry toneMint
class node_backend_routes,node_backend_controllers,node_backend_auth,node_backend_users,node_backend_tasks,node_backend_feed,node_backend_requests toneRose
class node_backend_data_models,node_backend_db,node_backend_media,node_backend_otp,node_backend_notifications,node_backend_uploads,node_backend_auth_mw toneIndigo
class node_frontend_pages,node_frontend_components,node_frontend_client,node_frontend_theme toneTeal
```

## Components

### HireHelper

Monorepo split into client and server apps

- **HireHelper**: monorepo · Top-level package for the full app

### Frontend

React/Vite user interface

- [React app](https://github.com/ritu-raj-9262/hirehelper/blob/main/frontend/src/main.jsx): Vite/React · Frontend bootstrap and route composition · `frontend/src/main.jsx`

### Backend

Node/Express API and data layer

- [API server](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/index.js): Express server · Backend process entry point · `backend/index.js`

### Backend domains

Route/controller modules organized by business area

- [Routes](https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/src/routes): HTTP routes · Domain-specific endpoint modules · `backend/src/routes`
- [Controllers](https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/src/controllers): request handlers · HTTP handlers for auth, users, tasks, and requests · `backend/src/controllers`
- [Auth flow](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/authRoutes.js): auth/otp · Login, signup, OTP verification, and auth middleware · `backend/src/routes/authRoutes.js`
- [Users](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/userRoutes.js): profile/account · User profile and account operations · `backend/src/routes/userRoutes.js`
- [Tasks](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/taskRoutes.js): task management · Task creation and task ownership flows · `backend/src/routes/taskRoutes.js`
- [Task feed](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/taskFeedRoutes.js): discovery · Browse and filter available tasks · `backend/src/routes/taskFeedRoutes.js`
- [Requests](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/routes/requestRoutes.js): workflow · Task request and acceptance workflow · `backend/src/routes/requestRoutes.js`

### Backend data

Persistence, config, and shared helpers

- [Models](https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/src/models): persistence models · User, Task, Request, AcceptedTask, Notification · `backend/src/models`
- [Database](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/config/db.js): db config · Database connection setup · `backend/src/config/db.js`
- [Media storage](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/config/multer.js): upload/cloudinary · Multer upload handling and Cloudinary integration · `backend/src/config/multer.js`
- [OTP utils](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/utils/otp.js): otp helpers · OTP generation, store, and delivery helpers · `backend/src/utils/otp.js`
- [Notifications](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/models/Notification.js): event records · Stored notification events surfaced to the UI · `backend/src/models/Notification.js`
- [Uploads](https://github.com/ritu-raj-9262/hirehelper/tree/main/backend/uploads): file storage · Profile and task upload directories · `backend/uploads`
- [Auth middleware](https://github.com/ritu-raj-9262/hirehelper/blob/main/backend/src/middleware/auth.js): request guard · Protects private API routes · `backend/src/middleware/auth.js`

### Frontend app

Pages, shared UI, and client utilities

- [Pages](https://github.com/ritu-raj-9262/hirehelper/tree/main/frontend/src/pages): screens · Landing, auth, feed, task, request, and profile screens · `frontend/src/pages`
- [Components](https://github.com/ritu-raj-9262/hirehelper/tree/main/frontend/src/components): ui components · Reusable cards, layout, modal, sidebar, and notification UI · `frontend/src/components`
- [API client](https://github.com/ritu-raj-9262/hirehelper/tree/main/frontend/src/utils): routing/auth helpers · HTTP client plus public/protected route guards · `frontend/src/utils`
- [Styling](https://github.com/ritu-raj-9262/hirehelper/blob/main/frontend/hirehelper_theme.js): tailwind/css · Theme, Tailwind, and global styles · `frontend/hirehelper_theme.js`

## Connections

- HireHelper → React app: hosts · Monorepo includes the browser application
- HireHelper → API server: hosts · Monorepo includes the API server
- React app → Pages: renders · App composes screen-level pages
- React app → Components: uses · Pages rely on reusable UI components
- React app → API client: routes via · Navigation and API access are centralized here
- React app → Styling: styles with · Global styling and theme configuration
- API client → API server: calls · Frontend talks to backend over HTTP
- API server → Routes: mounts · Server wires up route modules
- Routes → Controllers: dispatches to · Routes delegate work to controllers
- Routes → Auth middleware: protects · Authenticated endpoints use middleware guards
- Auth flow → OTP utils: verifies · Signup/login flow includes OTP generation and delivery
- Auth flow → Models: reads/writes · Auth logic persists user state
- Users → Models: reads/writes · Profile and account data is stored in models
- Tasks → Models: reads/writes · Task CRUD persists through task models
- Task feed → Models: queries · Feed endpoints assemble visible tasks from stored data
- Requests → Models: reads/writes · Requests and accepted tasks are persisted
- Models → Database: connects to · Models rely on the database configuration
- Tasks → Media storage: uploads via · Task assets use upload handling and external storage
- Users → Media storage: uploads via · Profile assets use upload handling and external storage
- Models → Notifications: includes · Notification records are part of the core data layer
- Models → Uploads: stores in · Uploaded assets are organized on disk by use case
- Components → Notifications: surfaces · Notification bell presents backend notification state
- Pages → Requests: manages · Request-related screens drive request workflow
- Pages → Tasks: manages · Task creation and editing screens drive task APIs
- Pages → Auth flow: onboards · Login, signup, OTP, and reset screens use auth APIs
- Pages → Users: updates · Profile settings screens use user APIs
- Pages → Task feed: browses · Feed screens consume task discovery endpoints
