cc-devflow 1.0.1

package/.claude/skills/_reference-implementations/backend-express-prisma/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: backend-dev-guidelines
+description: Comprehensive backend development guide for Node.js/Express/TypeScript microservices. Use when creating routes, controllers, services, repositories, middleware, or working with Express APIs, Prisma database access, Sentry error tracking, Zod validation, unifiedConfig, dependency injection, or async patterns. Covers layered architecture (routes → controllers → services → repositories), BaseController pattern, error handling, performance monitoring, testing strategies, and migration from legacy patterns.
+---
+
+# Backend Development Guidelines
+
+## Purpose
+
+Establish consistency and best practices across backend microservices (blog-api, auth-service, notifications-service) using modern Node.js/Express/TypeScript patterns.
+
+## When to Use This Skill
+
+Automatically activates when working on:
+- Creating or modifying routes, endpoints, APIs
+- Building controllers, services, repositories
+- Implementing middleware (auth, validation, error handling)
+- Database operations with Prisma
+- Error tracking with Sentry
+- Input validation with Zod
+- Configuration management
+- Backend testing and refactoring
+
+---
+
+## Quick Start
+
+### New Backend Feature Checklist
+
+- [ ] **Route**: Clean definition, delegate to controller
+- [ ] **Controller**: Extend BaseController
+- [ ] **Service**: Business logic with DI
+- [ ] **Repository**: Database access (if complex)
+- [ ] **Validation**: Zod schema
+- [ ] **Sentry**: Error tracking
+- [ ] **Tests**: Unit + integration tests
+- [ ] **Config**: Use unifiedConfig
+
+### New Microservice Checklist
+
+- [ ] Directory structure (see [architecture-overview.md](architecture-overview.md))
+- [ ] instrument.ts for Sentry
+- [ ] unifiedConfig setup
+- [ ] BaseController class
+- [ ] Middleware stack
+- [ ] Error boundary
+- [ ] Testing framework
+
+---
+
+## Architecture Overview
+
+### Layered Architecture
+
+```
+HTTP Request
+    ↓
+Routes (routing only)
+    ↓
+Controllers (request handling)
+    ↓
+Services (business logic)
+    ↓
+Repositories (data access)
+    ↓
+Database (Prisma)
+```
+
+**Key Principle:** Each layer has ONE responsibility.
+
+See [architecture-overview.md](architecture-overview.md) for complete details.
+
+---
+
+## Directory Structure
+
+```
+service/src/
+├── config/              # UnifiedConfig
+├── controllers/         # Request handlers
+├── services/            # Business logic
+├── repositories/        # Data access
+├── routes/              # Route definitions
+├── middleware/          # Express middleware
+├── types/               # TypeScript types
+├── validators/          # Zod schemas
+├── utils/               # Utilities
+├── tests/               # Tests
+├── instrument.ts        # Sentry (FIRST IMPORT)
+├── app.ts               # Express setup
+└── server.ts            # HTTP server
+```
+
+**Naming Conventions:**
+- Controllers: `PascalCase` - `UserController.ts`
+- Services: `camelCase` - `userService.ts`
+- Routes: `camelCase + Routes` - `userRoutes.ts`
+- Repositories: `PascalCase + Repository` - `UserRepository.ts`
+
+---
+
+## Core Principles (7 Key Rules)
+
+### 1. Routes Only Route, Controllers Control
+
+```typescript
+// ❌ NEVER: Business logic in routes
+router.post('/submit', async (req, res) => {
+    // 200 lines of logic
+});
+
+// ✅ ALWAYS: Delegate to controller
+router.post('/submit', (req, res) => controller.submit(req, res));
+```
+
+### 2. All Controllers Extend BaseController
+
+```typescript
+export class UserController extends BaseController {
+    async getUser(req: Request, res: Response): Promise<void> {
+        try {
+            const user = await this.userService.findById(req.params.id);
+            this.handleSuccess(res, user);
+        } catch (error) {
+            this.handleError(error, res, 'getUser');
+        }
+    }
+}
+```
+
+### 3. All Errors to Sentry
+
+```typescript
+try {
+    await operation();
+} catch (error) {
+    Sentry.captureException(error);
+    throw error;
+}
+```
+
+### 4. Use unifiedConfig, NEVER process.env
+
+```typescript
+// ❌ NEVER
+const timeout = process.env.TIMEOUT_MS;
+
+// ✅ ALWAYS
+import { config } from './config/unifiedConfig';
+const timeout = config.timeouts.default;
+```
+
+### 5. Validate All Input with Zod
+
+```typescript
+const schema = z.object({ email: z.string().email() });
+const validated = schema.parse(req.body);
+```
+
+### 6. Use Repository Pattern for Data Access
+
+```typescript
+// Service → Repository → Database
+const users = await userRepository.findActive();
+```
+
+### 7. Comprehensive Testing Required
+
+```typescript
+describe('UserService', () => {
+    it('should create user', async () => {
+        expect(user).toBeDefined();
+    });
+});
+```
+
+---
+
+## Common Imports
+
+```typescript
+// Express
+import express, { Request, Response, NextFunction, Router } from 'express';
+
+// Validation
+import { z } from 'zod';
+
+// Database
+import { PrismaClient } from '@prisma/client';
+import type { Prisma } from '@prisma/client';
+
+// Sentry
+import * as Sentry from '@sentry/node';
+
+// Config
+import { config } from './config/unifiedConfig';
+
+// Middleware
+import { SSOMiddlewareClient } from './middleware/SSOMiddleware';
+import { asyncErrorWrapper } from './middleware/errorBoundary';
+```
+
+---
+
+## Quick Reference
+
+### HTTP Status Codes
+
+| Code | Use Case |
+|------|----------|
+| 200 | Success |
+| 201 | Created |
+| 400 | Bad Request |
+| 401 | Unauthorized |
+| 403 | Forbidden |
+| 404 | Not Found |
+| 500 | Server Error |
+
+### Service Templates
+
+**Blog API** (✅ Mature) - Use as template for REST APIs
+**Auth Service** (✅ Mature) - Use as template for authentication patterns
+
+---
+
+## Anti-Patterns to Avoid
+
+❌ Business logic in routes
+❌ Direct process.env usage
+❌ Missing error handling
+❌ No input validation
+❌ Direct Prisma everywhere
+❌ console.log instead of Sentry
+
+---
+
+## Navigation Guide
+
+| Need to... | Read this |
+|------------|-----------|
+| Understand architecture | [architecture-overview.md](architecture-overview.md) |
+| Create routes/controllers | [routing-and-controllers.md](routing-and-controllers.md) |
+| Organize business logic | [services-and-repositories.md](services-and-repositories.md) |
+| Validate input | [validation-patterns.md](validation-patterns.md) |
+| Add error tracking | [sentry-and-monitoring.md](sentry-and-monitoring.md) |
+| Create middleware | [middleware-guide.md](middleware-guide.md) |
+| Database access | [database-patterns.md](database-patterns.md) |
+| Manage config | [configuration.md](configuration.md) |
+| Handle async/errors | [async-and-errors.md](async-and-errors.md) |
+| Write tests | [testing-guide.md](testing-guide.md) |
+| See examples | [complete-examples.md](complete-examples.md) |
+
+---
+
+## Resource Files
+
+### [architecture-overview.md](architecture-overview.md)
+Layered architecture, request lifecycle, separation of concerns
+
+### [routing-and-controllers.md](routing-and-controllers.md)
+Route definitions, BaseController, error handling, examples
+
+### [services-and-repositories.md](services-and-repositories.md)
+Service patterns, DI, repository pattern, caching
+
+### [validation-patterns.md](validation-patterns.md)
+Zod schemas, validation, DTO pattern
+
+### [sentry-and-monitoring.md](sentry-and-monitoring.md)
+Sentry init, error capture, performance monitoring
+
+### [middleware-guide.md](middleware-guide.md)
+Auth, audit, error boundaries, AsyncLocalStorage
+
+### [database-patterns.md](database-patterns.md)
+PrismaService, repositories, transactions, optimization
+
+### [configuration.md](configuration.md)
+UnifiedConfig, environment configs, secrets
+
+### [async-and-errors.md](async-and-errors.md)
+Async patterns, custom errors, asyncErrorWrapper
+
+### [testing-guide.md](testing-guide.md)
+Unit/integration tests, mocking, coverage
+
+### [complete-examples.md](complete-examples.md)
+Full examples, refactoring guide
+
+---
+
+## Related Skills
+
+- **database-verification** - Verify column names and schema consistency
+- **error-tracking** - Sentry integration patterns
+- **skill-developer** - Meta-skill for creating and managing skills
+
+---
+
+**Skill Status**: COMPLETE ✅
+**Line Count**: < 500 ✅
+**Progressive Disclosure**: 11 resource files ✅