# rahulreddy006/local-freelance-job-board-backend architecture

> Architecture diagram of the GitHub repository rahulreddy006/local-freelance-job-board-backend, 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/rahulreddy006/local-freelance-job-board-backend
- Repository: https://github.com/rahulreddy006/local-freelance-job-board-backend

## Overview

1. **What this repository is**
   - This is a Node.js 22 + Express 5 backend for a freelance marketplace.
   - Its core domain is three MongoDB-backed entities: users, gigs, and applications.
   - The backend is organized as a typical request pipeline: route → middleware → controller → service → model.

2. **Entry points and process shape**
   - `server.js` is the runtime startup file: it likely loads environment variables, connects to MongoDB, and starts listening on a port.
   - `app.js` is the Express application assembly point: it typically wires middleware, routes, Swagger docs, and error handling.
   - This split matters architecturally because the HTTP app and the process bootstrap are separated.

3. **Request handling boundaries**
   - `src/routes/*` defines the API surface for auth, gigs, and applications.
   - `src/controllers/*` handles HTTP concerns only: parsing request data, returning responses, and delegating business rules.
   - `src/services/*` contains the business logic and cross-model workflow, keeping controllers thin.
   - `src/models/*` holds the Mongoose schemas and database constraints.

4. **Domain model layer**
   - `user.model.js` represents account identity and authorization state, including role and onboarding/provider metadata.
   - `gig.model.js` represents job postings created by businesses.
   - `application.model.js` represents a student’s application to a gig.
   - The application model’s compound uniqueness constraint is important because it enforces “one application per user per gig” at the database boundary.

5. **Authentication subsystem**
   - Authentication is split between local JWT login/register and Google OAuth.
   - `src/config/passport.config.js` sets up Passport’s Google strategy.
   - `src/controllers/auth.controller.js` and `src/routes/auth.route.js` expose login, registration, refresh-token, Google callback, and profile-completion flows.
   - `src/middlewares/auth.middleware.js` protects routes by validating JWTs and likely attaching the authenticated user to the request context.

6. **Authorization model**
   - The repository is role-based, with at least `student` and `business`.
   - Authorization is enforced at both route and business-logic level: students can apply, businesses can create gigs and manage applications, and ownership checks ensure a business can only act on its own gigs/applications.
   - This is a key architectural boundary because not all “authenticated” users can perform all operations.

7. **Gig management flow**
   - The gig subsystem is centered on `gig.controller.js`, `gig.service.js`, and `gig.route.js`.
   - It supports public read access for browsing gigs and authenticated business-only writes for creating and managing owned gigs.
   - The README’s query features imply the service layer handles filtering, search, pagination, and sort translation before querying MongoDB.

8. **Application workflow**
   - `application.controller.js`, `application.service.js`, and `application.route.js` implement the workflow from student submission to business review.
   - A student applies to a gig, and the business owner can accept or reject applications.
   - The business rule that accepting one application auto-rejects competing pending applications lives in the service layer, where multi-document workflow decisions belong.

9. **Validation and input safety**
   - `src/validators/auth.validator.js` and `src/validators/gig.validator.js` provide schema-based request validation.
   - `src/middlewares/validator.middleware.js` is the execution boundary that applies those schemas before controller logic runs.
   - This design keeps malformed or incomplete data out of the service and model layers.

10. **Cross-cutting middleware stack**
   - `src/middlewares/rateLimiter.middleware.js` adds request throttling.
   - `src/middlewares/error.middleware.js` centralizes error translation and response formatting.
   - The app also uses common security middleware from the README stack: Helmet, CORS, and MongoDB injection sanitization.
   - These are infrastructural concerns that sit around the business routes rather than inside them.

11. **Configuration and external integration**
   - `src/config/db.config.js` handles MongoDB connection setup.
   - `src/config/logger.config.js` configures structured logging with Winston.
   - `src/config/swagger.config.js` builds the OpenAPI/Swagger documentation served by the API.
   - Passport config is the OAuth integration point, while the database config is the persistence integration point.

12. **Utilities and error model**
   - `src/utils/asyncHandler.util.js` is used to avoid repetitive try/catch wrappers around async controllers.
   - `src/utils/error.util.js` defines the application’s custom error shape and status handling.
   - These utilities support a consistent error path from service/controller failures into the centralized error middleware.

13. **Operational and deployment characteristics**
   - The project is designed for production deployment on Render, backed by MongoDB Atlas or another MongoDB instance.
   - Swagger UI is part of the runtime surface, not just documentation, so it is an architectural endpoint for API exploration and testing.
   - Logging is split between request logs and application/error logs, which matters for observability boundaries.

