Merge pull request #49 from bwmirek-tsh/copilot-instructions

Add Copilot Instructions

Author: sethii

.github/copilot-instructions.md

@@ -0,0 +1,127 @@
+# Coding Guidelines for Serverless TypeScript Application
+
+## Project Overview
+
+This repository is a serverless application boilerplate using AWS Lambda functions, TypeScript, and the Serverless Framework. It follows modern serverless patterns and best practices for building scalable applications on AWS infrastructure.
+
+## Code Architecture
+
+### Key Patterns
+- **Serverless Functions**: Individual Lambda functions with specific responsibilities, each in its own directory
+- **Microservices approach**: Each function handles a specific business capability
+- **Dependency Injection**: Functions receive dependencies as parameters for better testability
+- **Middleware-based processing**: Uses Middy middleware for cross-cutting concerns
+- **Schema validation**: Zod schemas for input validation and type safety
+
+### Project Structure
+```
+functions/
+├── [function-name]/          # Each function has its own directory
+│   ├── handler.ts            # Main lambda handler with middleware
+│   ├── service.ts            # Business logic (optional)
+│   ├── service.spec.ts       # Unit tests for service
+│   ├── event.schema.ts       # Zod validation schema
+│   ├── function.yml          # Serverless configuration
+│   └── config/
+│       └── index.ts          # Environment configuration
+shared/
+├── config/                   # Database and shared configuration
+├── errors/                   # Custom error classes
+├── middleware/               # Reusable middleware functions
+├── models/                   # TypeORM database models
+├── repositories/             # Data access layer
+├── utils/                    # Shared utility functions
+└── logger/                   # Winston logging setup
+workflows/
+├── [workflow-name]/          # Step Functions workflows
+│   ├── workflow.yml          # Step Function definition
+│   └── workflow.asl.yml      # Amazon States Language
+migrations/                   # TypeORM database migrations
+```
+
+### Key Libraries and Functionalities
+- **TypeScript**: For static typing and modern JavaScript features
+- **Serverless Framework**: For deployment and infrastructure management
+- **AWS Lambda**: Function compute platform
+- **AWS Step Functions**: Workflow orchestration
+- **Middy**: Lambda middleware framework for Node.js
+- **TypeORM**: ORM for PostgreSQL database interactions
+- **Zod**: Schema validation and type inference
+- **Winston**: Structured logging
+- **AWS SDK v3**: AWS service clients
+- **PostgreSQL**: Primary database
+- **DynamoDB**: NoSQL database for high-performance data storage
+- **Mocha + Sinon**: Testing framework and mocking
+
+### Key Development Guidelines
+
+#### General Guidelines
+- Always use TypeScript for type safety
+- Follow serverless best practices and patterns
+- Use dependency injection for all external dependencies
+- All environment variables must be extracted and validated using Zod in function config files
+- Use the provided middleware stack for all Lambda functions
+- Keep functions focused on single responsibilities
+
+#### Naming Guidelines
+- Function directories: Use **kebab-case** (e.g., `create-transaction`, `get-exchange-rates`)
+- File names: Use **kebab-case** with appropriate suffixes (e.g., `handler.ts`, `service.ts`)
+- Variables and functions: Use **camelCase** (e.g., `getUserById`, `transactionData`)
+- Classes and interfaces: Use **PascalCase** (e.g., `TransactionModel`, `PaymentService`)
+- Database columns: Use **snake_case** for TypeORM entity properties
+- Schema names: Use **camelCase** with "Schema" suffix (e.g., `createTransactionSchema`)
+- AWS resources: Use descriptive names with service prefixes
+
+#### Lambda Function Guidelines
+- All handlers must use the standard Middy middleware stack
+- Initialize database connections and AWS clients outside the handler function
+- Use dependency injection - pass all dependencies to service functions
+- Validate all inputs with Zod schemas
+- Use existing error classes from `shared/errors/`
+- Keep handlers thin - move business logic to service functions
+- Never create tests for handlers - only test service logic
+
+#### Database Guidelines
+- Use **TypeORM** for PostgreSQL interactions
+- Use **UUID v4** for primary keys, avoid auto-increment IDs
+- Models must have `.model.ts` suffix and include factory methods
+- Always generate migrations
+- Migrations are auto-executed at application start
+- Pass repositories to service functions, never import directly
+
+#### AWS Integration Guidelines
+- Use AWS SDK v3 with command pattern
+- Initialize AWS clients outside Lambda handlers for connection reuse
+- Use Step Functions for complex workflows
+- Follow AWS security best practices
+
+#### Testing Guidelines
+- Create unit tests for service logic only (`.spec.ts` files)
+- Use Sinon for mocking AWS clients and external dependencies
+- Mock all external dependencies (databases, APIs, AWS services)
+- Test both success and error scenarios
+- Place tests next to the files they test
+
+#### Error Handling Guidelines
+- Use existing error classes
+- Throw errors as exceptions - middleware handles responses
+- Include meaningful error messages with context
+
+#### Security Guidelines
+- Never expose sensitive information in error messages
+- Validate all inputs with Zod schemas
+- Use proper IAM roles and permissions
+- Store secrets in AWS Parameter Store or Secrets Manager
+- Enable CORS only when necessary and configure properly
+
+#### Middleware Guidelines
+- Always use the standard middleware stack in correct order
+- For non-HTTP triggers, omit HTTP-specific middleware
+- Use custom middleware sparingly and document well
+
+#### Workflow Guidelines
+- Use Step Functions for complex business processes
+- Define workflows in Amazon States Language (ASL)
+- Each step should be a focused Lambda function
+- Handle errors and retries at the workflow level
+- Use Task Tokens for human-in-the-loop processes

