Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
163 changes: 163 additions & 0 deletions .github/copilot-instructions.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
# Lambda Starter Project Instructions

## Project Overview

This is an AWS Lambda serverless starter project written in **Node.js** and **TypeScript**. The project uses the **AWS CDK** for infrastructure as code. The project uses **Jest** for unit tests of the infrastructure and application code.

---

## Technology Stack

Each pattern project uses the following technology stack:

- **Language:** TypeScript
- **Platform:** AWS Lambda
- **Runtime:** Node.js 24+
- **AWS SDK:** v3 (modular packages)
- **Testing:** Jest
- **Linting/Formatting:** ESLint + Prettier
- **Validation:** Zod
- **Logging:** Pino + Pino-Lambda
- **Package Manager:** npm
- **Infrastructure:** AWS CDK
- **DevOps:** GitHub Actions

---

## Project Structure

The project follows a consistent directory and file structure to promote maintainability and scalability. Below is the high-level structure:

```
/docs # Project documentation
README.md # Documentation table of contents

/src
/handlers
get-task.ts # Lambda handler
get-task.test.ts # Unit tests for get-task
/services
task-service.ts # Business logic
task-service.test.ts # Unit tests for task-service
/models
task.ts # Task data model
/utils
dynamodb-client.ts # AWS SDK client for DynamoDB
config.ts # App configuration helper
response.ts # Helper for formatting Lambda responses
response.test.ts

/infrastructure
/stacks
lambda-stack.ts # CDK stack for Lambdas
lambda-stack.test.ts # Unit tests for lambda-stack
/utils
config.ts # CDK config helper
config.test.ts # Unit tests for CDK config helper
app.ts # CDK app entry point
cdk.json # CDK config
jest.config.ts # CDK Jest config
jest.setup.ts # CDK Jest setup
package.json # CDK NPM package config
README.md # CDK README
tsconfig.json # CDK TypeScript config

.editorconfig # Editor config
.gitignore # Git ignore rules
.nvmrc # Node version manager config
.prettierrc # Prettier config
eslint.config.mjs # ESLint config
jest.config.ts # App Jest config
jest.setup.ts # App Jest setup
package.json # App NPM package config
README.md # Project README
tsconfig.json # Project TypeScript config
```

---

## Source Code Guidelines

The project follows best practices for source code organization, naming conventions, and coding standards. Below are the key guidelines:

- Use **TypeScript** for all source and infrastructure code.
- Use arrow functions for defining functions.
- Use path aliases for cleaner imports (e.g., `@/utils`, `@/models`).
- Handlers parse input, call services, and return responses reside in `/handlers`.
- Core business logic should reside in `/services`.
- Create types and interfaces in `/models` for data structures and DTOs.
- Create reusable utilities in `/utils` (e.g., AWS clients, response helpers, config helpers, logging).
- Validate configuration and input data with **Zod**.
- Organize import statements: external packages first, then internal modules.
- Use async/await for asynchronous operations.
- Handle errors gracefully and return meaningful error responses.
- Document functions and modules with JSDoc comments.

### Source Code Commands & Scripts

- Use `npm run build` to compile TypeScript.
- Use `npm run test` to run tests.
- Use `npm run test:coverage` to run tests with coverage report.
- Use `npm run lint` to run ESLint.
- Use `npm run lint:fix` to fix ESLint issues.
- Use `npm run format` to run Prettier to format code.
- Use `npm run format:check` to check code formatting with Prettier.

---

## Unit Testing Guidelines

The project includes comprehensive unit tests for both application and infrastructure code. Below are the key guidelines for writing unit tests:

- Use the **Jest** testing framework.
- Place test files next to the source file, with `.test.ts` suffix.
- Use `describe` and `it` blocks for organization.
- Use `beforeEach` for setup and `afterEach` for cleanup.
- Use `expect` assertions for results.
- Mock dependencies to isolate the component under test.
- Mock external calls (e.g., AWS SDK, databases).
- Structure your tests using the Arrange-Act-Assert pattern:
- **Arrange:** Set up the test environment, including any necessary mocks and test data.
- **Act:** Execute the function or service being tested.
- **Assert:** Verify that the results are as expected.
- Add comments to separate these sections for clarity.

---

## AWS CDK Guidelines

The project uses AWS CDK for infrastructure as code. Below are the key guidelines for using AWS CDK:

- Design philosophy prioritizes cost efficiency, scalability, and security.
- Self-contained AWS CDK project for infrastructure as code.
- Use **TypeScript** for all infrastructure code.
- Use **AWS CDK v2**.
- Define one CDK stack per major grouping of resources (e.g., lambda stack, data stack).
- Never commit secrets or hardcoded credentials.
- Use **.env** for local development configuration, but do not commit to source control.
- Use **.env.example** to document required environment variables.
- Prefix environment variables with `CDK_` to avoid conflicts.
- Use **AWS SSM Parameter Store** for secure configuration.
- All CDK resources must be tagged for cost allocation and management:
- `App`: Application name
- `Env`: Environment (e.g., dev, qat, prd)
- `OU`: Organizational Unit, e.g. `leanstacks` or `shared-services`
- `Owner`: Team or individual responsible
- Tag all CDK resources appropriately (`App`, `Env`, `OU`, `Owner`).

### DynamoDB Tables

- Prefer using single-table design where feasible.
- Use composite primary keys (partition key + sort key) for efficient querying.

### Lambda Functions

- Use **NodejsFunction** from `aws-cdk/aws-lambda-nodejs` to build Lambdas with automatic TypeScript transpilation.

### AWS CDK Commands & Scripts

- Use `npm run build` to compile TypeScript.
- Use `npm run test` to run tests.
- Use `npm run test:coverage` to run tests with coverage report.
- Use `npm run synth` to synthesize CDK stacks.
- Use `npm run cdk <command>` to run CDK commands (e.g., deploy, diff).
48 changes: 0 additions & 48 deletions .github/instructions/cdk.instructions.md

This file was deleted.

82 changes: 0 additions & 82 deletions .github/instructions/main.instructions.md

This file was deleted.

28 changes: 0 additions & 28 deletions .github/instructions/src.instructions.md

This file was deleted.

27 changes: 0 additions & 27 deletions .github/instructions/test.instructions.md

This file was deleted.

1 change: 1 addition & 0 deletions infrastructure/jest.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ const config: Config = {
testMatch: ['**/*.test.ts'],
collectCoverageFrom: [
'**/*.ts',
'!app.ts',
'!**/*.test.ts',
'!**/*.spec.ts',
'!**/node_modules/**',
Expand Down
Loading