cc-devflow 4.3.0 → 4.5.0

package/.claude/skills/_reference-implementations/backend-express-prisma/resources/architecture-overview.md

@@ -1,451 +0,0 @@
-# Architecture Overview - Backend Services
-
-Complete guide to the layered architecture pattern used in backend microservices.
-
-## Table of Contents
-
-- [Layered Architecture Pattern](#layered-architecture-pattern)
-- [Request Lifecycle](#request-lifecycle)
-- [Service Comparison](#service-comparison)
-- [Directory Structure Rationale](#directory-structure-rationale)
-- [Module Organization](#module-organization)
-- [Separation of Concerns](#separation-of-concerns)
-
----
-
-## Layered Architecture Pattern
-
-### The Four Layers
-
-```
-┌─────────────────────────────────────┐
-│         HTTP Request                │
-└───────────────┬─────────────────────┘
-                ↓
-┌─────────────────────────────────────┐
-│  Layer 1: ROUTES                    │
-│  - Route definitions only           │
-│  - Middleware registration          │
-│  - Delegate to controllers          │
-│  - NO business logic                │
-└───────────────┬─────────────────────┘
-                ↓
-┌─────────────────────────────────────┐
-│  Layer 2: CONTROLLERS               │
-│  - Request/response handling        │
-│  - Input validation                 │
-│  - Call services                    │
-│  - Format responses                 │
-│  - Error handling                   │
-└───────────────┬─────────────────────┘
-                ↓
-┌─────────────────────────────────────┐
-│  Layer 3: SERVICES                  │
-│  - Business logic                   │
-│  - Orchestration                    │
-│  - Call repositories                │
-│  - No HTTP knowledge                │
-└───────────────┬─────────────────────┘
-                ↓
-┌─────────────────────────────────────┐
-│  Layer 4: REPOSITORIES              │
-│  - Data access abstraction          │
-│  - Prisma operations                │
-│  - Query optimization               │
-│  - Caching                          │
-└───────────────┬─────────────────────┘
-                ↓
-┌─────────────────────────────────────┐
-│         Database (MySQL)            │
-└─────────────────────────────────────┘
-```
-
-### Why This Architecture?
-
-**Testability:**
-- Each layer can be tested independently
-- Easy to mock dependencies
-- Clear test boundaries
-
-**Maintainability:**
-- Changes isolated to specific layers
-- Business logic separate from HTTP concerns
-- Easy to locate bugs
-
-**Reusability:**
-- Services can be used by routes, cron jobs, scripts
-- Repositories hide database implementation
-- Business logic not tied to HTTP
-
-**Scalability:**
-- Easy to add new endpoints
-- Clear patterns to follow
-- Consistent structure
-
----
-
-## Request Lifecycle
-
-### Complete Flow Example
-
-```typescript
-1. HTTP POST /api/users
-   ↓
-2. Express matches route in userRoutes.ts
-   ↓
-3. Middleware chain executes:
-   - SSOMiddleware.verifyLoginStatus (authentication)
-   - auditMiddleware (context tracking)
-   ↓
-4. Route handler delegates to controller:
-   router.post('/users', (req, res) => userController.create(req, res))
-   ↓
-5. Controller validates and calls service:
-   - Validate input with Zod
-   - Call userService.create(data)
-   - Handle success/error
-   ↓
-6. Service executes business logic:
-   - Check business rules
-   - Call userRepository.create(data)
-   - Return result
-   ↓
-7. Repository performs database operation:
-   - PrismaService.main.user.create({ data })
-   - Handle database errors
-   - Return created user
-   ↓
-8. Response flows back:
-   Repository → Service → Controller → Express → Client
-```
-
-### Middleware Execution Order
-
-**Critical:** Middleware executes in registration order
-
-```typescript
-app.use(Sentry.Handlers.requestHandler());  // 1. Sentry tracing (FIRST)
-app.use(express.json());                     // 2. Body parsing
-app.use(express.urlencoded({ extended: true })); // 3. URL encoding
-app.use(cookieParser());                     // 4. Cookie parsing
-app.use(SSOMiddleware.initialize());         // 5. Auth initialization
-// ... routes registered here
-app.use(auditMiddleware);                    // 6. Audit (if global)
-app.use(errorBoundary);                      // 7. Error handler (LAST)
-app.use(Sentry.Handlers.errorHandler());     // 8. Sentry errors (LAST)
-```
-
-**Rule:** Error handlers must be registered AFTER routes!
-
----
-
-## Service Comparison
-
-### Email Service (Mature Pattern ✅)
-
-**Strengths:**
-- Comprehensive BaseController with Sentry integration
-- Clean route delegation (no business logic in routes)
-- Consistent dependency injection pattern
-- Good middleware organization
-- Type-safe throughout
-- Excellent error handling
-
-**Example Structure:**
-```
-email/src/
-├── controllers/
-│   ├── BaseController.ts          ✅ Excellent template
-│   ├── NotificationController.ts  ✅ Extends BaseController
-│   └── EmailController.ts         ✅ Clean patterns
-├── routes/
-│   ├── notificationRoutes.ts      ✅ Clean delegation
-│   └── emailRoutes.ts             ✅ No business logic
-├── services/
-│   ├── NotificationService.ts     ✅ Dependency injection
-│   └── BatchingService.ts         ✅ Clear responsibility
-└── middleware/
-    ├── errorBoundary.ts           ✅ Comprehensive
-    └── DevImpersonationSSOMiddleware.ts
-```
-
-**Use as template** for new services!
-
-### Form Service (Transitioning ⚠️)
-
-**Strengths:**
-- Excellent workflow architecture (event sourcing)
-- Good Sentry integration
-- Innovative audit middleware (AsyncLocalStorage)
-- Comprehensive permission system
-
-**Weaknesses:**
-- Some routes have 200+ lines of business logic
-- Inconsistent controller naming
-- Direct process.env usage (60+ occurrences)
-- Minimal repository pattern usage
-
-**Example:**
-```
-form/src/
-├── routes/
-│   ├── responseRoutes.ts          ❌ Business logic in routes
-│   └── proxyRoutes.ts             ✅ Good validation pattern
-├── controllers/
-│   ├── formController.ts          ⚠️ Lowercase naming
-│   └── UserProfileController.ts   ✅ PascalCase naming
-├── workflow/                      ✅ Excellent architecture!
-│   ├── core/
-│   │   ├── WorkflowEngineV3.ts   ✅ Event sourcing
-│   │   └── DryRunWrapper.ts      ✅ Innovative
-│   └── services/
-└── middleware/
-    └── auditMiddleware.ts         ✅ AsyncLocalStorage pattern
-```
-
-**Learn from:** workflow/, middleware/auditMiddleware.ts
-**Avoid:** responseRoutes.ts, direct process.env
-
----
-
-## Directory Structure Rationale
-
-### Controllers Directory
-
-**Purpose:** Handle HTTP request/response concerns
-
-**Contents:**
-- `BaseController.ts` - Base class with common methods
-- `{Feature}Controller.ts` - Feature-specific controllers
-
-**Naming:** PascalCase + Controller
-
-**Responsibilities:**
-- Parse request parameters
-- Validate input (Zod)
-- Call appropriate service methods
-- Format responses
-- Handle errors (via BaseController)
-- Set HTTP status codes
-
-### Services Directory
-
-**Purpose:** Business logic and orchestration
-
-**Contents:**
-- `{feature}Service.ts` - Feature business logic
-
-**Naming:** camelCase + Service (or PascalCase + Service)
-
-**Responsibilities:**
-- Implement business rules
-- Orchestrate multiple repositories
-- Transaction management
-- Business validations
-- No HTTP knowledge (Request/Response types)
-
-### Repositories Directory
-
-**Purpose:** Data access abstraction
-
-**Contents:**
-- `{Entity}Repository.ts` - Database operations for entity
-
-**Naming:** PascalCase + Repository
-
-**Responsibilities:**
-- Prisma query operations
-- Query optimization
-- Database error handling
-- Caching layer
-- Hide Prisma implementation details
-
-**Current Gap:** Only 1 repository exists (WorkflowRepository)
-
-### Routes Directory
-
-**Purpose:** Route registration ONLY
-
-**Contents:**
-- `{feature}Routes.ts` - Express router for feature
-
-**Naming:** camelCase + Routes
-
-**Responsibilities:**
-- Register routes with Express
-- Apply middleware
-- Delegate to controllers
-- **NO business logic!**
-
-### Middleware Directory
-
-**Purpose:** Cross-cutting concerns
-
-**Contents:**
-- Authentication middleware
-- Audit middleware
-- Error boundaries
-- Validation middleware
-- Custom middleware
-
-**Naming:** camelCase
-
-**Types:**
-- Request processing (before handler)
-- Response processing (after handler)
-- Error handling (error boundary)
-
-### Config Directory
-
-**Purpose:** Configuration management
-
-**Contents:**
-- `unifiedConfig.ts` - Type-safe configuration
-- Environment-specific configs
-
-**Pattern:** Single source of truth
-
-### Types Directory
-
-**Purpose:** TypeScript type definitions
-
-**Contents:**
-- `{feature}.types.ts` - Feature-specific types
-- DTOs (Data Transfer Objects)
-- Request/Response types
-- Domain models
-
----
-
-## Module Organization
-
-### Feature-Based Organization
-
-For large features, use subdirectories:
-
-```
-src/workflow/
-├── core/              # Core engine
-├── services/          # Workflow-specific services
-├── actions/           # System actions
-├── models/            # Domain models
-├── validators/        # Workflow validation
-└── utils/             # Workflow utilities
-```
-
-**When to use:**
-- Feature has 5+ files
-- Clear sub-domains exist
-- Logical grouping improves clarity
-
-### Flat Organization
-
-For simple features:
-
-```
-src/
-├── controllers/UserController.ts
-├── services/userService.ts
-├── routes/userRoutes.ts
-└── repositories/UserRepository.ts
-```
-
-**When to use:**
-- Simple features (< 5 files)
-- No clear sub-domains
-- Flat structure is clearer
-
----
-
-## Separation of Concerns
-
-### What Goes Where
-
-**Routes Layer:**
-- ✅ Route definitions
-- ✅ Middleware registration
-- ✅ Controller delegation
-- ❌ Business logic
-- ❌ Database operations
-- ❌ Validation logic (should be in validator or controller)
-
-**Controllers Layer:**
-- ✅ Request parsing (params, body, query)
-- ✅ Input validation (Zod)
-- ✅ Service calls
-- ✅ Response formatting
-- ✅ Error handling
-- ❌ Business logic
-- ❌ Database operations
-
-**Services Layer:**
-- ✅ Business logic
-- ✅ Business rules enforcement
-- ✅ Orchestration (multiple repos)
-- ✅ Transaction management
-- ❌ HTTP concerns (Request/Response)
-- ❌ Direct Prisma calls (use repositories)
-
-**Repositories Layer:**
-- ✅ Prisma operations
-- ✅ Query construction
-- ✅ Database error handling
-- ✅ Caching
-- ❌ Business logic
-- ❌ HTTP concerns
-
-### Example: User Creation
-
-**Route:**
-```typescript
-router.post('/users',
-    SSOMiddleware.verifyLoginStatus,
-    auditMiddleware,
-    (req, res) => userController.create(req, res)
-);
-```
-
-**Controller:**
-```typescript
-async create(req: Request, res: Response): Promise<void> {
-    try {
-        const validated = createUserSchema.parse(req.body);
-        const user = await this.userService.create(validated);
-        this.handleSuccess(res, user, 'User created');
-    } catch (error) {
-        this.handleError(error, res, 'create');
-    }
-}
-```
-
-**Service:**
-```typescript
-async create(data: CreateUserDTO): Promise<User> {
-    // Business rule: check if email already exists
-    const existing = await this.userRepository.findByEmail(data.email);
-    if (existing) throw new ConflictError('Email already exists');
-
-    // Create user
-    return await this.userRepository.create(data);
-}
-```
-
-**Repository:**
-```typescript
-async create(data: CreateUserDTO): Promise<User> {
-    return PrismaService.main.user.create({ data });
-}
-
-async findByEmail(email: string): Promise<User | null> {
-    return PrismaService.main.user.findUnique({ where: { email } });
-}
-```
-
-**Notice:** Each layer has clear, distinct responsibilities!
-
----
-
-**Related Files:**
-- [SKILL.md](SKILL.md) - Main guide
-- [routing-and-controllers.md](routing-and-controllers.md) - Routes and controllers details
-- [services-and-repositories.md](services-and-repositories.md) - Service and repository patterns