plcode-darwin-x64 2.1.0

package/.plcode/skill/core/backend-dev-guidelines/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: backend-dev-guidelines
+description: "Opinionated backend development standards for Node.js + Express + TypeScript microservices. Covers layered architecture, BaseController pattern, dependency injection, Prisma repositories, Zod valid..."
+category: backend
+risk: unknown
+source: community
+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
+
+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
+
+```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. 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.
+
+---
+
+## 4. 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
+```
+
+---
+
+## 5. Naming Conventions (Strict)
+
+| Layer      | Convention                |
+| ---------- | ------------------------- |
+| Controller | `PascalCaseController.ts` |
+| Service    | `camelCaseService.ts`     |
+| Repository | `PascalCaseRepository.ts` |
+| Routes     | `camelCaseRoutes.ts`      |
+| Validators | `camelCase.schema.ts`     |
+
+---
+
+## 6. 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) {}
+}
+```
+
+---
+
+## 7. Prisma & Repository Rules
+
+- Prisma client **never used directly in controllers**
+- Repositories:
+  - Encapsulate queries
+  - Handle transactions
+  - Expose intent-based methods
+
+```ts
+await userRepository.findActiveUsers()
+```
+
+---
+
+## 8. Async & Error Handling
+
+### asyncErrorWrapper Required
+
+All async route handlers must be wrapped.
+
+```ts
+router.get(
+  "/users",
+  asyncErrorWrapper((req, res) => controller.list(req, res)),
+)
+```
+
+No unhandled promise rejections.
+
+---
+
+## 9. Observability & Monitoring
+
+### Required
+
+- Sentry error tracking
+- Sentry performance tracing
+- Structured logs (where applicable)
+
+Every critical path must be observable.
+
+---
+
+## 10. 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.
+
+---
+
+## 11. Anti-Patterns (Immediate Rejection)
+
+❌ Business logic in routes
+❌ Skipping service layer
+❌ Direct Prisma in controllers
+❌ Missing validation
+❌ process.env usage
+❌ console.log instead of Sentry
+❌ Untested business logic
+
+---
+
+## 12. 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
+
+---
+
+## 13. Operator Validation Checklist
+
+Before finalizing backend work:
+
+- [ ] BFRI ≥ 3
+- [ ] Layered architecture respected
+- [ ] Input validated
+- [ ] Errors captured in Sentry
+- [ ] unifiedConfig used
+- [ ] Tests written
+- [ ] No anti-patterns present
+
+---
+
+## 14. Skill Status
+
+**Status:** Stable · Enforceable · Production-grade
+**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.