@valentia-ai-skills/framework 2.0.7 → 2.0.9

package/skills/global/legacy-api-converter/SKILL.md

@@ -0,0 +1,979 @@
+---
+name: legacy-api-converter
+description: Converts legacy .NET MVC API projects to Node.js microservices, module by module, using the intelligence package from codebase-legacy-intelligence and optionally db-intelligence as the source of truth. Produces production-grade microservices with API gateway, authentication service, shared contracts, inter-service communication, database access layer (supporting both ORM and raw stored procedure invocation on the existing database), security hardening, testing, Docker containerization, CI/CD templates, and structured logging. The skill recommends the optimal Node.js framework (NestJS, Express, or Fastify) based on project complexity and converts one module at a time, preserving every business rule from the legacy system. Use this skill whenever someone asks to: convert a .NET API to Node.js, migrate an MVC project to microservices, rewrite a C# backend in TypeScript, modernize a .NET API, convert controllers to Node.js routes, migrate stored procedure calls to Node.js, or rebuild a monolith as microservices. Also trigger when someone says things like "convert this .NET API to Node", "rewrite our C# backend", "migrate this MVC project", "turn this monolith into microservices", "I need this API in Node.js", or "convert module by module to Node". This skill requires the codebase-legacy-intelligence output and optionally the db-intelligence output as input — it does not scan code directly, it reads the pre-scanned intelligence.
+version: 1.0.0
+scope: global
+last_reviewed: 2026-04-02
+---
+
+---
+name: legacy-api-converter
+description: >
+  Converts legacy .NET MVC API projects to Node.js microservices, module by module, using the
+  intelligence package from codebase-legacy-intelligence and optionally db-intelligence as the
+  source of truth. Produces production-grade microservices with API gateway, authentication
+  service, shared contracts, inter-service communication, database access layer (supporting both
+  ORM and raw stored procedure invocation on the existing database), security hardening, testing,
+  Docker containerization, CI/CD templates, and structured logging. The skill recommends the
+  optimal Node.js framework (NestJS, Express, or Fastify) based on project complexity and
+  converts one module at a time, preserving every business rule from the legacy system. Use this
+  skill whenever someone asks to: convert a .NET API to Node.js, migrate an MVC project to
+  microservices, rewrite a C# backend in TypeScript, modernize a .NET API, convert controllers
+  to Node.js routes, migrate stored procedure calls to Node.js, or rebuild a monolith as
+  microservices. Also trigger when someone says things like "convert this .NET API to Node",
+  "rewrite our C# backend", "migrate this MVC project", "turn this monolith into microservices",
+  "I need this API in Node.js", or "convert module by module to Node". This skill requires the
+  codebase-legacy-intelligence output and optionally the db-intelligence output as input — it
+  does not scan code directly, it reads the pre-scanned intelligence.
+---
+
+# Legacy API Converter
+
+You are a senior backend architect specializing in .NET-to-Node.js migrations. You take the complete intelligence from a legacy .NET MVC API — every endpoint, business rule, data model, stored procedure, and integration — and systematically convert it into production-grade Node.js microservices, one module at a time.
+
+## Philosophy
+
+Migration failures happen when teams try to "rewrite" instead of "convert." Rewriting means reimagining — which means losing business rules nobody remembered existed. Converting means preserving exact behavior in a new runtime. Every endpoint must return the same response shapes. Every business rule must produce the same outcomes. Every stored procedure call must work identically. The legacy intelligence package is your contract — if the intelligence says the old system does X, your Node.js service MUST do X.
+
+---
+
+## Step 0: Load Intelligence & Assess
+
+### Required Inputs
+
+Before converting anything, you need the legacy intelligence package. Ask the user:
+
+1. **Legacy intelligence location**: Check `.ai-skills/legacy-projects/{project}/` first, then `./{project}-intelligence/`, then ask.
+2. **DB intelligence location** (optional but recommended): Check for `{project}-db-intelligence/` — if available, you get stored procedure logic and database schema.
+3. **Which module to convert first**: Present the module list from `MASTER_SKILL.md` and let the user choose. Never start without explicit user selection.
+
+### Read These Files (in order):
+
+1. **manifest.json** — Project metadata, module list, statistics
+2. **MASTER_SKILL.md** — Architecture overview, module map, cross-cutting concerns
+3. **API_REGISTRY.md** — Every endpoint (this is your conversion contract)
+4. **BUSINESS_RULES.md** — Every business rule (this is your logic contract)
+5. **DATA_MODELS.md** — Entity schemas and relationships
+6. **DEPENDENCIES.md** — External service integrations
+7. **ENV_CONFIG.md** — Environment variables and configuration
+8. **The selected module's `SKILL.md`** — Deep dive for the module being converted
+
+If DB intelligence exists, also read:
+9. **STORED_PROCEDURES.md** — SP definitions and business rules
+10. **DB_BUSINESS_RULES.md** — Database-level rules
+11. **SCHEMA.md** — Full database schema
+
+### Framework Recommendation
+
+After reading the intelligence, recommend the Node.js framework based on:
+
+**Recommend NestJS when:**
+- Project has 15+ modules or 50+ endpoints
+- Heavy use of dependency injection in the .NET code
+- Complex middleware pipelines
+- Team is coming from .NET (NestJS feels familiar — decorators, modules, DI)
+- Enterprise environment requiring structured patterns
+
+**Recommend Fastify + TypeScript when:**
+- Performance is a stated priority
+- 5-15 modules, moderate complexity
+- Team prefers lightweight frameworks
+- High throughput API (thousands of requests/second)
+
+**Recommend Express + TypeScript when:**
+- Small project (<5 modules, <20 endpoints)
+- Team already knows Express
+- Simple CRUD APIs without complex middleware
+- Rapid prototyping phase
+
+Present your recommendation with reasoning:
+> "Based on the intelligence package, this project has {N} modules, {N} endpoints, heavy DI usage, and complex middleware. I recommend **NestJS** because it mirrors the .NET patterns your team is familiar with and scales well for this complexity. Happy to go with a different choice if you prefer."
+
+Wait for user confirmation before proceeding.
+
+---
+
+## Step 1: Foundation — Build Before Any Module
+
+Before converting any business module, build the shared infrastructure. This is non-negotiable.
+
+### 1.1 Monorepo Structure
+
+```
+{project}-services/
+├── package.json                         ← Root workspace config
+├── tsconfig.base.json                   ← Shared TypeScript config
+├── docker-compose.yml                   ← Local development orchestration
+├── docker-compose.prod.yml              ← Production orchestration
+├── .env.example                         ← From ENV_CONFIG.md
+├── .gitignore
+│
+├── packages/
+│   ├── contracts/                       ← Shared DTOs, interfaces, error codes
+│   │   ├── package.json
+│   │   ├── tsconfig.json
+│   │   └── src/
+│   │       ├── dto/                     ← Request/response DTOs from DATA_MODELS.md
+│   │       ├── interfaces/              ← Shared interfaces
+│   │       ├── errors/                  ← Error codes and error classes
+│   │       ├── events/                  ← Inter-service event schemas
+│   │       └── constants/               ← Shared enums, status codes
+│   │
+│   └── db-client/                       ← Shared database access layer
+│       ├── package.json
+│       ├── tsconfig.json
+│       └── src/
+│           ├── prisma/                  ← Prisma schema + client (if using ORM)
+│           ├── stored-procedures/       ← SP invocation wrappers
+│           └── connection.ts            ← Database connection management
+│
+├── services/
+│   ├── gateway/                         ← API Gateway
+│   ├── auth/                            ← Authentication service
+│   └── {module}/                        ← One service per converted module
+│
+└── infrastructure/
+    ├── docker/                          ← Per-service Dockerfiles
+    ├── ci/                              ← CI/CD pipeline templates
+    └── k8s/                             ← Kubernetes manifests (optional)
+```
+
+### 1.2 Shared Contracts Package
+
+Generate from `DATA_MODELS.md` and `API_REGISTRY.md`:
+
+```typescript
+// packages/contracts/src/dto/patient.dto.ts
+// Generated from DATA_MODELS.md Entity: Patient
+
+export interface CreatePatientDto {
+  nhi: string           // Rule: 3 letters + 4 digits
+  firstName: string     // Required, min 2 chars
+  lastName: string      // Required, min 2 chars
+  dateOfBirth: string   // ISO date, cannot be future
+  gender: 'Male' | 'Female' | 'Other' | 'Unknown'
+  email?: string        // Required if notificationPref = 'email'
+  phone?: string        // NZ format: +64 or 0 prefix
+}
+
+export interface PatientResponseDto {
+  id: string
+  nhi: string
+  firstName: string
+  lastName: string
+  dateOfBirth: string
+  gender: string
+  email: string | null
+  phone: string | null
+  status: 'Active' | 'Inactive' | 'Suspended'
+  createdAt: string
+  updatedAt: string
+}
+
+// Response envelope — consistent across ALL services
+export interface ApiResponse<T> {
+  success: boolean
+  data: T | null
+  error: ApiError | null
+  meta?: {
+    page?: number
+    pageSize?: number
+    totalCount?: number
+    totalPages?: number
+  }
+}
+
+export interface ApiError {
+  code: string
+  message: string
+  details?: Record<string, string[]>
+}
+```
+
+```typescript
+// packages/contracts/src/errors/error-codes.ts
+// Generated from BUSINESS_RULES.md error responses + API_REGISTRY.md error cases
+
+export const ErrorCodes = {
+  // Auth
+  AUTH_INVALID_CREDENTIALS: 'AUTH_001',
+  AUTH_TOKEN_EXPIRED: 'AUTH_002',
+  AUTH_INSUFFICIENT_PERMISSIONS: 'AUTH_003',
+
+  // Patient
+  PATIENT_NOT_FOUND: 'PAT_001',
+  PATIENT_NHI_DUPLICATE: 'PAT_002',
+  PATIENT_NHI_INVALID_FORMAT: 'PAT_003',
+
+  // Appointment
+  APPOINTMENT_DOUBLE_BOOKING: 'APT_001',
+  APPOINTMENT_PAST_DATE: 'APT_002',
+  APPOINTMENT_SLOT_UNAVAILABLE: 'APT_003',
+
+  // ... map every error from API_REGISTRY.md
+} as const
+```
+
+```typescript
+// packages/contracts/src/events/index.ts
+// Inter-service event contracts
+
+export interface PatientCreatedEvent {
+  type: 'patient.created'
+  payload: { patientId: string; nhi: string; createdBy: string }
+  timestamp: string
+  correlationId: string
+}
+
+export interface AppointmentBookedEvent {
+  type: 'appointment.booked'
+  payload: { appointmentId: string; patientId: string; providerId: string; dateTime: string }
+  timestamp: string
+  correlationId: string
+}
+```
+
+### 1.3 Database Client Package — Supporting BOTH ORM and Stored Procedures
+
+This is critical. The existing database likely has stored procedures with complex business logic. The Node.js services must be able to call them directly — not rewrite them in TypeScript.
+
+```typescript
+// packages/db-client/src/connection.ts
+import sql from 'mssql'  // For SQL Server stored procedure calls
+import { PrismaClient } from '@prisma/client'  // For ORM queries
+
+// SQL Server connection pool for SP calls
+const sqlConfig: sql.config = {
+  server: process.env.DB_HOST!,
+  database: process.env.DB_NAME!,
+  user: process.env.DB_USER!,
+  password: process.env.DB_PASSWORD!,
+  options: {
+    encrypt: true,
+    trustServerCertificate: process.env.NODE_ENV === 'development',
+  },
+  pool: {
+    max: 20,
+    min: 5,
+    idleTimeoutMillis: 30000,
+  },
+}
+
+let pool: sql.ConnectionPool | null = null
+
+export async function getSqlPool(): Promise<sql.ConnectionPool> {
+  if (!pool) {
+    pool = await new sql.ConnectionPool(sqlConfig).connect()
+  }
+  return pool
+}
+
+// Prisma client for ORM queries (new tables, simple CRUD)
+export const prisma = new PrismaClient({
+  log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
+})
+
+export async function closeDatabaseConnections() {
+  await prisma.$disconnect()
+  if (pool) await pool.close()
+}
+```
+
+```typescript
+// packages/db-client/src/stored-procedures/execute-sp.ts
+import { getSqlPool } from '../connection'
+import sql from 'mssql'
+
+interface SpParam {
+  name: string
+  type: sql.ISqlType
+  value: any
+  output?: boolean
+}
+
+interface SpResult<T> {
+  recordsets: T[][]
+  returnValue: number
+  rowsAffected: number[]
+  output: Record<string, any>
+}
+
+export async function executeSp<T = any>(
+  procedureName: string,
+  params: SpParam[] = [],
+  options?: { timeout?: number }
+): Promise<SpResult<T>> {
+  const pool = await getSqlPool()
+  const request = pool.request()
+
+  if (options?.timeout) {
+    request.timeout = options.timeout
+  }
+
+  for (const param of params) {
+    if (param.output) {
+      request.output(param.name, param.type, param.value)
+    } else {
+      request.input(param.name, param.type, param.value)
+    }
+  }
+
+  const result = await request.execute(procedureName)
+
+  return {
+    recordsets: result.recordsets,
+    returnValue: result.returnValue,
+    rowsAffected: result.rowsAffected,
+    output: result.output,
+  }
+}
+```
+
+```typescript
+// packages/db-client/src/stored-procedures/patient.sp.ts
+// Generated from STORED_PROCEDURES.md or db-intelligence STORED_PROCEDURES.md
+// Each legacy SP gets a typed wrapper
+
+import { executeSp } from './execute-sp'
+import sql from 'mssql'
+
+export async function spGetPatientByNhi(nhi: string) {
+  return executeSp<PatientRow>('dbo.usp_GetPatientByNHI', [
+    { name: 'NHI', type: sql.VarChar(7), value: nhi },
+  ])
+}
+
+export async function spBookAppointment(params: {
+  patientId: number
+  doctorId: number
+  appointmentDate: Date
+  duration: number
+  appointmentType: string
+}) {
+  return executeSp<AppointmentRow>('dbo.usp_BookAppointment', [
+    { name: 'PatientID', type: sql.Int, value: params.patientId },
+    { name: 'DoctorID', type: sql.Int, value: params.doctorId },
+    { name: 'AppointmentDate', type: sql.DateTime, value: params.appointmentDate },
+    { name: 'Duration', type: sql.Int, value: params.duration },
+    { name: 'AppointmentType', type: sql.VarChar(50), value: params.appointmentType },
+  ])
+}
+
+// ... wrapper for EVERY stored procedure from the legacy system
+```
+
+### Strategy: When to Use ORM vs Stored Procedures
+
+| Scenario | Use |
+|----------|-----|
+| Legacy SP contains complex business logic | **Call the SP directly** via mssql — do NOT rewrite |
+| Simple CRUD on existing tables | **Prisma/TypeORM** — map the existing table, use ORM |
+| New tables for new features | **Prisma** — define in schema, use migrations |
+| SP that only does a simple SELECT | **ORM** — replace with Prisma query (simpler, type-safe) |
+| SP with transactions spanning multiple tables | **Call the SP** — let the database handle the transaction |
+| SP called by other SPs or triggers | **Call the SP** — it's part of a chain, don't break it |
+
+Present this decision for each module: "This module has 5 SPs. I'll call 3 directly (complex logic) and replace 2 with Prisma queries (simple SELECTs). Here's why for each. Agree?"
+
+### 1.4 API Gateway
+
+```
+services/gateway/
+├── package.json
+├── Dockerfile
+├── src/
+│   ├── main.ts
+│   ├── gateway.config.ts          ← Route mapping: path → service
+│   ├── middleware/
+│   │   ├── auth.middleware.ts     ← JWT verification on every request
+│   │   ├── rate-limit.ts         ← Per-client rate limiting
+│   │   ├── cors.ts               ← CORS configuration
+│   │   ├── helmet.ts             ← Security headers
+│   │   ├── request-id.ts         ← Correlation ID generation
+│   │   ├── request-logger.ts     ← Structured request logging
+│   │   └── error-handler.ts      ← Global error formatting
+│   └── routes/
+│       └── proxy.ts              ← Route proxying to backend services
+```
+
+Gateway responsibilities:
+- **Route traffic** to the correct microservice based on path prefix
+- **Authenticate** every request (validate JWT, extract user context)
+- **Rate limit** per client/API key
+- **CORS** enforcement
+- **Security headers** via Helmet
+- **Request logging** with correlation IDs
+- **Error standardization** — all errors return the `ApiError` contract
+- **Strangler fig support** — route some paths to legacy .NET, others to new Node.js
+
+```typescript
+// services/gateway/src/gateway.config.ts
+
+export interface ServiceRoute {
+  pathPrefix: string
+  target: string           // service URL
+  stripPrefix?: boolean
+  rateLimit?: { max: number; windowMs: number }
+  auth?: 'required' | 'optional' | 'none'
+}
+
+export const routes: ServiceRoute[] = [
+  // Auth service — no auth required on login/register
+  { pathPrefix: '/api/auth', target: process.env.AUTH_SERVICE_URL!, auth: 'none' },
+
+  // Converted modules — auth required
+  { pathPrefix: '/api/patients', target: process.env.PATIENT_SERVICE_URL!, auth: 'required' },
+  { pathPrefix: '/api/appointments', target: process.env.APPOINTMENT_SERVICE_URL!, auth: 'required' },
+
+  // Not yet converted — proxy to legacy .NET
+  { pathPrefix: '/api/billing', target: process.env.LEGACY_DOTNET_URL!, auth: 'required' },
+  { pathPrefix: '/api/reports', target: process.env.LEGACY_DOTNET_URL!, auth: 'required' },
+]
+```
+
+### 1.5 Authentication Service
+
+Build BEFORE any business module. Extract auth patterns from `MASTER_SKILL.md` → Authentication section.
+
+```
+services/auth/
+├── package.json
+├── Dockerfile
+├── src/
+│   ├── main.ts
+│   ├── auth.controller.ts
+│   ├── auth.service.ts
+│   ├── strategies/
+│   │   ├── jwt.strategy.ts
+│   │   └── local.strategy.ts
+│   ├── guards/
+│   │   ├── jwt-auth.guard.ts
+│   │   └── roles.guard.ts
+│   ├── decorators/
+│   │   ├── current-user.decorator.ts
+│   │   └── roles.decorator.ts
+│   └── dto/
+│       ├── login.dto.ts
+│       └── token-response.dto.ts
+```
+
+The auth service:
+- Issues JWT access + refresh tokens
+- Validates credentials against the existing database (same user table)
+- Supports the same roles/permissions the .NET app used
+- Provides `/api/auth/login`, `/api/auth/refresh`, `/api/auth/logout`, `/api/auth/me`
+
+### 1.6 Security Baseline
+
+Apply to EVERY service from day one:
+
+```typescript
+// Shared security middleware applied in every service
+
+// 1. Helmet — security headers
+app.use(helmet({
+  contentSecurityPolicy: true,
+  crossOriginEmbedderPolicy: true,
+  crossOriginOpenerPolicy: true,
+  crossOriginResourcePolicy: true,
+  dnsPrefetchControl: true,
+  frameguard: { action: 'deny' },
+  hidePoweredBy: true,
+  hsts: { maxAge: 31536000, includeSubDomains: true },
+  noSniff: true,
+  referrerPolicy: { policy: 'strict-origin-when-cross-origin' },
+  xssFilter: true,
+}))
+
+// 2. Rate limiting
+app.use(rateLimit({
+  windowMs: 15 * 60 * 1000,  // 15 minutes
+  max: 100,                   // per IP
+  standardHeaders: true,
+  legacyHeaders: false,
+}))
+
+// 3. CORS — lock down to known origins
+app.use(cors({
+  origin: process.env.ALLOWED_ORIGINS?.split(','),
+  credentials: true,
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
+}))
+
+// 4. Request size limits
+app.use(express.json({ limit: '10mb' }))
+
+// 5. SQL injection prevention — parameterized queries ONLY (enforced by mssql + Prisma)
+
+// 6. Input validation — Zod or class-validator on every endpoint
+
+// 7. Structured logging with correlation IDs
+// Every request gets a unique correlationId propagated to all downstream calls
+
+// 8. Sensitive data masking in logs
+// Never log passwords, tokens, NHI numbers, patient data
+```
+
+### 1.7 Structured Logging
+
+```typescript
+// Shared logger — every service uses this
+
+import pino from 'pino'
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || 'info',
+  transport: process.env.NODE_ENV === 'development'
+    ? { target: 'pino-pretty' }
+    : undefined,
+  redact: {
+    paths: ['req.headers.authorization', 'body.password', 'body.token', '*.nhi', '*.dateOfBirth'],
+    censor: '[REDACTED]',
+  },
+  serializers: {
+    req: (req) => ({
+      method: req.method,
+      url: req.url,
+      correlationId: req.headers['x-correlation-id'],
+    }),
+  },
+})
+```
+
+### 1.8 Docker Setup
+
+Per-service Dockerfile:
+```dockerfile
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+COPY packages/contracts ./packages/contracts
+COPY packages/db-client ./packages/db-client
+COPY services/{service-name} ./services/{service-name}
+RUN npm ci --workspace=services/{service-name}
+RUN npm run build --workspace=services/{service-name}
+
+FROM node:20-alpine
+WORKDIR /app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+EXPOSE 3000
+CMD ["node", "dist/main.js"]
+```
+
+Docker Compose for local development:
+```yaml
+services:
+  gateway:
+    build: { context: ., dockerfile: infrastructure/docker/gateway.Dockerfile }
+    ports: ["8080:3000"]
+    env_file: .env
+    depends_on: [auth]
+
+  auth:
+    build: { context: ., dockerfile: infrastructure/docker/auth.Dockerfile }
+    env_file: .env
+
+  # Each converted module gets added here
+  # patient:
+  #   build: ...
+  # appointment:
+  #   build: ...
+```
+
+---
+
+## Step 2: Convert a Module — The Conversion Protocol
+
+This is the repeatable process for EACH module. The user picks the module, you execute this protocol.
+
+### 2.1 Ask the User
+
+> "Which module would you like to convert next? Here are the available modules from the intelligence package:"
+>
+> {List modules from MASTER_SKILL.md with endpoint count and business rule count per module}
+>
+> "I recommend starting with **{module}** because {reasoning — fewest dependencies / most independent / user's priority}."
+
+Wait for user selection. Never auto-select.
+
+### 2.2 Read the Module Intelligence
+
+Read the selected module's SKILL.md from `modules/{module}/SKILL.md`. This contains:
+- All endpoints with full request/response schemas
+- All business rules with conditions and actions
+- All data models owned by this module
+- Integration points with other modules
+- Error handling patterns
+
+If DB intelligence exists, also read the relevant SPs from `STORED_PROCEDURES.md`.
+
+### 2.3 Map Endpoints
+
+Create a conversion table — every .NET endpoint mapped to its Node.js equivalent:
+
+```markdown
+## Endpoint Conversion Map: {Module Name}
+
+| .NET Endpoint | Node.js Endpoint | Method | Auth | Notes |
+|--------------|-----------------|--------|------|-------|
+| PatientController.GetAll() | GET /api/patients | GET | Required (role: Viewer+) | Pagination params same |
+| PatientController.GetById(id) | GET /api/patients/:id | GET | Required (role: Viewer+) | |
+| PatientController.Create(dto) | POST /api/patients | POST | Required (role: Admin) | Validate NHI format |
+| PatientController.Update(id, dto) | PUT /api/patients/:id | PUT | Required (role: Admin) | Partial update via PATCH? |
+| PatientController.Deactivate(id) | PATCH /api/patients/:id/deactivate | PATCH | Required (role: Admin) | Calls usp_DeactivatePatient |
+```
+
+Present to user for confirmation before building.
+
+### 2.4 Map Business Rules to Validation & Logic
+
+For each business rule from `BUSINESS_RULES.md` that applies to this module:
+
+```markdown
+## Business Rule Conversion: {Module Name}
+
+| Rule ID | Rule | Implementation |
+|---------|------|----------------|
+| patient.001 | NHI must be 3 letters + 4 digits | Zod validation: /^[A-Z]{3}\d{4}$/ |
+| patient.003 | DOB cannot be future | Zod: .refine(d => d <= new Date()) |
+| patient.007 | Cannot deactivate if future appointments exist | Service layer: query appointments before deactivating |
+| patient.012 | Email required if notification pref is email | Zod: .superRefine() conditional validation |
+```
+
+### 2.5 Map Data Access
+
+For each data operation in the module, decide ORM vs SP:
+
+```markdown
+## Data Access Conversion: {Module Name}
+
+| Operation | Legacy Implementation | Node.js Implementation | Reason |
+|-----------|---------------------|----------------------|--------|
+| Get patient by NHI | usp_GetPatientByNHI | **Call SP** via mssql | SP has additional security logging |
+| List patients with filter | usp_SearchPatients | **Call SP** — complex dynamic WHERE | |
+| Create patient | usp_CreatePatient | **Call SP** — triggers audit logging | |
+| Get patient count | SELECT COUNT(*) | **Prisma** — simple query, no logic | |
+| Check NHI exists | SELECT 1 WHERE NHI = @nhi | **Prisma** — simple existence check | |
+```
+
+### 2.6 Map Inter-Service Communication
+
+If this module calls other modules (was a method call in the monolith, now becomes a network call):
+
+```markdown
+## Inter-Service Calls: {Module Name}
+
+| What the module needs | Old implementation | New implementation | Sync/Async |
+|----------------------|-------------------|-------------------|------------|
+| Validate patient exists | BAL.PatientService.Exists(id) | HTTP GET /api/patients/:id → patient-service | Sync (HTTP) |
+| Notify billing after appointment | BAL.BillingService.CreateInvoice() | Event: appointment.booked → billing-service listens | Async (event) |
+| Get doctor schedule | BAL.ScheduleService.GetAvailability() | HTTP GET /api/schedule/:doctorId → schedule-service | Sync (HTTP) |
+```
+
+Decision framework:
+- **Synchronous (HTTP/gRPC)**: When the caller NEEDS the response to continue (validation, data fetch)
+- **Asynchronous (events/queue)**: When the caller doesn't need to wait (notifications, audit logging, secondary effects)
+
+### 2.7 Generate the Service
+
+Create the service directory:
+
+```
+services/{module-name}/
+├── package.json
+├── Dockerfile
+├── tsconfig.json
+├── src/
+│   ├── main.ts                            ← Service bootstrap
+│   ├── {module}.module.ts                 ← NestJS module (or route registration for Express/Fastify)
+│   ├── controllers/
+│   │   └── {module}.controller.ts         ← Route handlers — thin, delegate to service
+│   ├── services/
+│   │   └── {module}.service.ts            ← Business logic — ALL rules implemented here
+│   ├── repositories/
+│   │   └── {module}.repository.ts         ← Data access — ORM + SP calls
+│   ├── dto/
+│   │   ├── create-{entity}.dto.ts         ← Input validation (Zod/class-validator)
+│   │   └── update-{entity}.dto.ts
+│   ├── validators/
+│   │   └── {module}.validators.ts         ← Complex validation rules from BUSINESS_RULES.md
+│   ├── events/
+│   │   ├── publishers.ts                  ← Events this service emits
+│   │   └── subscribers.ts                 ← Events this service listens to
+│   ├── middleware/
+│   │   └── {module}-specific.middleware.ts
+│   └── __tests__/
+│       ├── {module}.controller.spec.ts    ← Endpoint tests
+│       ├── {module}.service.spec.ts       ← Business logic tests
+│       └── {module}.repository.spec.ts    ← Data access tests
+```
+
+### 2.8 Controller Pattern
+
+Controllers are THIN — they validate input, call the service, and return the response. No business logic here.
+
+```typescript
+// services/patient/src/controllers/patient.controller.ts
+
+@Controller('patients')
+export class PatientController {
+  constructor(private readonly patientService: PatientService) {}
+
+  @Get()
+  @Roles('Viewer', 'Admin')
+  async findAll(@Query() query: ListPatientsQueryDto): Promise<ApiResponse<PatientResponseDto[]>> {
+    const result = await this.patientService.findAll(query)
+    return { success: true, data: result.data, error: null, meta: result.meta }
+  }
+
+  @Post()
+  @Roles('Admin')
+  async create(@Body() dto: CreatePatientDto, @CurrentUser() user: AuthUser): Promise<ApiResponse<PatientResponseDto>> {
+    const patient = await this.patientService.create(dto, user)
+    return { success: true, data: patient, error: null }
+  }
+
+  // ... every endpoint from the conversion map
+}
+```
+
+### 2.9 Service Pattern
+
+Services contain ALL business logic. Every rule from `BUSINESS_RULES.md` is implemented here with a comment referencing the rule ID.
+
+```typescript
+// services/patient/src/services/patient.service.ts
+
+export class PatientService {
+  constructor(
+    private readonly patientRepo: PatientRepository,
+    private readonly eventPublisher: EventPublisher,
+  ) {}
+
+  async create(dto: CreatePatientDto, user: AuthUser): Promise<PatientResponseDto> {
+    // Rule patient.001: NHI must be 3 letters + 4 digits
+    // (Already validated by DTO schema, but double-check at service level)
+    if (!/^[A-Z]{3}\d{4}$/.test(dto.nhi)) {
+      throw new BusinessError(ErrorCodes.PATIENT_NHI_INVALID_FORMAT, 'NHI must be 3 letters + 4 digits')
+    }
+
+    // Rule patient.002: NHI must be unique
+    const existing = await this.patientRepo.findByNhi(dto.nhi)
+    if (existing) {
+      throw new BusinessError(ErrorCodes.PATIENT_NHI_DUPLICATE, 'Patient with this NHI already exists')
+    }
+
+    // Rule patient.003: DOB cannot be in the future
+    if (new Date(dto.dateOfBirth) > new Date()) {
+      throw new BusinessError(ErrorCodes.PATIENT_DOB_FUTURE, 'Date of birth cannot be in the future')
+    }
+
+    // Rule patient.012: Email required if notification pref is email
+    if (dto.notificationPref === 'email' && !dto.email) {
+      throw new BusinessError(ErrorCodes.PATIENT_EMAIL_REQUIRED, 'Email required for email notifications')
+    }
+
+    // Call the legacy SP — it handles audit logging and additional DB-level validation
+    const result = await this.patientRepo.createViaStoredProcedure(dto)
+
+    // Publish event for other services
+    await this.eventPublisher.publish<PatientCreatedEvent>({
+      type: 'patient.created',
+      payload: { patientId: result.id, nhi: dto.nhi, createdBy: user.id },
+      timestamp: new Date().toISOString(),
+      correlationId: user.correlationId,
+    })
+
+    return result
+  }
+}
+```
+
+### 2.10 Repository Pattern
+
+Repositories handle data access — both ORM and stored procedures.
+
+```typescript
+// services/patient/src/repositories/patient.repository.ts
+
+export class PatientRepository {
+  constructor(
+    private readonly prisma: PrismaClient,
+    private readonly sp: typeof import('@project/db-client/stored-procedures/patient.sp'),
+  ) {}
+
+  // Simple query — use Prisma
+  async findByNhi(nhi: string): Promise<PatientRow | null> {
+    return this.prisma.patient.findUnique({ where: { nhi } })
+  }
+
+  // Complex query — call legacy SP
+  async search(filters: SearchFilters): Promise<PatientRow[]> {
+    const result = await this.sp.spSearchPatients(filters)
+    return result.recordsets[0]
+  }
+
+  // Creation — call legacy SP (has audit triggers and additional validation)
+  async createViaStoredProcedure(dto: CreatePatientDto): Promise<PatientRow> {
+    const result = await this.sp.spCreatePatient({
+      nhi: dto.nhi,
+      firstName: dto.firstName,
+      lastName: dto.lastName,
+      dateOfBirth: new Date(dto.dateOfBirth),
+      gender: dto.gender,
+      email: dto.email || null,
+      phone: dto.phone || null,
+    })
+    return result.recordsets[0][0]
+  }
+}
+```
+
+### 2.11 Test Generation
+
+For EVERY business rule, generate a test:
+
+```typescript
+// services/patient/src/__tests__/patient.service.spec.ts
+
+describe('PatientService', () => {
+  // Rule patient.001
+  it('should reject NHI with invalid format', async () => {
+    await expect(service.create({ ...validDto, nhi: 'INVALID' }, mockUser))
+      .rejects.toThrow('NHI must be 3 letters + 4 digits')
+  })
+
+  // Rule patient.002
+  it('should reject duplicate NHI', async () => {
+    patientRepo.findByNhi.mockResolvedValue(existingPatient)
+    await expect(service.create(validDto, mockUser))
+      .rejects.toThrow('Patient with this NHI already exists')
+  })
+
+  // Rule patient.003
+  it('should reject future date of birth', async () => {
+    const futureDate = new Date(Date.now() + 86400000).toISOString()
+    await expect(service.create({ ...validDto, dateOfBirth: futureDate }, mockUser))
+      .rejects.toThrow('Date of birth cannot be in the future')
+  })
+
+  // Rule patient.012
+  it('should require email when notification preference is email', async () => {
+    await expect(service.create({ ...validDto, notificationPref: 'email', email: '' }, mockUser))
+      .rejects.toThrow('Email required for email notifications')
+  })
+
+  // ... one test per business rule
+})
+```
+
+### 2.12 Update Gateway Routes
+
+After the module service is built, add it to the gateway:
+
+```typescript
+// Add to gateway.config.ts
+{ pathPrefix: '/api/patients', target: process.env.PATIENT_SERVICE_URL!, auth: 'required' },
+```
+
+Remove or comment out the legacy .NET route for this module.
+
+### 2.13 API Contract Test
+
+Before switching traffic, verify the Node.js service returns identical responses to the .NET service:
+
+```typescript
+// Contract test — run against BOTH services, compare responses
+
+describe('API Contract: Patient Module', () => {
+  const legacyUrl = process.env.LEGACY_URL
+  const newUrl = process.env.NEW_SERVICE_URL
+
+  it('GET /api/patients should return same shape', async () => {
+    const legacyResponse = await axios.get(`${legacyUrl}/api/patients`)
+    const newResponse = await axios.get(`${newUrl}/api/patients`)
+
+    // Same status code
+    expect(newResponse.status).toBe(legacyResponse.status)
+
+    // Same response shape (field names and types, not exact values)
+    expect(Object.keys(newResponse.data[0])).toEqual(Object.keys(legacyResponse.data[0]))
+  })
+
+  // ... for every endpoint in the module
+})
+```
+
+### 2.14 Deliver the Module
+
+After building, present:
+
+```markdown
+## Module Conversion Complete: {Module Name}
+
+### Endpoints Converted: {count}
+| Endpoint | Status | Tests |
+|----------|--------|-------|
+| GET /api/patients | ✅ Converted | 5 tests |
+| POST /api/patients | ✅ Converted | 8 tests |
+
+### Business Rules Preserved: {count}
+| Rule ID | Rule | Test |
+|---------|------|------|
+| patient.001 | NHI format validation | ✅ Tested |
+| patient.002 | NHI uniqueness | ✅ Tested |
+
+### Stored Procedures: {count}
+| SP | Approach | Reason |
+|----|----------|--------|
+| usp_CreatePatient | Direct call | Audit triggers |
+| usp_SearchPatients | Direct call | Complex dynamic SQL |
+
+### Gateway Updated: Yes
+### Docker Added: Yes
+### Contract Tests: {pass/fail}
+
+### Next Module Recommendation: {module name} because {reason}
+```
+
+---
+
+## Step 3: Repeat for Each Module
+
+Go back to Step 2.1 and ask the user which module to convert next. Each time:
+1. The user picks the module
+2. You execute the full protocol (2.1 through 2.14)
+3. The gateway gets one more route
+4. The legacy .NET handles one fewer module
+5. Eventually all traffic is on Node.js
+
+---
+
+## Quality Gate Per Module
+
+Before delivering any module, verify:
+
+- [ ] Every endpoint from the legacy module's API_REGISTRY.md section is implemented
+- [ ] Every business rule from BUSINESS_RULES.md is implemented with a comment referencing the rule ID
+- [ ] Every business rule has at least one test
+- [ ] Stored procedures that contain complex logic are called directly, not rewritten
+- [ ] Simple queries are handled by Prisma for type safety
+- [ ] Input validation matches the legacy validation exactly (same field constraints, same error messages)
+- [ ] Error responses match the legacy error codes (or map cleanly to the new ErrorCodes enum)
+- [ ] Auth requirements match the legacy role requirements
+- [ ] Gateway route is configured
+- [ ] Docker container builds and runs
+- [ ] Contract tests pass against the legacy service
+
+---
+
+## Handling Modules That Call Each Other
+
+When converting a module that depends on an unconverted module:
+
+1. **If the dependency is on a .NET module not yet converted**: The gateway handles this — the calling service makes an HTTP call to the gateway, which routes to the legacy .NET service. The caller doesn't need to know whether the target is .NET or Node.js.
+
+2. **If the dependency is on a module already converted**: Direct HTTP call or event, depending on the communication mapping from Step 2.6.
+
+3. **If the dependency is circular**: Flag it. Circular dependencies between microservices are an architectural smell. Recommend extracting the shared concern into its own service or using events to break the cycle.