backend-dev-guidelines

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 |

---

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

---

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

```ts

// ❌ 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`

```ts

export class UserController extends BaseController {

async getUser(req: Request, res: Response): Promise {

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

```ts

catch (error) {

Sentry.captureException(error);

throw error;

}

```

❌ console.log

❌ silent failures

❌ swallowed errors

---

6. unifiedConfig Is the Only Config Source

```ts

// ❌ 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

```ts

const schema = z.object({

email: z.string().email(),

});

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

```

No validation = bug.

---

```

src/

├── config/ # unifiedConfig

├── controllers/ # BaseController + controllers

├── services/ # Business logic

├── repositories/ # Prisma access

├── routes/ # Express routes

├── middleware/ # Auth, validation, errors

├── validators/ # Zod schemas

├── types/ # Shared types

├── utils/ # Helpers

├── tests/ # Unit + integration tests

├── instrument.ts # Sentry (FIRST IMPORT)

├── app.ts # Express app

└── server.ts # HTTP server

```

---

| Layer | Convention |

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

| Controller | PascalCaseController.ts |

| Service | camelCaseService.ts |

| Repository | PascalCaseRepository.ts |

| Routes | camelCaseRoutes.ts |

| Validators | camelCase.schema.ts |

---

• Services receive dependencies via constructor
• No importing repositories directly inside controllers
• Enables mocking and testing

```ts

export class UserService {

constructor(

private readonly userRepository: UserRepository

) {}

}

```

---

• Prisma client never used directly in controllers
• Repositories:

* Encapsulate queries

* Handle transactions

* Expose intent-based methods

```ts

await userRepository.findActiveUsers();

```

---

asyncErrorWrapper Required

All async route handlers must be wrapped.

```ts

router.get(

'/users',

asyncErrorWrapper((req, res) =>

controller.list(req, res)

)

);

```

No unhandled promise rejections.

---

Required

• Sentry error tracking
• Sentry performance tracing
• Structured logs (where applicable)

Every critical path must be observable.

---

Required Tests

• Unit tests for services
• Integration tests for routes
• Repository tests for complex queries

```ts

describe('UserService', () => {

it('creates a user', async () => {

expect(user).toBeDefined();

});

});

```

No tests → no merge.

---

❌ Business logic in routes

❌ Skipping service layer

❌ Direct Prisma in controllers

❌ Missing validation

❌ process.env usage

❌ console.log instead of Sentry

❌ Untested business logic

---

• frontend-dev-guidelines → API contract alignment
• error-tracking → Sentry standards
• database-verification → Schema correctness
• analytics-tracking → Event pipelines
• skill-developer → Skill governance

---

Before finalizing backend work:

• [ ] BFRI ≥ 3
• [ ] Layered architecture respected
• [ ] Input validated
• [ ] Errors captured in Sentry
• [ ] unifiedConfig used
• [ ] Tests written
• [ ] No anti-patterns present

---

Status: Stable · Enforceable · Production-grade

Intended Use: Long-lived Node.js microservices with real traffic and real risk

---