14. **Primary data flows to diagram**
   - **Auth flow:** client → auth routes → auth controller/service → user model/MongoDB → JWT/refresh token response.
   - **Gig flow:** client → gig routes → auth/validator middleware → gig controller/service → gig model/MongoDB → response.
   - **Application flow:** student client → application routes → auth/validator middleware → application service → application + gig models → update/reject side effects → response.
   - These three flows are the main architecture arrows to draw.

15. **Overall architectural shape**
   - This is a layered monolith with clear separation of concerns, not a microservice system.
   - The main boundaries are HTTP routing, request validation, authentication/authorization, domain services, and MongoDB persistence.
   - External systems that materially affect the design are MongoDB, Google OAuth/Passport, JWT, and Swagger documentation.

Main entry points: [`app.js`](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/app.js) (Express App), [`src/controllers/auth.controller.js`](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/controllers/auth.controller.js) (Auth Controller), [`src/routes/auth.route.js`](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/routes/auth.route.js) (Auth Routes), [`src/routes/gig.route.js`](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/routes/gig.route.js) (Gig Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_bootstrap["Bootstrap"]
  node_server["Server<br/>runtime bootstrap<br/>[server.js]"]
  node_app["Express App<br/>app assembly<br/>[app.js]"]
end

subgraph group_api["API Layer"]
  node_auth_route["Auth Routes<br/>http routes<br/>[auth.route.js]"]
  node_gig_route["Gig Routes<br/>http routes<br/>[gig.route.js]"]
  node_application_route["Application Routes<br/>http routes"]
  node_auth_mw["Auth Guard<br/>jwt middleware<br/>[auth.middleware.js]"]
  node_validator_mw["Validator<br/>schema middleware"]
  node_rate_limit_mw["Rate Limiter<br/>throttle middleware"]
  node_error_mw["Error Middleware<br/>error handler"]
  node_auth_controller["Auth Controller<br/>http controller<br/>[auth.controller.js]"]
  node_gig_controller["Gig Controller<br/>http controller<br/>[gig.controller.js]"]
  node_application_controller["App Controller<br/>http controller"]
  node_auth_validator["Auth Validator<br/>request schema<br/>[auth.validator.js]"]
  node_gig_validator["Gig Validator<br/>request schema<br/>[gig.validator.js]"]
end

subgraph group_domain["Domain"]
  node_user_service["User Service<br/>account workflow<br/>[user.service.js]"]
  node_gig_service["Gig Service<br/>business logic<br/>[gig.service.js]"]
  node_application_service["Application Service<br/>workflow logic"]
  node_user_model["User Model<br/>mongoose model<br/>[user.model.js]"]
  node_gig_model["Gig Model<br/>mongoose model<br/>[gig.model.js]"]
  node_application_model["Application Model<br/>mongoose model"]
end

subgraph group_infra["Infrastructure"]
  node_db_config["Mongo Config<br/>db connector<br/>[db.config.js]"]
  node_passport_config["Passport Config<br/>oauth strategy<br/>[passport.config.js]"]
  node_swagger_config["Swagger Config<br/>api docs<br/>[swagger.config.js]"]
  node_logger_config["Logger Config<br/>logging<br/>[logger.config.js]"]
  node_async_handler["Async Handler"]
  node_error_util["App Error<br/>[error.util.js]"]
end

node_server -->|"bootstraps"| node_app
node_server -->|"connects"| node_db_config
node_app -->|"uses"| node_rate_limit_mw
node_app -->|"serves"| node_swagger_config
node_app -->|"terminates with"| node_error_mw
node_app -->|"mounts"| node_auth_route
node_app -->|"mounts"| node_gig_route
node_app -->|"mounts"| node_application_route
node_auth_route -->|"protects"| node_auth_mw
node_gig_route -->|"protects"| node_auth_mw
node_application_route -->|"protects"| node_auth_mw
node_auth_route -->|"validates"| node_validator_mw
node_gig_route -->|"validates"| node_validator_mw
node_application_route -->|"validates"| node_validator_mw
node_auth_route -->|"dispatches"| node_auth_controller
node_gig_route -->|"dispatches"| node_gig_controller
node_application_route -->|"dispatches"| node_application_controller
node_auth_controller -->|"wraps"| node_async_handler
node_gig_controller -->|"wraps"| node_async_handler
node_application_controller -->|"wraps"| node_async_handler
node_auth_controller -->|"delegates to"| node_user_service
node_gig_controller -->|"delegates to"| node_gig_service
node_application_controller -->|"delegates to"| node_application_service
node_auth_controller -->|"uses"| node_auth_validator
node_gig_controller -->|"uses"| node_gig_validator
node_user_service -->|"persists to"| node_user_model
node_gig_service -->|"persists to"| node_gig_model
node_application_service -->|"persists to"| node_application_model
node_application_service -->|"checks"| node_gig_model
node_auth_controller -->|"integrates"| node_passport_config
node_user_service -->|"supports"| node_passport_config
node_auth_mw -->|"throws"| node_error_util
node_validator_mw -->|"throws"| node_error_util
node_gig_service -->|"throws"| node_error_util
node_application_service -->|"throws"| node_error_util
node_app -->|"uses"| node_logger_config

click node_server "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/server.js"
click node_app "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/app.js"
click node_auth_route "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/routes/auth.route.js"
click node_gig_route "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/routes/gig.route.js"
click node_application_route "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/routes/application.route.js"
click node_auth_mw "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/middlewares/auth.middleware.js"
click node_validator_mw "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/middlewares/validator.middleware.js"
click node_rate_limit_mw "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/middlewares/rateLimiter.middleware.js"
click node_error_mw "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/middlewares/error.middleware.js"
click node_auth_controller "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/controllers/auth.controller.js"
click node_gig_controller "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/controllers/gig.controller.js"
click node_application_controller "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/controllers/application.controller.js"
click node_auth_validator "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/validators/auth.validator.js"
click node_gig_validator "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/validators/gig.validator.js"
click node_user_service "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/services/user.service.js"
click node_gig_service "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/services/gig.service.js"
click node_application_service "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/services/application.service.js"
click node_user_model "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/models/user.model.js"
click node_gig_model "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/models/gig.model.js"
click node_application_model "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/models/application.model.js"
click node_db_config "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/config/db.config.js"
click node_passport_config "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/config/passport.config.js"
click node_swagger_config "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/config/swagger.config.js"
click node_logger_config "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/config/logger.config.js"
click node_async_handler "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/utils/asyncHandler.util.js"
click node_error_util "https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/utils/error.util.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_server,node_app toneBlue
class node_auth_route,node_gig_route,node_application_route,node_auth_mw,node_validator_mw,node_rate_limit_mw,node_error_mw,node_auth_controller,node_gig_controller,node_application_controller,node_auth_validator,node_gig_validator toneAmber
class node_user_service,node_gig_service,node_application_service,node_user_model,node_gig_model,node_application_model toneMint
class node_db_config,node_passport_config,node_swagger_config,node_logger_config,node_async_handler,node_error_util toneRose
```

## Components

### Bootstrap

Process startup and Express app assembly.

- [Server](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/server.js): runtime bootstrap · Starts the process, loads env, connects DB, and listens. · `server.js`
- [Express App](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/app.js): app assembly · Wires middleware, routes, docs, and error handling. · `app.js`

### API Layer

HTTP routing, middleware, controllers, and validation.

- [Auth Routes](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/routes/auth.route.js): http routes · Auth endpoints for login, register, refresh, Google callback, and profile completion. · `src/routes/auth.route.js`
- [Gig Routes](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/routes/gig.route.js): http routes · Gig browsing and business gig management endpoints. · `src/routes/gig.route.js`
- [Application Routes](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/routes/application.route.js): http routes · Student application submission and business review endpoints. · `src/routes/application.route.js`
- [Auth Guard](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/middlewares/auth.middleware.js): jwt middleware · Validates JWTs and attaches the authenticated user context. · `src/middlewares/auth.middleware.js`
- [Validator](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/middlewares/validator.middleware.js): schema middleware · Applies request schemas before controller logic runs. · `src/middlewares/validator.middleware.js`
- [Rate Limiter](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/middlewares/rateLimiter.middleware.js): throttle middleware · Constrains request volume at the edge of the API. · `src/middlewares/rateLimiter.middleware.js`
- [Error Middleware](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/middlewares/error.middleware.js): error handler · Converts thrown errors into consistent API responses. · `src/middlewares/error.middleware.js`
- [Auth Controller](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/controllers/auth.controller.js): http controller · Handles auth requests and response shaping. · `src/controllers/auth.controller.js`
- [Gig Controller](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/controllers/gig.controller.js): http controller · Handles gig request parsing and response formatting. · `src/controllers/gig.controller.js`
- [App Controller](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/controllers/application.controller.js): http controller · Handles application request parsing and response formatting. · `src/controllers/application.controller.js`
- [Auth Validator](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/validators/auth.validator.js): request schema · Validates auth and profile-completion payloads. · `src/validators/auth.validator.js`
- [Gig Validator](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/validators/gig.validator.js): request schema · Validates gig creation and update payloads. · `src/validators/gig.validator.js`

### Domain

Business services and MongoDB models.

- [User Service](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/services/user.service.js): account workflow · Coordinates user identity and onboarding-related persistence logic. · `src/services/user.service.js`
- [Gig Service](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/services/gig.service.js): business logic · Implements gig filtering, search, pagination, ownership, and writes. · `src/services/gig.service.js`
- [Application Service](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/services/application.service.js): workflow logic · Handles apply, review, accept/reject, and competing-application side effects. · `src/services/application.service.js`
- [User Model](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/models/user.model.js): mongoose model · Stores accounts, roles, onboarding, and provider metadata. · `src/models/user.model.js`
- [Gig Model](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/models/gig.model.js): mongoose model · Stores business job postings and queryable gig fields. · `src/models/gig.model.js`
- [Application Model](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/models/application.model.js): mongoose model · Stores student gig applications and enforces one-per-user-per-gig uniqueness. · `src/models/application.model.js`

### Infrastructure

Configuration, external integrations, and cross-cutting utilities.

- [Mongo Config](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/config/db.config.js): db connector · Creates and manages the MongoDB connection. · `src/config/db.config.js`
- [Passport Config](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/config/passport.config.js): oauth strategy · Configures Google OAuth strategy and callback behavior. · `src/config/passport.config.js`
- [Swagger Config](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/config/swagger.config.js): api docs · Builds the OpenAPI/Swagger surface exposed by the app. · `src/config/swagger.config.js`
- [Logger Config](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/config/logger.config.js): logging · Sets up structured application logging with Winston. · `src/config/logger.config.js`
- [Async Handler](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/utils/asyncHandler.util.js): utility · Wraps async handlers to avoid repetitive try/catch blocks. · `src/utils/asyncHandler.util.js`
- [App Error](https://github.com/rahulreddy006/local-freelance-job-board-backend/blob/main/src/utils/error.util.js): utility · Defines the custom error shape and status handling. · `src/utils/error.util.js`

## Connections

- Server → Express App: bootstraps · Starts the Express application after initialization.
- Server → Mongo Config: connects · Establishes the MongoDB connection during startup.
- Express App → Rate Limiter: uses · Applies throttling around incoming requests.
- Express App → Swagger Config: serves · Exposes API documentation at runtime.
- Express App → Error Middleware: terminates with · Centralizes error translation and response formatting.
- Express App → Auth Routes: mounts · Registers auth endpoints.
- Express App → Gig Routes: mounts · Registers gig endpoints.
- Express App → Application Routes: mounts · Registers application endpoints.
- Auth Routes → Auth Guard: protects · Applies JWT checks where needed.
- Gig Routes → Auth Guard: protects · Restricts business-only write operations.
- Application Routes → Auth Guard: protects · Requires authentication for application workflows.
- Auth Routes → Validator: validates · Runs auth request schema checks.
- Gig Routes → Validator: validates · Runs gig request schema checks.
- Application Routes → Validator: validates · Checks application payloads before handlers.
- Auth Routes → Auth Controller: dispatches · Sends auth requests to controller actions.
- Gig Routes → Gig Controller: dispatches · Sends gig requests to controller actions.
- Application Routes → App Controller: dispatches · Sends application requests to controller actions.
- Auth Controller → Async Handler: wraps · Uses async wrapper for controller errors.
- Gig Controller → Async Handler: wraps · Uses async wrapper for controller errors.
- App Controller → Async Handler: wraps · Uses async wrapper for controller errors.
- Auth Controller → User Service: delegates to · Hands off auth and onboarding workflows.
- Gig Controller → Gig Service: delegates to · Hands off gig business operations.
- App Controller → Application Service: delegates to · Hands off application workflow operations.
- Auth Controller → Auth Validator: uses · Validates auth payloads.
- Gig Controller → Gig Validator: uses · Validates gig payloads.
- User Service → User Model: persists to · Reads and writes user records in MongoDB.
- Gig Service → Gig Model: persists to · Reads and writes gig records in MongoDB.
- Application Service → Application Model: persists to · Reads and writes application records in MongoDB.
- Application Service → Gig Model: checks · Uses gig ownership and gig state in workflow decisions.
- Auth Controller → Passport Config: integrates · Uses Google OAuth callback flow.
- User Service → Passport Config: supports · Persists OAuth-linked account metadata.
- Auth Guard → App Error: throws · Uses custom errors for auth failures.
- Validator → App Error: throws · Uses custom errors for validation failures.
- Gig Service → App Error: throws · Uses custom errors for business rule failures.
- Application Service → App Error: throws · Uses custom errors for workflow failures.
- Express App → Logger Config: uses · Initializes structured logging for the runtime.
