sickn33/agentic-awesome-skills / plugins/aasb-aas-api-platform-builder/skills/backend-dev-guidelines
backend-dev-guidelines
VerifiedYou are a senior backend engineer operating production-grade services under strict architectural and reliability constraints. Use when routes, controllers, services, repositories, express middleware, or prisma database access.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.9 KB |
| resources/architecture-overview.md | markdown | 13.3 KB |
| resources/async-and-errors.md | markdown | 7.8 KB |
| resources/complete-examples.md | markdown | 17.6 KB |
| resources/configuration.md | markdown | 7.0 KB |
| resources/database-patterns.md | markdown | 5.8 KB |
| resources/middleware-guide.md | markdown | 6.2 KB |
| resources/routing-and-controllers.md | markdown | 20.8 KB |
| resources/sentry-and-monitoring.md | markdown | 7.4 KB |
| resources/services-and-repositories.md | markdown | 23.2 KB |
| resources/testing-guide.md | markdown | 6.1 KB |
| resources/validation-patterns.md | markdown | 18.4 KB |
SKILL.md
View on GitHub---
name: backend-dev-guidelines
description: You are a senior backend engineer operating production-grade services under strict architectural and reliability constraints. Use when routes, controllers, services, repositories, express middleware, or prisma database access.
metadata:
aas-risk: critical
aas-source: community
aas-date-added: '2026-02-27'
---
# 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
Use these patterns when they fit the target repository; its architecture, authorization model and dependency versions take precedence. This documentation does not ship a runnable service.
---
## 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:** `-13 → +7` (each input is 1–5). This is an informal discussion aid, not a validated risk model or merge gate.
### Interpretation
| BFRI | Meaning | Action |
| -------- | --------- | ---------------------- |
| **6–7** | Lower concern | Proceed |
| **3–5** | Moderate | Add tests + monitoring |
| **0–2** | Risky | Refactor or isolate |
| **< 0** | Dangerous | Redesign before coding |
---
## When to Use
Automatically applies when working on:
* Routes, controllers, services, repositories
* Express middleware
* Prisma database access
* Zod validation
* Approved error tracking with redaction and destination/retention controls
* Configuration management
* Backend refactors or migrations
---
## 2. Architecture Pattern (When Adopted by the Repository)
### 1. Layered Architecture Option
```
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<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. Capture Unexpected Errors at One Approved Boundary
```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.
---
## 3. Directory Structure (Canonical)
```
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
```
---
## 4. Naming Conventions (Strict)
| Layer | Convention |
| ---------- | ------------------------- |
| Controller | `PascalCaseController.ts` |
| Service | `camelCaseService.ts` |
| Repository | `PascalCaseRepository.ts` |
| Routes | `camelCaseRoutes.ts` |
| Validators | `camelCase.schema.ts` |
---
## 5. Dependency Injection Rules
* Services receive dependencies via constructor
* No importing repositories directly inside controllers
* Enables mocking and testing
```ts
export class UserService {
constructor(
private readonly userRepository: UserRepository
) {}
}
```
---
## 6. Prisma & Repository Rules
* Prisma client **never used directly in controllers**
* Repositories:
* Encapsulate queries
* Handle transactions
* Expose intent-based methods
```ts
await userRepository.findActiveUsers();
```
---
## 7. Async & Error Handling
### asyncErrorWrapper Required
For Express 4, route promises need an error-forwarding wrapper. Express 5 forwards rejected returned promises; avoid duplicate handlers.
```ts
router.get(
'/users',
asyncErrorWrapper((req, res) =>
controller.list(req, res)
)
);
```
Return or await the handler promise; a wrapper does not handle detached background work.
---
## 8. Observability & Monitoring
### Required
* Approved error tracking with redaction and destination/retention controls
* Sampled performance tracing appropriate to the installed SDK
* Structured logs (where applicable)
Every critical path must be observable.
---
## 9. Testing Discipline
### 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.
---
## 10. Review Signals
❌ Business logic in routes
❌ Skipping service layer
❌ Direct Prisma in controllers
❌ Missing validation
❌ Unvalidated environment access outside configuration bootstrap
❌ Unredacted or unapproved telemetry
❌ Untested business logic
---
## Resource Guide
Read the relevant bundled resources before applying examples. Private project paths and `@project-lifecycle-portal/database`, `SSOMiddleware`, `BaseController` and configuration utilities are illustrative application components, not installed dependencies. Authenticate with access tokens, authorize every object/tenant action, allowlist public DTO fields, project response fields and protect cookie-authenticated mutations against CSRF.
## 11. Integration With Other Skills
* **frontend-dev-guidelines** → API contract alignment
* **error-tracking** → Sentry standards
* **database-verification** → Schema correctness
* **analytics-tracking** → Event pipelines
* **skill-developer** → Skill governance
---
## 12. Operator Validation Checklist
Before finalizing backend work:
* [ ] Risks discussed with evidence; no numeric score grants approval
* [ ] Layered architecture respected
* [ ] Input validated
* [ ] Errors captured in Sentry
* [ ] unifiedConfig used
* [ ] Tests written
* [ ] No anti-patterns present
---
## 13. Skill Status
**Status:** Illustrative patterns; target-specific compilation, tests and security review required
**Intended Use:** Long-lived Node.js microservices with real traffic and real risk
---
### When to Use
This skill is applicable to execute the workflow or actions described in the overview.
## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |