pos-system/.agent/rules/microservices-development-process.md

trigger

trigger
always_on

Microservices Development Process

When to Use This Skill

Use this skill when:

• Creating a new microservice from scratch
• Migrating or refactoring an existing service
• Planning service implementation with multiple phases
• Ensuring comprehensive coverage of all development aspects
• Need structured approach to service development

Development Process Overview

The microservices development process follows these phases:

1. Planning & Impact Analysis - Define scope, impact, dependencies
2. Foundation Setup - Service structure, configs, infrastructure
3. Core Implementation - Business logic, APIs, data layer
4. Integration - Routes, middleware, external services
5. Testing - Unit, integration, E2E tests
6. Documentation - API docs, README, guides
7. Cleanup & Verification - Remove temporary files, verify completeness
8. Deployment - Staging deployment, production deployment

Process Flow Diagram

graph TD
    Start([Start: New Service Requirements]) --> Phase1[Phase 1: Planning & Impact Analysis]
    Phase1 --> ImpactCheck{Impact Analysis<br/>Complete?}
    ImpactCheck -->|No| Phase1
    ImpactCheck -->|Yes| Phase2[Phase 2: Foundation Setup]
    
    Phase2 --> FoundationCheck{Service Starts<br/>& Health Check Passes?}
    FoundationCheck -->|No| Phase2
    FoundationCheck -->|Yes| Phase3[Phase 3: Core Implementation]
    
    Phase3 --> ImplementationCheck{Business Logic<br/>Implemented?}
    ImplementationCheck -->|No| Phase3
    ImplementationCheck -->|Yes| Phase4[Phase 4: Integration]
    
    Phase4 --> IntegrationCheck{Routes & Middleware<br/>Working?}
    IntegrationCheck -->|No| Phase4
    IntegrationCheck -->|Yes| Phase5[Phase 5: Testing]
    
    Phase5 --> TestCheck{Tests Pass<br/>& Coverage Met?}
    TestCheck -->|No| Phase5
    TestCheck -->|Yes| Phase6[Phase 6: Documentation]
    
    Phase6 --> DocCheck{Docs<br/>Complete?}
    DocCheck -->|No| Phase6
    DocCheck -->|Yes| Phase7[Phase 7: Cleanup & Verification]
    
    Phase7 --> VerificationCheck{All Checks<br/>Pass?}
    VerificationCheck -->|No| Phase7
    VerificationCheck -->|Yes| Phase8[Phase 8: Deployment]
    
    Phase8 --> DeployCheck{Staging<br/>Deployed?}
    DeployCheck -->|No| Phase8
    DeployCheck -->|Yes| Production{Deploy to<br/>Production?}
    Production -->|Yes| ProdDeploy[Production Deployment]
    Production -->|No| Complete([Complete])
    ProdDeploy --> Complete
    
    style Phase1 fill:#e1f5ff
    style Phase2 fill:#fff4e1
    style Phase3 fill:#f0e1ff
    style Phase4 fill:#e1ffe1
    style Phase5 fill:#ffe1e1
    style Phase6 fill:#e1ffff
    style Phase7 fill:#fff0e1
    style Phase8 fill:#ffe1f5
    style Complete fill:#d4edda

Detailed Phase Flow

graph LR
    subgraph Planning["Phase 1: Planning"]
        P1A[Define Scope] --> P1B[Impact Analysis]
        P1B --> P1C[Dependencies Map]
        P1C --> P1D[Acceptance Criteria]
    end
    
    subgraph Foundation["Phase 2: Foundation"]
        F2A[Copy Template] --> F2B[Configure Package]
        F2B --> F2C[Setup Database]
        F2C --> F2D[Configure Docker]
        F2D --> F2E[Setup Traefik]
    end
    
    subgraph Implementation["Phase 3: Implementation"]
        I3A[DTOs] --> I3B[Repository]
        I3B --> I3C[Service]
        I3C --> I3D[Controller]
        I3D --> I3E[Module]
    end
    
    subgraph Integration["Phase 4: Integration"]
        IN4A[Register Routes] --> IN4B[Setup Middleware]
        IN4B --> IN4C[External Services]
        IN4C --> IN4D[Health Checks]
    end
    
    subgraph Testing["Phase 5: Testing"]
        T5A[Unit Tests] --> T5B[Integration Tests]
        T5B --> T5C[E2E Tests]
        T5C --> T5D[Coverage Check]
    end
    
    subgraph Documentation["Phase 6: Documentation"]
        D6A[README] --> D6B[API Docs]
        D6B --> D6C[Architecture Docs]
    end
    
    subgraph Cleanup["Phase 7: Cleanup"]
        C7A[Remove Temp Files] --> C7B[Update References]
        C7B --> C7C[Verify Everything]
    end
    
    subgraph Deployment["Phase 8: Deployment"]
        DEP8A[Staging] --> DEP8B[Verification]
        DEP8B --> DEP8C[Production]
    end
    
    Planning --> Foundation
    Foundation --> Implementation
    Implementation --> Integration
    Integration --> Testing
    Testing --> Documentation
    Documentation --> Cleanup
    Cleanup --> Deployment
    
    style Planning fill:#e1f5ff
    style Foundation fill:#fff4e1
    style Implementation fill:#f0e1ff
    style Integration fill:#e1ffe1
    style Testing fill:#ffe1e1
    style Documentation fill:#e1ffff
    style Cleanup fill:#fff0e1
    style Deployment fill:#ffe1f5

Phase 1: Planning & Impact Analysis

Scope Definition

Define clearly:

