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

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

---

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

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

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.

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

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.