# shreysoni1102-cell/hirehub architecture

> Architecture diagram of the GitHub repository shreysoni1102-cell/hirehub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shreysoni1102-cell/hirehub
- Repository: https://github.com/shreysoni1102-cell/hirehub

## Overview

1. **Overall shape**
   This is a three-part monorepo: a **React/Vite frontend** in `client/`, an **Express/MongoDB API** in `server/`, and a separate **Python AI service** in `ai-service/`. The core architecture boundary is browser UI → REST API → MongoDB, with AI-related features split off into their own service layer.

2. **Frontend subsystem**
   The `client/` app is a single-page application built with **React 18**, **Vite**, **Tailwind CSS**, **React Router v6**, and **Axios**. Its job is presentation, navigation, and session state, not business logic. Key shared UI pieces live in `components/` (`Navbar`, `Layout`, `ProtectedRoute`), while page-level features are organized under `pages/` for home, auth, dashboards, job detail, applications, chat, and ATS checking.

3. **Client-side state and access control**
   Authentication state is managed in `context/AuthContext.jsx`, and theme state in `context/ThemeContext.jsx`. JWTs and the current user snapshot are stored in `localStorage`, then reused by Axios for authenticated requests. `ProtectedRoute` enforces route-level access and can gate pages by role, which keeps the role-specific views separated in the UI.

4. **Frontend-to-backend integration**
   The frontend calls the API through `client/src/api/axios.js`. In development, it relies on the Vite proxy so `/api` routes reach the backend on port 5000; in production it can point to a deployed API root via `VITE_API_URL`. Every request includes `Authorization: Bearer <token>` when present, so the server remains the source of truth for authorization.

5. **Backend entry and structure**
   The backend starts from `server/server.js` and follows an MVC-style layout: `config/`, `controllers/`, `middleware/`, `models/`, `routes/`, and `utils/`. This makes the API the central orchestration layer: routes dispatch to controllers, controllers apply business rules, models map to MongoDB, and utilities handle cross-cutting concerns like JWT generation and email/AI helpers.

6. **Authentication and role model**
   Authentication is based on **JWT** and password hashing with **bcrypt**. The `User` model stores credentials and role information, and auth middleware (`protect`, `role.js`) enforces access by role: **admin**, **recruiter**, and **user/job seeker**. Public registration is restricted to non-admin roles; admin accounts are expected to come from seeding or direct database setup.

7. **Jobs domain**
   The job portal core lives in `Job` model + `jobController.js` + `jobRoutes.js`. Anyone can read job listings and job detail pages, but only recruiters can create, edit, or delete jobs, and only for jobs they own. This ownership rule is a key boundary in the backend: authorization is not just role-based, but also resource-scoped.

8. **Applications domain**
   Applications are represented by `Application` and handled through `applicationController.js` and `applicationRoutes.js`. Job seekers submit applications tied to a specific job, then view their own submissions through a dedicated endpoint. Recruiters can inspect applications for jobs they own and update application status, which supports shortlist/reject-style workflow.

9. **Admin subsystem**
   Admin functions are isolated under `adminController.js` and `adminRoutes.js`. This area is responsible for platform-level user management, including listing and deleting users. The controller includes a safety guard preventing admins from deleting their own account through the delete-user endpoint.

10. **Chat and AI boundary**
   The repo includes both `chatRoutes.js`/`ChatMessage` and an AI utility layer (`utils/aiService.js`) plus a separate `ai-service/` Python package. That suggests AI features such as chat or ATS checking are intentionally separated from the main CRUD API. The React pages `Chat.jsx` and `ATSChecker.jsx` sit on top of this boundary, likely calling either the Express AI routes or the standalone Python service depending on deployment.

11. **Data persistence**
   MongoDB is the primary data store, accessed through **Mongoose** models for `User`, `Job`, `Application`, and `ChatMessage`. The database is the shared state boundary for the whole platform, while controllers and middleware keep business rules in the API layer rather than in the client.

12. **Operational concerns**
   The backend includes middleware for **logging**, **rate limiting**, and centralized **error handling**, plus a **Swagger** config for API documentation. There is also a `seed.js` script for loading demo data, and the root `docker-compose.yml` indicates the repo is designed for local containerized setup. Environment files in both client and server define runtime boundaries such as `MONGODB_URI`, `JWT_SECRET`, `CLIENT_URL`, and optional API base URL settings.

13. **Typical request flows**
   The main user flow is: browser loads the React app → user logs in/registers → token is stored → Axios sends authenticated API requests → Express validates JWT and role → Mongoose reads/writes MongoDB → UI updates based on the response. Separate flows exist for recruiters managing jobs/applications, admins managing users, and AI/chat screens calling the AI-related service boundary.

