backend-setup

name	backend-setup
description	Express server scaffolding, plugin architecture, middleware patterns for Resource-Adda. Use when starting backend development, adding middleware, troubleshooting server startup, or creating new plugin modules.

Backend Setup

When to Use

• Starting backend development or adding a new module
• Adding Express middleware
• Troubleshooting server startup
• Understanding the plugin architecture

Procedure

Phase 1: Project Structure

The backend lives in /backend/src/:

backend/src/
├── index.js              # Entry point — connectDB → createApp → startServer
├── app.js                # Express app, middleware + plugin loading
├── server.js             # HTTP server with graceful shutdown
├── plugin-loader.js      # Scans /apps/ and calls init() on each module
├── auth/
│   └── jwt-authenticator.js
├── middleware/
│   ├── auth.js           # JWT verification, public route whitelist
│   ├── permissions.js    # requireRoles() RBAC middleware
│   ├── logger.js         # Request logging with trace IDs
│   └── error.js          # Error handler + 404 handler
├── database/
│   ├── connection.js     # Mongoose connect/disconnect/healthCheck
│   └── schemas/          # Mongoose models
└── utils/
    └── registry.js       # ModuleRegistry — service locator

Phase 2: Creating a New Module

1. Create directory: apps/<module-name>/src/
2. Create entry file (src/index.js or plugin.js):

export async function init(app, registry) {
  const requireRoles = registry.getService("requireRoles");
  // Register routes
  app.get("/api/v1/my-resource", controller.list);
  app.post(
    "/api/v1/my-resource",
    requireRoles("admin", "coordinator"),
    controller.create,
  );
  // Register module
  registry.registerModule("my-module", { routes: ["/api/v1/my-resource"] });
}

3. Create module structure:

apps/<module>/src/
├── index.js          # Plugin entry (exports init)
├── controller/       # Thin HTTP handlers
├── routes/           # Express route definitions
├── schema/           # Mongoose models
└── service/          # Business logic
    ├── module.service.js
    └── module.service.test.js

Phase 3: Startup Flow

index.js → connectDB() → createApp(registry) → startServer(app, 4000)

• MongoDB must be running before startup
• Plugin loader scans /apps/ for plugin.js or src/index.js
• Failed plugins log errors but don't crash (dev mode)

Phase 4: Middleware Order (in app.js)

Body parsing → CORS → Logger → Health check → Auth → Plugin routes → 404 → Error handler

This order is critical. Auth must come before plugin routes.

Quick Reference

cd backend && pnpm install
pnpm dev              # Start with --watch (port 4000)
curl http://localhost:4000/health   # Test health

Common Issues

Issue	Solution
Plugin not loading	Check entry file exports init() — must be plugin.js or src/index.js
MongoDB connection failed	Ensure MongoDB is running: docker start mongodb
Port in use	Backend uses port 4000, check PORT env var
Services not found	Use registry.getService('name') — not direct imports
Module imports another module	Use registry or shared DB — never direct imports