How rahulreddy006/local-freelance-job-board-backend works
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 Express App · auth.controller.js Auth Controller · auth.route.js Auth Routes · gig.route.js Gig Routes
Components 26
Bootstrap
Process startup and Express app assembly.
- Server · Starts the process, loads env, connects DB, and listens.
server.js - Express App · Wires middleware, routes, docs, and error handling.
app.js
API Layer
HTTP routing, middleware, controllers, and validation.
- Auth Routes · Auth endpoints for login, register, refresh, Google callback, and profile completion.
src/routes/auth.route.js - Gig Routes · Gig browsing and business gig management endpoints.
src/routes/gig.route.js - Application Routes · Student application submission and business review endpoints.
src/routes/application.route.js - Auth Guard · Validates JWTs and attaches the authenticated user context.
src/middlewares/auth.middleware.js - Validator · Applies request schemas before controller logic runs.
src/middlewares/validator.middleware.js - Rate Limiter · Constrains request volume at the edge of the API.
src/middlewares/rateLimiter.middleware.js - Error Middleware · Converts thrown errors into consistent API responses.
src/middlewares/error.middleware.js - Auth Controller · Handles auth requests and response shaping.
src/controllers/auth.controller.js - Gig Controller · Handles gig request parsing and response formatting.
src/controllers/gig.controller.js - App Controller · Handles application request parsing and response formatting.
src/controllers/application.controller.js - Auth Validator · Validates auth and profile-completion payloads.
src/validators/auth.validator.js - Gig Validator · Validates gig creation and update payloads.
src/validators/gig.validator.js
Domain
Business services and MongoDB models.
- User Service · Coordinates user identity and onboarding-related persistence logic.
src/services/user.service.js - Gig Service · Implements gig filtering, search, pagination, ownership, and writes.
src/services/gig.service.js - Application Service · Handles apply, review, accept/reject, and competing-application side effects.
src/services/application.service.js - User Model · Stores accounts, roles, onboarding, and provider metadata.
src/models/user.model.js - Gig Model · Stores business job postings and queryable gig fields.
src/models/gig.model.js - Application 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 · Creates and manages the MongoDB connection.
src/config/db.config.js - Passport Config · Configures Google OAuth strategy and callback behavior.
src/config/passport.config.js - Swagger Config · Builds the OpenAPI/Swagger surface exposed by the app.
src/config/swagger.config.js - Logger Config · Sets up structured application logging with Winston.
src/config/logger.config.js - Async Handler · Wraps async handlers to avoid repetitive try/catch blocks.
src/utils/asyncHandler.util.js - App Error · Defines the custom error shape and status handling.
src/utils/error.util.js
Connections 36
- 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.