.github/instructions/lambda-configuration.instructions.md

@@ -0,0 +1,39 @@
+---
+applyTo: "**/functions/*/config/index.ts"
+---
+
+## Configuration Structure
+- All functions must have a `config/index.ts` file for environment variable handling
+- Always use Zod for configuration validation
+- Use the pipeline pattern with `ts-pipe-compose`
+
+## Basic Configuration Template
+```typescript
+import { z } from "zod";
+import { pipeline } from "ts-pipe-compose";
+
+const loadEnvs = (env: any) => ({
+  appName: env.APP_NAME,
+  // Add other environment variables here
+});
+
+const validateConfig = (config: any) => {
+  const schema = z.object({
+    appName: z.string().min(1),
+    // Add validation for other variables
+  });
+
+  try {
+    return schema.parse(config);
+  } catch (error) {
+    throw new Error(error as string);
+  }
+};
+
+export const createConfig = pipeline(loadEnvs, validateConfig);
+```
+
+## Environment Variable Naming
+- Use SCREAMING_SNAKE_CASE for environment variable names
+- Be descriptive: `EXCHANGE_RATES_API_URL` not `API_URL`
+- Include service name: `PAYMENT_SERVICE_API_KEY`

.github/instructions/lambda-handlers.instructions.md

@@ -0,0 +1,25 @@
+---
+applyTo: "**/functions/*/handler.ts"
+---
+
+## Lambda Handler Structure
+- All handlers must have a `.handler.ts` suffix
+- Always use the middy middleware framework with the standard middleware stack (see lambda-middleware.instructions.md)
+- Export the handler as `handle`
+
+## Response Format
+- Always use `awsLambdaResponse` helper for consistent response formatting:
+```typescript
+import { awsLambdaResponse } from "../../shared/aws";
+import { StatusCodes } from "http-status-codes";
+
+return awsLambdaResponse(StatusCodes.OK, {
+  success: true,
+  data: result,
+});
+```
+
+## Business Logic Separation
+- Extract complex business logic into separate service functions
+- Pass all dependencies (clients, repositories, config) to service functions
+- Keep handlers thin - they should only handle HTTP concerns and orchestration

.github/instructions/lambda-middleware.instructions.md

@@ -0,0 +1,43 @@
+---
+applyTo: "**/functions/*/handler.ts"
+---
+
+## Middleware Stack
+Always use middleware in this specific order for consistency:
+
+```typescript
+import middy from "@middy/core";
+import httpEventNormalizer from "@middy/http-event-normalizer";
+import httpHeaderNormalizer from "@middy/http-header-normalizer";
+import jsonBodyParser from "@middy/http-json-body-parser";
+import { inputOutputLoggerConfigured } from "../../shared/middleware/input-output-logger-configured";
+import { zodValidator } from "../../shared/middleware/zod-validator";
+import { queryParser } from "../../shared/middleware/query-parser";
+import { httpCorsConfigured } from "../../shared/middleware/http-cors-configured";
+import { httpErrorHandlerConfigured } from "../../shared/middleware/http-error-handler-configured";
+
+export const handle = middy()
+  .use(jsonBodyParser())                    // 1. Parse JSON body
+  .use(inputOutputLoggerConfigured())       // 2. Log inputs and outputs
+  .use(httpEventNormalizer())               // 3. Normalize HTTP events
+  .use(httpHeaderNormalizer())              // 4. Normalize HTTP headers
+  .use(httpCorsConfigured)                  // 5. Handle CORS
+  .use(queryParser())                       // 6. Parse query parameters (optional)
+  .use(zodValidator(yourLambdaSchema))      // 7. Validate input schema
+  .use(httpErrorHandlerConfigured)          // 8. Handle errors (MUST BE LAST)
+  .handler(lambdaHandler);
+```
+
+## Middleware Rules
+- `httpErrorHandlerConfigured` must always be the last middleware
+- `jsonBodyParser()` should be first for HTTP endpoints that accept JSON
+- `queryParser()` is optional - only include if your function uses query parameters
+- `zodValidator()` should come after all parsers but before error handler
+
+## Optional Middleware
+- Include `queryParser()` only if your event schema includes `queryStringParameters`
+- For non-HTTP triggers (SQS, EventBridge), omit HTTP-specific middleware:
+  - Skip `httpEventNormalizer()`
+  - Skip `httpHeaderNormalizer()`
+  - Skip `httpCorsConfigured`
+  - Skip `queryParser()`

.github/instructions/lambda-schemas.instructions.md

@@ -0,0 +1,13 @@
+---
+applyTo: "**/functions/*/event.schema.ts"
+---
+
+## Event Schema Structure
+- All event schemas must have a `.event.schema.ts` suffix
+- Always use Zod for input validation and type generation
+- Export both the schema and the inferred type
+
+## Naming Conventions
+- Schema names: `camelCase` with "Schema" suffix (e.g., `createTransactionSchema`)
+- Type names: `PascalCase` with "Payload" suffix (e.g., `CreateTransactionPayload`)
+- Use descriptive names that match the function purpose

.github/instructions/lambda-serverless-config.instructions

@@ -0,0 +1,14 @@
+---
+applyTo: "**/functions/*/function.yml"
+---
+
+## Serverless Function Configuration
+Each function must have a `function.yml` file with proper serverless framework configuration.
+
+## Environment Variables
+Always include required environment variables:
+
+## Naming Conventions
+- Function names: Use `kebab-case` matching the directory name
+- Handler path: Always `functions/{function-name}/handler.handle`
+- Environment variables: Use `SCREAMING_SNAKE_CASE`

.github/instructions/lambda-services.instructions.md

