opencode-agent-kit
Version:
Multi-stack OpenCode agent toolkit — 33+ specialized AI agents, 200+ skills, 46 commands, 8 MCP servers (Nuxt, React, Node.js, Laravel, CI3, Android, Flutter, DevOps, SEO, SonarQube, and more)
83 lines (59 loc) • 2.79 kB
Markdown
# Backend Patterns (Enterprise, Portable)
Use these patterns as baseline across backend services with Node.js + TypeScript + Express + Prisma.
## Standard Module Layout
- Controllers: request orchestration and response mapping
- Routes: endpoint registration and middleware chain
- DTOs: request validation and response exposure contracts
- Middlewares: auth, validation, upload, limiter, etc.
- Utilities/services: reusable domain/business logic
## DTO Conventions
- Request DTO suffix: `*.dto.ts`
- Response DTO suffix: `*.response.dto.ts`
- Explicit field exposure with `@Expose()`
- Route-level validation middleware uses request DTO class
- Response serialization maps through response DTO with extraneous field exclusion
Example mapping:
```ts
const result = plainToInstance(ResponseDTO, payload, {
excludeExtraneousValues: true,
});
```
## API Response Conventions
- Use one centralized response helper for success and error envelopes
- Keep status/message/data structure consistent across endpoints
- Avoid ad-hoc response shapes in controllers
## Error Handling Conventions
- Wrap controller logic in try/catch
- Delegate catch to centralized error handler
- Provide predictable business error mappings
- Log unexpected errors once, near boundary layer
## Route and Middleware Conventions
- Register specific paths before parameterized paths
- Place auth middleware before validation and handler
- Keep middleware order deterministic and explicit
- For multipart endpoints, apply upload middleware before DTO validation when needed
## Data Access Conventions
- Use transactions for multi-step state mutations
- Keep write paths idempotent where practical (especially webhook/event handlers)
- Query only fields/relations needed for output
- Maintain tenant/ownership scoping where service model requires it
## Security Conventions
- Validate all external input via DTOs
- Enforce auth and resource-level authorization consistently
- Keep error responses safe (no stack traces/internal details)
- Restrict upload MIME types, size, and destination path
- Never leak secret values in logs or API responses
## Pagination and List Conventions
- Normalize paging params and cap upper bounds
- Apply filters and sorting through deterministic query builder logic
- Return pagination metadata alongside items
## Mutation Conventions
- Validate request payload and preconditions first
- Apply domain mutation in transaction
- Emit domain/audit log entries for critical operations
- Return mapped response DTO from committed state
## Test and Verification Conventions
- Tiny changes: one focused check
- Small changes: type-check plus one targeted check
- Medium+ changes: type-check, lint, and relevant tests
- Contract changes: include endpoint behavior validation