Main entry points: [`server/server.js`](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/server.js) (API Server), [`server/models/User.js`](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/models/User.js) (Mongo Models), [`client/src/main.jsx`](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/main.jsx) (Route Shell), [`client/src/pages/Home.jsx`](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/pages/Home.jsx) (Feature Pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_browser(("Browser UI<br/>SPA frontend<br/>[App.jsx]"))
  node_client_routes["Route Shell<br/>router shell<br/>[main.jsx]"]
  node_client_auth["Auth State<br/>context state<br/>[AuthContext.jsx]"]
  node_client_theme["Theme State<br/>ui context<br/>[ThemeContext.jsx]"]
  node_client_api["API Client<br/>axios client<br/>[axios.js]"]
  node_client_guard["Access Guard<br/>route guard<br/>[ProtectedRoute.jsx]"]
  node_client_pages["Feature Pages<br/>page layer<br/>[Home.jsx]"]
end

subgraph group_server["Server"]
  node_server_entry(("API Server<br/>express entry<br/>[server.js]"))
  node_server_auth["Auth API<br/>auth controller<br/>[authController.js]"]
  node_server_jobs["Jobs API<br/>job controller<br/>[jobController.js]"]
  node_server_apps["Applications API<br/>application controller"]
  node_server_admin["Admin API<br/>admin controller<br/>[adminController.js]"]
  node_server_chat["Chat API<br/>chat routes<br/>[chatRoutes.js]"]
  node_server_models[("Mongo Models<br/>mongoose models<br/>[User.js]")]
  node_server_mw["Middleware Layer<br/>express middleware<br/>[auth.js]"]
  node_server_db[("MongoDB<br/>database<br/>[db.js]")]
  node_server_utils["Server Utils<br/>utility layer<br/>[generateToken.js]"]
end

subgraph group_ai["AI Service"]
  node_ai_service(("Python AI<br/>fastapi service<br/>[main.py]"))
end

node_browser -->|"renders"| node_client_routes
node_client_routes -->|"navigates"| node_client_pages
node_client_routes -->|"protects"| node_client_guard
node_client_guard -->|"reads session"| node_client_auth
node_client_pages -->|"requests"| node_client_api
node_client_api -->|"HTTP /api"| node_server_entry
node_client_auth -->|"attaches token"| node_client_api
node_client_theme -->|"themes UI"| node_browser
node_server_entry -->|"applies"| node_server_mw
node_server_entry -->|"routes auth"| node_server_auth
node_server_entry -->|"routes jobs"| node_server_jobs
node_server_entry -->|"routes applications"| node_server_apps
node_server_entry -->|"routes admin"| node_server_admin
node_server_entry -->|"routes chat"| node_server_chat
node_server_auth -->|"issues token"| node_server_utils
node_server_jobs -->|"reads/writes"| node_server_models
node_server_apps -->|"reads/writes"| node_server_models
node_server_admin -->|"reads/writes"| node_server_models
node_server_chat -->|"uses AI"| node_server_utils
node_server_models -->|"persists to"| node_server_db
node_server_chat -->|"delegates"| node_ai_service
node_client_pages -.->|"AI screens"| node_ai_service

click node_browser "https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/App.jsx"
click node_client_routes "https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/main.jsx"
click node_client_auth "https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/context/AuthContext.jsx"
click node_client_theme "https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/context/ThemeContext.jsx"
click node_client_api "https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/api/axios.js"
click node_client_guard "https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/components/ProtectedRoute.jsx"
click node_client_pages "https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/pages/Home.jsx"
click node_server_entry "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/server.js"
click node_server_auth "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/controllers/authController.js"
click node_server_jobs "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/controllers/jobController.js"
click node_server_apps "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/controllers/applicationController.js"
click node_server_admin "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/controllers/adminController.js"
click node_server_chat "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/routes/chatRoutes.js"
click node_server_models "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/models/User.js"
click node_server_mw "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/middleware/auth.js"
click node_server_db "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/config/db.js"
click node_server_utils "https://github.com/shreysoni1102-cell/hirehub/blob/main/server/utils/generateToken.js"
click node_ai_service "https://github.com/shreysoni1102-cell/hirehub/blob/main/ai-service/main.py"

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_browser,node_client_routes,node_client_auth,node_client_theme,node_client_api,node_client_guard,node_client_pages toneBlue
class node_server_entry,node_server_auth,node_server_jobs,node_server_apps,node_server_admin,node_server_chat,node_server_models,node_server_mw,node_server_db,node_server_utils toneAmber
class node_ai_service toneMint
```

## Components

### Client

React/Vite single-page app and UI state

- [Browser UI](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/App.jsx): SPA frontend · User-facing React app for navigation, forms, and role-based views · `client/src/App.jsx`
- [Route Shell](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/main.jsx): router shell · Top-level routing and page composition · `client/src/main.jsx`
- [Auth State](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/context/AuthContext.jsx): context state · JWT-backed session and user snapshot stored in client state · `client/src/context/AuthContext.jsx`
- [Theme State](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/context/ThemeContext.jsx): ui context · Light/dark theme selection and UI preference state · `client/src/context/ThemeContext.jsx`
- [API Client](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/api/axios.js): axios client · Authenticated HTTP client and API base URL handling · `client/src/api/axios.js`
- [Access Guard](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/components/ProtectedRoute.jsx): route guard · Role-based protected route wrapper for dashboard and admin views · `client/src/components/ProtectedRoute.jsx`
- [Feature Pages](https://github.com/shreysoni1102-cell/hirehub/blob/main/client/src/pages/Home.jsx): page layer · Home, auth, dashboards, jobs, applications, chat, and ATS checking screens · `client/src/pages/Home.jsx`

### Server

Express API, persistence, and domain logic

- [API Server](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/server.js): express entry · Backend bootstrap and middleware wiring · `server/server.js`
- [Auth API](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/controllers/authController.js): auth controller · Registration, login, token issuance, and current-user flows · `server/controllers/authController.js`
- [Jobs API](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/controllers/jobController.js): job controller · Job listing and recruiter-owned CRUD operations · `server/controllers/jobController.js`
- [Applications API](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/controllers/applicationController.js): application controller · Apply, inspect submissions, and update application status · `server/controllers/applicationController.js`
- [Admin API](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/controllers/adminController.js): admin controller · Platform user management and protected admin actions · `server/controllers/adminController.js`
- [Chat API](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/routes/chatRoutes.js): chat routes · Chat and AI-facing HTTP endpoints · `server/routes/chatRoutes.js`
- [Mongo Models](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/models/User.js): mongoose models · User, Job, Application, and ChatMessage persistence models · `server/models/User.js`
- [Middleware Layer](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/middleware/auth.js): express middleware · JWT protection, role checks, logging, rate limiting, and error handling · `server/middleware/auth.js`
- [MongoDB](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/config/db.js): database · Primary persistent data store for the platform · `server/config/db.js`
- [Server Utils](https://github.com/shreysoni1102-cell/hirehub/blob/main/server/utils/generateToken.js): utility layer · Token generation, email helpers, and AI integration support · `server/utils/generateToken.js`

### AI Service

Standalone Python service for AI features

- [Python AI](https://github.com/shreysoni1102-cell/hirehub/blob/main/ai-service/main.py): fastapi service · Separate Python service for AI-related processing · `ai-service/main.py`

## Connections

- Browser UI → Route Shell: renders · The React app is composed through the route shell
- Route Shell → Feature Pages: navigates · Routes switch between page-level feature screens
- Route Shell → Access Guard: protects · Protected routes gate sensitive dashboards and admin screens
- Access Guard → Auth State: reads session · Route access depends on user identity and role
- Feature Pages → API Client: requests · Pages fetch and mutate data through the shared API client
- API Client → API Server: HTTP /api · Authenticated REST calls go to the Express backend
- Auth State → API Client: attaches token · Stored JWT is reused for authorized requests
- Theme State → Browser UI: themes UI · Theme context affects client presentation
- API Server → Middleware Layer: applies · Requests pass through middleware for security and observability
- API Server → Auth API: routes auth · Authentication endpoints are mounted on the server
- API Server → Jobs API: routes jobs · Job endpoints are mounted on the server
- API Server → Applications API: routes applications · Application endpoints are mounted on the server
- API Server → Admin API: routes admin · Admin endpoints are mounted on the server
- API Server → Chat API: routes chat · Chat and AI-related endpoints are mounted on the server
- Auth API → Server Utils: issues token · Auth logic relies on token generation utilities
- Jobs API → Mongo Models: reads/writes · Job controller persists through Mongoose models
- Applications API → Mongo Models: reads/writes · Applications are stored and queried via models
- Admin API → Mongo Models: reads/writes · Admin user management operates on persisted users
- Chat API → Server Utils: uses AI · Chat endpoints can invoke AI helper utilities
- Mongo Models → MongoDB: persists to · All major domain models map to MongoDB
- Chat API → Python AI: delegates · AI-specific requests can be handled by the separate Python service
- Feature Pages → Python AI: AI screens · Chat and ATS checking screens sit on the AI feature boundary