@@ -0,0 +1,34 @@
+---
+applyTo: "**/functions/*/service.ts"
+---
+
+## Service Layer Principles
+- Extract complex business logic into separate `service.ts` files
+- Services should be pure functions that accept all dependencies as parameters
+- Never import dependencies directly in services - use dependency injection
+
+## Error Handling
+- Use existing error classes from `shared/errors/` (see lambda-error-handling.instructions.md)
+- Validate business rules and throw appropriate errors
+- Let the middleware handle error responses
+
+## AWS SDK Integration
+- Use AWS SDK v3 with command pattern
+- Always pass clients as parameters
+- Handle AWS SDK errors appropriately:
+
+## Database Operations
+- Always pass repositories as parameters
+- Use TypeORM query builder for complex queries:
+
+## Business Logic Validation
+- Validate business rules before database operations
+- Use domain-specific errors for business rule violations:
+
+## Return Values
+- Return only the data needed by the handler
+- Don't return entire entities if only ID is needed
+- Use meaningful return types:
+
+## Utility Integration
+- Pass utility classes as parameters when needed:

.github/instructions/lambda-testing.instructions.md

@@ -0,0 +1,24 @@
+---
+applyTo: "**/functions/*/*.spec.ts"
+---
+
+## Testing Lambda Services
+- Create unit tests for services in `.spec.ts` files placed next to the service file
+- Test file naming: `service.spec.ts` for `service.ts`
+- Never create tests for handlers - only test service logic
+
+## What NOT to Test
+- Don't test middleware behavior (it's tested separately)
+- Don't test AWS SDK internals
+- Don't test TypeORM internals
+- Don't test validation schemas (Zod handles this)
+- Don't test handler functions (keep them thin)
+
+## Test Coverage
+Ensure you test:
+- Happy path scenarios
+- All error conditions
+- Edge cases (empty data, boundary values)
+- Business rule validations
+- External service interactions
+- Database operations

.github/instructions/lambda.instructions.md

@@ -0,0 +1,56 @@
+---
+applyTo: "**/functions/**/*"
+---
+
+# Serverless Lambda Development Guidelines
+
+This is the main entry point for serverless lambda development instructions. Follow the specific guidelines based on the file you're working with:
+
+## Quick Reference by File Type
+
+### Handler Files (`handler.ts`)
+See: [lambda-handlers.instructions.md](lambda-handlers.instructions.md)
+- Main lambda entry point with middleware configuration
+- Database connection handling
+- AWS client initialization
+- Response formatting
+
+### Middleware Configuration
+See: [lambda-middleware.instructions.md](lambda-middleware.instructions.md)
+- Standard middy middleware stack
+- Proper middleware ordering
+- HTTP vs non-HTTP lambda configurations
+
+### Event Schemas (`event.schema.ts`)
+See: [lambda-schemas.instructions.md](lambda-schemas.instructions.md)
+- Zod validation schemas
+- Type generation
+- Common validation patterns
+
+### Configuration (`config/index.ts`)
+See: [lambda-configuration.instructions.md](lambda-configuration.instructions.md)
+- Environment variable handling
+- Configuration validation
+- Pipeline pattern implementation
+
+### Service Layer (`service.ts`)
+See: [lambda-services.instructions.md](lambda-services.instructions.md)
+- Business logic separation
+- Dependency injection patterns
+- AWS SDK integration
+
+### Testing (`*.spec.ts`)
+See: [lambda-testing.instructions.md](lambda-testing.instructions.md)
+- Unit testing with Sinon
+- Mocking AWS services
+- Test structure and patterns
+
+## Development Workflow
+
+1. **Create Function Structure**: Use the plop template or create the required files manually
+2. **Define Event Schema**: Start with `event.schema.ts` to define input validation
+3. **Configure Environment**: Set up `config/index.ts` with required environment variables
+4. **Implement Handler**: Create the main `handler.ts` with middleware stack
+5. **Add Business Logic**: If complex, create `service.ts` with business logic
+6. **Write Tests**: Create `service.spec.ts` for testing business logic
+7. **Configure Serverless**: Set up `function.yml` with proper events and settings