• Service Purpose: What business capability does it provide?
• API Surface: What endpoints are needed?
• Data Models: What data structures are required?
• Dependencies: What services/packages does it depend on?
• Breaking Changes: Any backward compatibility concerns?

Impact Analysis Checklist

Before starting implementation, identify all affected areas:

Files to Create:

• Service directory: services/service-name/
• Prisma schema: services/service-name/prisma/schema.prisma
• Dockerfile: services/service-name/Dockerfile
• Service README: services/service-name/README.md

Files to Update:

• Root package.json workspace config
• deployments/local/docker-compose.yml - Add service
• infra/traefik/dynamic/routes.yml - Add routes
• .github/workflows/ci-*.yml - Add CI workflow (if needed)
• Documentation: docs/en/guides/, docs/vi/guides/
• Scripts: scripts/db/*.sh, scripts/dev/*.sh (if service-specific)

Infrastructure Changes:

• Database: New schema/tables
• Redis: New cache keys/patterns (if needed)
• Traefik: New routes and services
• Observability: New service metrics/traces

Dependencies:

• External: Database, Redis, third-party APIs
• Internal: Shared packages (@goodgo/logger, @goodgo/types, etc.)
• Other Services: List dependent services

Phase 2: Foundation Setup

Service Structure Creation

Template Usage:

cp -r services/_template services/new-service-name
cd services/new-service-name
# Update package.json name to @goodgo/new-service-name

Required Files:

• Service structure from template
• package.json with correct name and dependencies
• src/config/app.config.ts - Configuration with Zod validation
• .env.example - Environment variables template
• prisma/schema.prisma - Database schema
• Dockerfile - Container configuration
• jest.config.ts - Test configuration

Database Setup

# Create initial migration
cd services/service-name
pnpm prisma migrate dev --name init
pnpm prisma generate

Docker & Infrastructure

Docker Compose Integration: Add service to deployments/local/docker-compose.yml with:

• Build context and dockerfile
• Environment variables
• Traefik labels for routing
• Health check configuration

Traefik Routes: Update infra/traefik/dynamic/routes.yml with:

• Router rules (PathPrefix)
• Service configuration
• Middleware chain (CORS, rate-limit, auth)

Acceptance Criteria for Phase 2

• Service directory created from template
• package.json configured correctly
• Environment variables defined
• Prisma schema created and migration run
• Service starts: pnpm dev (health check passes)
• Docker build succeeds
• Service accessible via Traefik
• No TypeScript errors: pnpm typecheck

Phase 3: Core Implementation

Module Structure

Each feature module follows this pattern:

modules/feature-name/
├── feature.controller.ts    # HTTP handlers
├── feature.service.ts       # Business logic
├── feature.repository.ts    # Data access
├── feature.dto.ts          # Validation schemas (Zod)
├── feature.module.ts       # Module registration
└── index.ts                # Public exports

Implementation Flow

graph TD
    Start[Start Implementation] --> DTOs[1. Create DTOs<br/>Zod Validation Schemas]
    DTOs --> Repo[2. Create Repository<br/>Prisma Data Access]
    Repo --> Service[3. Create Service<br/>Business Logic]
    Service --> Controller[4. Create Controller<br/>HTTP Handlers]
    Controller --> Module[5. Create Module<br/>Wire Up Components]
    Module --> Test[Manual Testing]
    Test --> Pass{Tests Pass?}
    Pass -->|No| Repo
    Pass -->|Yes| Next[Next Feature Module]
    
    style DTOs fill:#e1f5ff
    style Repo fill:#fff4e1
    style Service fill:#f0e1ff
    style Controller fill:#e1ffe1
    style Module fill:#ffe1e1

Implementation Order

1. DTOs - Zod schemas for request/response validation
2. Repository - Prisma-based data access, CRUD operations
3. Service - Business logic, error handling, validation
4. Controller - HTTP request handling, standardized responses
5. Module - Wire up components, export router

Code Patterns

Repository: Extend base Repository, use Prisma client for data access Service: Inject repository, implement business logic, use logger Controller: Handle HTTP requests, validate with DTOs, call services Module: Wire up dependencies, export router

Acceptance Criteria for Phase 3

• All DTOs defined with Zod validation
• Repository methods implemented
• Service business logic implemented
• Controllers handle requests correctly
• Modules configured properly
• No TypeScript errors
• Manual API testing successful

Phase 4: Integration

Route Registration

Update src/routes/index.ts:

• Import feature modules
• Create router instances
• Register routes with path prefixes
• Mount to main app with /api/v1/service-name prefix

Middleware Setup

Required Middlewares (in order):

1. Correlation middleware
2. Logging middleware
3. Metrics middleware
4. CORS middleware
5. Rate limiting middleware
6. Authentication middleware (if needed)
7. Error middleware (always last)

External Service Integration

• HTTP clients: Use @goodgo/http-client for external APIs
• Redis caching: Implement cache patterns for frequently accessed data
• Error handling: Handle external service failures gracefully

Acceptance Criteria for Phase 4

• All routes registered and accessible
• Middlewares applied in correct order
• Error handling works for all scenarios
• External services integrated (if any)
• Caching implemented (if needed)
• Health check endpoint works: /health

Phase 5: Testing

Test Structure

Unit Tests: Next to source files (*.test.ts), mock all dependencies Integration Tests: src/__tests__/, test component interactions E2E Tests: src/__tests__/*.e2e.ts, test full API workflows

Test Coverage Targets

• Minimum: 70% coverage (branches, functions, lines, statements)
• Critical paths: 90%+ coverage
• Repositories: 80%+ coverage
• Services: 80%+ coverage
• Controllers: 70%+ coverage