plcode-windows-x64-baseline 2.1.0

package/.plcode/skill/core/backend-dev-guidelines/resources/configuration.md

@@ -0,0 +1,285 @@
+# Configuration Management - UnifiedConfig Pattern
+
+Complete guide to managing configuration in backend microservices.
+
+## Table of Contents
+
+- [UnifiedConfig Overview](#unifiedconfig-overview)
+- [NEVER Use process.env Directly](#never-use-processenv-directly)
+- [Configuration Structure](#configuration-structure)
+- [Environment-Specific Configs](#environment-specific-configs)
+- [Secrets Management](#secrets-management)
+- [Migration Guide](#migration-guide)
+
+---
+
+## UnifiedConfig Overview
+
+### Why UnifiedConfig?
+
+**Problems with process.env:**
+
+- ❌ No type safety
+- ❌ No validation
+- ❌ Hard to test
+- ❌ Scattered throughout code
+- ❌ No default values
+- ❌ Runtime errors for typos
+
+**Benefits of unifiedConfig:**
+
+- ✅ Type-safe configuration
+- ✅ Single source of truth
+- ✅ Validated at startup
+- ✅ Easy to test with mocks
+- ✅ Clear structure
+- ✅ Fallback to environment variables
+
+---
+
+## NEVER Use process.env Directly
+
+### The Rule
+
+```typescript
+// ❌ NEVER DO THIS
+const timeout = parseInt(process.env.TIMEOUT_MS || "5000")
+const dbHost = process.env.DB_HOST || "localhost"
+
+// ✅ ALWAYS DO THIS
+import { config } from "./config/unifiedConfig"
+const timeout = config.timeouts.default
+const dbHost = config.database.host
+```
+
+### Why This Matters
+
+**Example of problems:**
+
+```typescript
+// Typo in environment variable name
+const host = process.env.DB_HSOT // undefined! No error!
+
+// Type safety
+const port = process.env.PORT // string! Need parseInt
+const timeout = parseInt(process.env.TIMEOUT) // NaN if not set!
+```
+
+**With unifiedConfig:**
+
+```typescript
+const port = config.server.port // number, guaranteed
+const timeout = config.timeouts.default // number, with fallback
+```
+
+---
+
+## Configuration Structure
+
+### UnifiedConfig Interface
+
+```typescript
+export interface UnifiedConfig {
+  database: {
+    host: string
+    port: number
+    username: string
+    password: string
+    database: string
+  }
+  server: {
+    port: number
+    sessionSecret: string
+  }
+  tokens: {
+    jwt: string
+    inactivity: string
+    internal: string
+  }
+  keycloak: {
+    realm: string
+    client: string
+    baseUrl: string
+    secret: string
+  }
+  aws: {
+    region: string
+    emailQueueUrl: string
+    accessKeyId: string
+    secretAccessKey: string
+  }
+  sentry: {
+    dsn: string
+    environment: string
+    tracesSampleRate: number
+  }
+  // ... more sections
+}
+```
+
+### Implementation Pattern
+
+**File:** `/blog-api/src/config/unifiedConfig.ts`
+
+```typescript
+import * as fs from "fs"
+import * as path from "path"
+import * as ini from "ini"
+
+const configPath = path.join(__dirname, "../../config.ini")
+const iniConfig = ini.parse(fs.readFileSync(configPath, "utf-8"))
+
+export const config: UnifiedConfig = {
+  database: {
+    host: iniConfig.database?.host || process.env.DB_HOST || "localhost",
+    port: parseInt(iniConfig.database?.port || process.env.DB_PORT || "3306"),
+    username: iniConfig.database?.username || process.env.DB_USER || "root",
+    password: iniConfig.database?.password || process.env.DB_PASSWORD || "",
+    database: iniConfig.database?.database || process.env.DB_NAME || "blog_dev",
+  },
+  server: {
+    port: parseInt(iniConfig.server?.port || process.env.PORT || "3002"),
+    sessionSecret: iniConfig.server?.sessionSecret || process.env.SESSION_SECRET || "dev-secret",
+  },
+  // ... more configuration
+}
+
+// Validate critical config
+if (!config.tokens.jwt) {
+  throw new Error("JWT secret not configured!")
+}
+```
+
+**Key Points:**
+
+- Read from config.ini first
+- Fallback to process.env
+- Default values for development
+- Validation at startup
+- Type-safe access
+
+---
+
+## Environment-Specific Configs
+
+### config.ini Structure
+
+```ini
+[database]
+host = localhost
+port = 3306
+username = root
+password = password1
+database = blog_dev
+
+[server]
+port = 3002
+sessionSecret = your-secret-here
+
+[tokens]
+jwt = your-jwt-secret
+inactivity = 30m
+internal = internal-api-token
+
+[keycloak]
+realm = myapp
+client = myapp-client
+baseUrl = http://localhost:8080
+secret = keycloak-client-secret
+
+[sentry]
+dsn = https://your-sentry-dsn
+environment = development
+tracesSampleRate = 0.1
+```
+
+### Environment Overrides
+
+```bash
+# .env file (optional overrides)
+DB_HOST=production-db.example.com
+DB_PASSWORD=secure-password
+PORT=80
+```
+
+**Precedence:**
+
+1. config.ini (highest priority)
+2. process.env variables
+3. Hard-coded defaults (lowest priority)
+
+---
+
+## Secrets Management
+
+### DO NOT Commit Secrets
+
+```gitignore
+# .gitignore
+config.ini
+.env
+sentry.ini
+*.pem
+*.key
+```
+
+### Use Environment Variables in Production
+
+```typescript
+// Development: config.ini
+// Production: Environment variables
+
+export const config: UnifiedConfig = {
+  database: {
+    password: process.env.DB_PASSWORD || iniConfig.database?.password || "",
+  },
+  tokens: {
+    jwt: process.env.JWT_SECRET || iniConfig.tokens?.jwt || "",
+  },
+}
+```
+
+---
+
+## Migration Guide
+
+### Find All process.env Usage
+
+```bash
+grep -r "process.env" blog-api/src/ --include="*.ts" | wc -l
+```
+
+### Migration Example
+
+**Before:**
+
+```typescript
+// Scattered throughout code
+const timeout = parseInt(process.env.OPENID_HTTP_TIMEOUT_MS || "15000")
+const keycloakUrl = process.env.KEYCLOAK_BASE_URL
+const jwtSecret = process.env.JWT_SECRET
+```
+
+**After:**
+
+```typescript
+import { config } from "./config/unifiedConfig"
+
+const timeout = config.keycloak.timeout
+const keycloakUrl = config.keycloak.baseUrl
+const jwtSecret = config.tokens.jwt
+```
+
+**Benefits:**
+
+- Type-safe
+- Centralized
+- Easy to test
+- Validated at startup
+
+---
+
+**Related Files:**
+
+- SKILL.md
+- [testing-guide.md](testing-guide.md)

package/.plcode/skill/core/backend-dev-guidelines/resources/database-patterns.md

@@ -0,0 +1,227 @@
+# Database Patterns - Prisma Best Practices
+
+Complete guide to database access patterns using Prisma in backend microservices.
+
+## Table of Contents
+
+- [PrismaService Usage](#prismaservice-usage)
+- [Repository Pattern](#repository-pattern)
+- [Transaction Patterns](#transaction-patterns)
+- [Query Optimization](#query-optimization)
+- [N+1 Query Prevention](#n1-query-prevention)
+- [Error Handling](#error-handling)
+
+---
+
+## PrismaService Usage
+
+### Basic Pattern
+
+```typescript
+import { PrismaService } from "@project-lifecycle-portal/database"
+
+// Always use PrismaService.main
+const users = await PrismaService.main.user.findMany()
+```
+
+### Check Availability
+
+```typescript
+if (!PrismaService.isAvailable) {
+  throw new Error("Prisma client not initialized")
+}
+
+const user = await PrismaService.main.user.findUnique({ where: { id } })
+```
+
+---
+
+## Repository Pattern
+
+### Why Use Repositories
+
+✅ **Use repositories when:**
+
+- Complex queries with joins/includes
+- Query used in multiple places
+- Need caching layer
+- Want to mock for testing
+
+❌ **Skip repositories for:**
+
+- Simple one-off queries
+- Prototyping (can refactor later)
+
+### Repository Template
+
+```typescript
+export class UserRepository {
+  async findById(id: string): Promise<User | null> {
+    return PrismaService.main.user.findUnique({
+      where: { id },
+      include: { profile: true },
+    })
+  }
+
+  async findActive(): Promise<User[]> {
+    return PrismaService.main.user.findMany({
+      where: { isActive: true },
+      orderBy: { createdAt: "desc" },
+    })
+  }
+
+  async create(data: Prisma.UserCreateInput): Promise<User> {
+    return PrismaService.main.user.create({ data })
+  }
+}
+```
+
+---
+
+## Transaction Patterns
+
+### Simple Transaction
+
+```typescript
+const result = await PrismaService.main.$transaction(async (tx) => {
+  const user = await tx.user.create({ data: userData })
+  const profile = await tx.userProfile.create({ data: { userId: user.id } })
+  return { user, profile }
+})
+```
+
+### Interactive Transaction
+
+```typescript
+const result = await PrismaService.main.$transaction(
+  async (tx) => {
+    const user = await tx.user.findUnique({ where: { id } })
+    if (!user) throw new Error("User not found")
+
+    return await tx.user.update({
+      where: { id },
+      data: { lastLogin: new Date() },
+    })
+  },
+  {
+    maxWait: 5000,
+    timeout: 10000,
+  },
+)
+```
+
+---
+
+## Query Optimization
+
+### Use select to Limit Fields
+
+```typescript
+// ❌ Fetches all fields
+const users = await PrismaService.main.user.findMany()
+
+// ✅ Only fetch needed fields
+const users = await PrismaService.main.user.findMany({
+  select: {
+    id: true,
+    email: true,
+    profile: { select: { firstName: true, lastName: true } },
+  },
+})
+```
+
+### Use include Carefully
+
+```typescript
+// ❌ Excessive includes
+const user = await PrismaService.main.user.findUnique({
+  where: { id },
+  include: {
+    profile: true,
+    posts: { include: { comments: true } },
+    workflows: { include: { steps: { include: { actions: true } } } },
+  },
+})
+
+// ✅ Only include what you need
+const user = await PrismaService.main.user.findUnique({
+  where: { id },
+  include: { profile: true },
+})
+```
+
+---
+
+## N+1 Query Prevention
+
+### Problem: N+1 Queries
+
+```typescript
+// ❌ N+1 Query Problem
+const users = await PrismaService.main.user.findMany() // 1 query
+
+for (const user of users) {
+  // N queries (one per user)
+  const profile = await PrismaService.main.userProfile.findUnique({
+    where: { userId: user.id },
+  })
+}
+```
+
+### Solution: Use include or Batching
+
+```typescript
+// ✅ Single query with include
+const users = await PrismaService.main.user.findMany({
+  include: { profile: true },
+})
+
+// ✅ Or batch query
+const userIds = users.map((u) => u.id)
+const profiles = await PrismaService.main.userProfile.findMany({
+  where: { userId: { in: userIds } },
+})
+```
+
+---
+
+## Error Handling
+
+### Prisma Error Types
+
+```typescript
+import { Prisma } from "@prisma/client"
+
+try {
+  await PrismaService.main.user.create({ data })
+} catch (error) {
+  if (error instanceof Prisma.PrismaClientKnownRequestError) {
+    // Unique constraint violation
+    if (error.code === "P2002") {
+      throw new ConflictError("Email already exists")
+    }
+
+    // Foreign key constraint
+    if (error.code === "P2003") {
+      throw new ValidationError("Invalid reference")
+    }
+
+    // Record not found
+    if (error.code === "P2025") {
+      throw new NotFoundError("Record not found")
+    }
+  }
+
+  // Unknown error
+  Sentry.captureException(error)
+  throw error
+}
+```
+
+---
+
+**Related Files:**
+
+- SKILL.md
+- [services-and-repositories.md](services-and-repositories.md)
+- [async-and-errors.md](async-and-errors.md)

package/.plcode/skill/core/backend-dev-guidelines/resources/middleware-guide.md

@@ -0,0 +1,205 @@
+# Middleware Guide - Express Middleware Patterns
+
+Complete guide to creating and using middleware in backend microservices.
+
+## Table of Contents
+
+- [Authentication Middleware](#authentication-middleware)
+- [Audit Middleware with AsyncLocalStorage](#audit-middleware-with-asynclocalstorage)
+- [Error Boundary Middleware](#error-boundary-middleware)
+- [Validation Middleware](#validation-middleware)
+- [Composable Middleware](#composable-middleware)
+- [Middleware Ordering](#middleware-ordering)
+
+---
+
+## Authentication Middleware
+
+### SSOMiddleware Pattern
+
+**File:** `/form/src/middleware/SSOMiddleware.ts`
+
+```typescript
+export class SSOMiddlewareClient {
+  static verifyLoginStatus(req: Request, res: Response, next: NextFunction): void {
+    const token = req.cookies.refresh_token
+
+    if (!token) {
+      return res.status(401).json({ error: "Not authenticated" })
+    }
+
+    try {
+      const decoded = jwt.verify(token, config.tokens.jwt)
+      res.locals.claims = decoded
+      res.locals.effectiveUserId = decoded.sub
+      next()
+    } catch (error) {
+      res.status(401).json({ error: "Invalid token" })
+    }
+  }
+}
+```
+
+---
+
+## Audit Middleware with AsyncLocalStorage
+
+### Excellent Pattern from Blog API
+
+**File:** `/form/src/middleware/auditMiddleware.ts`
+
+```typescript
+import { AsyncLocalStorage } from "async_hooks"
+
+export interface AuditContext {
+  userId: string
+  userName?: string
+  impersonatedBy?: string
+  sessionId?: string
+  timestamp: Date
+  requestId: string
+}
+
+export const auditContextStorage = new AsyncLocalStorage<AuditContext>()
+
+export function auditMiddleware(req: Request, res: Response, next: NextFunction): void {
+  const context: AuditContext = {
+    userId: res.locals.effectiveUserId || "anonymous",
+    userName: res.locals.claims?.preferred_username,
+    impersonatedBy: res.locals.isImpersonating ? res.locals.originalUserId : undefined,
+    timestamp: new Date(),
+    requestId: req.id || uuidv4(),
+  }
+
+  auditContextStorage.run(context, () => {
+    next()
+  })
+}
+
+// Getter for current context
+export function getAuditContext(): AuditContext | null {
+  return auditContextStorage.getStore() || null
+}
+```
+
+**Benefits:**
+
+- Context propagates through entire request
+- No need to pass context through every function
+- Automatically available in services, repositories
+- Type-safe context access
+
+**Usage in Services:**
+
+```typescript
+import { getAuditContext } from "../middleware/auditMiddleware"
+
+async function someOperation() {
+  const context = getAuditContext()
+  console.log("Operation by:", context?.userId)
+}
+```
+
+---
+
+## Error Boundary Middleware
+
+### Comprehensive Error Handler
+
+**File:** `/form/src/middleware/errorBoundary.ts`
+
+```typescript
+export function errorBoundary(error: Error, req: Request, res: Response, next: NextFunction): void {
+  // Determine status code
+  const statusCode = getStatusCodeForError(error)
+
+  // Capture to Sentry
+  Sentry.withScope((scope) => {
+    scope.setLevel(statusCode >= 500 ? "error" : "warning")
+    scope.setTag("error_type", error.name)
+    scope.setContext("error_details", {
+      message: error.message,
+      stack: error.stack,
+    })
+    Sentry.captureException(error)
+  })
+
+  // User-friendly response
+  res.status(statusCode).json({
+    success: false,
+    error: {
+      message: getUserFriendlyMessage(error),
+      code: error.name,
+    },
+    requestId: Sentry.getCurrentScope().getPropagationContext().traceId,
+  })
+}
+
+// Async wrapper
+export function asyncErrorWrapper(handler: (req: Request, res: Response, next: NextFunction) => Promise<any>) {
+  return async (req: Request, res: Response, next: NextFunction) => {
+    try {
+      await handler(req, res, next)
+    } catch (error) {
+      next(error)
+    }
+  }
+}
+```
+
+---
+
+## Composable Middleware
+
+### withAuthAndAudit Pattern
+
+```typescript
+export function withAuthAndAudit(...authMiddleware: any[]) {
+  return [...authMiddleware, auditMiddleware]
+}
+
+// Usage
+router.post("/:formID/submit", ...withAuthAndAudit(SSOMiddlewareClient.verifyLoginStatus), async (req, res) =>
+  controller.submit(req, res),
+)
+```
+
+---
+
+## Middleware Ordering
+
+### Critical Order (Must Follow)
+
+```typescript
+// 1. Sentry request handler (FIRST)
+app.use(Sentry.Handlers.requestHandler())
+
+// 2. Body parsing
+app.use(express.json())
+app.use(express.urlencoded({ extended: true }))
+
+// 3. Cookie parsing
+app.use(cookieParser())
+
+// 4. Auth initialization
+app.use(SSOMiddleware.initialize())
+
+// 5. Routes registered here
+app.use("/api/users", userRoutes)
+
+// 6. Error handler (AFTER routes)
+app.use(errorBoundary)
+
+// 7. Sentry error handler (LAST)
+app.use(Sentry.Handlers.errorHandler())
+```
+
+**Rule:** Error handlers MUST be registered AFTER all routes!
+
+---
+
+**Related Files:**
+
+- SKILL.md
+- [routing-and-controllers.md](routing-and-controllers.md)
+- [async-and-errors.md](async-and-errors.md)