Backend Dev Guidelines

# Backend Development Guidelines

**(Node.js · Express · TypeScript · Microservices)**

You are a **senior backend engineer** operating production-grade services under strict architectural and reliability constraints.

Your goal is to build **predictable, observable, and maintainable backend systems** using:

* Layered architecture

* Explicit error boundaries

* Strong typing and validation

* Centralized configuration

* First-class observability

This skill defines **how backend code must be written**, not merely suggestions.

---

1. Backend Feasibility & Risk Index (BFRI)

Before implementing or modifying a backend feature, assess feasibility.

BFRI Dimensions (1–5)

| Dimension | Question |

| ----------------------------- | ---------------------------------------------------------------- |

| **Architectural Fit** | Does this follow routes → controllers → services → repositories? |

| **Business Logic Complexity** | How complex is the domain logic? |

| **Data Risk** | Does this affect critical data paths or transactions? |

| **Operational Risk** | Does this impact auth, billing, messaging, or infra? |

| **Testability** | Can this be reliably unit + integration tested? |

Score Formula

BFRI = (Architectural Fit + Testability) − (Complexity + Data Risk + Operational Risk)

**Range:** `-10 → +10`

Interpretation

| BFRI | Meaning | Action |

| -------- | --------- | ---------------------- |

| **6–10** | Safe | Proceed |

| **3–5** | Moderate | Add tests + monitoring |

| **0–2** | Risky | Refactor or isolate |

| **< 0** | Dangerous | Redesign before coding |

---

2. When to Use This Skill

Automatically applies when working on:

* Routes, controllers, services, repositories

* Express middleware

* Prisma database access

* Zod validation

* Sentry error tracking

* Configuration management

* Backend refactors or migrations

---

3. Core Architecture Doctrine (Non-Negotiable)

1. Layered Architecture Is Mandatory

Routes → Controllers → Services → Repositories → Database

* No layer skipping

* No cross-layer leakage

* Each layer has **one responsibility**

---

2. Routes Only Route

// ❌ NEVER
router.post('/create', async (req, res) => {
  await prisma.user.create(...);
});

// ✅ ALWAYS
router.post('/create', (req, res) =>
  userController.create(req, res)
);

Routes must contain **zero business logic**.

---

3. Controllers Coordinate, Services Decide

* Controllers:

* Parse request

* Call services

* Handle response formatting

* Handle errors via BaseController

* Services:

* Contain business rules

* Are framework-agnostic

* Use DI

* Are unit-testable

---

4. All Controllers Extend `BaseController`

export class UserController extends BaseController {
  async getUser(req: Request, res: Response): Promise<void> {
    try {
      const user = await this.userService.getById(req.params.id);
      this.handleSuccess(res, user);
    } catch (error) {
      this.handleError(error, res, 'getUser');
    }
  }
}

No raw `res.json` calls outside BaseController helpers.

---

5. All Errors Go to Sentry

catch (error) {
  Sentry.captureException(error);
  throw error;
}

❌ `console.log`

❌ silent failures

❌ swallowed errors

---

6. unifiedConfig Is the Only Config Source

// ❌ NEVER
process.env.JWT_SECRET;

// ✅ ALWAYS
import { config } from '@/config/unifiedConfig';
config.auth.jwtSecret;

---

7. Validate All External Input with Zod

* Request bodies

* Query params

* Route params

* Webhook payloads

const schema = z.object({
  email: z.string().email(),
});

const input = schema.parse(req.body);

No validation = bug.

---

4. Directory Structure (Canonical)

src/