# MBC CQRS Serverless Framework - Full Documentation

> Production-ready CQRS and Event Sourcing framework for building serverless applications on AWS with NestJS, DynamoDB, and other AWS services.

This file contains the full documentation content following the llmstxt.org standard.

---

# Getting Started

## CLI

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/cli

# CLI

The mbc-cqrs-serverless CLI helps you quickly scaffold new projects and generate boilerplate code for modules, services, and entities. It follows the framework's conventions to ensure consistency.

## When to Use the CLI {#when-to-use}

Use the CLI when you need to:

- Create a new MBC CQRS Serverless project from scratch
- Add a new domain module (product, order, user)
- Generate controller, service, entity, and DTO files with correct structure
- Start the local development server

## Problems the CLI Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| Setting up project structure manually is error-prone | `mbc new` creates complete project skeleton |
| Remembering correct file names and imports | `mbc generate` creates consistent boilerplate |
| Forgetting to register modules correctly | Generated code follows NestJS conventions |

## Installation {#installation}

To install the CLI globally:

```bash
npm install -g @mbc-cqrs-serverless/cli
```

## Available Commands {#available-commands}

To get a list of the available CLI commands, run the following command:

```bash
mbc -h
```

The output should look like this:

```bash
Usage: mbc <command> [options]

Options:
  -v, --version                            Output the current version.
  -h, --help                               Output usage information.

Commands:
  new|n [name]                             Generate a new CQRS application using the MBC CQRS serverless framework
  start|s                                  Start application with serverless framework
  ui-common|ui [options]                   Add mbc-cqrs-ui-common components to your project.
  generate|g [options] <schematic> [name]  Generate a MBC-cqrs-serverless element.
    Schematics available on the collection:
      ┌────────────┬───────┬──────────────────────┐
      │ name       │ alias │ description          │
      │ module     │ mo    │ Create a module.     │
      │ controller │ co    │ Create a controller. │
      │ service    │ se    │ Create a service.    │
      │ entity     │ en    │ Create an entity.    │
      │ dto        │ dto   │ Create a DTO.        │
      └────────────┴───────┴──────────────────────┘
  install-skills|skills [options]          Install Claude Code skills for MBC CQRS Serverless development
  help [command]                           display help for command
```

## new Command {#new-command}

### Use Case: Start a New Backend Project

Scenario: You're starting a new microservice or API backend and need the complete project structure with all dependencies.

```bash
mbc new [projectName[@version]]
```

### Examples

Create a new project in the current directory:

```bash
mbc new
```

Create a project with a specific name:

```bash
mbc new my-cqrs-app
```

Create a project with a specific version:

```bash
mbc new my-cqrs-app@0.1.45
```

## generate Command {#generate-command}

### Use Case: Add a New Domain to Existing Project

Scenario: Your project needs a new Order feature with API endpoints, business logic, and database entities.

Solution: Generate module, controller, service, entity, and DTO in sequence.

```bash
mbc generate <schematic> [name]
# or
mbc g <schematic> [name]
```

### Available Schematics

| Name | Alias | Description |
|------|-------|-------------|
| module | mo | Create a module |
| controller | co | Create a controller |
| service | se | Create a service |
| entity | en | Create an entity |
| dto | dto | Create a DTO |

### Options

| Option | Description |
|--------|-------------|
| `-d, --dry-run` | Report actions that would be taken without writing out results |
| `--mode <mode>` | Specify the mode of operation: sync or async (default: async) |
| `--schema` | Enable schema generation (default: true) |
| `--no-schema` | Disable schema generation |

### Examples

Generate a new module:

```bash
mbc generate module order
# or
mbc g mo order
```

Generate a controller:

```bash
mbc generate controller order
# or
mbc g co order
```

Generate a service:

```bash
mbc generate service order
# or
mbc g se order
```

Generate an entity:

```bash
mbc generate entity order
# or
mbc g en order
```

Generate a DTO:

```bash
mbc generate dto order
# or
mbc g dto order
```

Dry run (preview without creating files):

```bash
mbc g mo order --dry-run
```

## start Command {#start-command}

```bash
mbc start
# or
mbc s
```

:::warning Not Yet Implemented
The `mbc start` command is currently a placeholder and does not start a local development server yet. To run your application locally, use the npm scripts included in generated projects instead:

```bash
npm run build          # Build the application in watch mode
npm run offline:docker # Start local Docker services (DynamoDB, Cognito, etc.)
npm run offline:sls    # Start the serverless offline server
```

See [Installation](/docs/installation) for the full local development setup.
:::

## ui-common Command {#ui-common-command}

### Use Case: Add Pre-built UI Components to Frontend

Scenario: You're building a frontend and want to use the standard MBC CQRS UI component library.

```bash
mbc ui-common [options]
# or
mbc ui [options]
```

This command integrates the MBC CQRS UI Common library into your project, providing pre-built UI components and utilities.

### Options

| Option | Description |
|--------|-------------|
| `-p, --pathDir <string>` | (Required) The destination path for common-ui components |
| `-b, --branch <string>` | The branch name to clone from (default: main) |
| `--auth <string>` | The authentication method: SSH or HTTPS - Token (default: SSH) |
| `--token <string>` | The token for HTTPS authentication, format: tokenId:tokenPassword |
| `-c, --component <string>` | Component to install: all, appsync, or component (default: all) |
| `--alias` | Currently has no effect — the `@ms/*` path alias is always added to tsconfig.json regardless of this flag |

### Examples

Install all components using SSH authentication:

```bash
mbc ui-common -p src/common-ui
```

Install only UI components (excluding appsync):

```bash
mbc ui -p src/common-ui -c component
```

Install from a specific branch:

```bash
mbc ui -p src/common-ui -b develop
```

Install using HTTPS with token authentication:

```bash
mbc ui -p src/common-ui --auth "HTTPS - Token" --token "user:password"
```

## install-skills Command {#install-skills}

### Use Case: Install Claude Code Skills

Scenario: You want to use Claude Code skills for MBC CQRS Serverless development assistance.

```bash
mbc install-skills [options]
# or
mbc skills [options]
```

This command installs Claude Code skills that provide guided assistance for code generation, code review, migration, and debugging.

### Options

| Option | Description |
|--------|-------------|
| `-p, --project` | Install to project directory (`.claude/skills/`) instead of personal (`~/.claude/skills/`) |
| `-f, --force` | Overwrite existing skills |
| `-l, --list` | List available skills without installing |
| `-c, --check` | Check if updates are available without installing |

### Examples

Install to personal skills directory (available in all projects):

```bash
mbc install-skills
```

Install to project directory (shared with team via git):

```bash
mbc install-skills --project
# or
mbc skills -p
```

List available skills:

```bash
mbc install-skills --list
```

Force overwrite existing skills:

```bash
mbc install-skills --force
```

Check for updates:

```bash
mbc install-skills --check
```

### Upgrading Skills

Skills do not auto-update. To upgrade to the latest version:

```bash
# Update CLI to latest version
npm update -g @mbc-cqrs-serverless/cli

# Check if updates are available
mbc install-skills --check

# Force reinstall to get latest version
mbc install-skills --force
```

### Available Skills

| Skill | Description |
|-------|-------------|
| `/mbc-generate` | Generate boilerplate code (modules, services, controllers, DTOs, handlers) |
| `/mbc-review` | Review code for best practices and anti-patterns (22 patterns) |
| `/mbc-migrate` | Guide version migrations and breaking changes |
| `/mbc-debug` | Debug and troubleshoot common issues |

:::info Version Note
The `install-skills` command was added in [version 1.0.24](/docs/changelog#v1024).
:::

## Troubleshooting {#troubleshooting}

### Version not found

```bash
mbc new myapp@999.999.999
# Error: Version not found
```

Solution: Use a valid version number. Check available versions in npm registry.

### Directory not empty

```bash
mbc new my-project
# Error: Directory not empty
```

Solution: Use a new directory or remove existing files before creating a project.

### Permission denied

If you encounter permission errors during global installation:

```bash
sudo npm install -g @mbc-cqrs-serverless/cli
# or use npm prefix
npm config set prefix ~/.npm-global
npm install -g @mbc-cqrs-serverless/cli
```


## Related Documentation

- [Getting Started](/docs/getting-started) - Introduction and first steps
- [Installation](/docs/installation) - Install CLI and setup
- [MCP Server](/docs/mcp-server) - AI development tool integration
- [AI Prompts Library](/docs/ai-prompts) - Optimized prompts for generating modules and services
- [Project Structure](/docs/project-structure) - Generated project layout


---

## Introduction

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/getting-started

# Introduction

Welcome to the MBC CQRS Serverless framework documentation!

## What is MBC CQRS Serverless framework? {#what-is-mbc-cqrs}

This framework provides core functionalities for implementing the Command Query Responsibility Segregation (CQRS) pattern within AWS serverless architectures, powered by the incredible NestJS framework. It simplifies the development of highly scalable and decoupled systems that can handle complex business logic and high-volume data processing.

## Main features {#main-features}

| features | Description |
| ---------------------------- | ---------------------------- |
| CQRS framework for AWS serverless          | - Structured approach for separating commands and queries. <br/>- Integration with AWS services like Cognito, API Gateway, Lambda, DynamoDB, SNS, and SQS, Step Functions, RDS ⚡    |
| Event-driven architecture          | - Leverages Event Sourcing and messaging for asynchronous communication <br/>- Enables loose coupling and independent scaling of components    |
| Command and query handlers          | - Provides abstractions for handling commands and queries <br/>- Facilitates business logic implementation and data persistence    |
| Asynchronous communication          | - Supports event publishing and message passing for inter-component communication    |
| Data consistency and integrity          | - Ensures data consistency through Event Sourcing and optimistic locking <br/>- Enforces data integrity with validation and constraints    |
| Experience a harmonious symphony of CQRS and NestJS          | - **Modular structure**: Organize CQRS components with NestJS's elegant modularity.<br/>- **Dependency injection**: Simplify dependency management and embrace loose coupling with NestJS's DI system <br/>- **TypeScript support**: Write type-safe, crystal-clear code with built-in TypeScript <br/>- **Testing and error handling**: Build confidence with comprehensive testing and robust error handling, courtesy of NestJS <br/>- **Ecosystem compatibility**: Tap into the vast NestJS universe of modules and libraries to expand possibilities    |
| Local Development          | - **Embrace agility**: Experience rapid iteration and experimentation in a local environment, without the need for constant cloud deployment.<br/>- **Debugging bliss**: Debug with ease using your favorite tools and techniques, gaining deeper insights into your application's behavior. <br/>- **Cost-effective exploration**: Explore and refine your CQRS implementation locally, without incurring AWS costs during development.    |

## How to Use These Docs {#how-to-use-docs}

On the left side of the screen, you'll find the docs navbar. The pages of the docs are organized sequentially, you can follow them step-by-step when building your application. However, you can read them in any order or skip to the pages that apply to your case.

On the right side of the screen, you'll see a table of contents that makes it easier to navigate between sections of a page. If you need to quickly find a page, you can use the search bar at the top, or the search shortcut (Ctrl+K or Cmd+K).

To get started, check out the [Installation](/docs/installation) guide.

## Recommended Learning Path {#recommended-learning-path}

If you're new to the framework, follow this sequence:

| Step | Page | What you'll learn |
|----------|----------|----------------------|
| 1 | [Installation](/docs/installation) | Set up your local development environment |
| 2 | [Quickstart Tutorial](/docs/quickstart-tutorial) | Build a working API in 15 minutes |
| 3 | [Project Structure](/docs/project-structure) | Understand the generated file layout |
| 4 | [Architecture](/docs/architecture) | CQRS and Event Sourcing concepts |
| 5 | [Backend Development](/docs/backend-development) | Implement features with the CQRS pattern |
| 6 | [Authentication](/docs/authentication) | Role-based access control and group-based authorization |
| 7 | Examples | [E-commerce](/docs/ecommerce-example) · [SaaS](/docs/saas-example) |

## Related Documentation

- [Installation](/docs/installation) - System requirements and setup instructions
- [Quickstart Tutorial](/docs/quickstart-tutorial) - Build your first API in 15 minutes
- [Project Structure](/docs/project-structure) - Understanding the generated project layout
- [Architecture](/docs/architecture) - CQRS and Event Sourcing concepts
- [Building Your Application](/docs/build-your-application) - Application development guides and patterns
- [Glossary](/docs/glossary) - Framework terminology and key concepts
- [Changelog](/docs/changelog) - Release history and version notes
- [AI Integration](/docs/ai-integration) - AI development tool support with llms.txt and MCP
- [Examples](/docs/recipes) - Practical implementation examples and use cases
- [API Reference](/docs/api-reference) - Complete module API reference


---

## Installation

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/installation

# Installation

System Requirements:

- [Node.js](https://nodejs.org/en/download/package-manager) (20.x or later)
- [JQ cli](https://jqlang.github.io/jq/download/)
- [AWS cli](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
- [Docker](https://docs.docker.com/engine/install/)
- Windows, macOS and Linux are supported.

## Automatic Installation {#automatic-installation}

To get started, scaffold the project with the [mbc-cqrs-serverless CLI](/docs/cli). Run the following commands. This will create a new project directory, and populate the directory with the initial core mbc-cqrs-serverless files and supporting modules, creating a conventional base structure for your project.

```bash
npm i -g @mbc-cqrs-serverless/cli
mbc new project-name
```

If you're new to mbc-cqrs-serverless, see the [project structure](/docs/project-structure) docs for an overview of all the possible files and folders in your application.

## Run the Development Server {#run-dev-server}

1. Run `npm run build` to build the project in watch mode.
2. Open another terminal session and run `npm run offline:docker` to start Docker services (DynamoDB Local, MySQL, LocalStack).
3. Wait ~30 seconds for MySQL to fully start, then open another terminal and run `npm run migrate` to migrate RDS and DynamoDB tables.
4. Finally, run `npm run offline:sls` to start serverless offline mode.

:::info AWS Credentials for Local Development
Local development uses LocalStack to emulate AWS services. You do not need real AWS credentials — set dummy values in your `.env` file:

```bash
AWS_ACCESS_KEY_ID=local
AWS_SECRET_ACCESS_KEY=local
```
:::

After the server runs successfully, you can see:

```bash
DEBUG[serverless-offline-sns][adapter]: successfully subscribed queue "http://localhost:9324/101010101010/notification-queue" to topic: "arn:aws:sns:ap-northeast-1:101010101010:MySnsTopic"
Offline Lambda Server listening on http://localhost:4000
serverless-offline-aws-eventbridge :: Plugin ready
serverless-offline-aws-eventbridge :: Mock server running at port: 4010
Starting Offline SQS at stage dev (ap-northeast-1)
Starting Offline Dynamodb Streams at stage dev (ap-northeast-1)

Starting Offline at stage dev (ap-northeast-1)

Offline [http for lambda] listening on http://localhost:3002
Function names exposed for local invocation by aws-sdk:
           * main: serverless-example-dev-main
Configuring JWT Authorization: ANY /{proxy+}

   ┌────────────────────────────────────────────────────────────────────────┐
   │                                                                        │
   │   ANY | http://localhost:3000/api/public                               │
   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
   │   ANY | http://localhost:3000/swagger-ui/{proxy*}                      │
   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
   │   ANY | http://localhost:3000/{proxy*}                                 │
   │   POST | http://localhost:3000/2015-03-31/functions/main/invocations   │
   │                                                                        │
   └────────────────────────────────────────────────────────────────────────┘

Server ready: http://localhost:3000 🚀
```

You can also use several endpoints:

- API gateway: http://localhost:3000
- Swagger UI: http://localhost:3000/swagger-ui
- Offline Lambda Server: http://localhost:4000
- HTTP for lambda: http://localhost:3002
- Step Functions: http://localhost:8083
- DynamoDB: http://localhost:8000
- DynamoDB admin: http://localhost:8001
- SNS: http://localhost:4002
- SQS: http://localhost:9324
- SQS admin: http://localhost:9325
- Localstack: http://localhost:4566
- AppSync: http://localhost:4001
- Cognito: http://localhost:9229
- EventBridge: http://localhost:4010
- Simple Email Service: http://localhost:8005
- Run `npx prisma studio` to open studio web: http://localhost:5000

:::tip Verify Your Setup
Open the [Swagger UI](http://localhost:3000/swagger-ui) in your browser to confirm the API server is running. You should see the interactive API documentation with all available endpoints.
:::

## Configuring Local Service Ports {#configuring-local-ports}

:::info Version Note
Local port configuration feature was added in [version 1.0.26](/docs/changelog#v1026).
:::

If you have port conflicts with other services (e.g., another MySQL instance, another application using port 3000), you can configure the local service ports via environment variables in your `.env` file.

### Available Port Variables

| Variable | Default | Service |
|-------------|-------------|-------------|
| `LOCAL_HTTP_PORT` | `3000` | API Gateway (Serverless Offline) |
| `LOCAL_LAMBDA_PORT` | `3002` | Lambda HTTP endpoint |
| `LOCAL_DYNAMODB_PORT` | `8000` | DynamoDB Local |
| `LOCAL_RDS_PORT` | `3306` | MySQL (RDS) |
| `LOCAL_S3_PORT` | `4566` | LocalStack (S3) |
| `LOCAL_SNS_PORT` | `4002` | SNS |
| `LOCAL_SQS_PORT` | `9324` | SQS (ElasticMQ) |
| `LOCAL_SQS_UI_PORT` | `9325` | SQS Admin UI |
| `LOCAL_SFN_PORT` | `8083` | Step Functions Local |
| `LOCAL_COGNITO_PORT` | `9229` | Cognito Local |
| `LOCAL_APPSYNC_PORT` | `4001` | AppSync Simulator |
| `LOCAL_EVENTBRIDGE_PORT` | `4010` | EventBridge |
| `LOCAL_SES_PORT` | `8005` | Simple Email Service |
| `LOCAL_DDB_ADMIN_PORT` | `8001` | DynamoDB Admin UI |

### Example: Changing Ports

To change the API Gateway port from 3000 to 3010 and MySQL port from 3306 to 3307, add the following to your `.env` file:

```bash
# Change API Gateway port to 3010
LOCAL_HTTP_PORT=3010

# Change MySQL port to 3307
LOCAL_RDS_PORT=3307

# Change DynamoDB port to 9000
LOCAL_DYNAMODB_PORT=9000
```

After changing the ports, restart all services:

1. Stop all running services (Docker and Serverless Offline)
2. Run `npm run offline:docker` to restart Docker services
3. Run `npm run offline:sls` to restart Serverless Offline

:::tip
The port configuration is automatically applied to all related services including Docker Compose, Serverless Offline, and the DynamoDB stream trigger script. You only need to set the environment variables once in your `.env` file.
:::

:::note

In the local environment, if you have trouble with the `npm run migrate` command or cannot log in with local Cognito, you will need to add more permissions to files and folders using the command below:

```bash
sudo chmod -R 777 ./infra-local/cognito-local
sudo chmod -R 777 ./infra-local/cognito-local/db/clients.json
sudo chmod -R 777 ./infra-local
sudo chmod -R 777 ./infra-local/docker-data/
sudo chmod -R 777 ./infra-local/docker-data/dynamodb-local
```

:::


## Next Steps {#next-steps}

Your local environment is ready. Here's the recommended path forward:

1. **[Quickstart Tutorial](/docs/quickstart-tutorial)** — Build your first API endpoint in 15 minutes
2. **[Project Structure](/docs/project-structure)** — Understand what each generated file and folder does
3. **[Architecture](/docs/architecture)** — Learn the CQRS and Event Sourcing concepts behind the framework
4. **[Backend Development](/docs/backend-development)** — Start implementing real features

## Related Documentation

- [Getting Started](/docs/getting-started) - Introduction to MBC CQRS Serverless
- [Project Structure](/docs/project-structure) - Understanding the generated project layout
- [Configuring](/docs/configuring) - Configure modules for your application
- [CLI](/docs/cli) - CLI commands for scaffolding
- [Glossary](/docs/glossary) - Framework terminology and concepts
- [Building Your Application](/docs/build-your-application) - Application development guides after setup
- [CodePipeline CI/CD](/docs/codepipeline-cicd) - Automated deployment with AWS CodePipeline


---

## Project structure

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/project-structure

# Project structure

## MBC CQRS Serverless Project Structure {#project-structure}

This page provides an overview of the project structure of an mbc-cqrs-serverless application. It covers top-level files and folders, configuration files.

### Top-level folders

Top-level folders are used to organize your application's code, infrastructure for local development, data migration, and testing.

| <!-- -->    | <!-- -->                    |
| ----------- | --------------------------- |
| infra       | AWS CDK infrastructure code for cloud deployment |
| infra-local | Infrastructure runs in a local environment |
| prisma      | Configuration for your Prisma ORM and DynamoDB table      |
| src         | Application source folder         |
| test        | Configuration for e2e Jest testing and manual API tests        |

### Top-level files

Top-level files are used to configure your application, manage dependencies, and define environment variables.

| <!-- -->            | <!-- -->                       |
| ------------------- | ------------------------------ |
| .env                | Environment variables            |
| .env.local          | Local environment variables      |
| .eslintrc.js        | Configuration file for ESLint       |
| .gitignore          | Specifies files and directories that Git should ignore      |
| .prettierrc         | Configure Prettier's code formatting rules     |
| jest.config.json    | Configuration for Jest testing    |
| nest-cli.json       | NestJS plugins configuration       |
| package-lock.json   | Lockfile that holds information on the dependencies installed   |
| package.json        | Project dependencies and scripts        |
| README.md           | Information about a project, including its description, installation instructions, and usage guidelines         |
| tsconfig.build.json | Configuration for TypeScript compiler options |
| tsconfig.json       | Configuration file for TypeScript       |

## Application module conventions {#module-conventions}

The following file conventions are used to define a new module in the src folder.

| <!-- -->             | folder | <!-- -->                        |
| -------------------- | ------ | ------------------------------- |
| dto                  | folder | Define the DTO (Data Transfer Object) schema. A DTO is an object that defines how the data will be sent over the network.      |
| entity               | folder | Define the business object. |
| handler              | folder | Define the data sync handler classes.  |
| [name].service.ts    | file   | Define business logic.    |
| [name].controller.ts | file   | Define a controller. |
| [name].module.ts     | file   | Organizes code relevant for a specific feature, keeping code organized and establishing clear boundaries.     |


## Related Documentation

- [Getting Started](/docs/getting-started) - Introduction and prerequisites
- [Modules](/docs/modules) - Module configuration and usage
- [Configuring](/docs/configuring) - Configuration options
- [CLI](/docs/cli) - Generate project with CLI
- [Absolute Imports and Module Path Aliases](/docs/absolute_imports_and_module_path_aliases) - TypeScript path alias configuration


---

# Tutorials

## Build a Todo App

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/build-todo-app

# Build a Todo App

This tutorial guides you through building a complete Todo application using MBC CQRS Serverless. You'll learn CQRS patterns, event handling, and progressive feature additions.

This tutorial follows the [sample code](https://github.com/mbc-net/mbc-cqrs-serverless-samples) which is organized into progressive steps.

## What You'll Build {#what-youll-build}

A fully functional Todo application with:

- CRUD operations for todos
- CQRS pattern with Command/Query separation
- Event-driven data synchronization to RDS
- Optional: Sequence numbers for todos
- Optional: Async task processing

## Prerequisites {#prerequisites}

- Completed the [Quickstart Tutorial](/docs/quickstart-tutorial)
- Basic understanding of NestJS
- Docker running for local development

## Running the Samples {#running-samples}

Each step has a complete working sample. To run any sample:

```bash
# Navigate to the step directory
cd step-02-create  # or any other step

# Install dependencies
npm install

# Terminal 1: Start Docker services
npm run offline:docker

# Terminal 2: Run database migrations
npm run migrate

# Terminal 3: Start the serverless offline server
npm run offline:sls
```

## Part 1: Basic CQRS Implementation (step-02-create) {#part1-create}

### Step 1: Create Helper Functions

First, create helper functions for managing partition keys and sort keys (`src/helpers/id.ts`):

```typescript
import { KEY_SEPARATOR } from '@mbc-cqrs-serverless/core'
import { ulid } from 'ulid'

export const TODO_PK_PREFIX = 'TODO'

export function generateTodoPk(tenantCode: string): string {
  return `${TODO_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`
}

export function generateTodoSk(): string {
  return ulid() // ULID provides time-ordered unique identifiers
}

export function parsePk(pk: string): { type: string; tenantCode: string } {
  if (pk.split(KEY_SEPARATOR).length !== 2) {
    throw new Error('Invalid PK')
  }
  const [type, tenantCode] = pk.split(KEY_SEPARATOR)
  return { type, tenantCode }
}
```

### Step 2: Define DTOs

Create the todo attributes DTO (`dto/todo-attributes.dto.ts`):

```typescript
import { ApiProperty } from '@nestjs/swagger'
import { IsDateString, IsEnum, IsOptional, IsString } from 'class-validator'

// TodoStatus enum (will be synced with Prisma in step-03)
export enum TodoStatus {
  PENDING = 'PENDING',
  IN_PROGRESS = 'IN_PROGRESS',
  COMPLETED = 'COMPLETED',
  CANCELED = 'CANCELED',
}

export class TodoAttributes {
  @IsOptional()
  @IsString()
  description?: string

  @IsOptional()
  @ApiProperty({ enum: TodoStatus })
  @IsEnum(TodoStatus)
  status?: TodoStatus

  @IsOptional()
  @IsDateString()
  dueDate?: string
}
```

Create the input DTO (`dto/create-todo.dto.ts`):

```typescript
import { Type } from 'class-transformer'
import { IsOptional, IsString, ValidateNested } from 'class-validator'
import { TodoAttributes } from './todo-attributes.dto'

export class CreateTodoDto {
  @IsString()
  name: string // The name field is required by CommandEntity

  @Type(() => TodoAttributes)
  @ValidateNested()
  @IsOptional()
  attributes?: TodoAttributes

  constructor(partial: Partial<CreateTodoDto>) {
    Object.assign(this, partial)
  }
}
```

### Step 3: Define Entities

Create the command entity (`entity/todo-command.entity.ts`):

```typescript
import { CommandEntity } from '@mbc-cqrs-serverless/core'
import { TodoAttributes } from '../dto/todo-attributes.dto'

export class TodoCommandEntity extends CommandEntity {
  attributes: TodoAttributes

  constructor(partial: Partial<TodoCommandEntity>) {
    super()
    Object.assign(this, partial)
  }
}
```

Create the command DTO (`dto/todo-command.dto.ts`):

```typescript
import { CommandDto } from '@mbc-cqrs-serverless/core'
import { Type } from 'class-transformer'
import { IsOptional, ValidateNested } from 'class-validator'
import { TodoAttributes } from './todo-attributes.dto'

export class TodoCommandDto extends CommandDto {
  @Type(() => TodoAttributes)
  @ValidateNested()
  @IsOptional()
  attributes?: TodoAttributes

  constructor(partial: Partial<TodoCommandDto>) {
    super()
    Object.assign(this, partial)
  }
}
```

Create the data entity (`entity/todo-data.entity.ts`):

```typescript
import { DataEntity } from '@mbc-cqrs-serverless/core'
import { TodoAttributes } from '../dto/todo-attributes.dto'

export class TodoDataEntity extends DataEntity {
  attributes: TodoAttributes

  constructor(partial: Partial<TodoDataEntity>) {
    super(partial)
    Object.assign(this, partial)
  }
}
```

### Step 4: Implement the Service

Create the todo service (`todo.service.ts`):

```typescript
import {
  CommandService,
  generateId,
  getUserContext,
  IInvoke,
  VERSION_FIRST,
} from '@mbc-cqrs-serverless/core'
import { Injectable, Logger } from '@nestjs/common'
import { generateTodoPk, generateTodoSk, TODO_PK_PREFIX } from 'src/helpers'
import { CreateTodoDto } from './dto/create-todo.dto'
import { TodoCommandDto } from './dto/todo-command.dto'
import { TodoDataEntity } from './entity/todo-data.entity'

@Injectable()
export class TodoService {
  private readonly logger = new Logger(TodoService.name)

  constructor(private readonly commandService: CommandService) {}

  async create(
    createDto: CreateTodoDto,
    opts: { invokeContext: IInvoke },
  ): Promise<TodoDataEntity> {
    // Get tenant code from user context (JWT token)
    const { tenantCode } = getUserContext(opts.invokeContext)

    // Generate partition key and sort key
    const pk = generateTodoPk(tenantCode)
    const sk = generateTodoSk()

    // Create command DTO
    const todo = new TodoCommandDto({
      pk,
      sk,
      id: generateId(pk, sk),
      tenantCode,
      code: sk,
      type: TODO_PK_PREFIX,
      version: VERSION_FIRST, // Version for optimistic locking
      name: createDto.name,
      attributes: createDto.attributes,
    })

    this.logger.debug('Creating todo:', todo)

    // Publish command to DynamoDB
    const item = await this.commandService.publishAsync(todo, opts)
    // New entities (VERSION_FIRST) always publish successfully and return a non-null result
    return new TodoDataEntity(item as TodoDataEntity)
  }
}
```

:::info publishAsync null return (v1.2.0+)
Since v1.2.0, `publishAsync()` and `publishPartialUpdateAsync()` return `null` when the command produces no changes (no-op). New entities created with `VERSION_FIRST` (0) are always dirty and never return `null`. For update operations where the payload may be unchanged, null-check the result before using it. See the [v1.2.0 migration guide](/docs/migration/v1.2.0) for details.
:::

### Step 5: Create the Controller

Create the controller (`todo.controller.ts`):

```typescript
import { getUserContext, IInvoke, INVOKE_CONTEXT } from '@mbc-cqrs-serverless/core'
import { Body, Controller, Get, Logger, Post, Query } from '@nestjs/common'
import { ApiTags } from '@nestjs/swagger'
import { CreateTodoDto } from './dto/create-todo.dto'
import { TodoDataEntity } from './entity/todo-data.entity'
import { TodoService } from './todo.service'

@Controller('api/todo')
@ApiTags('todo')
export class TodoController {
  private readonly logger = new Logger(TodoController.name)

  constructor(private readonly todoService: TodoService) {}

  @Post('/')
  async create(
    @INVOKE_CONTEXT() invokeContext: IInvoke,
    @Body() createDto: CreateTodoDto,
  ): Promise<TodoDataEntity> {
    this.logger.debug('createDto:', createDto)
    return this.todoService.create(createDto, { invokeContext })
  }
}
```

### Step 6: Create the Module

Create the module (`todo.module.ts`):

```typescript
import { CommandModule } from '@mbc-cqrs-serverless/core'
import { Module } from '@nestjs/common'
import { TodoController } from './todo.controller'
import { TodoService } from './todo.service'

@Module({
  imports: [
    CommandModule.register({
      tableName: 'todo',
      // Data sync handlers will be added in step-03-rds-sync
      // dataSyncHandlers: [TodoDataSyncRdsHandler],
    }),
  ],
  controllers: [TodoController],
  providers: [TodoService],
})
export class TodoModule {}
```

## Part 2: RDS Data Synchronization (step-03-rds-sync) {#part2-rds-sync}

Implement automatic data synchronization from DynamoDB to RDS.

### Update Prisma Schema

Add TodoStatus enum and Todo model to `prisma/schema.prisma`:

```prisma
// Todo status enum
enum TodoStatus {
  PENDING
  IN_PROGRESS
  COMPLETED
  CANCELED
}

// Todo model for RDS (PostgreSQL) - synchronized from DynamoDB
model Todo {
  id         String   @id                        // Unique ID (generated from pk#sk)
  cpk        String                              // Command partition key
  csk        String                              // Command sort key (with version)
  pk         String                              // Data partition key: TODO#tenantCode
  sk         String                              // Data sort key: ULID
  tenantCode String   @map("tenant_code")        // Tenant code for multi-tenancy
  seq        Int      @default(0)                // Sequence number (for ordering)
  code       String                              // Record code (same as sk)
  name       String                              // Todo name/title
  version    Int                                 // Version for optimistic locking
  isDeleted  Boolean  @default(false) @map("is_deleted")  // Soft delete flag
  createdBy  String   @default("") @map("created_by")     // Created by user
  createdIp  String   @default("") @map("created_ip")     // Created from IP
  createdAt  DateTime @default(now()) @map("created_at") @db.Timestamp(0)
  updatedBy  String   @default("") @map("updated_by")     // Updated by user
  updatedIp  String   @default("") @map("updated_ip")     // Updated from IP
  updatedAt  DateTime @updatedAt @map("updated_at") @db.Timestamp(0)

  // Todo-specific attributes
  description String?    @default("") @map("description")  // Description
  status      TodoStatus @default(PENDING) @map("status")  // Status
  dueDate     DateTime?  @map("due_date")                  // Due date

  // Indexes for efficient queries
  @@unique([cpk, csk])           // Command table unique constraint
  @@unique([pk, sk])             // Data table unique constraint
  @@unique([tenantCode, code])   // Tenant + code unique constraint
  @@index([tenantCode, name])    // Search by tenant and name
  @@map("todos")                 // Table name in database
}
```

### Create Data Sync Handler

Create the RDS sync handler (`handler/todo-rds.handler.ts`):

```typescript
import {
  CommandModel,
  IDataSyncHandler,
  removeSortKeyVersion,
} from '@mbc-cqrs-serverless/core'
import { Injectable, Logger } from '@nestjs/common'
import { PrismaService } from 'src/prisma'
import { TodoAttributes } from '../dto/todo-attributes.dto'

@Injectable()
export class TodoDataSyncRdsHandler implements IDataSyncHandler {
  private readonly logger = new Logger(TodoDataSyncRdsHandler.name)

  constructor(private readonly prismaService: PrismaService) {}

  // Called when data is created or updated in DynamoDB
  async up(cmd: CommandModel): Promise<any> {
    this.logger.debug('Syncing to RDS:', cmd)

    // Remove version suffix from sort key for the data table
    const sk = removeSortKeyVersion(cmd.sk)
    const attrs = cmd.attributes as TodoAttributes

    await this.prismaService.todo.upsert({
      where: { id: cmd.id },
      // Update existing record
      update: {
        csk: cmd.sk,
        name: cmd.name,
        version: cmd.version,
        seq: cmd.seq,
        isDeleted: cmd.isDeleted || false,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
        updatedIp: cmd.updatedIp,
        description: attrs?.description,
        status: attrs?.status,
        dueDate: attrs?.dueDate,
      },
      // Create new record
      create: {
        id: cmd.id,
        cpk: cmd.pk,
        csk: cmd.sk,
        pk: cmd.pk,
        sk,
        code: sk,
        name: cmd.name,
        version: cmd.version,
        tenantCode: cmd.tenantCode,
        seq: cmd.seq,
        createdAt: cmd.createdAt,
        createdBy: cmd.createdBy,
        createdIp: cmd.createdIp,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
        updatedIp: cmd.updatedIp,
        description: attrs?.description,
        status: attrs?.status,
        dueDate: attrs?.dueDate,
      },
    })
  }

  // Called when data needs to be rolled back
  async down(cmd: CommandModel): Promise<any> {
    this.logger.debug('Rollback requested:', cmd)
    // Implement rollback logic if needed
  }
}
```

### Register Handler in Module

Update `todo.module.ts`:

```typescript
import { CommandModule } from '@mbc-cqrs-serverless/core'
import { Module } from '@nestjs/common'
import { TodoDataSyncRdsHandler } from './handler/todo-rds.handler'
import { TodoController } from './todo.controller'
import { TodoService } from './todo.service'

@Module({
  imports: [
    CommandModule.register({
      tableName: 'todo',
      // Register RDS sync handler to synchronize DynamoDB data to PostgreSQL
      dataSyncHandlers: [TodoDataSyncRdsHandler],
    }),
  ],
  controllers: [TodoController],
  providers: [TodoService],
})
export class TodoModule {}
```

## Part 3: Read Operations (step-04-read) {#part3-read}

Add methods to retrieve single items from DynamoDB.

### Update Service

Add `findOne` method to `todo.service.ts`:

```typescript
import { DataService } from '@mbc-cqrs-serverless/core'
import { Injectable, NotFoundException } from '@nestjs/common'

@Injectable()
export class TodoService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService, // Inject DataService
  ) {}

  // ... create method ...

  async findOne(pk: string, sk: string): Promise<TodoDataEntity> {
    this.logger.debug(`Finding todo: pk=${pk}, sk=${sk}`)

    const item = await this.dataService.getItem({ pk, sk })

    if (!item) {
      throw new NotFoundException(`Todo not found: pk=${pk}, sk=${sk}`)
    }

    return new TodoDataEntity(item as TodoDataEntity)
  }
}
```

### Update Controller

```typescript
@Get(':pk/:sk')
async findOne(
  @Param('pk') pk: string,
  @Param('sk') sk: string,
): Promise<TodoDataEntity> {
  this.logger.debug(`findOne: pk=${pk}, sk=${sk}`)
  return this.todoService.findOne(pk, sk)
}
```

## Part 4: Search Operations (step-05-search) {#part4-search}

Implement search using RDS for efficient queries.

### Create Search DTO

```typescript
import { ApiPropertyOptional } from '@nestjs/swagger'
import { TodoStatus } from '@prisma/client' // Import from Prisma generated types
import { IsEnum, IsInt, IsOptional, IsString, Max, Min } from 'class-validator'
import { Transform, Type } from 'class-transformer'

export class SearchTodoDto {
  @IsOptional()
  @IsString()
  @ApiPropertyOptional({ description: 'Search by name (partial match)' })
  name?: string

  @IsOptional()
  @IsEnum(TodoStatus)
  @ApiPropertyOptional({ enum: TodoStatus, description: 'Filter by status' })
  status?: TodoStatus

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  @ApiPropertyOptional({ description: 'Page number (1-based)', default: 1 })
  page?: number = 1

  @IsOptional()
  @Type(() => Number)
  @IsInt()
  @Min(1)
  @Max(100)
  @ApiPropertyOptional({ description: 'Items per page', default: 10 })
  limit?: number = 10

  @IsOptional()
  @IsString()
  @ApiPropertyOptional({
    description: 'Sort field',
    default: 'createdAt',
    enum: ['name', 'status', 'createdAt', 'updatedAt'],
  })
  sortBy?: string = 'createdAt'

  @IsOptional()
  @IsString()
  @Transform(({ value }) => value?.toUpperCase())
  @ApiPropertyOptional({
    description: 'Sort order',
    default: 'DESC',
    enum: ['ASC', 'DESC'],
  })
  sortOrder?: 'ASC' | 'DESC' = 'DESC'
}

export class SearchTodoResultDto<T> {
  data: T[]
  total: number
  page: number
  limit: number
  totalPages: number

  constructor(data: T[], total: number, page: number, limit: number) {
    this.data = data
    this.total = total
    this.page = page
    this.limit = limit
    this.totalPages = Math.ceil(total / limit)
  }
}
```

### Update Service

```typescript
import { Prisma } from '@prisma/client'

async findAll(
  tenantCode: string,
  searchDto: SearchTodoDto,
): Promise<SearchTodoResultDto<TodoDataEntity>> {
  this.logger.debug(`Searching todos for tenant: ${tenantCode}`, searchDto)

  const { name, status, page = 1, limit = 10, sortBy = 'createdAt', sortOrder = 'DESC' } = searchDto

  // Build where clause dynamically
  const where: Prisma.TodoWhereInput = {
    tenantCode,
    isDeleted: false,
  }

  // Add name filter (partial match)
  if (name) {
    where.name = { contains: name }
  }

  // Add status filter (exact match)
  if (status) {
    where.status = status
  }

  // Build orderBy clause
  const orderBy: Prisma.TodoOrderByWithRelationInput = {
    [sortBy]: sortOrder.toLowerCase(),
  }

  // Calculate skip for pagination
  const skip = (page - 1) * limit

  // Execute query with pagination
  const [data, total] = await Promise.all([
    this.prismaService.todo.findMany({
      where,
      orderBy,
      skip,
      take: limit,
    }),
    this.prismaService.todo.count({ where }),
  ])

  // Map Prisma results to TodoDataEntity
  const todos = data.map((item) => new TodoDataEntity({
    ...item,
    type: TODO_PK_PREFIX,
    attributes: {
      description: item.description,
      status: item.status,
      dueDate: item.dueDate?.toISOString(),
    },
  } as unknown as TodoDataEntity))

  return new SearchTodoResultDto(todos, total, page, limit)
}
```

### Update Controller

```typescript
@Get('/')
async findAll(
  @INVOKE_CONTEXT() invokeContext: IInvoke,
  @Query() searchDto: SearchTodoDto,
): Promise<SearchTodoResultDto<TodoDataEntity>> {
  const { tenantCode } = getUserContext(invokeContext)
  this.logger.debug(`findAll: tenantCode=${tenantCode}`, searchDto)
  return this.todoService.findAll(tenantCode, searchDto)
}
```

## Part 5: Update and Delete (step-06-update-delete) {#part5-update-delete}

### Update DTO

```typescript
import { ApiPropertyOptional } from '@nestjs/swagger'
import { IsInt, IsOptional, IsString, Min } from 'class-validator'
import { Type } from 'class-transformer'
import { TodoAttributes } from './todo-attributes.dto'

export class UpdateTodoDto {
  @IsOptional()
  @IsString()
  @ApiPropertyOptional({ description: 'Todo name/title' })
  name?: string

  @IsOptional()
  @ApiPropertyOptional({ description: 'Todo attributes (description, status, dueDate)' })
  attributes?: TodoAttributes

  @Type(() => Number)
  @IsInt()
  @Min(1)
  @ApiPropertyOptional({ description: 'Version for optimistic locking' })
  version: number // Required for optimistic locking
}
```

### Update Service

```typescript
import { CommandPartialInputModel } from '@mbc-cqrs-serverless/core'

async update(
  pk: string,
  sk: string,
  updateDto: UpdateTodoDto,
  opts: { invokeContext: IInvoke },
): Promise<TodoDataEntity> {
  this.logger.debug(`Updating todo: pk=${pk}, sk=${sk}`, updateDto)

  // First, verify the item exists
  const currentItem = await this.dataService.getItem({ pk, sk })
  if (!currentItem) {
    throw new NotFoundException(`Todo not found: pk=${pk}, sk=${sk}`)
  }

  // Build the partial update object
  const partialUpdate: CommandPartialInputModel = {
    pk,
    sk,
    version: updateDto.version, // Required for optimistic locking
    ...(updateDto.name !== undefined && { name: updateDto.name }),
    ...(updateDto.attributes !== undefined && { attributes: updateDto.attributes }),
  }

  // Publish partial update command
  const item = await this.commandService.publishPartialUpdateAsync(partialUpdate, opts)
  // null means no fields changed — treat as NotFoundException since caller verified it exists
  if (!item) throw new NotFoundException(`Todo not found or no changes: pk=${pk}, sk=${sk}`)

  return new TodoDataEntity(item as TodoDataEntity)
}

async remove(
  pk: string,
  sk: string,
  version: number,
  opts: { invokeContext: IInvoke },
): Promise<TodoDataEntity> {
  this.logger.debug(`Removing todo: pk=${pk}, sk=${sk}, version=${version}`)

  // First, verify the item exists
  const currentItem = await this.dataService.getItem({ pk, sk })
  if (!currentItem) {
    throw new NotFoundException(`Todo not found: pk=${pk}, sk=${sk}`)
  }

  // Soft delete by setting isDeleted flag
  const item = await this.commandService.publishPartialUpdateAsync(
    {
      pk,
      sk,
      version,
      isDeleted: true,
    },
    opts,
  )
  // null means already deleted (isDeleted was already true)
  if (!item) throw new NotFoundException(`Todo not found or already deleted: pk=${pk}, sk=${sk}`)

  return new TodoDataEntity(item as TodoDataEntity)
}
```

### Update Controller

```typescript
@Patch(':pk/:sk')
async update(
  @INVOKE_CONTEXT() invokeContext: IInvoke,
  @Param('pk') pk: string,
  @Param('sk') sk: string,
  @Body() updateDto: UpdateTodoDto,
): Promise<TodoDataEntity> {
  this.logger.debug(`update: pk=${pk}, sk=${sk}`, updateDto)
  return this.todoService.update(pk, sk, updateDto, { invokeContext })
}

@Delete(':pk/:sk')
async remove(
  @INVOKE_CONTEXT() invokeContext: IInvoke,
  @Param('pk') pk: string,
  @Param('sk') sk: string,
  @Query('version') version: number,
): Promise<TodoDataEntity> {
  this.logger.debug(`remove: pk=${pk}, sk=${sk}, version=${version}`)
  return this.todoService.remove(pk, sk, version, { invokeContext })
}
```

## Part 6: Sequence Numbers (step-07-sequence) {#part6-sequence}

Add auto-incrementing todo numbers.

### Install Sequence Module

```bash
npm install @mbc-cqrs-serverless/sequence
```

### Update Module

```typescript
import { SequencesModule } from '@mbc-cqrs-serverless/sequence'

@Module({
  imports: [
    CommandModule.register({
      tableName: 'todo',
      dataSyncHandlers: [TodoDataSyncRdsHandler],
    }),
    SequencesModule, // Add SequencesModule
  ],
  // ...
})
export class TodoModule {}
```

### Update Service

```typescript
import { Injectable } from '@nestjs/common'
import { SequencesService } from '@mbc-cqrs-serverless/sequence'

@Injectable()
export class TodoService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly prismaService: PrismaService,
    private readonly sequencesService: SequencesService, // Inject SequencesService
  ) {}

  async create(
    createDto: CreateTodoDto,
    opts: { invokeContext: IInvoke },
  ): Promise<TodoDataEntity> {
    const { tenantCode } = getUserContext(opts.invokeContext)

    // Generate sequential number
    const seqItem = await this.sequencesService.generateSequenceItem(
      {
        tenantCode,
        typeCode: TODO_PK_PREFIX,
      },
      opts,
    )

    this.logger.debug(`Generated sequence number: ${seqItem.formattedNo} for tenant: ${tenantCode}`)

    const pk = generateTodoPk(tenantCode)
    const sk = generateTodoSk() // SK is still ULID

    const todo = new TodoCommandDto({
      pk,
      sk,
      id: generateId(pk, sk),
      tenantCode,
      code: sk,
      type: TODO_PK_PREFIX,
      version: VERSION_FIRST,
      seq: seqItem.no, // Store sequence number in seq field
      name: createDto.name,
      attributes: createDto.attributes,
    })

    this.logger.debug('Creating todo with sequence:', todo)

    const item = await this.commandService.publishAsync(todo, opts)
    // New entities (VERSION_FIRST) always publish successfully and return a non-null result
    return new TodoDataEntity(item as TodoDataEntity)
  }
}
```

## Part 7: Async Task Processing (complete/with-task) {#part7-async-tasks}

Process long-running todo operations asynchronously.

### Install Task Module

```bash
npm install @mbc-cqrs-serverless/task
```

### Create Task Event

```typescript
// src/todo/handler/todo-task.event.ts
import { TaskQueueEvent } from '@mbc-cqrs-serverless/task'

export class TodoTaskEvent extends TaskQueueEvent {}
```

### Create Task Handler

```typescript
// src/todo/handler/todo-task.event.handler.ts
import { EventHandler, IEventHandler } from '@mbc-cqrs-serverless/core'
import { Logger } from '@nestjs/common'
import { TodoTaskEvent } from './todo-task.event'

@EventHandler(TodoTaskEvent)
export class TodoTaskEventHandler implements IEventHandler<TodoTaskEvent> {
  private readonly logger = new Logger(TodoTaskEventHandler.name)

  async execute(event: TodoTaskEvent): Promise<any> {
    this.logger.debug('Processing todo task:', event)

    // Implement your async task processing here
    // e.g., send notification, sync to external system

    return { processed: true }
  }
}
```

### Create Task Queue Event Factory

```typescript
// src/my-task/task-queue-event-factory.ts
import {
  ITaskQueueEventFactory,
  TaskQueueEvent,
} from '@mbc-cqrs-serverless/task'
import { TodoTaskEvent } from '../todo/handler/todo-task.event'

export class TaskQueueEventFactory implements ITaskQueueEventFactory {
  async transformTask(event: TaskQueueEvent): Promise<any[]> {
    return [new TodoTaskEvent().fromSqsRecord(event)]
  }
}
```

### Create Task Module

```typescript
// src/my-task/my-task.module.ts
import { TaskModule } from '@mbc-cqrs-serverless/task'
import { Module } from '@nestjs/common'
import { TaskQueueEventFactory } from './task-queue-event-factory'

@Module({
  imports: [
    TaskModule.register({
      taskQueueEventFactory: TaskQueueEventFactory,
    }),
  ],
  exports: [TaskModule],
})
export class MyTaskModule {}
```

## Testing Your Application {#testing}

### Run Locally

```bash
# Terminal 1: Start Docker services
npm run offline:docker

# Terminal 2: Run database migrations
npm run migrate

# Terminal 3: Start serverless offline
npm run offline:sls
```

### Test API Endpoints

```bash
# Create a todo
curl -X POST http://localhost:3000/api/todo \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{"name": "My First Todo", "attributes": {"description": "Testing CQRS", "status": "PENDING"}}'

# List todos
curl "http://localhost:3000/api/todo?page=1&limit=10" \
  -H "Authorization: Bearer <your-token>"

# Get a todo (Note: # in pk must be URL-encoded as %23)
curl "http://localhost:3000/api/todo/TODO%23MBC/<sk>" \
  -H "Authorization: Bearer <your-token>"

# Update a todo
curl -X PATCH "http://localhost:3000/api/todo/TODO%23MBC/<sk>" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-token>" \
  -d '{"name": "Updated Todo", "version": 1}'

# Delete a todo
curl -X DELETE "http://localhost:3000/api/todo/TODO%23MBC/<sk>?version=1" \
  -H "Authorization: Bearer <your-token>"
```

### Unit Tests

Create unit tests for the service (`todo.service.spec.ts`):

```typescript
import { Test, TestingModule } from '@nestjs/testing'
import { NotFoundException } from '@nestjs/common'
import { CommandService, DataService } from '@mbc-cqrs-serverless/core'
import { TodoService } from './todo.service'
import { PrismaService } from '../prisma/prisma.service'

// Mock getUserContext
jest.mock('@mbc-cqrs-serverless/core', () => ({
  ...jest.requireActual('@mbc-cqrs-serverless/core'),
  getUserContext: jest.fn().mockReturnValue({
    tenantCode: 'test',
    userId: 'user-123',
  }),
}))

describe('TodoService', () => {
  let service: TodoService
  let commandService: jest.Mocked<CommandService>
  let dataService: jest.Mocked<DataService>

  beforeEach(async () => {
    const mockCommandService = {
      publishAsync: jest.fn(),
      publishPartialUpdateAsync: jest.fn(),
    }

    const mockDataService = {
      getItem: jest.fn(),
    }

    const mockPrismaService = {
      todo: {
        findMany: jest.fn(),
        count: jest.fn(),
      },
    }

    const module: TestingModule = await Test.createTestingModule({
      providers: [
        TodoService,
        { provide: CommandService, useValue: mockCommandService },
        { provide: DataService, useValue: mockDataService },
        { provide: PrismaService, useValue: mockPrismaService },
      ],
    }).compile()

    service = module.get<TodoService>(TodoService)
    commandService = module.get(CommandService)
    dataService = module.get(DataService)
  })

  describe('findOne', () => {
    it('should return a todo when found', async () => {
      const mockTodo = { pk: 'TODO#test', sk: '01HXY', name: 'Test' }
      dataService.getItem.mockResolvedValue(mockTodo as any)

      const result = await service.findOne('TODO#test', '01HXY')

      expect(dataService.getItem).toHaveBeenCalledWith({
        pk: 'TODO#test',
        sk: '01HXY',
      })
      expect(result.name).toBe('Test')
    })

    it('should throw NotFoundException when not found', async () => {
      dataService.getItem.mockResolvedValue(null)

      await expect(service.findOne('TODO#test', 'nonexistent'))
        .rejects.toThrow(NotFoundException)
    })
  })
})
```

Run unit tests:

```bash
npm test
```

### E2E Tests

Create E2E tests (`test/todo.e2e-spec.ts`):

```typescript
import { Test, TestingModule } from '@nestjs/testing'
import { INestApplication, ValidationPipe } from '@nestjs/common'
import request from 'supertest'
import { TodoController } from '../src/todo/todo.controller'
import { TodoService } from '../src/todo/todo.service'

// Mock getUserContext
jest.mock('@mbc-cqrs-serverless/core', () => ({
  ...jest.requireActual('@mbc-cqrs-serverless/core'),
  getUserContext: jest.fn().mockReturnValue({
    tenantCode: 'test',
    userId: 'user-123',
  }),
  INVOKE_CONTEXT: () => () => {}, // Decorator stub
}))

describe('TodoController (e2e)', () => {
  let app: INestApplication

  const mockTodoData = {
    pk: 'TODO#test',
    sk: '01HXY',
    name: 'Test Todo',
    version: 1,
  }

  beforeAll(async () => {
    const mockTodoService = {
      create: jest.fn().mockResolvedValue(mockTodoData),
      findOne: jest.fn().mockResolvedValue(mockTodoData),
      findAll: jest.fn().mockResolvedValue({ data: [mockTodoData], total: 1 }),
      update: jest.fn().mockResolvedValue(mockTodoData),
      remove: jest.fn().mockResolvedValue({ ...mockTodoData, isDeleted: true }),
    }

    const moduleFixture: TestingModule = await Test.createTestingModule({
      controllers: [TodoController],
      providers: [{ provide: TodoService, useValue: mockTodoService }],
    }).compile()

    app = moduleFixture.createNestApplication()
    app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }))
    await app.init()
  })

  afterAll(async () => {
    await app.close()
  })

  it('POST /api/todo - should create a todo', () => {
    return request(app.getHttpServer())
      .post('/api/todo')
      .send({ name: 'New Todo', attributes: { status: 'PENDING' } })
      .expect(201)
  })

  it('GET /api/todo/:pk/:sk - should return a todo', () => {
    return request(app.getHttpServer())
      .get('/api/todo/TODO%23TEST/01HXY')
      .expect(200)
  })

  it('PATCH /api/todo/:pk/:sk - should update a todo', () => {
    return request(app.getHttpServer())
      .patch('/api/todo/TODO%23TEST/01HXY')
      .send({ name: 'Updated', version: 1 })
      .expect(200)
  })
})
```

Configure Jest for E2E tests (`test/jest-e2e.json`):

```json
{
  "moduleFileExtensions": ["js", "json", "ts"],
  "rootDir": ".",
  "testEnvironment": "node",
  "testRegex": ".e2e-spec.ts$",
  "transform": {
    "^.+\\.(t|j)s$": ["ts-jest", { "tsconfig": "<rootDir>/../tsconfig.json" }]
  },
  "moduleNameMapper": {
    "^src/(.*)$": "<rootDir>/../src/$1"
  }
}
```

Run E2E tests:

```bash
npm run test:e2e
```

## Sample Code Repository {#sample-repo}

The complete source code for each step is available at:

- [step-01-setup](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/step-01-setup) - Environment setup
- [step-02-create](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/step-02-create) - Create operation
- [step-03-rds-sync](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/step-03-rds-sync) - RDS synchronization
- [step-04-read](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/step-04-read) - Read operation
- [step-05-search](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/step-05-search) - Search operation
- [step-06-update-delete](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/step-06-update-delete) - Update and delete
- [step-07-sequence](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/step-07-sequence) - Sequence numbers
- [complete/basic](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/complete/basic) - Full basic implementation
- [complete/with-task](https://github.com/mbc-net/mbc-cqrs-serverless-samples/tree/main/complete/with-task) - With async task processing

## Related Documentation

- [Quickstart Tutorial](/docs/quickstart-tutorial) - Shorter introduction
- [Command Service](/docs/command-service) - CommandService API reference
- [Service Patterns](/docs/service-patterns) - Advanced CRUD patterns
- [Testing](/docs/testing) - Write tests for your application


---

## Quickstart Tutorial

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/quickstart-tutorial

# Quickstart Tutorial

This tutorial will guide you through creating your first MBC CQRS Serverless application. By the end, you'll have a working API running locally.

## Prerequisites {#prerequisites}

Before you begin, ensure you have the following installed:

- Node.js 20.x or later
- Docker and Docker Compose
- AWS CLI (real credentials are not required for local development — set `AWS_ACCESS_KEY_ID=local` and `AWS_SECRET_ACCESS_KEY=local` in your `.env` file)
- Git

## Step 1: Create a New Project {#step1-create}

Use the MBC CQRS CLI to scaffold a new project:

```bash
npx @mbc-cqrs-serverless/cli new my-app
cd my-app
```

The CLI will create a project with the following structure:

```text
my-app/
├── src/
│   ├── main.ts
│   ├── main.module.ts
│   └── ...
├── infra-local/
│   ├── docker-compose.yml
│   └── serverless.yml
├── prisma/
│   └── schema.prisma
├── package.json
└── ...
```

## Step 2: Install Dependencies {#step2-install}

```bash
npm install
```

## Step 3: Configure Environment {#step3-configure}

Copy the example environment file and set dummy AWS credentials for local development:

```bash
cp .env.example .env
```

Open `.env` and ensure these values are set (LocalStack emulates AWS — no real credentials needed):

```bash
AWS_ACCESS_KEY_ID=local
AWS_SECRET_ACCESS_KEY=local
```

Build the TypeScript application (required before starting the server):

```bash
npm run build
```

## Step 4: Start Local Infrastructure {#step4-infrastructure}

Start the local development environment using Docker Compose:

```bash
npm run offline:docker
```

This starts the following services:

- DynamoDB Local (port 8000)
- MySQL (port 3306)
- LocalStack for AWS services

## Step 5: Initialize the Database {#step5-database}

Wait ~30 seconds for MySQL to fully start, then run Prisma migrations to set up your database schema:

```bash
npm run migrate
```

## Step 6: Start the Development Server {#step6-server}

In a new terminal, start the Serverless Offline server:

```bash
npm run offline:sls
```

Your API is now running at `http://localhost:3000`.

## Step 7: Test Your API {#step7-test}

Open the Swagger UI in your browser to explore and test your API:

```text
http://localhost:3000/swagger-ui/
```

You should see the Swagger UI with all available endpoints listed.

## Creating Your First Endpoint {#first-endpoint}

Let's create a simple "Hello World" endpoint.

### Create a Controller

Create a new file `src/hello/hello.controller.ts`:

```typescript
import { Controller, Get } from '@nestjs/common';

@Controller('hello')
export class HelloController {
  @Get()
  getHello(): string {
    return 'Hello, MBC CQRS Serverless!';
  }
}
```

### Create a Module

Create a new file `src/hello/hello.module.ts`:

```typescript
import { Module } from '@nestjs/common';
import { HelloController } from './hello.controller';

@Module({
  controllers: [HelloController],
})
export class HelloModule {}
```

### Register the Module

Add the HelloModule to your main module in `src/main.module.ts`:

```typescript
import { Module } from '@nestjs/common';
import { HelloModule } from './hello/hello.module';

@Module({
  imports: [
    // ... existing imports
    HelloModule,
  ],
})
export class MainModule {}
```

### Test the New Endpoint

Restart the server and test your new endpoint:

```bash
curl http://localhost:3000/hello
```

You should see: `Hello, MBC CQRS Serverless!`

## Next Steps {#next-steps}

Congratulations! You've created your first MBC CQRS Serverless application. Here's what to explore next:

- [Build a Todo App](/docs/build-todo-app) - Learn CQRS patterns by building a complete application
- [Core Concepts](/docs/architecture) - Understand the CQRS and Event Sourcing architecture
- [Deployment Guide](/docs/deployment-guide) - Deploy your application to AWS

## Common Commands {#common-commands}

| Command | Description |
|-------------|-----------------|
| `npm run offline:docker` | Start local Docker services |
| `npm run offline:sls` | Start Serverless Offline |
| `npm run migrate` | Run database migrations |
| `npm run build` | Build the application |
| `npm run test` | Run unit tests |
| `npm run test:e2e` | Run end-to-end tests |

## Troubleshooting {#troubleshooting}

### Docker services won't start

Ensure Docker is running and you have sufficient resources allocated. Try:

```bash
docker-compose -f infra-local/docker-compose.yml down
docker-compose -f infra-local/docker-compose.yml up -d
```

### Database connection errors

Wait a few seconds for MySQL to fully start, then run migrations again:

```bash
npm run migrate
```

### Port conflicts

If ports 3000, 3306, or 8000 are in use, configure custom ports via environment variables in your `.env` file:

```bash
LOCAL_HTTP_PORT=3010
LOCAL_RDS_PORT=3307
LOCAL_DYNAMODB_PORT=9000
```

See [Configuring Local Service Ports](/docs/installation#configuring-local-ports) for all available port variables.


## Related Documentation

- [Build a Todo App](/docs/build-todo-app) - More complete CQRS pattern example
- [Backend Development](/docs/backend-development) - Deep dive into backend patterns
- [Service Patterns](/docs/service-patterns) - Complete CRUD service patterns
- [Command Service](/docs/command-service) - CommandService API reference
- [Glossary](/docs/glossary) - Framework terminology reference
- [Changelog](/docs/changelog) - Release history and what changed between versions
- [Building Your Application](/docs/build-your-application) - Application development guides and patterns
- [API Reference](/docs/api-reference) - Module API documentation
- [Examples](/docs/recipes) - More examples and implementation patterns


---

# Core Concepts

## CQRS Pattern Flow

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/architecture/cqrs-flow

# CQRS Pattern Flow

This document explains how the CQRS (Command Query Responsibility Segregation) pattern is implemented in MBC CQRS Serverless.

## CQRS Overview

```mermaid
flowchart TB
    Client[Client Application]

    subgraph Write
        CommandAPI[Command API]
        CommandHandler[Command Handler]
        CommandService[Command Service]
        EventStore[(Event Store)]
        EventPublisher[Event Publisher]
    end

    subgraph Read
        QueryAPI[Query API]
        QueryHandler[Query Handler]
        DataService[Data Service]
        ReadStore[(Read Store)]
    end

    subgraph Events
        EventHandler[Event Handler]
        Projector[Projector]
    end

    Client --> CommandAPI
    Client --> QueryAPI

    CommandAPI --> CommandHandler
    CommandHandler --> CommandService
    CommandService --> EventStore
    CommandService --> EventPublisher

    QueryAPI --> QueryHandler
    QueryHandler --> DataService
    DataService --> ReadStore

    EventPublisher --> EventHandler
    EventHandler --> Projector
    Projector --> ReadStore
```

## Command Flow - Write Path

The flow of write operations.

```mermaid
sequenceDiagram
    Client->>Gateway: POST request
    Gateway->>Controller: DTO
    Controller->>Handler: Command
    Handler->>Handler: Validate
    Handler->>Service: publish
    Service->>DynamoDB: PutItem (COMMAND table)
    DynamoDB-->>Service: OK
    Service-->>Handler: CommandModel | null
    Note over DynamoDB,SNS: Async: DynamoDB Streams → DataSyncHandler → DATA table → SNS
    Handler-->>Controller: Result
    Controller-->>Gateway: 201
    Gateway-->>Client: Response
```

### Command Flow Steps

1. **Request Received**: Client sends POST/PUT/DELETE request
2. **DTO Validation**: Controller validates input using class-validator
3. **Command Dispatch**: Controller creates and dispatches command
4. **Business Logic**: Command handler executes business rules
5. **Persistence**: Command service persists to DynamoDB with optimistic locking
6. **Event Publishing**: Domain events are published to SNS asynchronously via DynamoDB Streams and DataSyncHandler
7. **Response**: Success response returned to client

## Query Flow - Read Path

The flow of read operations.

```mermaid
sequenceDiagram
    Client->>Gateway: GET request
    Gateway->>Controller: Request
    Controller->>Handler: Query
    Handler->>DataService: getItem
    DataService->>Database: Query
    Database-->>DataService: Item
    DataService-->>Handler: Entity
    Handler-->>Controller: Result
    Controller-->>Gateway: 200
    Gateway-->>Client: Response
```

### Query Flow Steps

1. **Request Received**: Client sends GET request
2. **Query Dispatch**: Controller creates and dispatches query
3. **Data Retrieval**: Query handler calls data service
4. **Database Query**: Data service queries DynamoDB or RDS
5. **Response**: Data returned to client

## Read-Your-Writes Consistency {#read-your-writes}

### The Eventual Consistency Challenge

Because `publishAsync` writes to the command table and then returns immediately — before the SNS-triggered projector has updated the read store — there is a short window where a subsequent read will return stale data:

```text
publishAsync()
     │
     ▼
CommandTable ──► SNS ──► Lambda ──► ReadStore
     │                                  ▲
     │              ~async window~       │
     └──── publishAsync returns ────     │
                                         │
Client reads here ───────────────────────┘  ← may return OLD data
```

This is expected behaviour in an eventually-consistent system, but can cause confusing UX when a user creates/updates a record and immediately navigates to the list — only to see the previous state.

### Read-Your-Writes (RYW) Solution {#ryw-solution}

MBC CQRS Serverless v1.2.0 introduced a session-based **Read-Your-Writes** layer that bridges this async window for the user who just issued the write:

```text
publishAsync()
     │
     ├──► CommandTable ──► SNS ──► Lambda ──► ReadStore
     │
     └──► SessionTable  ← small TTL-bounded entry
               │
               ▼
         Repository.getItem / listItemsByPk / listItems
               │
               ├── fetch from ReadStore  (DataService)
               └── fetch pending commands from SessionTable
                         │
                         └── merge → return consistent result
```

When `RYW_SESSION_TTL_MINUTES` is set, after each `publishAsync` / `publishPartialUpdateAsync` call the `SessionService` writes a short-lived entry to a dedicated session table. The `Repository` class (which wraps `DataService`) automatically reads those entries and merges any pending commands into the query result — so the caller sees their own write immediately, even before the projector has run.

### RYW Concepts at a Glance

| Concept | Description |
|-------------|-----------------|
| Session entry | Written by `SessionService.put()` after every successful `publishAsync`; expires after `RYW_SESSION_TTL_MINUTES` minutes |
| Repository | Drop-in replacement for `DataService` that transparently applies the RYW merge |
| Merge strategy | Pending `create` commands are prepended; pending `delete` commands are filtered out; `update` / `partial-update` are applied on top of the read-store item |
| Fallback | When `RYW_SESSION_TTL_MINUTES` is unset or set to a non-positive value, `SessionService.put()` is a no-op and `Repository` behaves identically to `DataService` |

:::info Version Note (v1.2.0)
Read-Your-Writes support (`SessionService`, `Repository`) was added in [v1.2.0](/docs/changelog#v120). Enabling it requires setting `RYW_SESSION_TTL_MINUTES` and provisioning a session DynamoDB table.

See the [Read-Your-Writes implementation guide](/docs/command-service#read-your-writes) for setup steps and full API reference.
:::

## Key Components

### Command Handler

```typescript
@Injectable()
export class ResourceService {
  constructor(private readonly commandService: CommandService) {}

  async create(
    dto: CreateResourceDto,
    invokeContext: IInvoke,
  ): Promise<CommandModel | null> {
    // 1. Validate business rules
    // 2. Build the command input (pk, sk, attributes, ...)
    // 3. Persist and publish event
    return this.commandService.publishAsync(input, { invokeContext });
  }
}
```

### Query Handler

```typescript
@Injectable()
export class ResourceQueryService {
  constructor(private readonly dataService: DataService) {}

  async findOne(pk: string, sk: string): Promise<DataModel | undefined> {
    return this.dataService.getItem({ pk, sk });
  }
}
```

## Benefits of CQRS

Adopting the CQRS pattern provides these benefits:

- **Scalability**: Read and write can be scaled independently
- **Optimization**: Optimize each side for its specific purpose
- **Flexibility**: Use different data models for reads and writes
- **Performance**: Denormalize read models for fast queries
- **Auditability**: Complete event history for audit trails


## Related Documentation

- [System Overview](/docs/architecture/system-overview) - AWS infrastructure components
- [Event Sourcing](/docs/architecture/event-sourcing) - Event storage and replay
- [Command Service](/docs/command-service) - Implement CQRS commands
- [Data Service](/docs/data-service) - Implement CQRS queries


---

## Event Sourcing Pattern

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/architecture/event-sourcing

# Event Sourcing Pattern

This document explains the Event Sourcing implementation in MBC CQRS Serverless.

## Event Sourcing Overview

```mermaid
flowchart TB
    subgraph EventStore
        ES[(DynamoDB)]
    end

    subgraph EventFlow
        Command[Command]
        Aggregate[Aggregate]
        Event1[Event 1]
        Event2[Event 2]
        Event3[Event 3]
    end

    subgraph Projections
        P1[Read Model A]
        P2[Read Model B]
        P3[Notification Service]
    end

    Command --> Aggregate
    Aggregate --> Event1
    Aggregate --> Event2
    Aggregate --> Event3

    Event1 --> ES
    Event2 --> ES
    Event3 --> ES

    ES --> P1
    ES --> P2
    ES --> P3
```

## Event Lifecycle

```mermaid
sequenceDiagram
    Cmd->>Agg: Execute Command
    Agg->>Agg: Validate Business Rules
    Agg->>Agg: Apply State Change
    Agg->>ES: Store Event (COMMAND table)
    Note over ES,SQS: Async: DynamoDB Streams → DataSyncHandler → DATA table
    ES->>SNS: Publish Event (via DataSyncHandler)
    SNS->>SQS: Fan-out
    SQS->>EH: Trigger Handler
    EH->>RM: Update Projection
```

## DynamoDB Event Store Schema

### Key Structure

The DynamoDB key structure for event storage:

- **PK (Partition Key)**: `{TENANT}#{ENTITY_TYPE}` (Example: `TENANT001#ORDER`)
- **SK (Sort Key)**: `{ENTITY_TYPE}#{ID}@{version}` (Example: `ORDER#20240101-001@1`)

### Event Record Example

```json
{
  "pk": "TENANT001#ORDER",
  "sk": "ORDER#20240101-001@1",
  "version": 3,
  "type": "OrderCreated",
  "data": {
    "orderId": "20240101-001",
    "customerId": "CUST-001",
    "items": [],
    "totalAmount": 15000
  },
  "createdAt": "2024-01-01T10:00:00Z",
  "createdBy": "user-123"
}
```

## Optimistic Locking

Explains the optimistic locking mechanism for ensuring data consistency during concurrent updates.

```mermaid
sequenceDiagram
    C1->>DB: Read v1
    C2->>DB: Read v1
    C1->>DB: Update v1 to v2
    DB-->>C1: Success
    C2->>DB: Update v1 to v2
    DB-->>C2: ConditionalCheckFailed
    C2->>DB: Retry Read v2
    C2->>DB: Update v2 to v3
    DB-->>C2: Success
```

### Version Control Implementation

```typescript
// Command Service automatically handles versioning
await this.commandService.publishAsync(entity, {
  invokeContext: context,
});

// DynamoDB ConditionExpression ensures optimistic locking
// ConditionExpression: 'attribute_not_exists(pk) AND attribute_not_exists(sk)'
// sk includes the version number, preventing duplicate command versions
```

## Event Processing Pipeline

```mermaid
flowchart LR
    subgraph EventSource
        ES[Event Store]
    end

    subgraph MessageBroker
        SNS[SNS Topic]
        SQS1[SQS Queue 1]
        SQS2[SQS Queue 2]
        SQS3[SQS Queue 3]
    end

    subgraph EventHandlers
        EH1[Projection Handler]
        EH2[Notification Handler]
        EH3[Integration Handler]
    end

    subgraph Outputs
        RM[(Read Model)]
        Email[Email Service]
        ExtAPI[External API]
    end

    ES --> SNS
    SNS --> SQS1
    SNS --> SQS2
    SNS --> SQS3

    SQS1 --> EH1
    SQS2 --> EH2
    SQS3 --> EH3

    EH1 --> RM
    EH2 --> Email
    EH3 --> ExtAPI
```

## Event Handler Implementation

```typescript
import { EventHandler, IEventHandler } from '@mbc-cqrs-serverless/core';

@EventHandler(OrderCreatedEvent)
export class OrderCreatedHandler implements IEventHandler<OrderCreatedEvent> {
  constructor(
    private readonly notificationService: NotificationService,
    private readonly readModelService: ReadModelService,
  ) {}

  async execute(event: OrderCreatedEvent): Promise<void> {
    // Update read model
    await this.readModelService.updateOrderSummary(event);

    // Send notification
    await this.notificationService.sendOrderConfirmation(event);
  }
}
```

## Benefits of Event Sourcing

Adopting Event Sourcing provides these benefits:

- **Complete Audit Trail**: All state changes are recorded as events
- **Time Travel**: Reconstruct state at any point in time
- **Event Replay**: Replay events to rebuild projections
- **Debugging**: Trace exact sequence of operations
- **Analytics**: Rich event data for business intelligence
- **Integration**: Events can trigger external system updates

## Best Practices

Best practices for effective Event Sourcing:

1. **Immutable Events**: Never modify stored events
2. **Idempotent Handlers**: Handle duplicate event delivery gracefully
3. **Event Versioning**: Plan for event schema evolution
4. **Correlation IDs**: Track related events across services
5. **Dead Letter Queues**: Handle failed event processing


## Related Documentation

- [CQRS Flow](/docs/architecture/cqrs-flow) - Command and query separation
- [Command Service](/docs/command-service) - Publishing events with commands
- [DynamoDB](/docs/dynamodb) - Event store implementation
- [Version Conflict Guide](/docs/version-conflict-guide) - Optimistic locking with events


---

## System Architecture Overview

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/architecture/system-overview

# System Architecture Overview

This document provides an overview of the MBC CQRS Serverless framework architecture.

## AWS Infrastructure

```mermaid
flowchart TB
    subgraph Clients
        WebApp[Web Application]
        MobileApp[Mobile Application]
        External[External Systems]
    end

    subgraph AWS
        subgraph API
            APIGW[API Gateway]
            AppSync[AppSync]
            WSGateway[WebSocket API]
        end

        subgraph Auth
            Cognito[Amazon Cognito]
        end

        subgraph Compute
            Lambda[AWS Lambda]
        end

        subgraph Storage
            DynamoDB[(DynamoDB)]
            RDS[(RDS Aurora)]
            S3[(S3)]
        end

        subgraph Messaging
            SNS[SNS]
            SQS[SQS]
        end

        subgraph Orchestration
            StepFunctions[Step Functions]
        end

        subgraph Notifications
            SES[SES]
        end
    end

    WebApp --> APIGW
    WebApp --> AppSync
    WebApp --> WSGateway
    MobileApp --> APIGW
    MobileApp --> AppSync
    External --> APIGW

    APIGW --> Cognito
    AppSync --> Cognito
    WSGateway --> Cognito

    APIGW --> Lambda
    AppSync --> Lambda
    WSGateway --> Lambda

    Lambda --> DynamoDB
    Lambda --> RDS
    Lambda --> S3
    Lambda --> SNS
    Lambda --> SES
    Lambda --> StepFunctions

    SNS --> SQS
    SQS --> Lambda
    StepFunctions --> Lambda
```

## Component Description

### API Layer

The entry point for receiving client requests.

- **API Gateway**: REST API endpoints for CRUD operations
- **AppSync**: GraphQL API for flexible queries and subscriptions
- **WebSocket API**: Real-time bidirectional communication

### Authentication

- **Amazon Cognito**: User authentication, JWT tokens, and user pools

### Compute

- **AWS Lambda**: Serverless execution of NestJS applications

### Data Storage

- **DynamoDB**: Primary event store for CQRS data persistence
- **RDS Aurora**: Optional relational data for complex queries
- **S3**: File and document storage

### Messaging

- **SNS**: Event fan-out and topic-based publishing
- **SQS**: Reliable message queuing and async processing

### Orchestration

- **Step Functions**: Long-running workflows and saga patterns

### Notifications

- **SES**: Transactional email delivery

## Data Flow

How requests flow through the system.

1. **Client Request**: Client sends request via API Gateway, AppSync, or WebSocket
2. **Authentication**: Cognito validates JWT tokens
3. **Command Execution**: Lambda processes command and persists to DynamoDB
4. **Event Publishing**: DynamoDB Streams triggers DataSyncHandler, which syncs to the DATA table and publishes events to SNS
5. **Event Processing**: SQS queues trigger Lambda handlers for async processing
6. **Read Model Update**: Projections update RDS for complex queries

## Multi-Tenant Architecture

```mermaid
flowchart LR
    subgraph TenantIsolation
        Request[Incoming Request]
        Auth[Authentication]
        TenantResolver[Tenant Resolver]

        subgraph DataPartition
            T1[Tenant A Data]
            T2[Tenant B Data]
            T3[Tenant C Data]
        end
    end

    Request --> Auth
    Auth --> TenantResolver
    TenantResolver --> T1
    TenantResolver --> T2
    TenantResolver --> T3
```

Tenant isolation is achieved through:

- **Partition Key Prefix**: Each tenant's data is prefixed with the tenant code
- **Request Context**: Tenant information is extracted from JWT tokens
- **Query Filtering**: All queries are automatically scoped to the tenant


## Related Documentation

- [CQRS Flow](/docs/architecture/cqrs-flow) - How commands and queries flow
- [CDK Infrastructure](/docs/architecture/cdk-infrastructure) - AWS infrastructure code
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant isolation details
- [Getting Started](/docs/getting-started) - Start building


---

## Architecture

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/architecture

# Architecture

This section provides a comprehensive overview of the MBC CQRS Serverless framework architecture.

## Overview {#overview}

The framework is built on AWS serverless services and implements the CQRS pattern with Event Sourcing for scalable, event-driven applications.

## Architecture Sections {#architecture-sections}

- [System Overview](/docs/architecture/system-overview) - AWS infrastructure components and their interactions.
- [CQRS Pattern Flow](/docs/architecture/cqrs-flow) - How commands and queries are separated and processed.
- [Event Sourcing](/docs/architecture/event-sourcing) - Event storage, replay, and projection mechanisms.
- [Step Functions](/docs/architecture/step-functions) - Workflow orchestration for async task processing.
- [CDK Infrastructure](/docs/architecture/cdk-infrastructure) - AWS CDK infrastructure provisioning and configuration.

## Key Concepts {#key-concepts}

### CQRS

Separating read and write operations for optimized data handling.

### Event Sourcing

Storing all changes as a sequence of events.

### Serverless

Leveraging AWS Lambda, DynamoDB, and other managed services.


## Related Documentation

- [Getting Started](/docs/getting-started) - Introduction to the framework
- [Installation](/docs/installation) - Set up your local environment
- [Backend Development](/docs/backend-development) - Implement features using these patterns
- [Key Patterns](/docs/key-patterns) - PK/SK design in DynamoDB
- [Glossary](/docs/glossary) - Framework terminology reference


---

## Entity Definition Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/entity-patterns

# Entity Definition Patterns

This guide explains how to define entities, DTOs, and attributes in MBC CQRS Serverless applications. Proper entity definition ensures type safety, clear separation of read and write operations, and maintainable code.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Create a new domain entity (Product, Order, User, etc.)
- Define input validation for API endpoints
- Structure data for DynamoDB storage and RDS synchronization
- Implement pagination for list queries

## Problems This Pattern Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| No type safety for entity attributes | Define TypeScript interfaces for attributes |
| Same entity used for reads and writes causes confusion | Separate DataEntity (read) and CommandEntity (write) |
| Inconsistent validation across endpoints | Use DTOs with class-validator decorators |
| Missing audit fields (createdAt, updatedAt) | Base classes include standard audit fields |

## Entity Types Overview {#entity-types-overview}

The framework provides three base entity classes:

| Class | Purpose | Usage |
|-----------|-------------|-----------|
| `DataEntity` | Read operations | Query results from DynamoDB/RDS |
| `CommandEntity` | Write operations | Commands sent to DynamoDB |
| `DataListEntity` | Paginated lists | List responses with metadata |

## Data Entity {#data-entity}

### Use Case: Return Data from API Queries

Scenario: Your API needs to return product information to the frontend.

Problem: Raw DynamoDB items lack type safety and may contain version suffixes in keys.

Solution: Use DataEntity to wrap query results with typed attributes and computed properties.

```ts
import { DataEntity } from "@mbc-cqrs-serverless/core";

export interface ProductAttributes {
  description: string;
  price: number;
  category: string;
  inStock: boolean;
  tags?: string[];
}

export class ProductDataEntity extends DataEntity {
  attributes: ProductAttributes;

  constructor(partial: Partial<ProductDataEntity>) {
    super(partial);
    Object.assign(this, partial);
  }
}
```

The `DataEntity` base class includes:

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `pk` | `string` | Yes | Partition key. Format: `{entityType}#{tenantCode}` |
| `sk` | `string` | Yes | Sort key. Format: `{entityType}#{entityId}` — **no version suffix** (unlike CommandEntity) |
| `id` | `string` | Yes | Unique entity identifier |
| `code` | `string` | Yes | Business code |
| `name` | `string` | Yes | Display name |
| `version` | `number` | Yes | Version number for optimistic locking |
| `tenantCode` | `string` | Yes | Tenant code for multi-tenant isolation |
| `type` | `string` | Yes | Entity type identifier |
| `cpk` | `string` | No | Command partition key — records the PK of the command that created/updated this data item (audit trail) |
| `csk` | `string` | No | Command sort key — records the exact SK (including `@version`) of the source command (audit trail) |
| `seq` | `number` | No | Sequence number |
| `ttl` | `number` | No | Time-to-live in seconds for DynamoDB TTL |
| `isDeleted` | `boolean` | No | Soft delete flag |
| `source` | `string` | No | Event source identifier (e.g., 'POST /api/master', 'SQS') |
| `requestId` | `string` | No | Unique request ID for tracing and idempotency |
| `createdAt` | `Date` | No | Timestamp when the entity was created |
| `createdBy` | `string` | No | User ID who created the entity |
| `createdIp` | `string` | No | IP address of the creator |
| `updatedAt` | `Date` | No | Timestamp when the entity was last updated |
| `updatedBy` | `string` | No | User ID who last updated the entity |
| `updatedIp` | `string` | No | IP address of the last updater |
| `attributes` | `any` | No | Custom attributes object for domain-specific data |

The `key` getter returns a `DetailKey` object with `pk` and `sk` for DynamoDB operations.

## Command Entity {#command-entity}

### Use Case: Create or Update Data via Commands

Scenario: User submits a form to create a new product or update an existing one.

Problem: Need to structure data for DynamoDB command publishing with proper keys and version.

Solution: Use CommandEntity to structure write operations with required fields for CQRS command processing.

```ts
import { CommandEntity } from "@mbc-cqrs-serverless/core";

export interface ProductAttributes {
  description: string;
  price: number;
  category: string;
  inStock: boolean;
  tags?: string[];
}

export class ProductCommandEntity extends CommandEntity {
  attributes: ProductAttributes;

  constructor(partial: Partial<ProductCommandEntity>) {
    super();
    Object.assign(this, partial);
  }
}
```

The `CommandEntity` base class includes:

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `pk` | `string` | Yes | Partition key. Format: `{entityType}#{tenantCode}` |
| `sk` | `string` | Yes | Sort key. Format: `{entityType}#{entityId}@{version}` |
| `id` | `string` | Yes | Unique entity identifier |
| `code` | `string` | Yes | Business code |
| `name` | `string` | Yes | Display name |
| `version` | `number` | Yes | Version number for optimistic locking |
| `tenantCode` | `string` | Yes | Tenant code for multi-tenant isolation |
| `type` | `string` | Yes | Entity type identifier |
| `status` | `string` | No | Processing status (e.g., 'PENDING', 'COMPLETED', 'FAILED') |
| `seq` | `number` | No | Sequence number |
| `ttl` | `number` | No | Time-to-live in seconds for DynamoDB TTL |
| `isDeleted` | `boolean` | No | Soft delete flag |
| `source` | `string` | No | Event source identifier (e.g., 'POST /api/master', 'SQS') |
| `requestId` | `string` | No | Unique request ID for tracing and idempotency |
| `createdAt` | `Date` | No | Timestamp when the command was created |
| `createdBy` | `string` | No | User ID who created the command |
| `createdIp` | `string` | No | IP address of the creator |
| `updatedAt` | `Date` | No | Timestamp when the command was last updated |
| `updatedBy` | `string` | No | User ID who last updated the command |
| `updatedIp` | `string` | No | IP address of the last updater |
| `attributes` | `any` | No | Custom attributes object for domain-specific data |

The `key` getter returns a `DetailKey` object with `pk` and `sk` for DynamoDB operations.

:::info CommandEntity vs DataEntity
The main differences between `CommandEntity` and `DataEntity` are:

| Aspect | `CommandEntity` | `DataEntity` |
|------------|-----------------|--------------|
| Table | Command (write) table | Data (read) table |
| Sort Key | Includes version suffix (`@{version}`) | No version suffix |
| `status` | Yes (processing status) | No |
| `cpk`/`csk` | No | Yes (references source command) |

:::

## Data List Entity {#data-list-entity}

### Use Case: Return Paginated Lists

Scenario: Frontend requests a list of products with pagination.

Problem: Need to return both the items and total count for pagination UI.

Solution: Use DataListEntity to wrap list results with total count and pagination cursor.

```ts
import { DataListEntity } from "@mbc-cqrs-serverless/core";
import { ProductDataEntity } from "./product-data.entity";

export class ProductListEntity extends DataListEntity {
  items: ProductDataEntity[];

  constructor(partial: Partial<ProductListEntity>) {
    super(partial);
    Object.assign(this, partial);
  }
}
```

The `DataListEntity` base class includes:

```ts
// Inherited from DataListEntity
{
  total?: number;       // Total count (optional — not populated by listItemsByPk)
  lastSk?: string;      // Last sort key for pagination
}
```

:::warning total field is not auto-populated
`DataService.listItemsByPk()` does **not** set `total` — it only sets `items` and `lastSk`. To populate `total`, run a separate `countItemsByPk()` call. Avoid displaying `total` in the UI unless you explicitly populate it.
:::

Use `DataListEntity` as the return type for all list/search service methods. Always return it from controllers — never return raw arrays — so the frontend receives a consistent `{ items, total, lastSk }` envelope.

## Command DTO {#command-dto}

### Use Case: Prepare Data for Command Publishing

Scenario: Service layer needs to create a command from validated input.

Solution: Use CommandDto to transform input data into the structure required by CommandService.

```ts
import { CommandDto } from "@mbc-cqrs-serverless/core";

export interface ProductAttributes {
  description: string;
  price: number;
  category: string;
  inStock: boolean;
  tags?: string[];
}

export class ProductCommandDto extends CommandDto {
  attributes: ProductAttributes;

  constructor(partial: Partial<ProductCommandDto>) {
    super();
    Object.assign(this, partial);
  }
}
```

:::info CommandDto Features
The base `CommandDto` class includes:
- Swagger decorators (`@ApiProperty`, `@ApiPropertyOptional`) for API documentation
- Validation decorators from `class-validator` (`@IsString`, `@IsNumber`, `@IsOptional`, etc.)
- Properties: `pk`, `sk`, `id`, `code`, `name`, `version`, `tenantCode` (optional), `type`, `isDeleted`, `seq`, `ttl`, `attributes`

Note: `tenantCode` is marked as optional (`@IsOptional()`) in the base class, allowing the framework to extract it from the invoke context if not provided.
:::

## Attributes DTO {#attributes-dto}

### Use Case: Define Business Data Structure

Scenario: Your entity has business-specific fields like price, status, and shipping information.

Solution: Define TypeScript interfaces that describe the structure of your domain data.

```ts
// Simple attributes
export interface ProductAttributes {
  description: string;
  price: number;
  category: string;
  inStock: boolean;
}

// Complex attributes with nested objects
export interface OrderAttributes {
  customerId: string;
  status: OrderStatus;
  items: OrderItem[];
  shipping: {
    address: string;
    city: string;
    postalCode: string;
    country: string;
  };
  payment: {
    method: PaymentMethod;
    transactionId?: string;
    paidAt?: string;
  };
  totalAmount: number;
  currency: string;
}

interface OrderItem {
  productId: string;
  productName: string;
  quantity: number;
  unitPrice: number;
  subtotal: number;
}

enum OrderStatus {
  PENDING = "PENDING",
  CONFIRMED = "CONFIRMED",
  SHIPPED = "SHIPPED",
  DELIVERED = "DELIVERED",
  CANCELLED = "CANCELLED",
}

enum PaymentMethod {
  CREDIT_CARD = "CREDIT_CARD",
  BANK_TRANSFER = "BANK_TRANSFER",
  CASH_ON_DELIVERY = "CASH_ON_DELIVERY",
}
```

## Create/Update DTOs {#create-update-dtos}

### Use Case: Validate API Input

Scenario: API receives JSON from frontend and needs to validate before processing.

Problem: Invalid data (empty strings, negative prices) could corrupt your data store.

Solution: Use class-validator decorators to define validation rules that run automatically.

```ts
import { IsString, IsNumber, IsBoolean, IsOptional, Min } from "class-validator";

export class CreateProductDto {
  @IsString()
  name: string;

  @IsString()
  description: string;

  @IsNumber()
  @Min(0)
  price: number;

  @IsString()
  category: string;

  @IsBoolean()
  @IsOptional()
  inStock?: boolean;
}

export class UpdateProductDto {
  @IsString()
  @IsOptional()
  name?: string;

  @IsOptional()
  attributes?: Partial<ProductAttributes>;
}
```

## Detail/Search DTOs {#detail-search-dtos}

### Use Case: Query Parameters for List and Detail Endpoints

Scenario: Frontend sends query parameters for filtering, pagination, and detail lookups.

Solution: Define DTOs that validate query parameters and provide default values.

```ts
import { IsBoolean, IsNumber, IsOptional, IsString, Min, Max } from "class-validator";
import { Type } from "class-transformer";

// For single item lookup
export class DetailDto {
  @IsString()
  pk: string;

  @IsString()
  sk: string;
}

// For list queries
export class SearchProductDto {
  @IsString()
  tenantCode: string;

  @IsString()
  @IsOptional()
  category?: string;

  @IsBoolean()
  @IsOptional()
  inStock?: boolean;

  @IsString()
  @IsOptional()
  search?: string;

  @IsNumber()
  @IsOptional()
  @Type(() => Number)
  @Min(1)
  page?: number = 1;

  @IsNumber()
  @IsOptional()
  @Type(() => Number)
  @Min(1)
  @Max(100)
  limit?: number = 20;
}
```

## Complete Domain Example {#complete-example}

### Use Case: Full E-Commerce Order Domain

Scenario: Building an order management system with orders, items, shipping, and payment.

This example shows how all entity patterns work together in a real domain:

### Directory Structure

```text
src/order/
├── order.module.ts
├── order.service.ts
├── order.controller.ts
├── entity/
│   ├── order-data.entity.ts
│   ├── order-command.entity.ts
│   └── order-list.entity.ts
├── dto/
│   ├── order-command.dto.ts
│   ├── order-attributes.dto.ts
│   ├── create-order.dto.ts
│   ├── update-order.dto.ts
│   ├── detail.dto.ts
│   └── search-order.dto.ts
├── handler/
│   └── order-rds.handler.ts
└── constant/
    └── order.enum.ts
```

### Enums

```ts
// constant/order.enum.ts
export enum OrderStatus {
  DRAFT = "DRAFT",
  PENDING = "PENDING",
  CONFIRMED = "CONFIRMED",
  PROCESSING = "PROCESSING",
  SHIPPED = "SHIPPED",
  DELIVERED = "DELIVERED",
  CANCELLED = "CANCELLED",
  REFUNDED = "REFUNDED",
}

export enum PaymentMethod {
  CREDIT_CARD = "CREDIT_CARD",
  DEBIT_CARD = "DEBIT_CARD",
  BANK_TRANSFER = "BANK_TRANSFER",
  DIGITAL_WALLET = "DIGITAL_WALLET",
  CASH_ON_DELIVERY = "CASH_ON_DELIVERY",
}

export enum PaymentStatus {
  PENDING = "PENDING",
  AUTHORIZED = "AUTHORIZED",
  CAPTURED = "CAPTURED",
  FAILED = "FAILED",
  REFUNDED = "REFUNDED",
}
```

### Attributes DTO

```ts
// dto/order-attributes.dto.ts
import { OrderStatus, PaymentMethod, PaymentStatus } from "../constant/order.enum";

export interface OrderItem {
  productId: string;
  productCode: string;
  productName: string;
  quantity: number;
  unitPrice: number;
  discount: number;
  subtotal: number;
}

export interface ShippingInfo {
  recipientName: string;
  phoneNumber: string;
  address: string;
  city: string;
  state: string;
  postalCode: string;
  country: string;
  instructions?: string;
}

export interface PaymentInfo {
  method: PaymentMethod;
  status: PaymentStatus;
  transactionId?: string;
  authorizedAt?: string;
  capturedAt?: string;
}

export interface OrderAttributes {
  customerId: string;
  customerEmail: string;
  status: OrderStatus;
  items: OrderItem[];
  shipping: ShippingInfo;
  payment: PaymentInfo;
  subtotal: number;
  shippingFee: number;
  tax: number;
  discount: number;
  totalAmount: number;
  currency: string;
  notes?: string;
  orderedAt: string;
  confirmedAt?: string;
  shippedAt?: string;
  deliveredAt?: string;
}
```

### Data Entity

```ts
// entity/order-data.entity.ts
import { DataEntity } from "@mbc-cqrs-serverless/core";
import { OrderAttributes } from "../dto/order-attributes.dto";

export class OrderDataEntity extends DataEntity {
  attributes: OrderAttributes;

  constructor(partial: Partial<OrderDataEntity>) {
    super(partial);
    Object.assign(this, partial);
  }

  // Computed properties
  get status(): string {
    return this.attributes?.status;
  }

  get totalAmount(): number {
    return this.attributes?.totalAmount ?? 0;
  }

  get itemCount(): number {
    return this.attributes?.items?.length ?? 0;
  }
}
```

### Command Entity

```ts
// entity/order-command.entity.ts
import { CommandEntity } from "@mbc-cqrs-serverless/core";
import { OrderAttributes } from "../dto/order-attributes.dto";

export class OrderCommandEntity extends CommandEntity {
  attributes: OrderAttributes;

  constructor(partial: Partial<OrderCommandEntity>) {
    super();
    Object.assign(this, partial);
  }
}
```

### List Entity

```ts
// entity/order-list.entity.ts
import { DataListEntity } from "@mbc-cqrs-serverless/core";
import { OrderDataEntity } from "./order-data.entity";

export class OrderListEntity extends DataListEntity {
  items: OrderDataEntity[];

  constructor(partial: Partial<OrderListEntity>) {
    super(partial);
    Object.assign(this, partial);
  }
}
```

### Command DTO

```ts
// dto/order-command.dto.ts
import { CommandDto } from "@mbc-cqrs-serverless/core";
import { OrderAttributes } from "./order-attributes.dto";

export class OrderCommandDto extends CommandDto {
  attributes: OrderAttributes;

  constructor(partial: Partial<OrderCommandDto>) {
    super();
    Object.assign(this, partial);
  }
}
```

### Create DTO

```ts
// dto/create-order.dto.ts
import {
  IsString,
  IsEmail,
  IsArray,
  ValidateNested,
  IsNumber,
  Min,
  IsOptional,
} from "class-validator";
import { Type } from "class-transformer";

class CreateOrderItemDto {
  @IsString()
  productId: string;

  @IsNumber()
  @Min(1)
  quantity: number;
}

class CreateShippingDto {
  @IsString()
  recipientName: string;

  @IsString()
  phoneNumber: string;

  @IsString()
  address: string;

  @IsString()
  city: string;

  @IsString()
  state: string;

  @IsString()
  postalCode: string;

  @IsString()
  country: string;

  @IsString()
  @IsOptional()
  instructions?: string;
}

export class CreateOrderDto {
  @IsString()
  customerId: string;

  @IsEmail()
  customerEmail: string;

  @IsArray()
  @ValidateNested({ each: true })
  @Type(() => CreateOrderItemDto)
  items: CreateOrderItemDto[];

  @ValidateNested()
  @Type(() => CreateShippingDto)
  shipping: CreateShippingDto;

  @IsString()
  @IsOptional()
  notes?: string;
}
```

### Update DTO

```ts
// dto/update-order.dto.ts
import { IsString, IsEnum, IsOptional, ValidateNested } from "class-validator";
import { Type } from "class-transformer";
import { OrderStatus, PaymentStatus } from "../constant/order.enum";

class UpdateShippingDto {
  @IsString()
  @IsOptional()
  recipientName?: string;

  @IsString()
  @IsOptional()
  phoneNumber?: string;

  @IsString()
  @IsOptional()
  address?: string;

  @IsString()
  @IsOptional()
  instructions?: string;
}

export class UpdateOrderDto {
  @IsEnum(OrderStatus)
  @IsOptional()
  status?: OrderStatus;

  @ValidateNested()
  @Type(() => UpdateShippingDto)
  @IsOptional()
  shipping?: UpdateShippingDto;

  @IsString()
  @IsOptional()
  notes?: string;
}

export class UpdatePaymentDto {
  @IsEnum(PaymentStatus)
  status: PaymentStatus;

  @IsString()
  @IsOptional()
  transactionId?: string;
}
```

### Search DTO

```ts
// dto/search-order.dto.ts
import { IsString, IsEnum, IsOptional, IsNumber, Min, Max, IsDateString } from "class-validator";
import { Type } from "class-transformer";
import { OrderStatus } from "../constant/order.enum";

export class SearchOrderDto {
  @IsString()
  tenantCode: string;

  @IsString()
  @IsOptional()
  customerId?: string;

  @IsEnum(OrderStatus)
  @IsOptional()
  status?: OrderStatus;

  @IsDateString()
  @IsOptional()
  orderedFrom?: string;

  @IsDateString()
  @IsOptional()
  orderedTo?: string;

  @IsNumber()
  @IsOptional()
  @Type(() => Number)
  minAmount?: number;

  @IsNumber()
  @IsOptional()
  @Type(() => Number)
  maxAmount?: number;

  @IsNumber()
  @IsOptional()
  @Type(() => Number)
  @Min(1)
  page?: number = 1;

  @IsNumber()
  @IsOptional()
  @Type(() => Number)
  @Min(1)
  @Max(100)
  limit?: number = 20;

  @IsString()
  @IsOptional()
  sortBy?: "orderedAt" | "totalAmount" | "status" = "orderedAt";

  @IsString()
  @IsOptional()
  sortOrder?: "asc" | "desc" = "desc";
}
```

## Best Practices {#best-practices}

### 1. Separate Read and Write Entities

Use `DataEntity` for reads and `CommandEntity` for writes:

```ts
// Read operations return DataEntity
async findOne(key: DetailDto): Promise<OrderDataEntity>

// Write operations return DataEntity (after command is processed)
async create(dto: CreateOrderDto): Promise<OrderDataEntity>
```

### 2. Use Typed Attributes

Always define interfaces for attributes:

```ts
interface ProductAttributes {
  description: string;
  price: number;
  // ...
}

// Not this:
attributes: Record<string, any>  // Avoid
```

### 3. Add Computed Properties

Add getters for commonly accessed nested data:

```ts
export class OrderDataEntity extends DataEntity {
  attributes: OrderAttributes;

  get totalAmount(): number {
    return this.attributes?.totalAmount ?? 0;
  }

  get isPaid(): boolean {
    return this.attributes?.payment?.status === PaymentStatus.CAPTURED;
  }
}
```

### 4. Validate Input DTOs

Use class-validator for input validation:

```ts
import { IsString, IsNumber, Min, IsEmail } from "class-validator";

export class CreateOrderDto {
  @IsEmail()
  customerEmail: string;

  @IsNumber()
  @Min(0)
  totalAmount: number;
}
```

### 5. Use Enums for Status Fields

Define enums for status and type fields:

```ts
enum OrderStatus {
  PENDING = "PENDING",
  CONFIRMED = "CONFIRMED",
  // ...
}

// In DTO
@IsEnum(OrderStatus)
status: OrderStatus;
```


## Related Documentation

- [DynamoDB](/docs/dynamodb) - Table structure where entities are stored
- [Key Patterns](/docs/key-patterns) - PK/SK key design
- [Data Service](/docs/data-service) - Query entities with DataService
- [Serialization Helpers](/docs/serialization) - Convert between DynamoDB and external structures
- [Interfaces](/docs/interfaces) - DataEntity and CommandEntity interfaces
- [Service Patterns](/docs/service-patterns) - Service layer with entities


---

## Key Design Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/key-patterns

# Key Design Patterns

This guide explains how to design partition keys (PK) and sort keys (SK) for your entities in DynamoDB. Proper key design is critical for performance, scalability, and query efficiency.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Design keys for a new entity type
- Model parent-child relationships (Order → OrderItems)
- Support multi-tenant data isolation
- Enable efficient query patterns (list by tenant, filter by date)
- Handle versioning for optimistic locking

:::tip Related Documentation
- [Entity Definition Patterns](/docs/entity-patterns) - How to define entities that use these key patterns
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant isolation and cross-tenant operations
- [Backend Development Guide](/docs/backend-development) - Complete module implementation patterns
:::

## Problems This Pattern Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| Querying all items for a tenant is slow | Include tenant code in PK for partition-level isolation |
| Can't list child items without knowing all keys | Use shared PK with different SK prefixes |
| IDs are not sortable by creation time | Use ULID which is both unique and time-sortable |
| Version conflicts in concurrent updates | Version suffix in SK enables optimistic locking |

## Pattern Selection Guide {#pattern-selection}

Use this decision tree to choose the right key pattern for your use case:

### Decision Matrix

| Requirement | Recommended Pattern | PK Structure | SK Structure |
|-----------------|------------------------|------------------|------------------|
| Simple CRUD with tenant isolation | [Simple Entity](#pattern-1-simple-entity) | `ENTITY#tenantCode` | `ulid()` |
| Parent with multiple children | [Hierarchical](#pattern-2-hierarchical-entity) | `PARENT#tenantCode` | `TYPE#parentId[#childId]` |
| Multiple entity variants | [Composite SK](#pattern-3-user-with-multiple-auth-providers) | `ENTITY#tenantCode` | `variant#identifier` |
| Cross-tenant shared data | [Common Tenant](#pattern-4-multi-tenant-association) | `ENTITY#common` | `tenantCode#identifier` |
| Categorized configurations | [Master Data](#pattern-5-master-data-with-categories) | `MASTER#tenantCode` | `TYPE#category#code` |
| Time-based queries | [Time-Series](#pattern-6-time-series-data) | `LOG#tenantCode#YYYY-MM` | `timestamp#eventId` |

### Decision Tree

```text
Start: What type of data are you storing?
│
├─ Standalone entity (Product, Customer)
│  └─ Use Simple Entity Pattern
│
├─ Parent-child relationship (Order → Items)
│  └─ Do children need independent access?
│     ├─ Yes → Use separate PK with reference
│     └─ No → Use Hierarchical Pattern (shared PK)
│
├─ Configuration/Master data
│  └─ Use Master Data Pattern
│
├─ Time-based events (logs, audit)
│  └─ Use Time-Series Pattern
│
└─ User/Entity with multiple variants
   └─ Use Composite SK Pattern
```

## Key Structure Overview {#key-structure-overview}

The framework uses a consistent key structure:

```text
PK = PREFIX#TENANT_CODE
SK = IDENTIFIER[@VERSION]
ID = PK#SK (without version)
```

The `KEY_SEPARATOR` constant (`#`) is used to separate key components.

### Framework Constants {#framework-constants}

The framework provides these constants in `@mbc-cqrs-serverless/core`:

| Constant | Value | Description |
|--------------|-----------|-----------------|
| `KEY_SEPARATOR` | `#` | Separates key components (PK segments, SK segments, ID) |
| `VER_SEPARATOR` | `@` | Separates sort key from version number |
| `VERSION_FIRST` | `0` | Initial version for new entities |
| `VERSION_LATEST` | `-1` | Indicates query for latest version |
| `TENANT_COMMON` | `common` | Tenant code for shared/cross-tenant data (deprecated — use DEFAULT_COMMON_TENANT_CODES) |
| `DEFAULT_COMMON_TENANT_CODES` | `['common']` | Common tenant codes list, configurable via COMMON_TENANT_CODES env var |
| `DEFAULT_TENANT_CODE` | `single` | Default tenant for single-tenant mode |

:::tip Consistent Tenant Code Format
The `@mbc-cqrs-serverless/master` and `@mbc-cqrs-serverless/tenant` packages use `SettingTypeEnum.TENANT_COMMON = 'common'` (lowercase), which is consistent with the tenant code normalization in `getUserContext()`. This ensures that data saved by `createCommonTenantSetting()` or `createCommonTenant()` methods can be correctly queried.
:::

### Built-in Key Generators {#built-in-generators}

The framework provides these pre-built key generators:

```ts
import { masterPk, seqPk, ttlSk } from "@mbc-cqrs-serverless/core";

// Master data partition key
masterPk("tenant001");      // "MASTER#tenant001"
masterPk();                 // "MASTER#single" (default tenant)

// Sequence partition key
seqPk("tenant001");         // "SEQ#tenant001"

// TTL sort key for table-level TTL settings
ttlSk("product");           // "TTL#product"
```

## Basic Key Generation {#basic-key-generation}

Import utilities from the core package:

```ts
import {
  generateId,
  getTenantCode,
  KEY_SEPARATOR,
  VER_SEPARATOR,
  removeSortKeyVersion,
  addSortKeyVersion,
  getSortKeyVersion,
  VERSION_FIRST,
  VERSION_LATEST,
  TENANT_COMMON,
} from "@mbc-cqrs-serverless/core";
import { ulid } from "ulid";
```

### Generating Keys

```ts
const PRODUCT_PK_PREFIX = "PRODUCT";

// Generate PK
const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;
// Result: "PRODUCT#tenant001"

// Generate SK (using ULID for uniqueness and sortability)
const sk = ulid();
// Result: "01HX7MBJK3V9WQBZ7XNDK5ZT2M"

// Generate ID (combination of PK and SK)
const id = generateId(pk, sk);
// Result: "PRODUCT#tenant001#01HX7MBJK3V9WQBZ7XNDK5ZT2M"
```

### Version Handling

```ts
// Add version to SK
const skWithVersion = addSortKeyVersion(sk, 3);
// Result: "01HX7MBJK3V9WQBZ7XNDK5ZT2M@3"

// Remove version from SK
const baseSk = removeSortKeyVersion(skWithVersion);
// Result: "01HX7MBJK3V9WQBZ7XNDK5ZT2M"

// Get version number from SK
const version = getSortKeyVersion(skWithVersion);
// Result: 3

// Get version from SK without version suffix
const latestVersion = getSortKeyVersion(sk);
// Result: -1 (VERSION_LATEST)
```

### Tenant Code Extraction

```ts
import { getTenantCode } from "@mbc-cqrs-serverless/core";

// Extract tenant code from PK
const tenantCode = getTenantCode("PRODUCT#tenant001");
// Result: "tenant001"

// Returns undefined if no separator found
const noTenant = getTenantCode("PRODUCT");
// Result: undefined
```

## Common Key Patterns {#common-patterns}

### Pattern 1: Simple Entity {#pattern-1-simple-entity}

#### Use Case: Product Catalog

Scenario: Store products that belong to a tenant with unique IDs.

When to use: Standalone entities without parent-child relationships.

```ts
// Key Structure
PK: PRODUCT#<tenantCode>
SK: <ulid>

// Example
PK: PRODUCT#tenant001
SK: 01HX7MBJK3V9WQBZ7XNDK5ZT2M
ID: PRODUCT#tenant001#01HX7MBJK3V9WQBZ7XNDK5ZT2M
```

```ts
const pk = `PRODUCT${KEY_SEPARATOR}${tenantCode}`;
const sk = ulid();
const id = generateId(pk, sk);
```

### Pattern 2: Hierarchical Entity {#pattern-2-hierarchical-entity}

#### Use Case: Order with Line Items

Scenario: An order contains multiple items. Need to query all items for an order efficiently.

Solution: Share PK between parent and children, use SK prefix to distinguish item types.

```ts
// Order Key Structure
PK: ORDER#<tenantCode>
SK: ORDER#<orderId>

// Order Item Key Structure (same PK, different SK prefix)
PK: ORDER#<tenantCode>
SK: ORDER_ITEM#<orderId>#<itemId>

// Example
Order:
  PK: ORDER#tenant001
  SK: ORDER#01HX7MBJK3V9WQBZ7XNDK5ZT2M

Order Items:
  PK: ORDER#tenant001
  SK: ORDER_ITEM#01HX7MBJK3V9WQBZ7XNDK5ZT2M#001
  SK: ORDER_ITEM#01HX7MBJK3V9WQBZ7XNDK5ZT2M#002
```

```ts
const ORDER_SK_PREFIX = "ORDER";
const ORDER_ITEM_SK_PREFIX = "ORDER_ITEM";

// Create order
const orderPk = `ORDER${KEY_SEPARATOR}${tenantCode}`;
const orderId = ulid();
const orderSk = `${ORDER_SK_PREFIX}${KEY_SEPARATOR}${orderId}`;

// Create order item
const itemSk = `${ORDER_ITEM_SK_PREFIX}${KEY_SEPARATOR}${orderId}${KEY_SEPARATOR}${itemId}`;
```

### Pattern 3: User with Multiple Auth Providers {#pattern-3-user-with-multiple-auth-providers}

#### Use Case: Unified User Identity

Scenario: Users can sign in with local password, SSO, or OAuth. Need to link all auth methods to one user.

Solution: Same PK for all user records, SK prefix indicates authentication provider.

```ts
// Key Structure
PK: USER#<tenantCode>
SK: <provider>#<userId>

// Examples
PK: USER#common
SK: local#user123           // Local authentication
SK: sso#abc123def456        // SSO provider
SK: oauth#google789         // OAuth provider
SK: temp#session456         // Temporary session
SK: profile#user123         // User profile data
```

```ts
type AuthProvider = "local" | "sso" | "oauth" | "temp" | "profile";

function generateUserSk(provider: AuthProvider, userId: string): string {
  return `${provider}${KEY_SEPARATOR}${userId}`;
}

const pk = `USER${KEY_SEPARATOR}common`;
const sk = generateUserSk("sso", cognitoSubId);
```

### Pattern 4: Multi-Tenant Association {#pattern-4-multi-tenant-association}

#### Use Case: User Belongs to Multiple Organizations

Scenario: In a SaaS application, one user can belong to multiple tenants/organizations.

Solution: Use a common tenant with SK that combines tenant and user codes.

```ts
// Key Structure
PK: USER_TENANT#<commonTenant>
SK: <tenantCode>#<userCode>

// Example
PK: USER_TENANT#common
SK: tenant001#user123
SK: tenant002#user123   // Same user in different tenant
```

```ts
const pk = `USER_TENANT${KEY_SEPARATOR}common`;
const sk = `${tenantCode}${KEY_SEPARATOR}${userCode}`;
```

### Pattern 5: Master Data with Categories {#pattern-5-master-data-with-categories}

#### Use Case: Application Settings and Configuration

Scenario: Store email templates, product categories, and application settings.

Solution: Use type prefix (SETTING, DATA) in SK to organize different configuration types.

```ts
// Key Structure
PK: MASTER#common
SK: <type>#<category>#<code>

// Types: SETTING, DATA, COPY
// Master data is shared across all tenants under the common partition
// Examples
PK: MASTER#common
SK: SETTING#notification#email_template
SK: DATA#product_category#electronics
SK: DATA#product_category#clothing
SK: COPY#backup#2024-01-01
```

```ts
const SETTING_PREFIX = "SETTING";
const DATA_PREFIX = "DATA";

function generateMasterSk(type: string, category: string, code: string): string {
  return `${type}${KEY_SEPARATOR}${category}${KEY_SEPARATOR}${code}`;
}

const pk = `MASTER${KEY_SEPARATOR}common`;
const sk = generateMasterSk(DATA_PREFIX, "product_category", "electronics");
```

### Pattern 6: Time-Series Data {#pattern-6-time-series-data}

#### Use Case: Activity Logs and Audit Trail

Scenario: Store time-stamped events that need to be queried by date range.

Solution: Include date in PK for time-based partitioning, timestamp in SK for sorting.

```ts
// Key Structure
PK: LOG#<tenantCode>#<year-month>
SK: <timestamp>#<eventId>

// Example
PK: LOG#tenant001#2024-01
SK: 2024-01-15T10:30:00Z#evt001
SK: 2024-01-15T10:31:00Z#evt002
```

```ts
function generateLogKeys(tenantCode: string, timestamp: Date, eventId: string) {
  const yearMonth = timestamp.toISOString().slice(0, 7); // "2024-01"
  const pk = `LOG${KEY_SEPARATOR}${tenantCode}${KEY_SEPARATOR}${yearMonth}`;
  const sk = `${timestamp.toISOString()}${KEY_SEPARATOR}${eventId}`;
  return { pk, sk };
}
```

## Key Helper Functions {#key-helper-functions}

Create a helpers file for consistent key generation:

```ts
// helpers/key.ts
import { KEY_SEPARATOR, generateId } from "@mbc-cqrs-serverless/core";
import { ulid } from "ulid";

// Entity prefixes
export const PRODUCT_PK_PREFIX = "PRODUCT";
export const ORDER_PK_PREFIX = "ORDER";
export const ORDER_SK_PREFIX = "ORDER";
export const ORDER_ITEM_SK_PREFIX = "ORDER_ITEM";
export const USER_PK_PREFIX = "USER";
export const MASTER_PK_PREFIX = "MASTER";
export const NOTIFICATION_PK_PREFIX = "NOTIFICATION";

// Key generators
export function generateProductPk(tenantCode: string): string {
  return `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;
}

export function generateOrderPk(tenantCode: string): string {
  return `${ORDER_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;
}

export function generateOrderSk(orderId?: string): string {
  const id = orderId ?? ulid();
  return `${ORDER_SK_PREFIX}${KEY_SEPARATOR}${id}`;
}

export function generateOrderItemSk(orderId: string, itemId: string): string {
  return `${ORDER_ITEM_SK_PREFIX}${KEY_SEPARATOR}${orderId}${KEY_SEPARATOR}${itemId}`;
}

// Key parsers
export function parseOrderSk(sk: string): { prefix: string; orderId: string } {
  const parts = sk.split(KEY_SEPARATOR);
  return {
    prefix: parts[0],
    orderId: parts[1],
  };
}

export function parseOrderItemSk(sk: string): {
  prefix: string;
  orderId: string;
  itemId: string;
} {
  const parts = sk.split(KEY_SEPARATOR);
  return {
    prefix: parts[0],
    orderId: parts[1],
    itemId: parts[2],
  };
}

// ID generator with entity type
export function generateEntityId(
  prefix: string,
  tenantCode: string,
  sk?: string,
): { pk: string; sk: string; id: string } {
  const pk = `${prefix}${KEY_SEPARATOR}${tenantCode}`;
  const finalSk = sk ?? ulid();
  const id = generateId(pk, finalSk);
  return { pk, sk: finalSk, id };
}
```

## Version Management {#version-management}

The framework uses versioning for optimistic locking:

```ts
// DynamoDB Tables
// Command table: Stores all versions with @version suffix
// Data table: Stores latest version only (no version suffix)

// Version in SK (Command table)
SK: ORDER#01HX7MBJK3V9WQBZ7XNDK5ZT2M@1  // Version 1
SK: ORDER#01HX7MBJK3V9WQBZ7XNDK5ZT2M@2  // Version 2
SK: ORDER#01HX7MBJK3V9WQBZ7XNDK5ZT2M@3  // Version 3

// Data table SK (no version suffix)
SK: ORDER#01HX7MBJK3V9WQBZ7XNDK5ZT2M
```

```ts
import {
  VERSION_FIRST,
  VERSION_LATEST,
  addSortKeyVersion,
  removeSortKeyVersion,
} from "@mbc-cqrs-serverless/core";

// Creating first version
const command = new OrderCommandDto({
  pk,
  sk,
  version: VERSION_FIRST, // 0
  // ...
});

// Reading specific version from history
const skWithVersion = addSortKeyVersion(baseSk, 2);
const historicalItem = await historyService.getItem({ pk, sk: skWithVersion });

// In Data Sync Handler - always remove version for RDS storage
async up(cmd: CommandModel): Promise<any> {
  const sk = removeSortKeyVersion(cmd.sk);
  // Store sk without version in RDS
}
```

## Query Patterns {#query-patterns}

### Query by PK

```ts
// Get all products for a tenant
const items = await dataService.listItemsByPk(
  `PRODUCT${KEY_SEPARATOR}${tenantCode}`,
);
```

### Query with SK Prefix

```ts
// Get all order items for a specific order
const items = await dataService.listItemsByPk(
  `ORDER${KEY_SEPARATOR}${tenantCode}`,
  {
    sk: {
      skExpression: 'begins_with(sk, :skPrefix)',
      skAttributeValues: { ':skPrefix': `ORDER_ITEM${KEY_SEPARATOR}${orderId}` },
    },
  },
);
```

### Query with SK Range

```ts
// Get orders within a date range (if using timestamp in SK)
const items = await dataService.listItemsByPk(
  `ORDER${KEY_SEPARATOR}${tenantCode}`,
  {
    sk: {
      skExpression: 'sk BETWEEN :start AND :end',
      skAttributeValues: { ':start': startDate, ':end': endDate },
    },
  },
);
```

## Best Practices {#best-practices}

### 1. Use Consistent Prefixes

Define prefixes as constants:

```ts
// Good
export const PRODUCT_PK_PREFIX = "PRODUCT";
const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;

// Avoid
const pk = `PRODUCT#${tenantCode}`; // Magic string
```

### 2. Use ULID for Sortable IDs

ULID provides both uniqueness and time-based sorting:

```ts
import { ulid } from "ulid";

const sk = ulid();
// Result: "01HX7MBJK3V9WQBZ7XNDK5ZT2M"
// Sortable by creation time
```

### 3. Design for Query Patterns

Structure keys based on how you'll query data:

```ts
// If you need to query all items for an order:
PK: ORDER#tenant001
SK: ORDER_ITEM#orderId#itemId  // Query by SK prefix

// If you need to query items by product across orders:
// Consider a GSI or separate table
```

### 4. Keep PK Cardinality Manageable

Avoid too many unique PKs to prevent hot partitions:

```ts
// Good - bounded by tenants
PK: PRODUCT#tenant001

// Avoid - unbounded by users
PK: USER_ACTIVITY#user123  // Could create millions of partitions
```

### 5. Include Tenant in PK

Always include tenant code in PK for multi-tenant isolation:

```ts
// Good
PK: PRODUCT#tenant001

// Avoid
PK: PRODUCT  // No tenant isolation
SK: tenant001#productId  // Tenant in SK is less efficient
```

:::danger Tenant Code Normalization - Breaking Change
The `getUserContext()` function normalizes `tenantCode` to lowercase. This affects partition key generation:

```ts
// User's Cognito has uppercase tenant
custom:tenant = "MY_TENANT"

// getUserContext() returns lowercase
tenantCode = "my_tenant"

// Generated PK uses lowercase
PK: PRODUCT#my_tenant
```

**Impact on existing data:** If your existing data was saved with uppercase tenant codes in PK (e.g., `PRODUCT#MY_TENANT`), queries using normalized tenant codes will NOT find that data.

**Migration required:** See [Tenant Code Normalization Migration](/docs/data-migration-patterns#tenant-code-normalization-migration) for migration strategies, or the [v1.1.0 Migration Guide](/docs/migration/v1.1.0) for complete upgrade instructions.
:::

### 6. Use Common Tenant for Shared Data

Use a common tenant code for data shared across tenants:

```ts
// User data (shared across tenants)
PK: USER#common
SK: sso#userId

// User-tenant association
PK: USER_TENANT#common
SK: tenant001#userId
```

## Anti-Patterns to Avoid {#anti-patterns}

### 1. Embedding Too Much in Keys

```ts
// Avoid - too complex
SK: ORDER#2024-01-15#electronics#high-priority#01HX7M...

// Better - use attributes for filtering
SK: ORDER#01HX7MBJK3V9WQBZ7XNDK5ZT2M
attributes: {
  date: "2024-01-15",
  category: "electronics",
  priority: "high"
}
```

### 2. Using Mutable Data in Keys

```ts
// Avoid - status changes
SK: ORDER#pending#01HX7M...  // What happens when status changes?

// Better - use attributes
SK: ORDER#01HX7MBJK3V9WQBZ7XNDK5ZT2M
attributes: { status: "pending" }
```

### 3. Inconsistent Separators

```ts
// Avoid - mixed separators
SK: ORDER-01HX7M_item:001

// Better - consistent separator
SK: ORDER#01HX7M#ITEM#001
```

### 4. Version Suffix in Data Operations

```ts
// Avoid - including version in data table SK
await dataService.getItem({
  pk: "PRODUCT#tenant001",
  sk: "01HX7MBJK3V9WQBZ7XNDK5ZT2M@3"  // Version should not be here
});

// Better - always use removeSortKeyVersion
const cleanSk = removeSortKeyVersion(skWithVersion);
await dataService.getItem({ pk, sk: cleanSk });
```

## API Reference {#api-reference}

### Key Functions

| Function | Signature | Description |
|--------------|---------------|-----------------|
| `generateId` | `(pk: string, sk: string) => string` | Combines PK and SK into ID, removes version from SK |
| `getTenantCode` | `(pk: string) => string \| undefined` | Extracts tenant code from PK |
| `addSortKeyVersion` | `(sk: string, version: number) => string` | Adds version suffix to SK |
| `removeSortKeyVersion` | `(sk: string) => string` | Removes version suffix from SK |
| `getSortKeyVersion` | `(sk: string) => number` | Gets version number from SK (returns -1 if no version) |
| `masterPk` | `(tenantCode?: string) => string` | Generates MASTER#tenantCode PK |
| `seqPk` | `(tenantCode?: string) => string` | Generates SEQ#tenantCode PK |
| `ttlSk` | `(tableName: string) => string` | Generates TTL#tableName SK |

### Constants

| Constant | Value | Usage |
|--------------|-----------|-----------|
| `KEY_SEPARATOR` | `#` | Use for joining key components |
| `VER_SEPARATOR` | `@` | Used internally for version suffix |
| `VERSION_FIRST` | `0` | Use when creating new entities |
| `VERSION_LATEST` | `-1` | Returned when SK has no version |
| `TENANT_COMMON` | `common` | Use for cross-tenant shared data |
| `DEFAULT_TENANT_CODE` | `single` | Default for single-tenant mode |

## Related Documentation

- [DynamoDB](/docs/dynamodb) - Table architecture and attribute schema for these keys
- [Entity Patterns](/docs/entity-patterns) - Define entities that use these key patterns
- [Data Service](/docs/data-service) - Query data using designed keys
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant isolation and cross-tenant operations
- [Sequence](/docs/sequence) - SequencesModule for auto-incrementing sort keys
- [Version Conflict Guide](/docs/version-conflict-guide) - Concurrency control using version keys
- [Helpers](/docs/helpers) - Key helper functions reference


---

# Backend Development

## Backend Development Guide

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/backend-development

# Backend Development Guide

This guide provides comprehensive patterns and best practices for building backend applications with MBC CQRS Serverless framework. Examples are generalized from production projects.

## Module Structure {#module-structure}

### Standard Module Layout

Every domain module follows this consistent structure:

```text
src/[domain]/
├── dto/
│   ├── [domain]-command.dto.ts        # Command input validation
│   ├── [domain]-attributes.dto.ts     # Domain-specific attributes
│   └── [domain]-search.dto.ts         # Search parameters
├── entity/
│   ├── [domain]-command.entity.ts     # Command entity
│   ├── [domain]-data.entity.ts        # Data entity
│   └── [domain]-data-list.entity.ts   # List wrapper
├── handler/
│   └── [domain]-rds.handler.ts        # RDS sync handler
├── [domain].service.ts                # Business logic
├── [domain].controller.ts             # HTTP handlers
└── [domain].module.ts                 # Module definition
```

### Module Registration

Register your module with CommandModule to enable CQRS features:

```typescript
// product.module.ts
import { Module } from '@nestjs/common';
import { CommandModule } from '@mbc-cqrs-serverless/core';
import { ProductService } from './product.service';
import { ProductController } from './product.controller';
import { ProductDataSyncRdsHandler } from './handler/product-rds.handler';

@Module({
  imports: [
    CommandModule.register({
      tableName: 'product',
      dataSyncHandlers: [ProductDataSyncRdsHandler],
    }),
  ],
  controllers: [ProductController],
  providers: [ProductService],
  exports: [ProductService],
})
export class ProductModule {}
```

## Entity Design {#entity-design}

### Command Entity

Command entities represent write operations and include version tracking:

```typescript
// entity/product-command.entity.ts
import { CommandEntity } from '@mbc-cqrs-serverless/core';
import { ProductAttributes } from '../dto/product-attributes.dto';

export class ProductCommandEntity extends CommandEntity {
  attributes: ProductAttributes;
}
```

### Data Entity

Data entities represent the read model after processing:

```typescript
// entity/product-data.entity.ts
import { DataEntity } from '@mbc-cqrs-serverless/core';
import { ProductAttributes } from '../dto/product-attributes.dto';

export class ProductDataEntity extends DataEntity {
  attributes: ProductAttributes;
}

// entity/product-data-list.entity.ts
import { DataListEntity } from '@mbc-cqrs-serverless/core';
import { ProductDataEntity } from './product-data.entity';

export class ProductDataListEntity extends DataListEntity<ProductDataEntity> {
  items: ProductDataEntity[];
}
```

### Attributes DTO

Define domain-specific attributes with validation:

```typescript
// dto/product-attributes.dto.ts
import { IsString, IsNumber, IsOptional, ValidateNested, Type } from 'class-validator';

export class ProductAttributes {
  @IsString()
  @IsOptional()
  category?: string;

  @IsNumber()
  @IsOptional()
  price?: number;

  @IsString()
  @IsOptional()
  description?: string;

  @Type(() => ProductSpecification)
  @ValidateNested()
  @IsOptional()
  specification?: ProductSpecification;
}

export class ProductSpecification {
  @IsString()
  @IsOptional()
  weight?: string;

  @IsString()
  @IsOptional()
  dimensions?: string;
}
```

## Controller Pattern {#controller-pattern}

### Standard Controller

Controllers should be thin, delegating business logic to services:

```typescript
// product.controller.ts
import {
  Controller,
  Get,
  Post,
  Put,
  Body,
  Param,
  Query,
} from '@nestjs/common';
import { INVOKE_CONTEXT, IInvoke, SearchDto } from '@mbc-cqrs-serverless/core';
import { ProductService } from './product.service';
import { ProductCommandDto } from './dto/product-command.dto';
import { ProductDataEntity, ProductDataListEntity } from './entity';

@Controller('api/product')
export class ProductController {
  constructor(private readonly productService: ProductService) {}

  /**
   * Create or update a product
   */
  @Post('/')
  async publishCommand(
    @INVOKE_CONTEXT() invokeContext: IInvoke,
    @Body() cmdDto: ProductCommandDto,
  ): Promise<ProductDataEntity> {
    return this.productService.publishCommand(cmdDto, invokeContext);
  }

  /**
   * Bulk create/update products
   */
  @Post('/bulk')
  async publishBulkCommands(
    @INVOKE_CONTEXT() invokeContext: IInvoke,
    @Body() cmdDtos: ProductCommandDto[],
  ): Promise<ProductDataEntity[]> {
    return this.productService.publishBulkCommands(cmdDtos, invokeContext);
  }

  /**
   * Get product by PK and SK
   */
  @Get('data/:pk/:sk')
  async getData(
    @Param('pk') pk: string,
    @Param('sk') sk: string,
  ): Promise<ProductDataEntity> {
    return this.productService.getData(pk, sk);
  }

  /**
   * List products by PK
   */
  @Get('data/:pk')
  async listDataByPk(
    @Param('pk') pk: string,
    @Query() searchDto: SearchDto,
  ): Promise<ProductDataListEntity> {
    return this.productService.listDataByPk(pk, searchDto);
  }

  /**
   * Search products
   */
  @Get('data')
  async searchData(
    @Query() searchDto: SearchDto,
  ): Promise<ProductDataListEntity> {
    return this.productService.searchData(searchDto);
  }

  /**
   * Resync all data to RDS
   */
  @Put('resync-data/:pk')
  async resyncData(@Param('pk') pk: string): Promise<void> {
    return this.productService.resyncData(pk);
  }
}
```

## Service Implementation {#service-implementation}

### Basic Service Pattern

Services contain business logic and orchestrate data operations. Here is a minimal example:

```typescript
// product.service.ts
import { Injectable, Logger } from '@nestjs/common';
import {
  CommandService,
  DataService,
  IInvoke,
  KEY_SEPARATOR,
  generateId,
  getUserContext,
  VERSION_FIRST,
} from '@mbc-cqrs-serverless/core';
import { ulid } from 'ulid';
import { PrismaService } from '../prisma/prisma.service';
import { ProductCommandDto } from './dto/product-command.dto';
import { ProductDataEntity } from './entity';

const PRODUCT_PK_PREFIX = 'PRODUCT';

@Injectable()
export class ProductService {
  private readonly logger = new Logger(ProductService.name);

  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly prismaService: PrismaService,
  ) {}

  /**
   * Create a new product
   */
  async create(
    createDto: { name: string; description?: string },
    opts: { invokeContext: IInvoke },
  ): Promise<ProductDataEntity | null> {
    const { tenantCode } = getUserContext(opts.invokeContext);

    const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;
    const sk = ulid();

    const command = new ProductCommandDto({
      pk,
      sk,
      id: generateId(pk, sk),
      tenantCode,
      code: sk,
      type: 'PRODUCT',
      name: createDto.name,
      version: VERSION_FIRST,
      attributes: { description: createDto.description },
    });

    const item = await this.commandService.publishAsync(command, {
      invokeContext: opts.invokeContext,
    });

    // publishAsync returns null when command is a no-op (no changes detected)
    if (!item) return null;
    return new ProductDataEntity(item);
  }

  /**
   * Get product by key
   */
  async findOne(pk: string, sk: string): Promise<ProductDataEntity | undefined> {
    const item = await this.dataService.getItem({ pk, sk });
    if (!item) return undefined;
    return new ProductDataEntity(item);
  }
}
```

:::tip For Complete Service Patterns
For comprehensive CRUD operations, batch processing, optimistic locking, and more advanced patterns, see [Service Patterns](/docs/service-patterns).
:::

:::info Read-Your-Writes Consistency
`DataService.getItem()` reads from DynamoDB, which may return stale data immediately after a write (eventual consistency). If users need to see their own writes instantly, use the [Read-Your-Writes pattern with Repository](/docs/command-service#read-your-writes) instead.
:::

## Data Sync Handler {#data-sync-handler}

### RDS Sync Handler

Sync data from DynamoDB to RDS for complex queries:

```typescript
// handler/product-rds.handler.ts
import { Injectable, Logger } from '@nestjs/common';
import {
  IDataSyncHandler,
  CommandModel,
  removeSortKeyVersion,
} from '@mbc-cqrs-serverless/core';
import { PrismaService } from '../../prisma/prisma.service';
import { ProductAttributes } from '../dto/product-attributes.dto';

@Injectable()
export class ProductDataSyncRdsHandler implements IDataSyncHandler {
  private readonly logger = new Logger(ProductDataSyncRdsHandler.name);

  constructor(private readonly prismaService: PrismaService) {}

  /**
   * Sync command to RDS (upsert)
   */
  async up(cmd: CommandModel): Promise<any> {
    // Remove version suffix from SK
    const sk = removeSortKeyVersion(cmd.sk);
    const attrs = cmd.attributes as ProductAttributes;

    try {
      await this.prismaService.product.upsert({
        where: { id: cmd.id },
        update: {
          pk: cmd.pk,
          sk: sk,
          code: cmd.code,
          name: cmd.name,
          version: cmd.version,
          tenantCode: cmd.tenantCode,
          isDeleted: cmd.isDeleted ?? false,
          // Map attributes to columns
          category: attrs?.category,
          price: attrs?.price,
          description: attrs?.description,
          specification: attrs?.specification,
          // Audit fields
          createdAt: cmd.createdAt,
          createdBy: cmd.createdBy ?? '',
          createdIp: cmd.createdIp ?? '',
          updatedAt: cmd.updatedAt,
          updatedBy: cmd.updatedBy ?? '',
          updatedIp: cmd.updatedIp ?? '',
        },
        create: {
          id: cmd.id,
          cpk: cmd.pk,
          csk: cmd.sk,
          pk: cmd.pk,
          sk: sk,
          code: cmd.code,
          name: cmd.name,
          version: cmd.version,
          tenantCode: cmd.tenantCode,
          isDeleted: cmd.isDeleted ?? false,
          category: attrs?.category,
          price: attrs?.price,
          description: attrs?.description,
          specification: attrs?.specification,
          createdAt: cmd.createdAt,
          createdBy: cmd.createdBy ?? '',
          createdIp: cmd.createdIp ?? '',
          updatedAt: cmd.updatedAt,
          updatedBy: cmd.updatedBy ?? '',
          updatedIp: cmd.updatedIp ?? '',
        },
      });

      this.logger.debug(`Synced product ${cmd.id} to RDS`);
    } catch (error) {
      this.logger.error(`Failed to sync product ${cmd.id}:`, error);
      throw error;
    }
  }

  /**
   * Handle rollback or delete
   */
  async down(cmd: CommandModel): Promise<any> {
    // Soft delete implementation
    await this.prismaService.product.update({
      where: { id: cmd.id },
      data: { isDeleted: true },
    });
  }
}
```

## Prisma Schema {#prisma-schema}

### Standard Model Definition

Define your Prisma model with CQRS fields:

```prisma
// prisma/schema.prisma
model Product {
  // CQRS composite keys
  id     String @id            // PK#SK without version
  cpk    String                // Command PK
  csk    String                // Command SK with version
  pk     String                // Data PK
  sk     String                // Data SK without version

  // Domain fields
  code   String
  name   String

  // Domain-specific
  category     String?
  price        Decimal?
  description  String?
  specification Json?

  // Multi-tenant
  tenantCode String

  // Audit fields
  version   Int
  isDeleted Boolean  @default(false)
  createdBy String   @default("")
  createdIp String   @default("")
  createdAt DateTime
  updatedBy String   @default("")
  updatedIp String   @default("")
  updatedAt DateTime

  // Indexes
  @@unique([cpk, csk])
  @@unique([pk, sk])
  @@unique([tenantCode, code])
  @@index([tenantCode, name])
  @@index([category])
}
```

## Best Practices {#best-practices}

### 1. Source Tracking

Always track the source of operations for debugging:

```typescript
const opts = {
  source: getCommandSource(
    basename(__dirname),      // Module name
    this.constructor.name,    // Class name
    'methodName',             // Method name
  ),
  invokeContext,
};
```

### 2. Batch Processing

Process large datasets in batches to avoid timeouts. See [Service Patterns - Batch Operations](/docs/service-patterns#batch-operations) for detailed examples.

### 3. Error Handling

Implement proper error handling with logging:

```typescript
import { Injectable, Logger } from '@nestjs/common';
import { IDataSyncHandler, CommandModel, SnsService } from '@mbc-cqrs-serverless/core';

@Injectable()
export class MyDataSyncHandler implements IDataSyncHandler {
  private readonly logger = new Logger(MyDataSyncHandler.name);
  private readonly alarmTopicArn = process.env.ALARM_TOPIC_ARN || '';

  constructor(
    private readonly snsService: SnsService, // Inject for alarm notifications
  ) {}

  async up(cmd: CommandModel): Promise<void> {
    try {
      await this.processItem(cmd); // Your application-specific processing
    } catch (error) {
      this.logger.error(`Failed to process item ${cmd.sk}:`, error);

      // Send alarm for critical errors
      if (this.isCriticalError(error)) {
        await this.snsService.publish({
          topicArn: this.alarmTopicArn,
          subject: 'Processing Error',
          message: JSON.stringify({ sk: cmd.sk, error: error.message }),
        });
      }

      throw error;
    }
  }

  private isCriticalError(error: unknown): boolean {
    // Return true for errors that require immediate alerting
    return error instanceof Error && !error.message.includes('not found');
  }
}
```

### 4. Data Consistency

Use dirty checking to avoid unnecessary syncs:

```typescript
import { CommandService, CommandModel, CommandInputModel } from '@mbc-cqrs-serverless/core';

constructor(private readonly commandService: CommandService) {}

async syncToRds(existingData: CommandModel, newData: CommandInputModel): Promise<void> {
  if (this.commandService.isNotCommandDirty(existingData, newData)) {
    this.logger.debug('Data unchanged, skipping sync');
    return;
  }

  // Perform your actual sync: upsert via Prisma or publish a downstream command
  await this.prismaService.entity.upsert({
    where: { sk: newData.sk },
    create: { ...newData.attributes, sk: newData.sk, tenantCode: newData.tenantCode },
    update: { ...newData.attributes },
  });
}
```

### 5. Pagination

Always support pagination for list operations:

```typescript
async searchWithPagination(
  searchDto: SearchDto,
): Promise<DataListEntity> {
  const { page = 1, pageSize = 20 } = searchDto;

  const [total, items] = await Promise.all([
    this.prismaService.entity.count({ where }),
    this.prismaService.entity.findMany({
      where,
      take: pageSize,
      skip: pageSize * (page - 1),
      orderBy: [{ createdAt: 'desc' }],
    }),
  ]);

  return new DataListEntity({ total, items });
}
```

## Related Documentation

- [Service Patterns](/docs/service-patterns) - Advanced service implementation patterns
- [Command Service](/docs/command-service) - Publishing commands and Read-Your-Writes consistency
- [Data Service](/docs/data-service) - Querying data from the read model
- [Data Sync Handler Examples](/docs/data-sync-handler-examples) - Comprehensive sync handler examples
- [Key Patterns](/docs/key-patterns) - PK/SK design patterns
- [Anti-Patterns](/docs/anti-patterns) - Common mistakes and how to avoid them
- [Authentication](/docs/authentication) - Role-based access control with `@Auth` and `@Roles`
- [Controllers](/docs/controllers) - NestJS controller patterns with MBC decorators
- [Helpers](/docs/helpers) - getUserContext and key helper functions
- [Prisma](/docs/prisma) - ORM setup for RDS data sync
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Multi-tenant implementation
- [Import/Export Patterns](/docs/import-export-patterns) - Batch data processing
- [Examples](/docs/recipes) - Practical implementation examples
- [Versioning Rules](/docs/version-rules) - Optimistic locking and version conflict handling
- [Absolute Imports](/docs/absolute_imports_and_module_path_aliases) - TypeScript path aliases with `@/` prefix


---

## Building your application

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/build-your-application

# Building your application

MBC CQRS Serverless provides the core functionalities to create backend applications. These guides explain how to use these features and how to customize your application's behavior.

```mdx-code-block
import DocCardList from '@theme/DocCardList';

<DocCardList />
```


## Related Documentation

- [Getting Started](/docs/getting-started) - Initial setup
- [Backend Development](/docs/backend-development) - Backend development guide
- [Service Patterns](/docs/service-patterns) - Service implementation patterns


---

## Controllers

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/controllers

# Controllers

Controllers are responsible for handling incoming **requests** and returning **responses** to the client.

Defining a controller in the MBC Serverless Framework is the same as in NestJS, so please refer to this section using the [provided link](https://docs.nestjs.com/controllers).

:::note

To get the invoke context, you can provide the following argument in the controller function.

```ts
@INVOKE_CONTEXT() invokeContext: IInvoke,
```

:::

In the following example we'll use the `@Controller()` decorator, which is required to define a basic controller; `@Auth(ROLE_SYSTEM_ADMIN)` decorator, which is specified for authorization purpose; and `@ApiTags('cat')` to attach a controller to a specific tag.

```ts
import { Controller, Post, Body } from '@nestjs/common';
import { ApiTags } from '@nestjs/swagger';
import { ROLE_SYSTEM_ADMIN, INVOKE_CONTEXT, IInvoke, Auth } from '@mbc-cqrs-serverless/core';
import { CatService } from './cat.service';
import { CreateCatDto } from './create-cat.dto';

@Auth(ROLE_SYSTEM_ADMIN)
@Controller("api/cat")
@ApiTags("cat")
export class CatController {
  constructor(private readonly catService: CatService) {}

  @Post()
  async create(
    @INVOKE_CONTEXT() invokeContext: IInvoke,
    @Body() createCatDto: CreateCatDto
  ) {
    return this.catService.create(createCatDto, { invokeContext });
  }
}
```

## Decorators {#decorators}

The framework provides several decorators to simplify common patterns in your controllers.

### `@INVOKE_CONTEXT()`

Parameter decorator that extracts the invocation context from the request. This provides access to Lambda context, JWT claims, and request metadata.

```ts
import { INVOKE_CONTEXT, IInvoke } from '@mbc-cqrs-serverless/core';

@Get(':id')
async getItem(
  @INVOKE_CONTEXT() invokeContext: IInvoke,
  @Param('id') id: string
) {
  return this.service.getItem(id, { invokeContext });
}
```

### `@Auth(...roles)`

Method/class decorator that applies authentication and role-based access control. Combines RolesGuard with Swagger documentation (ApiBearerAuth, ApiUnauthorizedResponse).

```ts
import { Auth, ROLE_SYSTEM_ADMIN } from '@mbc-cqrs-serverless/core';

@Controller('admin')
@Auth(ROLE_SYSTEM_ADMIN)  // Class-level: applies to all methods
export class AdminController {

  @Post()
  @Auth(ROLE_SYSTEM_ADMIN)  // Method-level: override class decorator
  async create() {}
}
```

### `@HeaderTenant()`

Method/class decorator that adds tenant code header requirement to Swagger documentation. Use this when your endpoint requires a tenant code header.

```ts
import { HeaderTenant } from '@mbc-cqrs-serverless/core';

@Controller('items')
@HeaderTenant()  // Adds x-tenant-code header to Swagger docs
export class ItemController {

  @Get()
  async list() {
    // Tenant code available via invokeContext
  }
}
```

The decorator adds the following header to Swagger:
- **Header name**: `x-tenant-code`
- **Required**: `true`
- **Description**: Current working tenant code

### `@SwaggerResponse(ApiResponse, options?)`

Method decorator factory that applies standardized error response documentation. Use with Swagger response decorators to document error responses.

```ts
import { Controller, Get, Param } from '@nestjs/common';
import { ApiBadRequestResponse, ApiNotFoundResponse } from '@nestjs/swagger';
import { SwaggerResponse } from '@mbc-cqrs-serverless/core';

@Controller('items')
export class ItemController {

  @Get(':id')
  @SwaggerResponse(ApiNotFoundResponse, { description: 'Item not found' })
  @SwaggerResponse(ApiBadRequestResponse, { description: 'Invalid ID format' })
  async getItem(@Param('id') id: string) {}
}
```

This decorator automatically includes the standard HttpExceptionResponse schema with status and message fields.

### `@Roles(...roles)`

Method/class decorator that specifies which roles can access an endpoint. Used internally by `@Auth()` but can be used directly with custom guards.

:::info Version Note
Since [v1.3.1](/docs/changelog#v131), `RolesGuard` checks both direct roles (from `custom:roles`) and group-derived roles (from `custom:groups`, when a `@GroupRoleResolver()` is configured). Existing `@Roles()` calls benefit automatically — no code changes required. See [Group-Based Roles](/docs/authentication#group-based-roles).
:::

```ts
import { Roles } from '@mbc-cqrs-serverless/core';
import { Controller, Get, UseGuards } from '@nestjs/common';
import { CustomGuard } from './guards/custom.guard';

@Controller('custom')
export class CustomController {

  @Get()
  @Roles('admin', 'manager')
  @UseGuards(CustomGuard)
  async protectedEndpoint() {}
}
```


:::tip Other Framework Decorators
The following decorators are used on provider classes rather than controllers — see their respective guides:

- `@DataSyncHandler(tableName)` — marks a class as a DynamoDB Stream sync handler → [Data Sync Handler Examples](/docs/data-sync-handler-examples)
- `@EventHandler(EventClass)` — marks a class as a domain event handler → [Tasks](/docs/tasks)
- `@EventFactory()` — marks a class as an event factory → [Tasks](/docs/tasks)
- `@GroupRoleResolver()` — registers a group-to-role mapping class → [Authentication — Group-Based Roles](/docs/authentication#group-based-roles)
- `@NotificationTransport(name)` — registers a custom notification transport → [Notification Module](/docs/notification-module)
:::

## Related Documentation

- [Authentication](/docs/authentication) - Cognito authentication and JWT setup
- [Modules](/docs/modules) - Module configuration for controllers
- [Backend Development](/docs/backend-development) - Complete backend development guide
- [Interfaces](/docs/interfaces) - IInvoke and IInvokeContext interfaces
- [Service Patterns](/docs/service-patterns) - Service layer with CQRS patterns
- [Form Handling Patterns](/docs/form-handling-patterns) - DTO validation and form data processing
- [Serialization](/docs/serialization) - Date and class-transformer serialization


---

## Data Sync Handler Examples

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/data-sync-handler-examples

# Data Sync Handler Examples

This guide explains how to implement Data Sync Handlers that automatically synchronize data from DynamoDB (command source) to RDS (query database). This is the core mechanism that enables the CQRS read model.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Sync entity data from DynamoDB to MySQL/PostgreSQL for complex queries
- Transform nested JSON attributes into relational columns
- Handle different record types within the same DynamoDB table
- Process parent-child relationships (Order, OrderItem) separately

## Problems This Pattern Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| DynamoDB cannot do JOINs or complex filters | Sync data to RDS for SQL queries |
| Version suffix in SK causes duplicate records | Use removeSortKeyVersion() before upserting |
| Different record types need different RDS tables | Filter by SK prefix in handler |
| JSON attributes need to be searchable columns | Map attributes to individual RDS columns |

## Basic Structure {#basic-structure}

All Data Sync Handlers follow this basic structure:

```ts
import { CommandModel, IDataSyncHandler, removeSortKeyVersion } from "@mbc-cqrs-serverless/core";
import { Injectable, Logger } from "@nestjs/common";
import { PrismaService } from "src/prisma";

@Injectable()
export class EntityDataSyncRdsHandler implements IDataSyncHandler {
  private readonly logger = new Logger(EntityDataSyncRdsHandler.name);

  constructor(private readonly prismaService: PrismaService) {}

  async up(cmd: CommandModel): Promise<any> {
    // Sync data to RDS
  }

  async down(cmd: CommandModel): Promise<any> {
    // Optional: Handle rollback (usually just logs)
    this.logger.debug(cmd);
  }
}
```

## Example 1: Simple Entity Sync {#example-simple-sync}

### Use Case: Sync Products to Enable Search and Filtering

Scenario: Products stored in DynamoDB need to be searchable by category, price range, and text.

Solution: Sync to RDS and map attributes to indexed columns for efficient queries.

```ts
import {
  CommandModel,
  IDataSyncHandler,
  removeSortKeyVersion
} from "@mbc-cqrs-serverless/core";
import { Injectable, Logger } from "@nestjs/common";
import { PrismaService } from "src/prisma";

interface ProductAttributes {
  name: string;
  description: string;
  price: number;
  category: string;
  inStock: boolean;
}

@Injectable()
export class ProductDataSyncRdsHandler implements IDataSyncHandler {
  private readonly logger = new Logger(ProductDataSyncRdsHandler.name);

  constructor(private readonly prismaService: PrismaService) {}

  async up(cmd: CommandModel): Promise<any> {
    // Remove version suffix from sort key (e.g., "PROD001@1" -> "PROD001")
    const sk = removeSortKeyVersion(cmd.sk);
    const attrs = cmd.attributes as ProductAttributes;

    await this.prismaService.product.upsert({
      where: { id: cmd.id },
      update: {
        pk: cmd.pk,
        sk: sk,
        name: cmd.name,
        code: cmd.code,
        version: cmd.version,
        tenantCode: cmd.tenantCode,
        // Map attributes to columns
        description: attrs.description,
        price: attrs.price,
        category: attrs.category,
        inStock: attrs.inStock,
        // Audit fields
        isDeleted: cmd.isDeleted ?? false,
        createdAt: cmd.createdAt,
        createdBy: cmd.createdBy,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
      create: {
        id: cmd.id,
        pk: cmd.pk,
        sk: sk,
        // Also store original keys with version for reference
        cpk: cmd.pk,
        csk: cmd.sk,
        name: cmd.name,
        code: cmd.code,
        version: cmd.version,
        tenantCode: cmd.tenantCode,
        description: attrs.description,
        price: attrs.price,
        category: attrs.category,
        inStock: attrs.inStock,
        isDeleted: cmd.isDeleted ?? false,
        createdAt: cmd.createdAt,
        createdBy: cmd.createdBy,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
    });
  }

  async down(cmd: CommandModel): Promise<any> {
    this.logger.debug(cmd);
  }
}
```

## Example 2: Conditional Processing with SK Prefix {#example-sk-prefix}

### Use Case: Order and OrderItem in Same DynamoDB Table

Scenario: Orders and their items share the same PK but have different SK prefixes. Each needs to go to a different RDS table.

Solution: Check SK prefix to route to appropriate sync logic.

```ts
import {
  CommandModel,
  IDataSyncHandler,
  KEY_SEPARATOR,
  removeSortKeyVersion
} from "@mbc-cqrs-serverless/core";
import { Injectable, Logger } from "@nestjs/common";
import { PrismaService } from "src/prisma";

const ORDER_SK_PREFIX = "ORDER";
const ORDER_ITEM_SK_PREFIX = "ORDER_ITEM";

interface OrderAttributes {
  customerId: string;
  status: string;
  totalAmount: number;
  orderDate: string;
}

interface OrderItemAttributes {
  orderId: string;
  productId: string;
  quantity: number;
  unitPrice: number;
}

@Injectable()
export class OrderDataSyncRdsHandler implements IDataSyncHandler {
  private readonly logger = new Logger(OrderDataSyncRdsHandler.name);

  constructor(private readonly prismaService: PrismaService) {}

  async up(cmd: CommandModel): Promise<any> {
    const sk = removeSortKeyVersion(cmd.sk);

    // Process only ORDER records, skip ORDER_ITEM
    if (sk.startsWith(ORDER_SK_PREFIX) && !sk.startsWith(ORDER_ITEM_SK_PREFIX)) {
      await this.syncOrder(cmd, sk);
    } else if (sk.startsWith(ORDER_ITEM_SK_PREFIX)) {
      await this.syncOrderItem(cmd, sk);
    }
    // Skip other record types
  }

  private async syncOrder(cmd: CommandModel, sk: string): Promise<void> {
    const attrs = cmd.attributes as OrderAttributes;

    await this.prismaService.order.upsert({
      where: { id: cmd.id },
      update: {
        pk: cmd.pk,
        sk: sk,
        code: cmd.code,
        version: cmd.version,
        customerId: attrs.customerId,
        status: attrs.status,
        totalAmount: attrs.totalAmount,
        orderDate: new Date(attrs.orderDate),
        isDeleted: cmd.isDeleted ?? false,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
      create: {
        id: cmd.id,
        pk: cmd.pk,
        sk: sk,
        cpk: cmd.pk,
        csk: cmd.sk,
        code: cmd.code,
        version: cmd.version,
        tenantCode: cmd.tenantCode,
        customerId: attrs.customerId,
        status: attrs.status,
        totalAmount: attrs.totalAmount,
        orderDate: new Date(attrs.orderDate),
        isDeleted: cmd.isDeleted ?? false,
        createdAt: cmd.createdAt,
        createdBy: cmd.createdBy,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
    });
  }

  private async syncOrderItem(cmd: CommandModel, sk: string): Promise<void> {
    const attrs = cmd.attributes as OrderItemAttributes;

    await this.prismaService.orderItem.upsert({
      where: { id: cmd.id },
      update: {
        pk: cmd.pk,
        sk: sk,
        orderId: attrs.orderId,
        productId: attrs.productId,
        quantity: attrs.quantity,
        unitPrice: attrs.unitPrice,
        isDeleted: cmd.isDeleted ?? false,
        updatedAt: cmd.updatedAt,
      },
      create: {
        id: cmd.id,
        pk: cmd.pk,
        sk: sk,
        cpk: cmd.pk,
        csk: cmd.sk,
        tenantCode: cmd.tenantCode,
        orderId: attrs.orderId,
        productId: attrs.productId,
        quantity: attrs.quantity,
        unitPrice: attrs.unitPrice,
        isDeleted: cmd.isDeleted ?? false,
        createdAt: cmd.createdAt,
        updatedAt: cmd.updatedAt,
      },
    });
  }

  async down(cmd: CommandModel): Promise<any> {
    this.logger.debug(cmd);
  }
}
```

## Example 3: Complex Attribute Transformation {#example-attribute-transform}

### Use Case: Notifications with Different Content Types

Scenario: Notification entity has different content structures based on type (Alert, Info, Promotion).

Solution: Extract and flatten type-specific fields into common RDS columns.

```ts
import {
  CommandModel,
  IDataSyncHandler,
  removeSortKeyVersion
} from "@mbc-cqrs-serverless/core";
import { Injectable, Logger } from "@nestjs/common";
import { PrismaService } from "src/prisma";

enum NotificationType {
  ALERT = "ALERT",
  INFO = "INFO",
  PROMOTION = "PROMOTION",
}

interface AlertContent {
  title: string;
  message: string;
  severity: string;
}

interface InfoContent {
  headline: string;
  body: string;
}

interface PromotionContent {
  campaignName: string;
  discount: number;
  validUntil: string;
}

interface NotificationAttributes {
  type: NotificationType;
  alertContent?: AlertContent;
  infoContent?: InfoContent;
  promotionContent?: PromotionContent;
  targetUsers: string[];
  tags: string[];
  schedule: {
    startDate: string;
    endDate: string;
  };
}

@Injectable()
export class NotificationDataSyncRdsHandler implements IDataSyncHandler {
  private readonly logger = new Logger(NotificationDataSyncRdsHandler.name);

  constructor(private readonly prismaService: PrismaService) {}

  async up(cmd: CommandModel): Promise<any> {
    const sk = removeSortKeyVersion(cmd.sk);
    const attrs = cmd.attributes as NotificationAttributes;

    // Extract title based on notification type
    const title = this.getTitle(attrs);
    const body = this.getBody(attrs);

    await this.prismaService.notification.upsert({
      where: { id: cmd.id },
      update: {
        pk: cmd.pk,
        sk: sk,
        code: cmd.code,
        version: cmd.version,
        type: attrs.type,
        title: title,
        body: body,
        // Convert arrays to comma-separated strings for RDS
        targetUsers: attrs.targetUsers?.join(",") ?? null,
        tags: attrs.tags?.join(",") ?? null,
        // Handle dates
        startDate: attrs.schedule?.startDate
          ? new Date(attrs.schedule.startDate)
          : null,
        endDate: attrs.schedule?.endDate
          ? new Date(attrs.schedule.endDate)
          : null,
        isDeleted: cmd.isDeleted ?? false,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
      create: {
        id: cmd.id,
        pk: cmd.pk,
        sk: sk,
        cpk: cmd.pk,
        csk: cmd.sk,
        code: cmd.code,
        version: cmd.version,
        tenantCode: cmd.tenantCode,
        type: attrs.type,
        title: title,
        body: body,
        targetUsers: attrs.targetUsers?.join(",") ?? null,
        tags: attrs.tags?.join(",") ?? null,
        startDate: attrs.schedule?.startDate
          ? new Date(attrs.schedule.startDate)
          : null,
        endDate: attrs.schedule?.endDate
          ? new Date(attrs.schedule.endDate)
          : null,
        isDeleted: cmd.isDeleted ?? false,
        createdAt: cmd.createdAt,
        createdBy: cmd.createdBy,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
    });
  }

  /**
   * Extract title based on notification type
   */
  private getTitle(attrs: NotificationAttributes): string | null {
    switch (attrs.type) {
      case NotificationType.ALERT:
        return attrs.alertContent?.title ?? null;
      case NotificationType.INFO:
        return attrs.infoContent?.headline ?? null;
      case NotificationType.PROMOTION:
        return attrs.promotionContent?.campaignName ?? null;
      default:
        return null;
    }
  }

  /**
   * Extract body/message based on notification type
   */
  private getBody(attrs: NotificationAttributes): string | null {
    switch (attrs.type) {
      case NotificationType.ALERT:
        return attrs.alertContent?.message ?? null;
      case NotificationType.INFO:
        return attrs.infoContent?.body ?? null;
      case NotificationType.PROMOTION:
        return `${attrs.promotionContent?.discount}% off until ${attrs.promotionContent?.validUntil}`;
      default:
        return null;
    }
  }

  async down(cmd: CommandModel): Promise<any> {
    this.logger.debug(cmd);
  }
}
```

## Example 4: PK Prefix Filtering {#example-pk-filtering}

### Use Case: User Records in Shared Table

Scenario: Multiple entity types share a DynamoDB table. Handler should only process USER records.

Solution: Check PK prefix and skip non-matching records early.

```ts
import {
  CommandModel,
  IDataSyncHandler,
  KEY_SEPARATOR,
  removeSortKeyVersion
} from "@mbc-cqrs-serverless/core";
import { Injectable, Logger } from "@nestjs/common";
import { PrismaService } from "src/prisma";

const USER_PK_PREFIX = "USER";

interface UserAttributes {
  email: string;
  userId: string;
  displayName: string;
  role: string;
  lastLoginAt?: string;
}

@Injectable()
export class UserDataSyncRdsHandler implements IDataSyncHandler {
  private readonly logger = new Logger(UserDataSyncRdsHandler.name);

  constructor(private readonly prismaService: PrismaService) {}

  async up(cmd: CommandModel): Promise<any> {
    // Only process USER records
    if (!cmd.pk.startsWith(USER_PK_PREFIX + KEY_SEPARATOR)) {
      return;
    }

    // Skip temporary or profile records
    if (cmd.sk.startsWith("temp") || cmd.sk.startsWith("profile")) {
      return;
    }

    const sk = removeSortKeyVersion(cmd.sk);
    const attrs = cmd.attributes as UserAttributes;

    await this.prismaService.user.upsert({
      where: { id: cmd.id },
      update: {
        pk: cmd.pk,
        sk: sk,
        code: cmd.code,
        version: cmd.version,
        email: attrs.email,
        userId: attrs.userId,
        displayName: attrs.displayName,
        role: attrs.role,
        lastLoginAt: attrs.lastLoginAt
          ? new Date(attrs.lastLoginAt)
          : null,
        isDeleted: cmd.isDeleted ?? false,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
      create: {
        id: cmd.id,
        pk: cmd.pk,
        sk: sk,
        cpk: cmd.pk,
        csk: cmd.sk,
        code: cmd.code,
        version: cmd.version,
        tenantCode: cmd.tenantCode,
        type: cmd.type,
        email: attrs.email,
        userId: attrs.userId,
        displayName: attrs.displayName,
        role: attrs.role,
        lastLoginAt: attrs.lastLoginAt
          ? new Date(attrs.lastLoginAt)
          : null,
        isDeleted: cmd.isDeleted ?? false,
        createdAt: cmd.createdAt,
        createdBy: cmd.createdBy,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
    });
  }

  async down(cmd: CommandModel): Promise<any> {
    this.logger.debug(cmd);
  }
}
```

## Example 5: Parsing SK for Derived Data {#example-sk-parsing}

### Use Case: Master Data with Category Information in SK

Scenario: SK contains structured data like "SETTING#category#code" that should be stored as separate columns.

Solution: Parse SK to extract type, category, and code for querying.

```ts
import {
  CommandModel,
  IDataSyncHandler,
  KEY_SEPARATOR,
  removeSortKeyVersion
} from "@mbc-cqrs-serverless/core";
import { Injectable, Logger } from "@nestjs/common";
import { PrismaService } from "src/prisma";

const SETTING_SK_PREFIX = "SETTING";
const DATA_SK_PREFIX = "DATA";

interface MasterAttributes {
  value: any;
  displayOrder: number;
  isActive: boolean;
}

@Injectable()
export class MasterDataSyncRdsHandler implements IDataSyncHandler {
  private readonly logger = new Logger(MasterDataSyncRdsHandler.name);

  constructor(private readonly prismaService: PrismaService) {}

  async up(cmd: CommandModel): Promise<any> {
    const sk = removeSortKeyVersion(cmd.sk);
    const attrs = cmd.attributes as MasterAttributes;

    // Parse SK to extract type and code
    // SK format: "SETTING#category#code" or "DATA#category#code"
    const skParts = sk.split(KEY_SEPARATOR);

    let masterType: string;
    let masterCategory: string;
    let masterCode: string;

    if (sk.startsWith(SETTING_SK_PREFIX)) {
      masterType = "SETTING";
      masterCategory = skParts[1] ?? "";
      masterCode = skParts[2] ?? "";
    } else if (sk.startsWith(DATA_SK_PREFIX)) {
      masterType = "DATA";
      masterCategory = skParts[1] ?? "";
      masterCode = skParts[2] ?? "";
    } else {
      // Skip unknown types
      return;
    }

    await this.prismaService.master.upsert({
      where: { id: cmd.id },
      update: {
        pk: cmd.pk,
        sk: sk,
        code: cmd.code,
        version: cmd.version,
        masterType: masterType,
        masterCategory: masterCategory,
        masterCode: masterCode,
        name: cmd.name,
        value: JSON.stringify(attrs.value),
        displayOrder: attrs.displayOrder,
        isActive: attrs.isActive,
        isDeleted: cmd.isDeleted ?? false,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
      create: {
        id: cmd.id,
        pk: cmd.pk,
        sk: sk,
        cpk: cmd.pk,
        csk: cmd.sk,
        code: cmd.code,
        version: cmd.version,
        tenantCode: cmd.tenantCode,
        masterType: masterType,
        masterCategory: masterCategory,
        masterCode: masterCode,
        name: cmd.name,
        value: JSON.stringify(attrs.value),
        displayOrder: attrs.displayOrder,
        isActive: attrs.isActive,
        isDeleted: cmd.isDeleted ?? false,
        createdAt: cmd.createdAt,
        createdBy: cmd.createdBy,
        updatedAt: cmd.updatedAt,
        updatedBy: cmd.updatedBy,
      },
    });
  }

  async down(cmd: CommandModel): Promise<any> {
    this.logger.debug(cmd);
  }
}
```

## Registering Multiple Handlers {#multiple-handlers}

You can register multiple handlers for the same table to handle different record types:

```ts
import { CommandModule } from "@mbc-cqrs-serverless/core";
import { Module } from "@nestjs/common";

import { OrderDataSyncRdsHandler } from "./handler/order-rds.handler";
import { OrderItemDataSyncRdsHandler } from "./handler/order-item-rds.handler";
import { OrderHistoryDataSyncRdsHandler } from "./handler/order-history-rds.handler";
import { OrderController } from "./order.controller";
import { OrderService } from "./order.service";

@Module({
  imports: [
    CommandModule.register({
      tableName: "order",
      dataSyncHandlers: [
        OrderDataSyncRdsHandler,
        OrderItemDataSyncRdsHandler,
        OrderHistoryDataSyncRdsHandler,
      ],
    }),
  ],
  controllers: [OrderController],
  providers: [OrderService],
})
export class OrderModule {}
```

## Best Practices {#best-practices}

### 1. Always Remove Version from SK

Use `removeSortKeyVersion()` to get a consistent SK for RDS storage:

```ts
const sk = removeSortKeyVersion(cmd.sk); // "ORDER001@3" -> "ORDER001"
```

### 2. Handle undefined isDeleted

Always provide a default value for `isDeleted`:

```ts
isDeleted: cmd.isDeleted ?? false,
```

### 3. Store Both Original and Cleaned Keys

Store original keys (cpk, csk) in create operations for reference:

```ts
create: {
  pk: cmd.pk,     // Cleaned PK
  sk: sk,         // Cleaned SK (without version)
  cpk: cmd.pk,    // Original PK (same as pk for most cases)
  csk: cmd.sk,    // Original SK (with version)
  // ...
}
```

### 4. Type Your Attributes

Define interfaces for attributes to ensure type safety:

```ts
interface ProductAttributes {
  name: string;
  price: number;
  // ...
}

const attrs = cmd.attributes as ProductAttributes;
```

### 5. Handle Null/Undefined Gracefully

Use nullish coalescing and optional chaining:

```ts
tags: attrs.tags?.join(",") ?? null,
startDate: attrs.schedule?.startDate
  ? new Date(attrs.schedule.startDate)
  : null,
```


## Related Documentation

- [Event Handling Patterns](/docs/event-handling-patterns) - Event handler patterns
- [Backend Development](/docs/backend-development) - Core backend patterns
- [Database Selection Guide](/docs/database-selection-guide) - DynamoDB vs RDS
- [Prisma](/docs/prisma) - RDS with Prisma ORM


---

## Event Handling Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/event-handling-patterns

# Event Handling Patterns

This guide covers patterns for implementing event-driven architectures using various AWS event sources including S3, Step Functions, SQS, and DynamoDB streams.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Process file uploads from S3
- Orchestrate workflows with Step Functions
- Handle asynchronous messages from SQS
- React to data changes via DynamoDB streams
- Implement error handling and retry logic
- Send notifications and alarms

## Event Architecture Overview {#event-architecture}

```text
┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│     S3      │────>│             │     │   Event     │
│   Events    │     │             │────>│  Handler 1  │
└─────────────┘     │             │     └─────────────┘
                    │             │
┌─────────────┐     │    Event    │     ┌─────────────┐
│    Step     │────>│   Factory   │────>│   Event     │
│  Functions  │     │             │     │  Handler 2  │
└─────────────┘     │             │     └─────────────┘
                    │             │
┌─────────────┐     │             │     ┌─────────────┐
│     SQS     │────>│             │────>│   Event     │
│   Events    │     │             │     │  Handler 3  │
└─────────────┘     └─────────────┘     └─────────────┘
```

## Event Factory {#event-factory}

### Custom Event Factory

The Event Factory routes incoming events to appropriate handlers:

```typescript
// event-factory.ts
import { Injectable } from '@nestjs/common';
import {
  EventFactory,
  DefaultEventFactory,
  IEvent,
} from '@mbc-cqrs-serverless/core';
import { S3Event } from 'aws-lambda';
import { StepFunctionsEvent, SQSEvent, DynamoDBStreamEvent } from './types';

// Import event classes
import { CsvImportEvent } from './csv-import/event/csv-import.event';
import { FileProcessEvent } from './file/event/file-process.event';
import { OrderCreatedEvent } from './order/event/order-created.event';
import { SendNotificationEvent } from './notification/event/send-notification.event';

@EventFactory()
@Injectable()
export class CustomEventFactory extends DefaultEventFactory {
  /**
   * Transform S3 events to domain events
   */
  async transformS3(event: S3Event): Promise<IEvent[]> {
    const events: IEvent[] = [];

    for (const record of event.Records) {
      const bucket = record.s3.bucket.name;
      const key = decodeURIComponent(record.s3.object.key.replace(/\+/g, ' '));

      // Route based on S3 key pattern
      if (key.startsWith('imports/csv/')) {
        events.push(new CsvImportEvent({
          bucket,
          key,
          eventType: record.eventName,
          size: record.s3.object.size,
        }));
      } else if (key.startsWith('uploads/')) {
        events.push(new FileProcessEvent({
          bucket,
          key,
          eventType: record.eventName,
        }));
      }
    }

    return events;
  }

  /**
   * Transform Step Functions events to domain events
   */
  async transformStepFunction(event: StepFunctionsEvent): Promise<IEvent[]> {
    const { type, payload, taskToken } = event;

    switch (type) {
      case 'CSV_IMPORT':
        return [new CsvImportEvent({
          ...payload,
          taskToken,
        })];

      case 'ORDER_PROCESS':
        return [new OrderCreatedEvent({
          ...payload,
          taskToken,
        })];

      default:
        console.warn(`Unknown Step Function event type: ${type}`);
        return [];
    }
  }

  /**
   * Transform SQS events to domain events
   */
  async transformSqs(event: SQSEvent): Promise<IEvent[]> {
    const events: IEvent[] = [];

    for (const record of event.Records) {
      const body = JSON.parse(record.body);

      switch (body.type) {
        case 'SEND_NOTIFICATION':
          events.push(new SendNotificationEvent(body));
          break;
        // Add more event types as needed
      }
    }

    return events;
  }

  /**
   * Transform DynamoDB stream events to domain events
   */
  async transformDynamodbStream(event: DynamoDBStreamEvent): Promise<IEvent[]> {
    const events: IEvent[] = [];

    for (const record of event.Records) {
      if (record.eventName === 'INSERT' || record.eventName === 'MODIFY') {
        const newImage = record.dynamodb?.NewImage;
        if (newImage) {
          // Route based on entity type
          const pk = newImage.pk?.S || '';
          if (pk.startsWith('ORDER#')) {
            events.push(new OrderCreatedEvent({
              pk,
              sk: newImage.sk?.S,
              data: newImage,
            }));
          }
        }
      }
    }

    return events;
  }
}
```

### Register Event Factory

```typescript
// main.module.ts
import { Module } from '@nestjs/common';
import { CustomEventFactory } from './event-factory';

@Module({
  providers: [CustomEventFactory],
  // ... other configuration
})
export class MainModule {}
```

## Event Handler Patterns {#event-handler-patterns}

### Basic Event Handler

```typescript
// order/event/order-created.event.ts
export class OrderCreatedEvent {
  pk: string;
  sk: string;
  orderId: string;
  tenantCode: string;
  taskToken?: string;

  constructor(data: Partial<OrderCreatedEvent>) {
    Object.assign(this, data);
  }
}

// order/event/order-created.handler.ts
import { Injectable, Logger } from '@nestjs/common';
import { EventHandler, IEventHandler } from '@mbc-cqrs-serverless/core';
import { OrderCreatedEvent } from './order-created.event';
import { NotificationService } from '../../notification/notification.service';
import { InventoryService } from '../../inventory/inventory.service';

interface OrderProcessingResult {
  success: boolean;
  orderId: string;
}

@EventHandler(OrderCreatedEvent)
@Injectable()
export class OrderCreatedHandler implements IEventHandler<OrderCreatedEvent, OrderProcessingResult> {
  private readonly logger = new Logger(OrderCreatedHandler.name);

  constructor(
    private readonly notificationService: NotificationService,
    private readonly inventoryService: InventoryService,
  ) {}

  /**
   * Handle order created event
   */
  async execute(event: OrderCreatedEvent): Promise<OrderProcessingResult> {
    this.logger.log(`Processing order: ${event.orderId}`);

    try {
      // Process order-related tasks
      await Promise.all([
        this.updateInventory(event),
        this.sendNotification(event),
        this.triggerWorkflow(event),
      ]);

      return {
        success: true,
        orderId: event.orderId,
      };
    } catch (error) {
      this.logger.error(`Failed to process order ${event.orderId}:`, error);
      throw error;
    }
  }

  private async updateInventory(event: OrderCreatedEvent): Promise<void> {
    await this.inventoryService.reserveItems(event.orderId);
  }

  private async sendNotification(event: OrderCreatedEvent): Promise<void> {
    await this.notificationService.sendOrderConfirmation(event.orderId);
  }

  private async triggerWorkflow(event: OrderCreatedEvent): Promise<void> {
    // Trigger additional workflows if needed
  }
}
```

### Step Function Event Handler

Handle events from Step Functions with task token support:

```typescript
// import/event/import-process.event.handler.ts
import { Injectable, Logger } from '@nestjs/common';
import {
  EventHandler,
  IEventHandler,
  StepFunctionService,
  SnsService,
  SnsEvent,
} from '@mbc-cqrs-serverless/core';
import { ConfigService } from '@nestjs/config';
import { ImportProcessEvent } from './import-process.event';
import { ImportService } from '../import.service';

// Define SNS event for alarm notifications
class AlarmSnsEvent implements SnsEvent {
  action: string;
  importId: string;
  bucket: string;
  key: string;
  errorMessage: string;
  timestamp: string;
}

@EventHandler(ImportProcessEvent)
@Injectable()
export class ImportProcessEventHandler
  implements IEventHandler<ImportProcessEvent>
{
  private readonly logger = new Logger(ImportProcessEventHandler.name);
  private readonly alarmTopicArn: string;

  constructor(
    private readonly importService: ImportService,
    private readonly sfnService: StepFunctionService,
    private readonly snsService: SnsService,
    private readonly configService: ConfigService,
  ) {
    this.alarmTopicArn = this.configService.get<string>('SNS_ALARM_TOPIC_ARN');
  }

  /**
   * Process import with Step Function callback
   */
  async execute(event: ImportProcessEvent): Promise<{ success: boolean; importId: string }> {
    this.logger.log(`Processing import: ${event.importId}`);

    try {
      // Process the import
      const result = await this.importService.processImport(event);

      // Resume Step Functions execution on success
      if (event.taskToken) {
        await this.sfnService.resumeExecution(event.taskToken, result);
      }

      return { success: true, importId: event.importId };
    } catch (error) {
      this.logger.error(`Import failed: ${event.importId}`, error);

      // Send alarm notification
      await this.sendAlarm(event, error as Error);

      throw error;
    }
  }

  private async sendAlarm(event: ImportProcessEvent, error: Error): Promise<void> {
    const alarmEvent: AlarmSnsEvent = {
      action: 'IMPORT_ERROR',
      importId: event.importId,
      bucket: event.bucket,
      key: event.key,
      errorMessage: error.message,
      timestamp: new Date().toISOString(),
    };

    await this.snsService.publish(alarmEvent, this.alarmTopicArn);
  }
}
```

### S3 Event Handler

Process file uploads from S3:

```typescript
// file/event/file-upload.event.ts
export class FileUploadEvent {
  bucket: string;
  key: string;
  size: number;
  eventType: string;

  constructor(data: Partial<FileUploadEvent>) {
    Object.assign(this, data);
  }
}

// file/event/file-upload.handler.ts
import { Injectable, Logger } from '@nestjs/common';
import { EventHandler, IEventHandler, S3Service } from '@mbc-cqrs-serverless/core';
import { GetObjectCommand } from '@aws-sdk/client-s3';
import { FileUploadEvent } from './file-upload.event';
import { FileProcessService } from '../file-process.service';

interface FileProcessingResult {
  status: 'processed' | 'skipped';
  fileType?: string;
  reason?: string;
}

@EventHandler(FileUploadEvent)
@Injectable()
export class FileUploadHandler implements IEventHandler<FileUploadEvent, FileProcessingResult> {
  private readonly logger = new Logger(FileUploadHandler.name);

  constructor(
    private readonly s3Service: S3Service,
    private readonly fileProcessService: FileProcessService,
  ) {}

  /**
   * Process uploaded file
   */
  async execute(event: FileUploadEvent): Promise<FileProcessingResult> {
    this.logger.log(`Processing file: ${event.key}`);

    // Get file content from S3
    const command = new GetObjectCommand({
      Bucket: event.bucket,
      Key: event.key,
    });
    const response = await this.s3Service.client.send(command);

    // Determine file type and process accordingly
    const fileExtension = event.key.split('.').pop()?.toLowerCase();

    switch (fileExtension) {
      case 'csv':
        await this.fileProcessService.processCsv(response.Body, event);
        return { status: 'processed', fileType: 'csv' };
      case 'xlsx':
      case 'xls':
        await this.fileProcessService.processExcel(response.Body, event);
        return { status: 'processed', fileType: fileExtension };
      case 'pdf':
        await this.fileProcessService.processPdf(response.Body, event);
        return { status: 'processed', fileType: 'pdf' };
      case 'jpg':
      case 'jpeg':
      case 'png':
        await this.fileProcessService.processImage(response.Body, event);
        return { status: 'processed', fileType: fileExtension };
      default:
        this.logger.warn(`Unsupported file type: ${fileExtension}`);
        return { status: 'skipped', reason: 'Unsupported file type' };
    }
  }
}
```

### SQS Event Handler

Process asynchronous messages from SQS:

```typescript
// notification/event/send-notification.event.ts
export class SendNotificationEvent {
  type: 'EMAIL' | 'SMS' | 'PUSH';
  recipient: string;
  subject: string;
  body: string;
  templateId?: string;
  templateData?: Record<string, any>;

  constructor(data: Partial<SendNotificationEvent>) {
    Object.assign(this, data);
  }
}

// notification/event/send-notification.handler.ts
import { Injectable, Logger } from '@nestjs/common';
import {
  EventHandler,
  IEventHandler,
  EmailService,
} from '@mbc-cqrs-serverless/core';
import { SendNotificationEvent } from './send-notification.event';

interface NotificationResult {
  status: 'sent' | 'skipped';
  type: 'EMAIL' | 'SMS' | 'PUSH';
  reason?: string;
}

@EventHandler(SendNotificationEvent)
@Injectable()
export class SendNotificationHandler
  implements IEventHandler<SendNotificationEvent, NotificationResult>
{
  private readonly logger = new Logger(SendNotificationHandler.name);

  constructor(private readonly emailService: EmailService) {}

  /**
   * Send notification based on type
   */
  async execute(event: SendNotificationEvent): Promise<NotificationResult> {
    this.logger.log(`Sending ${event.type} notification to ${event.recipient}`);

    switch (event.type) {
      case 'EMAIL':
        return this.sendEmail(event);
      case 'SMS':
        return this.sendSms(event);
      case 'PUSH':
        return this.sendPush(event);
      default:
        throw new Error(`Unknown notification type: ${event.type}`);
    }
  }

  private async sendEmail(event: SendNotificationEvent): Promise<NotificationResult> {
    let body = event.body;

    // Render template if provided
    if (event.templateId && event.templateData) {
      body = await this.renderTemplate(event.templateId, event.templateData);
    }

    await this.emailService.sendEmail({
      toAddrs: [event.recipient],
      subject: event.subject,
      body,
    });

    return { status: 'sent', type: 'EMAIL' };
  }

  private async sendSms(event: SendNotificationEvent): Promise<NotificationResult> {
    // Implement SMS sending logic
    this.logger.log('SMS sending not implemented');
    return { status: 'skipped', type: 'SMS', reason: 'Not implemented' };
  }

  private async sendPush(event: SendNotificationEvent): Promise<NotificationResult> {
    // Implement push notification logic
    this.logger.log('Push notification not implemented');
    return { status: 'skipped', type: 'PUSH', reason: 'Not implemented' };
  }

  private async renderTemplate(
    templateId: string,
    data: Record<string, any>,
  ): Promise<string> {
    // Template rendering logic
    return `Template ${templateId} rendered with data`;
  }
}
```

## DynamoDB Stream Handler {#dynamodb-stream-handler}

### Data Change Event Handler

React to data changes in DynamoDB:

```typescript
// sync/event/data-change.event.ts
export class DataChangeEvent {
  pk: string;
  sk: string;
  eventType: 'INSERT' | 'MODIFY' | 'REMOVE';
  oldImage?: Record<string, any>;
  newImage?: Record<string, any>;

  constructor(data: Partial<DataChangeEvent>) {
    Object.assign(this, data);
  }
}

// sync/event/data-change.handler.ts
import { Injectable, Logger } from '@nestjs/common';
import { EventHandler, IEventHandler } from '@mbc-cqrs-serverless/core';
import { DataChangeEvent } from './data-change.event';
import { ExternalSyncService } from '../external-sync.service';
import { CacheService } from '../../cache/cache.service';

interface DataSyncResult {
  synced: boolean;
  type?: string;
}

@EventHandler(DataChangeEvent)
@Injectable()
export class DataChangeHandler implements IEventHandler<DataChangeEvent, DataSyncResult> {
  private readonly logger = new Logger(DataChangeHandler.name);

  constructor(
    private readonly externalSyncService: ExternalSyncService,
    private readonly cacheService: CacheService,
  ) {}

  /**
   * Handle data changes from DynamoDB stream
   */
  async execute(event: DataChangeEvent): Promise<DataSyncResult> {
    this.logger.log(
      `Data change: ${event.eventType} on ${event.pk}/${event.sk}`,
    );

    // Invalidate cache
    await this.cacheService.invalidate(event.pk, event.sk);

    // Sync to external systems based on entity type
    const entityType = event.pk.split('#')[0];

    switch (entityType) {
      case 'PRODUCT':
        return this.syncProduct(event);
      case 'ORDER':
        return this.syncOrder(event);
      case 'USER':
        return this.syncUser(event);
      default:
        this.logger.debug(`No external sync for entity type: ${entityType}`);
        return { synced: false };
    }
  }

  private async syncProduct(event: DataChangeEvent): Promise<DataSyncResult> {
    if (event.eventType === 'REMOVE') {
      await this.externalSyncService.deleteProduct(event.pk, event.sk);
    } else {
      await this.externalSyncService.upsertProduct(event.newImage);
    }
    return { synced: true, type: 'PRODUCT' };
  }

  private async syncOrder(event: DataChangeEvent): Promise<DataSyncResult> {
    // Sync order to external ERP system
    await this.externalSyncService.syncOrder(event.newImage);
    return { synced: true, type: 'ORDER' };
  }

  private async syncUser(event: DataChangeEvent): Promise<DataSyncResult> {
    // Sync user to external identity provider
    await this.externalSyncService.syncUser(event.newImage);
    return { synced: true, type: 'USER' };
  }
}
```

## Error Handling and Retry {#error-handling-retry}

The following patterns show how you can implement error handling and retry logic in your application. These are example implementations that you need to create in your own project.

### Retry Pattern Example

:::info Example Implementation
The following retry decorator is not provided by the framework. You need to implement it yourself if you need retry functionality within Lambda execution.
:::

```typescript
// common/event/retry.decorator.ts
import { Logger } from '@nestjs/common';

export interface RetryOptions {
  maxRetries: number;
  backoffMs: number;
  backoffMultiplier: number;
}

const DEFAULT_RETRY_OPTIONS: RetryOptions = {
  maxRetries: 3,
  backoffMs: 1000,
  backoffMultiplier: 2,
};

/**
 * Example retry decorator for event handlers
 */
export function WithRetry(options: Partial<RetryOptions> = {}) {
  const retryOptions = { ...DEFAULT_RETRY_OPTIONS, ...options };

  return function (
    target: any,
    propertyKey: string,
    descriptor: PropertyDescriptor,
  ) {
    const originalMethod = descriptor.value;
    const logger = new Logger(`${target.constructor.name}.${propertyKey}`);

    descriptor.value = async function (...args: any[]) {
      let lastError: Error;
      let delay = retryOptions.backoffMs;

      for (let attempt = 1; attempt <= retryOptions.maxRetries; attempt++) {
        try {
          return await originalMethod.apply(this, args);
        } catch (error) {
          lastError = error;
          logger.warn(
            `Attempt ${attempt}/${retryOptions.maxRetries} failed: ${error.message}`,
          );

          if (attempt < retryOptions.maxRetries) {
            await new Promise(resolve => setTimeout(resolve, delay));
            delay *= retryOptions.backoffMultiplier;
          }
        }
      }

      logger.error(`All ${retryOptions.maxRetries} attempts failed`);
      throw lastError!;
    };

    return descriptor;
  };
}
```

### AWS Native Retry Options

For production use, consider using AWS-native retry mechanisms:

- **SQS Retry**: Configure `maxReceiveCount` on the SQS queue to automatically retry failed messages
- **Lambda Retry**: Configure retry settings on the Lambda function for asynchronous invocations
- **Step Functions Retry**: Use the `Retry` field in your state machine definition

## Best Practices {#best-practices}

### 1. Idempotent Event Handlers

```typescript
interface IdempotentResult {
  skipped?: boolean;
  processed?: boolean;
}

// Always check if event was already processed
async execute(event: OrderEvent): Promise<IdempotentResult> {
  const existing = await this.prismaService.processedEvent.findUnique({
    where: { eventId: event.eventId },
  });

  if (existing) {
    this.logger.log(`Event ${event.eventId} already processed, skipping`);
    return { skipped: true };
  }

  // Process event
  const result = await this.processEvent(event);

  // Mark as processed
  await this.prismaService.processedEvent.create({
    data: { eventId: event.eventId, processedAt: new Date() },
  });

  return { processed: true, ...result };
}
```

### 2. Structured Logging

```typescript
// Use structured logging for better observability
this.logger.log({
  message: 'Processing event',
  eventType: event.constructor.name,
  eventId: event.id,
  tenantCode: event.tenantCode,
  correlationId: event.correlationId,
});
```

### 3. Timeout Handling

```typescript
interface TimeoutResult {
  success: boolean;
  data?: Record<string, unknown>;
}

// Implement timeout for long-running operations
async execute(event: LongRunningEvent): Promise<TimeoutResult> {
  const timeout = 25000; // 25 seconds (Lambda default is 30s)

  const result = await Promise.race([
    this.processEvent(event),
    new Promise<never>((_, reject) =>
      setTimeout(() => reject(new Error('Operation timeout')), timeout),
    ),
  ]);

  return result;
}
```

### 4. Graceful Degradation

```typescript
interface BatchProcessingResult {
  processed: number;
  failed: number;
}

// Continue processing even if some operations fail
async execute(event: BatchEvent): Promise<BatchProcessingResult> {
  const results: unknown[] = [];
  const errors: Array<{ item: unknown; error: string }> = [];

  for (const item of event.items) {
    try {
      results.push(await this.processItem(item));
    } catch (error) {
      errors.push({ item, error: (error as Error).message });
      // Continue with next item
    }
  }

  if (errors.length > 0) {
    this.logger.warn(`${errors.length} items failed`, { errors });
  }

  return { processed: results.length, failed: errors.length };
}
```

## Data Sync Handler {#data-sync-handler}

The data sync event is a particularly significant custom event because it is one of the most commonly registered events within the application. Handlers for this event play a crucial role in ensuring data consistency and synchronization between different databases.

### IDataSyncHandler Interface

By convention, you create a class that implements `IDataSyncHandler` and then override the up and down methods:

```typescript
import { CommandModel, IDataSyncHandler, removeSortKeyVersion } from "@mbc-cqrs-serverless/core";
import { Injectable, Logger } from "@nestjs/common";
import { PrismaService } from "src/prisma";

@Injectable()
export class ProductDataSyncRdsHandler implements IDataSyncHandler<void, void> {
  private readonly logger = new Logger(ProductDataSyncRdsHandler.name);

  constructor(private readonly prismaService: PrismaService) {}

  /**
   * Sync data from DynamoDB to RDS on create/update
   */
  async up(cmd: CommandModel): Promise<void> {
    this.logger.debug('Syncing to RDS:', cmd.pk, cmd.sk);

    const { pk, id, code, name, tenantCode, attributes } = cmd;
    const sk = removeSortKeyVersion(cmd.sk); // Strip @version suffix from command sk

    await this.prismaService.product.upsert({
      where: { id },
      create: {
        id,
        pk,
        sk,
        code,
        name,
        tenantCode,
        ...attributes,
        createdAt: new Date(),
        updatedAt: new Date(),
      },
      update: {
        name,
        ...attributes,
        updatedAt: new Date(),
      },
    });
  }

  /**
   * Handle delete/rollback operations
   */
  async down(cmd: CommandModel): Promise<void> {
    this.logger.debug('Removing from RDS:', cmd.pk, cmd.sk);

    await this.prismaService.product.delete({
      where: { id: cmd.id },
    }).catch(() => {
      // Ignore if already deleted
    });
  }
}
```

### Register Data Sync Handler

Register your handler to `CommandModule`:

```typescript
import { Module } from '@nestjs/common';
import { CommandModule } from '@mbc-cqrs-serverless/core';
import { ProductDataSyncRdsHandler } from './handler/product-rds.handler';

@Module({
  imports: [
    CommandModule.register({
      tableName: 'product',
      dataSyncHandlers: [ProductDataSyncRdsHandler],
    }),
  ],
  // ...
})
export class ProductModule {}
```

### Multiple Sync Handlers

You can register multiple handlers for different sync targets:

```typescript
CommandModule.register({
  tableName: 'order',
  dataSyncHandlers: [
    OrderRdsSyncHandler,      // Sync to RDS for queries
    OrderElasticSyncHandler,  // Sync to Elasticsearch for search
    OrderAnalyticsSyncHandler, // Sync to analytics warehouse
  ],
}),
```

## Creating Custom Events {#creating-custom-events}

To create a custom event, implement the `IEvent` interface from `@mbc-cqrs-serverless/core`. Depending on the event source, you should typically implement a second interface from the `aws-lambda` library, such as `SNSEventRecord`, `SQSRecord`, `DynamoDBRecord`, `EventBridgeEvent`, `S3EventRecord`, etc.

### Custom S3 Event Example

```typescript
// custom-s3-import.event.ts
import { IEvent } from "@mbc-cqrs-serverless/core";
import { S3EventRecord } from "aws-lambda";

export class CustomS3ImportEvent implements IEvent, Partial<S3EventRecord> {
  source: string;
  bucket: string;
  key: string;
  size: number;
  eventType: string;

  static fromS3Record(record: S3EventRecord): CustomS3ImportEvent {
    const event = new CustomS3ImportEvent();
    event.source = record.eventSource;
    event.bucket = record.s3.bucket.name;
    event.key = record.s3.object.key;
    event.size = record.s3.object.size;
    event.eventType = record.eventName;
    return event;
  }
}
```

### Event Factory Transform Methods

The Event Factory supports transforming events from various AWS sources:

```typescript
// Available transform methods in DefaultEventFactory
transformSqs(event: SQSEvent): Promise<IEvent[]>;
transformSns(event: SNSEvent): Promise<IEvent[]>;
transformDynamodbStream(event: DynamoDBStreamEvent): Promise<IEvent[]>;
transformEventBridge(event: EventBridgeEvent<any, any>): Promise<IEvent[]>;
transformStepFunction(event: StepFunctionsEvent<any>): Promise<IEvent[]>;
transformS3(event: S3Event): Promise<IEvent[]>;
```

## Related Documentation

- [Backend Development Guide](/docs/backend-development) - Core patterns
- [Step Functions](/docs/architecture/step-functions) - Workflow orchestration
- [Data Sync Handler Examples](/docs/data-sync-handler-examples) - Comprehensive sync examples
- [Queue Module](/docs/queue) - SQS and SNS messaging services
- [Notification Module](/docs/notification-module) - Event-triggered notifications and email


---

## Import/Export Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/import-export-patterns

# Import/Export Patterns

This guide covers patterns for handling data import and export operations, including CSV processing, Excel file handling, and batch data operations with Step Functions.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Import bulk data from CSV or Excel files
- Export data to various formats
- Process large datasets with Step Functions
- Implement file upload with S3 presigned URLs
- Transform data between external and internal formats

## Import Architecture Overview {#import-architecture}

```text
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Client    │────>│     S3      │────>│Step Function│────>│   Lambda    │
│  (Upload)   │     │  (Storage)  │     │(Orchestrate)│     │ (Process)   │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                    │
                                        ┌───────────────────────────┘
                                        ▼
                    ┌─────────────┐     ┌─────────────┐
                    │  DynamoDB   │<────│   Import    │
                    │  (Command)  │     │   Handler   │
                    └─────────────┘     └─────────────┘
```

## File Upload Pattern {#file-upload-pattern}

### Storage Service

Generate presigned URLs for secure file uploads:

```typescript
// storage/storage.service.ts
import { Injectable } from '@nestjs/common';
import { S3Service } from '@mbc-cqrs-serverless/core';
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { PutObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';

@Injectable()
export class StorageService {
  constructor(private readonly s3Service: S3Service) {}

  /**
   * Generate upload URL for file import
   */
  async genUploadUrl(
    filename: string,
    contentType = 'text/csv',
  ): Promise<{ bucket: string; key: string; url: string }> {
    const bucket = this.s3Service.privateBucket;
    const timestamp = Date.now();
    const key = `imports/${timestamp}/${filename}`;

    const command = new PutObjectCommand({
      Bucket: bucket,
      Key: key,
      ContentType: contentType,
      ACL: 'private',
    });

    const url = await getSignedUrl(this.s3Service.client, command, {
      expiresIn: 3600, // 1 hour
    });

    return { bucket, key, url };
  }

  /**
   * Generate download URL for file export
   */
  async genDownloadUrl(
    key: string,
    filename?: string,
  ): Promise<{ url: string }> {
    const command = new GetObjectCommand({
      Bucket: this.s3Service.privateBucket,
      Key: key,
      ResponseContentDisposition: filename
        ? `attachment; filename="${filename}"`
        : undefined,
    });

    const url = await getSignedUrl(this.s3Service.client, command, {
      expiresIn: 3600,
    });

    return { url };
  }
}
```

### Storage Controller

```typescript
// storage/storage.controller.ts
import { Controller, Post, Get, Body, Query } from '@nestjs/common';
import { StorageService } from './storage.service';

@Controller('api/storage')
export class StorageController {
  constructor(private readonly storageService: StorageService) {}

  /**
   * Get presigned URL for upload
   */
  @Post('upload-url')
  async getUploadUrl(
    @Body() dto: { filename: string; contentType?: string },
  ) {
    return this.storageService.genUploadUrl(dto.filename, dto.contentType);
  }

  /**
   * Get presigned URL for download
   */
  @Get('download-url')
  async getDownloadUrl(
    @Query('key') key: string,
    @Query('filename') filename?: string,
  ) {
    return this.storageService.genDownloadUrl(key, filename);
  }
}
```

## CSV Import Pattern {#csv-import-pattern}

### CSV Import Controller

```typescript
// csv-import/csv-import.controller.ts
import { Controller, Post, Body } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { StepFunctionService, INVOKE_CONTEXT, IInvoke } from '@mbc-cqrs-serverless/core';

export class CsvImportDto {
  bucket: string;
  key: string;
  type: string;  // Import type identifier
}

@Controller('api/csv-import')
export class CsvImportController {
  private readonly importArn: string;

  constructor(
    private readonly configService: ConfigService,
    private readonly sfnService: StepFunctionService,
  ) {
    this.importArn = this.configService.get<string>('SFN_CSV_IMPORT_ARN');
  }

  /**
   * Start CSV import via Step Functions
   */
  @Post('/')
  async startImport(
    @INVOKE_CONTEXT() invokeContext: IInvoke,
    @Body() dto: CsvImportDto,
  ) {
    const executionName = `${dto.type}-${Date.now()}`;

    return this.sfnService.startExecution(
      this.importArn,
      {
        ...dto,
        invokeContext,
      },
      executionName,
    );
  }
}
```

### CSV Parser Service

```typescript
// csv-import/csv-parser.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { S3Service } from '@mbc-cqrs-serverless/core';
import { GetObjectCommand } from '@aws-sdk/client-s3';
import * as csvParser from 'csv-parser';
import { Readable } from 'stream';

export interface ParsedRow {
  rowNumber: number;
  data: Record<string, string>;
  errors: string[];
}

@Injectable()
export class CsvParserService {
  private readonly logger = new Logger(CsvParserService.name);

  constructor(private readonly s3Service: S3Service) {}

  /**
   * Parse CSV file from S3
   */
  async parseFromS3(
    bucket: string,
    key: string,
    options?: { encoding?: string; delimiter?: string },
  ): Promise<ParsedRow[]> {
    const command = new GetObjectCommand({ Bucket: bucket, Key: key });
    const response = await this.s3Service.client.send(command);

    const stream = response.Body as Readable;
    const results: ParsedRow[] = [];
    let rowNumber = 0;

    return new Promise((resolve, reject) => {
      stream
        .pipe(csvParser({
          separator: options?.delimiter || ',',
          skipLines: 0,
        }))
        .on('data', (data) => {
          rowNumber++;
          results.push({
            rowNumber,
            data,
            errors: [],
          });
        })
        .on('end', () => {
          this.logger.log(`Parsed ${results.length} rows from ${key}`);
          resolve(results);
        })
        .on('error', (error) => {
          this.logger.error(`Failed to parse CSV: ${error.message}`);
          reject(error);
        });
    });
  }

  /**
   * Validate parsed rows
   */
  validateRows(
    rows: ParsedRow[],
    requiredFields: string[],
  ): ParsedRow[] {
    return rows.map(row => {
      const errors: string[] = [];

      for (const field of requiredFields) {
        if (!row.data[field] || row.data[field].trim() === '') {
          errors.push(`Missing required field: ${field}`);
        }
      }

      return { ...row, errors };
    });
  }
}
```

### Import Event Handler

```typescript
// csv-import/event/csv-import.event.handler.ts
import { Injectable, Logger } from '@nestjs/common';
import { EventHandler, IEventHandler, SnsService } from '@mbc-cqrs-serverless/core';
import { ConfigService } from '@nestjs/config';
import { CsvParserService } from '../csv-parser.service';
import { ProductService } from '../../product/product.service';

export class CsvImportEvent {
  bucket: string;
  key: string;
  type: string;
  invokeContext: any;
}

@EventHandler(CsvImportEvent)
@Injectable()
export class CsvImportEventHandler implements IEventHandler<CsvImportEvent> {
  private readonly logger = new Logger(CsvImportEventHandler.name);
  private readonly alarmTopicArn: string;

  constructor(
    private readonly csvParser: CsvParserService,
    private readonly productService: ProductService,
    private readonly snsService: SnsService,
    private readonly configService: ConfigService,
  ) {
    this.alarmTopicArn = this.configService.get<string>('SNS_ALARM_TOPIC_ARN');
  }

  /**
   * Process CSV import event
   */
  async execute(event: CsvImportEvent): Promise<any> {
    this.logger.log(`Processing import: ${event.key}`);

    try {
      // Parse CSV
      const rows = await this.csvParser.parseFromS3(event.bucket, event.key);

      // Validate
      const validatedRows = this.csvParser.validateRows(rows, [
        'code', 'name', 'price',
      ]);

      // Filter valid rows
      const validRows = validatedRows.filter(r => r.errors.length === 0);
      const invalidRows = validatedRows.filter(r => r.errors.length > 0);

      if (invalidRows.length > 0) {
        this.logger.warn(`${invalidRows.length} rows have validation errors`);
      }

      // Process in batches
      const batchSize = 30;
      let processedCount = 0;

      for (let i = 0; i < validRows.length; i += batchSize) {
        const batch = validRows.slice(i, i + batchSize);

        await Promise.all(
          batch.map(row => this.processRow(row.data, event.invokeContext)),
        );

        processedCount += batch.length;
        this.logger.log(`Processed ${processedCount}/${validRows.length} rows`);
      }

      return {
        success: true,
        totalRows: rows.length,
        processedRows: processedCount,
        errorRows: invalidRows.length,
      };
    } catch (error) {
      await this.sendAlarm(event, error);
      throw error;
    }
  }

  private async processRow(data: Record<string, string>, invokeContext: any) {
    await this.productService.publishCommand({
      code: data.code,
      name: data.name,
      attributes: {
        price: parseFloat(data.price),
        category: data.category,
        description: data.description,
      },
    }, invokeContext);
  }

  private async sendAlarm(event: CsvImportEvent, error: Error) {
    await this.snsService.publish({
      action: 'CSV_IMPORT_ERROR',
      key: event.key,
      error: error.message,
      timestamp: new Date().toISOString(),
    }, this.alarmTopicArn);
  }
}
```

## Excel Import Pattern {#excel-import-pattern}

### Excel Helper Functions

```typescript
// helpers/excel.ts
import { Workbook, Worksheet, Cell } from 'exceljs';

/**
 * Get cell value handling formulas and rich text
 */
export function getCellValue(row: any, column: string): string | undefined {
  const cell = row.getCell(column);

  if (!cell || cell.value === null || cell.value === undefined) {
    return undefined;
  }

  // Handle formula result
  if (typeof cell.value === 'object' && 'result' in cell.value) {
    return String(cell.value.result);
  }

  // Handle rich text
  if (typeof cell.value === 'object' && 'richText' in cell.value) {
    return cell.value.richText.map((r: any) => r.text).join('');
  }

  return String(cell.value);
}

/**
 * Get numeric cell value
 */
export function getCellNumber(row: any, column: string): number | undefined {
  const value = getCellValue(row, column);
  if (!value) return undefined;

  const num = parseFloat(value.replace(/,/g, ''));
  return isNaN(num) ? undefined : num;
}

/**
 * Get date cell value
 */
export function getCellDate(row: any, column: string): Date | undefined {
  const cell = row.getCell(column);

  if (cell.value instanceof Date) {
    return cell.value;
  }

  const value = getCellValue(row, column);
  if (!value) return undefined;

  const date = new Date(value);
  return isNaN(date.getTime()) ? undefined : date;
}

/**
 * Find header row by matching column headers
 */
export function findHeaderRow(
  worksheet: Worksheet,
  expectedHeaders: string[],
  maxRows = 20,
): number {
  for (let rowNum = 1; rowNum <= maxRows; rowNum++) {
    const row = worksheet.getRow(rowNum);
    const values = row.values as any[];

    const matches = expectedHeaders.filter(header =>
      values.some(v => v && String(v).includes(header)),
    );

    if (matches.length >= expectedHeaders.length * 0.8) {
      return rowNum;
    }
  }

  throw new Error('Header row not found');
}
```

### Excel Import Service

```typescript
// excel-import/excel-import.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { S3Service } from '@mbc-cqrs-serverless/core';
import { GetObjectCommand } from '@aws-sdk/client-s3';
import { Workbook } from 'exceljs';
import { getCellValue, getCellNumber, findHeaderRow } from '../helpers/excel';

export interface ExcelImportResult {
  success: boolean;
  sheetName: string;
  totalRows: number;
  processedRows: number;
  errors: Array<{ row: number; message: string }>;
}

@Injectable()
export class ExcelImportService {
  private readonly logger = new Logger(ExcelImportService.name);

  constructor(private readonly s3Service: S3Service) {}

  /**
   * Load workbook from S3
   */
  async loadWorkbook(bucket: string, key: string): Promise<Workbook> {
    const command = new GetObjectCommand({ Bucket: bucket, Key: key });
    const response = await this.s3Service.client.send(command);

    const chunks: Buffer[] = [];
    for await (const chunk of response.Body as any) {
      chunks.push(chunk);
    }
    const buffer = Buffer.concat(chunks);

    const workbook = new Workbook();

    if (key.endsWith('.xlsx') || key.endsWith('.xlsm')) {
      await workbook.xlsx.load(buffer);
    } else if (key.endsWith('.xls')) {
      // For .xls files, use different parser
      throw new Error('XLS format not supported. Please use XLSX.');
    }

    return workbook;
  }

  /**
   * Process worksheet with row processor
   */
  async processWorksheet<T>(
    worksheet: any,
    config: {
      headerRow?: number;
      expectedHeaders?: string[];
      startRow?: number;
      processor: (row: any, rowNumber: number) => Promise<T | null>;
    },
  ): Promise<ExcelImportResult & { data: T[] }> {
    const errors: Array<{ row: number; message: string }> = [];
    const data: T[] = [];

    // Find or use specified header row
    const headerRow = config.headerRow || (
      config.expectedHeaders
        ? findHeaderRow(worksheet, config.expectedHeaders)
        : 1
    );

    const startRow = config.startRow || headerRow + 1;
    let processedRows = 0;
    let totalRows = 0;

    worksheet.eachRow((row: any, rowNumber: number) => {
      if (rowNumber < startRow) return;
      totalRows++;
    });

    for (let rowNum = startRow; rowNum <= worksheet.rowCount; rowNum++) {
      const row = worksheet.getRow(rowNum);

      // Skip empty rows
      if (this.isEmptyRow(row)) continue;

      try {
        const result = await config.processor(row, rowNum);
        if (result !== null) {
          data.push(result);
          processedRows++;
        }
      } catch (error) {
        errors.push({
          row: rowNum,
          message: error.message,
        });
      }
    }

    return {
      success: errors.length === 0,
      sheetName: worksheet.name,
      totalRows,
      processedRows,
      errors,
      data,
    };
  }

  private isEmptyRow(row: any): boolean {
    const values = row.values as any[];
    return !values || values.every(v => v === null || v === undefined || v === '');
  }
}
```

### Import Strategy Pattern

```typescript
// import/base-import.strategy.ts
import { BadRequestException } from '@nestjs/common';
import { validate, ValidationError } from 'class-validator';
import { IInvoke } from '@mbc-cqrs-serverless/core';

/**
 * Base interface for import strategies
 * @typeParam TInput - The input type, must be an object
 * @typeParam TAttributesDto - The output DTO type, must be an object
 */
export interface IImportStrategy<TInput extends object, TAttributesDto extends object> {
  /**
   * Transform raw input to command DTO
   */
  transform(input: TInput): Promise<TAttributesDto>;

  /**
   * Validate transformed DTO
   */
  validate(data: TAttributesDto): Promise<void>;
}

/**
 * Base import strategy with common functionality
 * @typeParam TInput - The input type, must be an object
 * @typeParam TAttributesDto - The output DTO type, must be an object
 */
export abstract class BaseImportStrategy<TInput extends object, TAttributesDto extends object>
  implements IImportStrategy<TInput, TAttributesDto>
{
  /**
   * Transform raw input to command DTO (default: return as-is)
   */
  async transform(input: TInput): Promise<TAttributesDto> {
    return input as unknown as TAttributesDto;
  }

  /**
   * Validate transformed DTO using class-validator
   */
  async validate(data: TAttributesDto): Promise<void> {
    // Uses class-validator for validation
    const errors = await validate(data as object);
    if (errors.length > 0) {
      throw new BadRequestException({
        statusCode: 400,
        message: this.flattenValidationErrors(errors),
        error: 'Bad Request',
      });
    }
  }

  /**
   * Flatten validation errors to a simple format
   */
  private flattenValidationErrors(
    errors: ValidationError[],
    parentPath = '',
  ): string[] {
    const messages: string[] = [];
    for (const error of errors) {
      const currentPath = parentPath
        ? `${parentPath}.${error.property}`
        : error.property;

      if (error.children && error.children.length > 0) {
        messages.push(
          ...this.flattenValidationErrors(error.children, currentPath),
        );
      } else if (error.constraints) {
        const firstConstraint = Object.values(error.constraints)[0];
        const message = firstConstraint.replace(error.property, currentPath);
        messages.push(message);
      }
    }
    return messages;
  }
}
```

### Concrete Import Strategy

```typescript
// product/import/product-import.strategy.ts
import { Injectable } from '@nestjs/common';
import { KEY_SEPARATOR, generateId } from '@mbc-cqrs-serverless/core';
import { BaseImportStrategy } from '@mbc-cqrs-serverless/import';
import { ulid } from 'ulid';
import { ProductCommandDto } from '../dto/product-command.dto';

const PRODUCT_PK_PREFIX = 'PRODUCT';

export interface ProductImportInput {
  code: string;
  name: string;
  category?: string;
  price?: string;
  description?: string;
  tenantCode: string; // Passed from import context
}

@Injectable()
export class ProductImportStrategy
  extends BaseImportStrategy<ProductImportInput, ProductCommandDto>
{
  /**
   * Transform import data to command DTO
   */
  async transform(input: ProductImportInput): Promise<ProductCommandDto> {
    const { tenantCode } = input;

    const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;
    const sk = ulid();
    const id = generateId(pk, sk);

    return new ProductCommandDto({
      pk,
      sk,
      id,
      tenantCode,
      code: input.code?.trim(),
      name: input.name?.trim(),
      type: 'PRODUCT',
      attributes: {
        category: input.category?.trim(),
        price: input.price ? parseFloat(input.price.replace(/,/g, '')) : undefined,
        description: input.description?.trim(),
      },
    });
  }

  /**
   * Validate import input
   */
  async validate(input: ProductImportInput): Promise<void> {
    if (!input.code) {
      throw new Error('Product code is required');
    }
    if (!input.name) {
      throw new Error('Product name is required');
    }
    if (input.price && isNaN(parseFloat(input.price.replace(/,/g, '')))) {
      throw new Error('Invalid price format');
    }
  }
}
```

## Export Pattern {#export-pattern}

:::info Note
The export patterns shown below are example implementations for your application. Unlike the import module (`@mbc-cqrs-serverless/import`), there is no dedicated export package in the framework. You can implement these patterns directly in your application code.
:::

### Export Service

```typescript
// export/export.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { S3Service } from '@mbc-cqrs-serverless/core';
import { PutObjectCommand } from '@aws-sdk/client-s3';
import { Workbook } from 'exceljs';

@Injectable()
export class ExportService {
  private readonly logger = new Logger(ExportService.name);

  constructor(private readonly s3Service: S3Service) {}

  /**
   * Export data to CSV and upload to S3
   */
  async exportToCsv(
    data: Record<string, any>[],
    headers: { key: string; label: string }[],
    filename: string,
  ): Promise<{ bucket: string; key: string }> {
    // Build CSV content
    const headerRow = headers.map(h => h.label).join(',');
    const dataRows = data.map(row =>
      headers.map(h => this.escapeCsvValue(row[h.key])).join(','),
    );
    const csvContent = [headerRow, ...dataRows].join('\n');

    // Upload to S3
    const bucket = this.s3Service.privateBucket;
    const key = `exports/${Date.now()}/${filename}`;

    await this.s3Service.client.send(new PutObjectCommand({
      Bucket: bucket,
      Key: key,
      Body: csvContent,
      ContentType: 'text/csv; charset=utf-8',
    }));

    this.logger.log(`Exported ${data.length} rows to ${key}`);
    return { bucket, key };
  }

  /**
   * Export data to Excel and upload to S3
   */
  async exportToExcel(
    data: Record<string, any>[],
    headers: { key: string; label: string; width?: number }[],
    filename: string,
    sheetName = 'Data',
  ): Promise<{ bucket: string; key: string }> {
    const workbook = new Workbook();
    const worksheet = workbook.addWorksheet(sheetName);

    // Set columns
    worksheet.columns = headers.map(h => ({
      header: h.label,
      key: h.key,
      width: h.width || 15,
    }));

    // Style header row
    worksheet.getRow(1).font = { bold: true };
    worksheet.getRow(1).fill = {
      type: 'pattern',
      pattern: 'solid',
      fgColor: { argb: 'FFE0E0E0' },
    };

    // Add data rows
    data.forEach(row => {
      const rowData: Record<string, any> = {};
      headers.forEach(h => {
        rowData[h.key] = row[h.key];
      });
      worksheet.addRow(rowData);
    });

    // Generate buffer
    const buffer = await workbook.xlsx.writeBuffer();

    // Upload to S3
    const bucket = this.s3Service.privateBucket;
    const key = `exports/${Date.now()}/${filename}`;

    await this.s3Service.client.send(new PutObjectCommand({
      Bucket: bucket,
      Key: key,
      Body: buffer as Buffer,
      ContentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    }));

    this.logger.log(`Exported ${data.length} rows to ${key}`);
    return { bucket, key };
  }

  private escapeCsvValue(value: any): string {
    if (value === null || value === undefined) return '';

    const str = String(value);
    if (str.includes(',') || str.includes('"') || str.includes('\n')) {
      return `"${str.replace(/"/g, '""')}"`;
    }
    return str;
  }
}
```

## Step Function Integration {#step-function-integration}

### Import Orchestration

```typescript
// Import workflow with Step Functions

// serverless.yml
/*
stepFunctions:
  stateMachines:
    csvImport:
      name: ${self:custom.prefix}-csv-import
      definition:
        StartAt: ParseFile
        States:
          ParseFile:
            Type: Task
            Resource: !GetAtt ParseFileLambda.Arn
            Next: ProcessBatches
            Catch:
              - ErrorEquals: ["States.ALL"]
                Next: HandleError

          ProcessBatches:
            Type: Map
            ItemsPath: $.batches
            MaxConcurrency: 5
            Iterator:
              StartAt: ProcessBatch
              States:
                ProcessBatch:
                  Type: Task
                  Resource: !GetAtt ProcessBatchLambda.Arn
                  End: true
            Next: Finalize

          Finalize:
            Type: Task
            Resource: !GetAtt FinalizeLambda.Arn
            End: true

          HandleError:
            Type: Task
            Resource: !GetAtt HandleErrorLambda.Arn
            End: true
*/
```

## Best Practices {#best-practices}

### 1. Batch Processing

Always process large files in batches:

```typescript
const BATCH_SIZE = 30;

async processBatches<T>(
  items: T[],
  processor: (item: T) => Promise<void>,
): Promise<void> {
  for (let i = 0; i < items.length; i += BATCH_SIZE) {
    const batch = items.slice(i, i + BATCH_SIZE);
    await Promise.all(batch.map(processor));
  }
}
```

### 2. Error Handling

Collect and report errors without stopping processing:

```typescript
const errors: Array<{ row: number; error: string }> = [];

for (const [index, row] of rows.entries()) {
  try {
    await processRow(row);
  } catch (error) {
    errors.push({ row: index + 1, error: error.message });
    // Continue processing
  }
}

if (errors.length > 0) {
  await this.reportErrors(errors);
}
```

### 3. Validation Before Processing

Validate all data before starting import:

```typescript
// First pass: validate
const validationErrors = await this.validateAll(rows);
if (validationErrors.length > 0) {
  return { success: false, errors: validationErrors };
}

// Second pass: process
await this.processAll(rows);
```

### 4. Progress Reporting

Report progress for long-running imports:

```typescript
const total = rows.length;
let processed = 0;

for (const batch of batches) {
  await processBatch(batch);
  processed += batch.length;

  // Report progress every 100 rows
  if (processed % 100 === 0) {
    this.logger.log(`Progress: ${processed}/${total} (${Math.round(processed/total*100)}%)`);
  }
}
```

## ImportModule API Reference {#importmodule-api}

The `@mbc-cqrs-serverless/import` package provides a comprehensive framework for managing data import tasks.

### Installation

```bash
npm install @mbc-cqrs-serverless/import
```

### ProcessingMode Enum {#processingmode-enum}

The `ProcessingMode` enum defines how import jobs are executed:

```typescript
export enum ProcessingMode {
  DIRECT = 'DIRECT',           // Direct processing without Step Functions
  STEP_FUNCTION = 'STEP_FUNCTION', // Processing orchestrated by Step Functions
}
```

| Mode | Description | Use Case |
|----------|-----------------|--------------|
| `DIRECT` | Import is processed directly without Step Functions orchestration | Small imports, simple data |
| `STEP_FUNCTION` | Import is orchestrated by Step Functions for reliability | Large imports, complex workflows, ZIP imports |

### CreateCsvImportDto {#createcsvimportdto}

The `CreateCsvImportDto` is used to start a CSV import job:

```typescript
import { IsEnum, IsNotEmpty, IsOptional, IsString } from 'class-validator'
import { ProcessingMode } from '@mbc-cqrs-serverless/import'

export class CreateCsvImportDto {
  @IsString()
  @IsOptional()
  sourceId?: string           // Optional source identifier

  @IsNotEmpty()
  @IsEnum(ProcessingMode)
  processingMode: ProcessingMode // How the import should be processed

  @IsString()
  @IsNotEmpty()
  bucket: string              // S3 bucket containing the CSV file

  @IsString()
  @IsNotEmpty()
  key: string                 // S3 key (path) to the CSV file

  @IsString()
  @IsNotEmpty()
  tableName: string           // Target table name for import profile matching

  @IsString()
  @IsNotEmpty()
  tenantCode: string          // Tenant code for multi-tenancy
}
```

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `sourceId` | `string` | No | Optional identifier for the import source |
| `processingMode` | `ProcessingMode` | Yes | DIRECT or STEP_FUNCTION mode |
| `bucket` | `string` | Yes | S3 bucket containing the CSV file |
| `key` | `string` | Yes | S3 key (path) to the CSV file |
| `tableName` | `string` | Yes | Target table name, used to match import profile |
| `tenantCode` | `string` | Yes | Tenant code for multi-tenancy |

### CreateZipImportDto {#createzipimportdto}

The `CreateZipImportDto` is used to start a ZIP import job that contains multiple CSV files:

```typescript
import { IsArray, IsNotEmpty, IsOptional, IsString } from 'class-validator'

export class CreateZipImportDto {
  @IsString()
  @IsNotEmpty()
  bucket: string              // S3 bucket containing the ZIP file

  @IsString()
  @IsNotEmpty()
  key: string                 // S3 key (path) to the ZIP file

  @IsString()
  @IsNotEmpty()
  tenantCode: string          // Tenant code for multi-tenancy

  // High priority: sortedFileKeys
  // If not provided, it will use the default sorting logic
  @IsArray()
  @IsOptional()
  sortedFileKeys?: string[]   // Optional ordered list of file keys to process

  // High priority: tableName
  // If not provided, it will be extracted from the filename
  @IsString()
  @IsOptional()
  tableName?: string   // Optional table name override
}
```

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `bucket` | `string` | Yes | S3 bucket containing the ZIP file |
| `key` | `string` | Yes | S3 key (path) to the ZIP file |
| `tenantCode` | `string` | Yes | Tenant code for multi-tenancy |
| `sortedFileKeys` | `string[]` | No | Ordered list of file keys to process. If not provided, default sorting is used |
| `tableName` | `string` | No | Table name override. If not provided, extracted from filename (format: yyyymmddhhMMss-\{tableName\}.csv) |

### Core Concepts

The module operates on a two-phase architecture:

1. **Import Phase** (`IImportStrategy`): Transform raw data (from JSON or CSV) into a standardized DTO and validate it.
2. **Process Phase** (`IProcessStrategy`): Compare validated DTO with existing data and map it to a command payload for creation or update.

### Implementing Import Strategy

The import strategy handles initial transformation and validation:

```typescript
import { BadRequestException, Injectable } from '@nestjs/common';
import { plainToInstance } from 'class-transformer';
import { BaseImportStrategy, IImportStrategy } from '@mbc-cqrs-serverless/import';
import { PolicyCommandDto } from '../dto/policy-command.dto';

@Injectable()
export class PolicyImportStrategy
  extends BaseImportStrategy<Record<string, any>, PolicyCommandDto>
  implements IImportStrategy<Record<string, any>, PolicyCommandDto>
{
  async transform(input: Record<string, any>): Promise<PolicyCommandDto> {
    const attrSource = input.attributes && typeof input.attributes === 'object'
      ? input.attributes
      : input;

    const mappedObject = {
      pk: input.pk,
      sk: input.sk,
      attributes: {
        policyType: attrSource.policyType,
        applyDate: new Date(attrSource.applyDate).toISOString(),
      },
    };

    return plainToInstance(PolicyCommandDto, mappedObject);
  }
}
```

### ComparisonStatus Enum {#comparisonstatus-enum}

The `ComparisonStatus` enum defines the result of comparing imported data with existing data:

```typescript
export enum ComparisonStatus {
  EQUAL = 'EQUAL',         // Data exists and is identical - no action needed
  NOT_EXIST = 'NOT_EXIST', // Data does not exist - create new record
  CHANGED = 'CHANGED',     // Data exists but differs - update existing record
}
```

| Value | Description | Action |
|-----------|-----------------|------------|
| `EQUAL` | Imported data matches existing data | Skip (no operation) |
| `NOT_EXIST` | No existing data found | Create new record |
| `CHANGED` | Existing data differs from imported data | Update existing record |

### ComparisonResult Interface {#comparisonresult-interface}

The `ComparisonResult<TEntity>` interface wraps the comparison status with optional existing data. The generic type `TEntity` must extend `DataModel`:

```typescript
import { DataModel } from '@mbc-cqrs-serverless/core'

export interface ComparisonResult<TEntity extends DataModel> {
  status: ComparisonStatus;  // The result of the comparison
  /**
   * If the status is 'CHANGED', this property holds the existing entity data
   * retrieved from the database. It is undefined otherwise.
   */
  existingData?: TEntity;
}
```

| Property | Type | Description |
|--------------|----------|-----------------|
| `status` | `ComparisonStatus` | The comparison result status |
| `existingData` | `TEntity \| undefined` | The existing entity data, present when status is CHANGED |

### IProcessStrategy Interface {#iprocessstrategy-interface}

The `IProcessStrategy` interface defines the contract for processing validated import data. Note that the generic type `TEntity` must extend `DataModel`:

```typescript
import {
  CommandInputModel,
  CommandPartialInputModel,
  CommandService,
  DataModel,
} from '@mbc-cqrs-serverless/core';

export interface IProcessStrategy<TEntity extends DataModel, TAttributesDto extends object> {
  /**
   * Compare the validated DTO with existing data
   */
  compare(
    importAttributes: TAttributesDto,
    tenantCode: string,
  ): Promise<ComparisonResult<TEntity>>;

  /**
   * Map the DTO to a command payload based on comparison status
   * Note: status excludes EQUAL since no mapping is needed for identical data
   * @returns CommandInputModel for create, CommandPartialInputModel for update
   */
  map(
    status: Exclude<ComparisonStatus, ComparisonStatus.EQUAL>,
    importAttributes: TAttributesDto,
    tenantCode: string,
    existingData?: TEntity,
  ): Promise<CommandInputModel | CommandPartialInputModel>;

  /**
   * Get the command service for publishing commands
   */
  getCommandService(): CommandService;
}
```

### BaseProcessStrategy Abstract Class {#baseprocessstrategy-class}

The `BaseProcessStrategy` abstract class provides a base implementation that subclasses must extend. The generic type `TEntity` must extend `DataModel`:

```typescript
import { DataModel } from '@mbc-cqrs-serverless/core';

export abstract class BaseProcessStrategy<TEntity extends DataModel, TTransformedDto extends object>
  implements IProcessStrategy<TEntity, TTransformedDto>
{
  /**
   * Abstract method - must be implemented to compare data
   */
  abstract compare(
    transformedData: TTransformedDto,
    tenantCode: string,
  ): Promise<ComparisonResult<TEntity>>;

  /**
   * Abstract method - must be implemented to map data to command payload
   * Note: status excludes EQUAL since no mapping is needed for identical data
   */
  abstract map(
    status: Exclude<ComparisonStatus, ComparisonStatus.EQUAL>,
    transformedData: TTransformedDto,
    tenantCode: string,
    existingData?: TEntity,
  ): Promise<CommandInputModel | CommandPartialInputModel>;

  /**
   * Abstract method - must be implemented to return the command service
   */
  abstract getCommandService(): CommandService;
}
```

:::info Note
All three methods (`compare()`, `map()`, `getCommandService()`) in `BaseProcessStrategy` are abstract and must be implemented by subclasses.
:::

### Implementing Process Strategy

The process strategy contains core business logic for comparing and mapping data:

```typescript
import { Injectable } from '@nestjs/common';
import {
  CommandInputModel,
  CommandPartialInputModel,
  CommandService,
  DataService,
} from '@mbc-cqrs-serverless/core';
import {
  BaseProcessStrategy,
  ComparisonResult,
  ComparisonStatus,
  IProcessStrategy,
} from '@mbc-cqrs-serverless/import';
import { PolicyCommandDto } from '../dto/policy-command.dto';
import { PolicyDataEntity } from '../entity/policy-data.entity';

@Injectable()
export class PolicyProcessStrategy
  extends BaseProcessStrategy<PolicyDataEntity, PolicyCommandDto>
  implements IProcessStrategy<PolicyDataEntity, PolicyCommandDto>
{
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
  ) {
    super();
  }

  getCommandService(): CommandService {
    return this.commandService;
  }

  async compare(
    dto: PolicyCommandDto,
    tenantCode: string,
  ): Promise<ComparisonResult<PolicyDataEntity>> {
    const existing = await this.dataService.getItem({ pk: dto.pk, sk: dto.sk });
    if (!existing) return { status: ComparisonStatus.NOT_EXIST };
    return { status: ComparisonStatus.CHANGED, existingData: existing as PolicyDataEntity };
  }

  async map(
    status: Exclude<ComparisonStatus, ComparisonStatus.EQUAL>,
    dto: PolicyCommandDto,
    tenantCode: string,
    existingData?: PolicyDataEntity,
  ): Promise<CommandInputModel | CommandPartialInputModel> {
    if (status === ComparisonStatus.NOT_EXIST) {
      // Return CommandInputModel for creating new records
      return { ...dto, version: 0 } as CommandInputModel;
    }
    // status === ComparisonStatus.CHANGED
    // Return CommandPartialInputModel for updating existing records
    return {
      pk: dto.pk,
      sk: dto.sk,
      attributes: dto.attributes,
      version: existingData.version,
    } as CommandPartialInputModel;
  }
}
```

### Module Configuration

Register the ImportModule with your profiles:

```typescript
import { Module } from '@nestjs/common';
import { ImportModule } from '@mbc-cqrs-serverless/import';
import { PolicyModule } from './policy/policy.module';
import { PolicyImportStrategy } from './policy/strategies/policy.import-strategy';
import { PolicyProcessStrategy } from './policy/strategies/policy.process-strategy';

@Module({
  imports: [
    PolicyModule,
    ImportModule.register({
      enableController: true,
      imports: [PolicyModule],
      profiles: [
        {
          tableName: 'policy',
          importStrategy: PolicyImportStrategy,
          processStrategy: PolicyProcessStrategy,
        },
      ],
    }),
  ],
})
export class AppModule {}
```

### Custom Event Factory for Imports

Configure the event factory to handle import events:

```typescript
import {
  EventFactory,
  IEvent,
  StepFunctionsEvent,
} from '@mbc-cqrs-serverless/core';
import {
  CsvImportSfnEvent,
  DEFAULT_IMPORT_ACTION_QUEUE,
  ImportEvent,
  ImportQueueEvent,
} from '@mbc-cqrs-serverless/import';
import { EventFactoryAddedTask } from '@mbc-cqrs-serverless/task';
import { DynamoDBStreamEvent, SQSEvent } from 'aws-lambda';

@EventFactory()
export class CustomEventFactory extends EventFactoryAddedTask {
  async transformDynamodbStream(event: DynamoDBStreamEvent): Promise<IEvent[]> {
    const curEvents = await super.transformDynamodbStream(event);

    const importEvents = event.Records.map((record) => {
      if (
        record.eventSourceARN.endsWith('import_tmp') ||
        record.eventSourceARN.includes('import_tmp/stream/')
      ) {
        if (record.eventName === 'INSERT') {
          return new ImportEvent().fromDynamoDBRecord(record);
        }
      }
      return undefined;
    }).filter((event) => !!event);

    return [...curEvents, ...importEvents];
  }

  async transformSqs(event: SQSEvent): Promise<IEvent[]> {
    const curEvents = await super.transformSqs(event);

    const importEvents = event.Records.map((record) => {
      if (record.eventSourceARN.endsWith(DEFAULT_IMPORT_ACTION_QUEUE)) {
        return new ImportQueueEvent().fromSqsRecord(record);
      }
      return undefined;
    }).filter((event) => !!event);

    return [...importEvents, ...curEvents];
  }

  async transformStepFunction(event: StepFunctionsEvent<any>): Promise<IEvent[]> {
    if (event.context.StateMachine.Name.includes('import-csv')) {
      return [new CsvImportSfnEvent(event)];
    }
    return super.transformStepFunction(event);
  }
}
```

### ImportStatusHandler API {#importstatushandler-api}

The `ImportStatusHandler` is an internal event handler that manages Step Functions callbacks for import jobs. When using Step Functions orchestration (ZIP imports or STEP_FUNCTION mode CSV imports), this handler ensures proper communication with the state machine.

#### Behavior

| Import Status | Action | Step Functions Command |
|-------------------|------------|---------------------------|
| `COMPLETED` | Send success callback | `SendTaskSuccessCommand` |
| `FAILED` | Send failure callback | `SendTaskFailureCommand` |
| Other statuses | Ignored | None |

#### Methods

| Method | Description |
|------------|-----------------|
| `sendTaskSuccess(taskToken, output)` | Sends success signal to Step Functions with the import result |
| `sendTaskFailure(taskToken, error, cause)` | Sends failure signal to Step Functions with error details |

#### Step Functions Integration

When an import job is created as part of a Step Functions workflow (e.g., ZIP import), a `taskToken` is stored in the job's attributes. The `ImportStatusHandler` listens for status change notifications and:

1. Retrieves the import job from DynamoDB
2. Checks if a `taskToken` exists in the job's attributes
3. Sends the appropriate callback based on the final status:
   - `COMPLETED` → `SendTaskSuccessCommand` with result data
   - `FAILED` → `SendTaskFailureCommand` with error details

This ensures Step Functions workflows properly handle both success and failure cases without hanging indefinitely.

:::info Version Note
The `sendTaskFailure()` method was added in [version 1.0.18](/docs/changelog#v1018) to fix an issue where Step Functions would wait indefinitely when import jobs failed. See also [Import Module Errors](/docs/error-catalog#import-module-errors) for troubleshooting.
:::

### ImportQueueEventHandler Error Handling {#import-error-handling}

The `ImportQueueEventHandler` processes individual import records from the SQS queue. When an error occurs during processing (e.g., `ConditionalCheckFailedException`), the handler properly updates the parent job status.

#### Error Flow (v1.0.19+)

```text
Child Job Error Occurs
         │
         ▼
Mark Child Job as FAILED
         │
         ▼
Update Parent Job Counters
  (incrementParentJobCounters)
         │
         ▼
Check if All Children Complete
         │
    ┌────┴────┐
    │ Yes     │ No
    ▼         ▼
Update Master  Wait for Job Status  more children
         │
    ┌────┴────┐
    │ Has     │ All
    │ Failures│ Succeeded
    ▼         ▼
FAILED    COMPLETED
         │
         ▼
ImportStatusHandler Triggered
         │
         ▼
SendTaskFailure/SendTaskSuccess
```

#### Key Methods

| Method | Description |
|------------|-----------------|
| `handleImport(event)` | Orchestrates single import record processing with error handling |
| `executeStrategy(...)` | Executes compare, map, and save lifecycle for a strategy |

#### Error Handling Behavior

When a child import job fails:

1. Child job status is set to `FAILED` with error details
2. Parent job counters are atomically updated (`failedRows` incremented)
3. When all children complete, master job status is set based on results:
   - If `failedRows > 0` → Master status = `FAILED`
   - If all succeeded → Master status = `COMPLETED`
4. Lambda does NOT crash - error is handled gracefully

:::warning Common Errors
`ConditionalCheckFailedException`: This occurs when attempting to import data that already exists with conflicting version. The import job will be marked as FAILED and the parent job will properly aggregate this failure.
:::

:::info Version Note
Prior to v1.0.19, errors in child jobs would crash the Lambda and leave the master job in `PROCESSING` status indefinitely. The fixes in [version 1.0.19](/docs/changelog#v1019) ensure proper error propagation and status updates.
:::

### CsvImportSfnEventHandler {#csvimportsfneventhandler}

The `CsvImportSfnEventHandler` handles Step Functions CSV import workflow states. It manages the `csv_loader` and `finalize_parent_job` states in the import state machine.

#### Key Methods

| Method | Description |
|------------|-----------------|
| `handleStepState(event)` | Routes events to appropriate handlers based on state name (`csv_loader` or `finalize_parent_job`) |
| `loadCsv(input)` | Processes the csv_loader state, creates child jobs for CSV rows |
| `finalizeParentJob(event)` | Finalizes the parent job after all children complete, sets final status |
| `countCsvRows(input)` | Counts total data rows in a CSV file from S3 (excluding header) |

#### V2 Batch Processing Architecture (v1.1.5+) {#v2-batch-processing}

:::info Version Note
The v2 batch processing architecture was introduced in [version 1.1.5](/docs/changelog#v115) to dramatically improve throughput for large-scale imports (e.g. 300,000+ rows).
:::

In v1.1.5, the CSV import pipeline was redesigned to eliminate Hot Partition bottlenecks:

| Aspect | v1 (≤ 1.1.4) | v2 (1.1.5+) |
|------------|------------------|-----------------|
| Batch size | `MaxInputBytesPerBatch: 10` | `MaxItemsPerBatch: 100` |
| Row processing | Write to `import_tmp` → SQS → Step Functions per row | Direct `CommandService` publish inside Lambda batch |
| Job finalization | Atomic counter update per row via `CommandFinishedHandler` | Single `UpdateItem` in `finalize_parent_job` state |
| Progress tracking | Real-time per-row | Aggregated at completion |

##### V2 Breaking Changes {#v2-batch-processing-breaking-changes}

:::danger Breaking Change (v1.1.5)
The following changes require infrastructure updates when upgrading to v1.1.5:

1. **No real-time progress tracking**: `processedRows`, `succeededRows`, `failedRows` counters are updated only once when the Step Functions execution completes. The job stays in `PROCESSING` until it transitions directly to `COMPLETED` or `FAILED`.
2. **`import_tmp` table bypassed**: Individual CSV rows are no longer written to the `import_tmp` DynamoDB table.
3. **State machine update required**: The `import-csv` state machine must include a `finalize_parent_job` state and `resultPath: '$.processingResults'`. Update CDK (`infra-stack.ts`) and `serverless.yml` together with this package.
:::

##### Configuring Publish Mode {#import-publish-mode}

v1.1.5 introduces `ImportPublishMode` to control how commands are published per entity:

```typescript
// Register import module with per-entity publish mode
ImportModule.register({
  profiles: [
    {
      tableName: 'building',
      importStrategy: BuildingImportStrategy,
      processStrategy: BuildingProcessStrategy,
      publishMode: ImportPublishMode.ASYNC, // Default: non-blocking (recommended for large imports)
    },
    {
      tableName: 'room',
      importStrategy: RoomImportStrategy,
      processStrategy: RoomProcessStrategy,
      publishMode: ImportPublishMode.SYNC,  // Blocking: use only for small batches
    },
  ],
}),
```

:::warning
`ImportPublishMode.SYNC` executes `publishSync` sequentially per row inside the Lambda batch. With `MaxItemsPerBatch: 100`, this can exceed the Lambda 15-minute timeout for slow operations. Prefer `ASYNC` for large imports.
:::

#### Total Row Counting (v1.1.3+) {#csv-total-row-counting}

In v1.1.3 and v1.1.4, `finalizeParentJob` counted total rows by reading the CSV from S3 using `countCsvRows()`. In v1.1.5+, total row counts are derived from batch summaries aggregated natively by Step Functions — no S3 re-read is needed.

:::info Version Note
In v1.1.3, the total row counting was changed from `MapResult.length` to `countCsvRows()` to avoid the AWS Step Functions 256KB state data limit. The Distributed Map `resultPath` is now set to `DISCARD`, preventing child execution results from being aggregated. See [version 1.1.3](/docs/changelog#v113).
:::

#### Status Determination (v1.0.20+)

When finalizing the parent job, the handler correctly determines the final status:

```typescript
// Correct behavior (v1.0.20+)
const status = failedRows > 0
  ? ImportJobStatus.FAILED    // Any child failed → FAILED
  : ImportJobStatus.COMPLETED // All children succeeded → COMPLETED
```

:::warning Known Issue (Fixed in v1.0.20)
Prior to v1.0.20, a bug in the ternary operator caused the status to always be `COMPLETED`:

```typescript
// Bug (pre-v1.0.20): always returned COMPLETED
const status = failedRows > 0
  ? ImportJobStatus.COMPLETED  // Wrong!
  : ImportJobStatus.COMPLETED
```

This caused Step Functions to report SUCCESS even when child import jobs failed. See [version 1.0.20](/docs/changelog#v1020) for details.
:::

### ZipImportSfnEventHandler {#zipimportsfneventhandler}

The `ZipImportSfnEventHandler` handles Step Functions ZIP import workflow states. It orchestrates the processing of multiple CSV files extracted from a ZIP archive.

#### Workflow States

| State | Description |
|-----------|-----------------|
| `trigger_single_csv_and_wait` | Triggers a single CSV import job for each file in the ZIP |
| `finalize_zip_job` | Aggregates results from all CSV imports and finalizes the master job |

#### Key Methods

| Method | Description |
|------------|-----------------|
| `triggerSingleCsvJob(event)` | Creates a CSV import job with STEP_FUNCTION mode, passing the taskToken for callback |
| `finalizeZipMasterJob(event)` | Aggregates results from all processed CSV files and updates the ZIP master job status |

:::warning Known Issue
The `finalizeZipMasterJob` method currently always sets the master job status to `COMPLETED`, regardless of whether any child CSV import jobs failed. This means ZIP import workflows will report success even when individual CSV files failed to import correctly.

To work around this, check the `failedRows` count in the result object to determine if any errors occurred during processing.
:::

#### File Naming Convention

When processing CSV files from a ZIP archive, the handler extracts the table name from the filename:

```text
Format: yyyymmddhhMMss-\{tableName\}.csv
Example: 20240115120000-products.csv → extracts tableName = "products"
```

If `tableName` is provided in the `CreateZipImportDto`, it overrides the extracted name.

#### Processing Flow

```text
ZIP File Uploaded to S3
         │
         ▼
Step Functions Triggered
         │
         ▼
Unzip and List CSV Files
         │
         ▼
Map State: For Each CSV File
    ┌────┴────┐
    │         │
    ▼         ▼
trigger_single_csv_and_wait
    │         │
    ▼         ▼
CSV Import Job Created    CSV Import Job Created
(with taskToken)          (with taskToken)
    │         │
    ▼         ▼
Wait for Completion       Wait for Completion
    │         │
    └────┬────┘
         │
         ▼
finalize_zip_job
         │
         ▼
Aggregate Results & Update Master Job
```

#### ZipImportSfnEvent Structure

```typescript
export class ZipImportSfnEvent implements IEvent {
  source: string           // Execution ID from Step Functions
  context: StepFunctionsContext // Step Functions context with state info
  input: string | any[]    // S3 key or array of results
  taskToken: string        // Token for callback to Step Functions
}
```

The `context.Execution.Input` contains:
- `masterJobKey`: Primary key of the ZIP master job in DynamoDB
- `parameters`: Original import parameters (bucket, tenantCode, tableName)

---

## Related Documentation

- [Backend Development Guide](/docs/backend-development) - Core backend patterns
- [Service Patterns](/docs/service-patterns) - Service implementation
- [Import Module](/docs/import) - ImportModule API reference and strategy interfaces
- [Data Migration Patterns](/docs/data-migration-patterns) - Migrating data between schema versions
- [Step Functions](/docs/architecture/step-functions) - Workflow orchestration
- [Directory](/docs/directory) - S3 file and folder management with presigned URLs
- [Data Sync Handler Examples](/docs/data-sync-handler-examples) - Sync handler patterns


---

## Modules

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/modules

# Modules

## Overview {#overview}

A module is a class annotated with a `@Module()` decorator. The `@Module()` decorator provides metadata that organizes the application structure. Modules encapsulate related functionality and follow the NestJS module pattern.

```mermaid
graph TB
    subgraph "Your Application"
        A["AppModule"]
        A --> B["CatModule"]
        A --> C["OrderModule"]
        A --> D["UserModule"]
    end

    subgraph "Framework Modules"
        E["CommandModule"]
        F["SequencesModule"]
        G["TenantModule"]
    end

    B --> E
    C --> E
    C --> F
    D --> G
```

## Module Structure {#module-structure}

A typical module in MBC CQRS Serverless includes:

```typescript
import { Module } from '@nestjs/common';
import { CommandModule } from '@mbc-cqrs-serverless/core';

import { CatController } from './cat.controller';
import { CatService } from './cat.service';
import { CatDataSyncRdsHandler } from './handler/cat-rds.handler';

@Module({
  imports: [
    CommandModule.register({
      tableName: 'cat',
      dataSyncHandlers: [CatDataSyncRdsHandler],
    }),
  ],
  controllers: [CatController],
  providers: [CatService],
  exports: [CatService],
})
export class CatModule {}
```

## Module Components {#module-components}

| Component | Description |
|-----------|-------------|
| `imports` | List of imported modules that export providers used in this module |
| `controllers` | Controllers that handle HTTP requests |
| `providers` | Services and other providers available for injection |
| `exports` | Providers that should be available in modules that import this module |

## Framework Modules {#framework-modules}

MBC CQRS Serverless provides several ready-to-use modules:

### Core Modules

| Module | Package | Purpose |
|--------|---------|---------|
| `CommandModule` | `@mbc-cqrs-serverless/core` | CQRS command handling and data sync |
| `SequencesModule` | `@mbc-cqrs-serverless/sequence` | Sequential ID generation |
| `TenantModule` | `@mbc-cqrs-serverless/tenant` | Multi-tenant management |

### Feature Modules

| Module | Package | Purpose |
|--------|---------|---------|
| `TaskModule` | `@mbc-cqrs-serverless/task` | Async task execution with Step Functions |
| `MasterModule` | `@mbc-cqrs-serverless/master` | Master data and settings management |
| `ImportModule` | `@mbc-cqrs-serverless/import` | CSV/API data import |
| `DirectoryStorageModule` | `@mbc-cqrs-serverless/directory` | File and folder management with S3 |
| `SurveyTemplateModule` | `@mbc-cqrs-serverless/survey-template` | Survey template management |

### Support Modules

| Module | Package | Purpose |
|--------|---------|---------|
| `QueueModule` | `@mbc-cqrs-serverless/core` | SNS publish and SQS send/receive messaging |
| `NotificationModule` | `@mbc-cqrs-serverless/core` | Email via SES and real-time WebSocket notifications via AppSync |
| `SettingModule` | `@mbc-cqrs-serverless/ui-setting` | User interface settings storage |

## Dynamic Module Registration {#dynamic-registration}

Most framework modules are dynamic modules that accept configuration:

### CommandModule

```typescript
CommandModule.register({
  tableName: 'cat',
  dataSyncHandlers: [CatDataSyncRdsHandler],
  skipError: false,
  disableDefaultHandler: false,
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `tableName` | `string` | Required | DynamoDB table name (without postfix) |
| `dataSyncHandlers` | `Type[]` | `[]` | Data sync handler classes |
| `skipError` | `boolean` | `false` | Reserved for future use (not yet implemented) |
| `disableDefaultHandler` | `boolean` | `false` | Disable default DynamoDB data sync handler |

### SequencesModule

```typescript
SequencesModule.register({
  enableController: true, // Enable built-in sequence REST endpoints
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableController` | `boolean` | `false` | Enable the built-in sequence generation endpoints |

### TenantModule

The TenantModule provides multi-tenant management. It can expose REST endpoints for creating and updating tenants and their group configurations.

```typescript
import { TenantModule } from '@mbc-cqrs-serverless/tenant';

TenantModule.register({
  enableController: true, // Enable built-in tenant REST endpoints
  dataSyncHandlers: [TenantRdsSyncHandler], // Optional: Data sync handlers for RDS synchronization
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableController` | `boolean` | `false` | Enable the built-in TenantController endpoints |
| `dataSyncHandlers` | `Type[]` | `[]` | Data sync handler classes |

See [Tenant](/docs/tenant) for the full API reference.

### MasterModule

```typescript
MasterModule.register({
  enableController: true,
  prismaService: PrismaService,
})
```

:::warning MasterModule Configuration Note
When `enableController: true`, the `prismaService` parameter is **required**. You must provide your application's PrismaService class. The framework will throw an error if `prismaService` is not provided when controllers are enabled.
:::

### TaskModule

TaskModule handles asynchronous task execution using AWS Step Functions. It requires a custom event factory that implements `ITaskQueueEventFactory`.

```typescript
import { TaskModule } from '@mbc-cqrs-serverless/task';
import { MyTaskQueueEventFactory } from './my-task-queue-event.factory';

TaskModule.register({
  taskQueueEventFactory: MyTaskQueueEventFactory,
  enableController: true,
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `taskQueueEventFactory` | `Type<ITaskQueueEventFactory>` | Required | Factory class for transforming task queue events |
| `enableController` | `boolean` | `false` | Enable built-in task REST endpoints |

The `taskQueueEventFactory` must implement the `ITaskQueueEventFactory` interface. Both methods are optional - implement only what you need:

```typescript
import { ITaskQueueEventFactory, TaskQueueEvent, StepFunctionTaskEvent } from '@mbc-cqrs-serverless/task';
import { IEvent } from '@mbc-cqrs-serverless/core';
import { MyTaskEvent } from './my-task.event';
import { MyStepFunctionTaskEvent } from './my-sfn-task.event';

export class MyTaskQueueEventFactory implements ITaskQueueEventFactory {
  // Optional: Transform SQS task queue events into domain events
  async transformTask(event: TaskQueueEvent): Promise<IEvent[]> {
    // Create domain-specific events from task queue events
    return [new MyTaskEvent().fromSqsRecord(event)];
  }

  // Optional: Transform Step Function task events into domain events
  async transformStepFunctionTask(event: StepFunctionTaskEvent): Promise<IEvent[]> {
    // Check taskKey.sk to determine which event type to create
    if (event.taskKey.sk.startsWith('MY_TASK')) {
      return [new MyStepFunctionTaskEvent(event)];
    }
    return [];
  }
}
```

### ImportModule

The ImportModule provides CSV and API data import functionality. It requires defining import profiles that specify how data should be imported and processed for each entity type.

```typescript
import { ImportModule } from '@mbc-cqrs-serverless/import';
import { PolicyImportStrategy } from './strategies/policy-import.strategy';
import { PolicyProcessStrategy } from './strategies/policy-process.strategy';
import { PolicyModule } from './policy.module';

@Module({
  imports: [
    ImportModule.register({
      profiles: [
        {
          tableName: 'policy',
          importStrategy: PolicyImportStrategy,
          processStrategy: PolicyProcessStrategy,
        },
      ],
      imports: [PolicyModule], // Modules that export providers needed by strategies
      enableController: true,
    }),
  ],
})
export class AppModule {}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `profiles` | `ImportEntityProfile[]` | Required | Array of import profiles for each entity type |
| `imports` | `ModuleMetadata['imports']` | `[]` | Modules that export providers needed by strategy classes |
| `enableController` | `boolean` | `false` | Enable built-in `/imports`, `/imports/csv`, and `/imports/zip` endpoints |

Each `ImportEntityProfile` requires:

| Property | Type | Description |
|----------|------|-------------|
| `tableName` | `string` | Unique identifier for the data type (e.g., 'policy', 'user') |
| `importStrategy` | `Type<IImportStrategy>` | Class implementing import logic (transform & validate) |
| `processStrategy` | `Type<IProcessStrategy>` | Class implementing business processing logic (compare & map) |

### DirectoryStorageModule

The DirectoryStorageModule provides S3-backed file and folder management with permissions, version history, and presigned URL generation.

```typescript
import { DirectoryStorageModule } from '@mbc-cqrs-serverless/directory';
import { PrismaService } from './prisma.service';

DirectoryStorageModule.register({
  enableController: true,
  prismaService: PrismaService,
  dataSyncHandlers: [],
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableController` | `boolean` | `false` | Enable built-in directory REST endpoints |
| `prismaService` | `Type<PrismaService>` | Required when enableController is true | Application PrismaService class |
| `dataSyncHandlers` | `Type[]` | `[]` | Data sync handler classes |

### SurveyTemplateModule

The SurveyTemplateModule provides survey template management with support for multiple question types including text, radio, checkbox, and rating questions.

```typescript
import { SurveyTemplateModule } from '@mbc-cqrs-serverless/survey-template';
import { PrismaService } from './prisma.service';

SurveyTemplateModule.register({
  enableController: true,
  prismaService: PrismaService,
})
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableController` | `boolean` | `false` | Enable built-in survey template REST endpoints |
| `prismaService` | `Type<PrismaService>` | Required when enableController is true | Application PrismaService class |

### SettingModule

The SettingModule manages user interface settings. It can optionally expose REST endpoints for managing settings.

```typescript
import { SettingModule } from '@mbc-cqrs-serverless/ui-setting';

@Module({
  imports: [
    SettingModule.register({
      enableSettingController: true,
      enableDataController: true,
    }),
  ],
})
export class AppModule {}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enableSettingController` | `boolean` | `false` | Enable the setting controller for UI settings management |
| `enableDataController` | `boolean` | `false` | Enable the data setting controller for data-related settings |

### NotificationModule (Static)

The NotificationModule is a static (not dynamic) module that provides email notifications via SES and real-time updates via AppSync. It is automatically registered as a global module, so you only need to import it once in your AppModule.

```typescript
import { NotificationModule } from '@mbc-cqrs-serverless/core';

@Module({
  imports: [
    NotificationModule, // No configuration needed - static module
  ],
})
export class AppModule {}
```

This module exports:
- `EmailService` - Send emails via Amazon SES
- `AppSyncService` - Send real-time notifications via AppSync (GraphQL Subscriptions)
- `AppSyncEventsService` - Send real-time notifications via AppSync Events API (opt-in, added in v1.3.0) → [Notification Module](/docs/notification-module#appsync-events-service)

## Creating Custom Modules {#custom-modules}

### Step 1: Create Module File

```typescript
// src/order/order.module.ts
import { Module } from '@nestjs/common';
import { CommandModule } from '@mbc-cqrs-serverless/core';
import { SequencesModule } from '@mbc-cqrs-serverless/sequence';

import { OrderController } from './order.controller';
import { OrderService } from './order.service';
import { OrderDataSyncHandler } from './handlers/order-data-sync.handler';

@Module({
  imports: [
    CommandModule.register({
      tableName: 'order',
      dataSyncHandlers: [OrderDataSyncHandler],
    }),
    SequencesModule.register({
      enableController: false,
    }),
  ],
  controllers: [OrderController],
  providers: [OrderService],
  exports: [OrderService],
})
export class OrderModule {}
```

### Step 2: Register in AppModule

```typescript
// src/app.module.ts
import { Module } from '@nestjs/common';
import { OrderModule } from './order/order.module';

@Module({
  imports: [OrderModule],
})
export class AppModule {}
```

## Best Practices {#best-practices}

1. **One module per entity**: Create a dedicated module for each business entity
2. **Export services, not controllers**: Only export providers that other modules need
3. **Use forRoot for global modules**: Register global configuration once in AppModule
4. **Keep modules focused**: Each module should have a single responsibility

## Related Documentation

- [NestJS Modules](https://docs.nestjs.com/modules): Official NestJS module documentation
- [CommandService](/docs/command-service): Detailed CommandModule configuration
- [API Reference](/docs/api-reference): Full module API documentation
- [Queue Module](/docs/queue): QueueModule — SNS and SQS messaging
- [Tenant Module](/docs/tenant): TenantModule — multi-tenant management
- [Sequence](/docs/sequence): SequencesModule — sequential ID generation
- [Tasks](/docs/tasks): TaskModule — async Step Functions execution
- [Master](/docs/master): MasterModule — master data and settings
- [Import Module](/docs/import): ImportModule — CSV data import
- [Event Handling Patterns](/docs/event-handling-patterns): Creating data sync handlers
- [Notification Module](/docs/notification-module): Real-time notifications and email via AppSync and SES
- [Directory](/docs/directory): File and folder management with DirectoryStorageModule
- [Survey Template](/docs/survey-template): Survey template management with SurveyTemplateModule
- [UI Setting](/docs/ui-setting): SettingModule for UI configuration storage


---

## Multi-Tenant Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/multi-tenant-patterns

# Multi-Tenant Patterns

This guide covers patterns for implementing multi-tenant applications with proper data isolation, shared resources, and cross-tenant operations.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Isolate data between tenants (customers/organizations)
- Share common data across all tenants
- Allow users to belong to multiple tenants
- Implement tenant-specific configuration
- Sync data between tenants

## Multi-Tenant Architecture {#multi-tenant-architecture}

```text
┌─────────────────────────────────────────────────────────────────┐
│                        Application                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
│   │  Tenant A   │   │  Tenant B   │   │   Common    │           │
│   │  PK: X#A    │   │  PK: X#B    │   │  PK: X#common│          │
│   └─────────────┘   └─────────────┘   └─────────────┘           │
│          │                 │                  │                  │
│          ▼                 ▼                  ▼                  │
│   ┌─────────────────────────────────────────────────────────┐   │
│   │                    DynamoDB Table                        │   │
│   │  PK: ENTITY#tenantCode  |  SK: identifier                │   │
│   └─────────────────────────────────────────────────────────┘   │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘
```

## Tenant Context {#tenant-context}

:::info Tenant Code Normalization
All tenant codes returned by `getUserContext()` are normalized to lowercase. This means `TenantA`, `TENANTA`, and `tenanta` are all treated as `tenanta`. When defining tenant codes in Cognito custom claims or HTTP headers, the case doesn't matter - internally they are always lowercase for consistent matching.
:::

### Extracting Tenant Context

Create a helper to extract tenant information from invoke context:

```typescript
// helpers/context.ts
import { IInvoke, getUserContext, getAuthorizerClaims } from '@mbc-cqrs-serverless/core';

export interface CustomUserContext {
  tenantCode: string;
  userCode: string;
  userId: string;
  email?: string;
  role?: string;
}

/**
 * Get custom user context from invoke context
 */
export function getCustomUserContext(invokeContext: IInvoke): CustomUserContext {
  const userContext = getUserContext(invokeContext);
  const claims = getAuthorizerClaims(invokeContext);

  return {
    tenantCode: userContext.tenantCode || DEFAULT_TENANT_CODE,
    userCode: claims['custom:userCode'] || userContext.userId || '',
    userId: userContext.userId || '',
    email: claims.email,
    role: claims['custom:role'],
  };
}

/**
 * Tenant code for shared/common data across all tenants
 * Use this for master data, settings, and resources shared by all tenants
 */
export const TENANT_COMMON = 'common';

/**
 * Default tenant code when no tenant is specified
 * Used in single-tenant mode or when tenant context is not available
 */
export const DEFAULT_TENANT_CODE = 'single';
```

:::info Consistent Tenant Code in Master and Tenant Modules
The `@mbc-cqrs-serverless/master` and `@mbc-cqrs-serverless/tenant` packages use `SettingTypeEnum.TENANT_COMMON = 'common'` (lowercase), consistent with `getUserContext()` normalization.

When using built-in methods (e.g., `createCommonTenantSetting`, `createCommonTenant`), data is stored under the `'common'` tenant code, which can be queried using the normalized lowercase tenant code.

```typescript
// In @mbc-cqrs-serverless/master and @mbc-cqrs-serverless/tenant
export enum SettingTypeEnum {
  TENANT_COMMON = 'common',  // Common tenant code (lowercase)
}
```
:::

```typescript

/**
 * Check if user has access to tenant
 */
export function hasTenantAccess(
  userContext: CustomUserContext,
  targetTenantCode: string,
): boolean {
  // System admin can access all tenants
  if (userContext.role === 'SYSTEM_ADMIN') {
    return true;
  }

  // User can only access their own tenant
  return userContext.tenantCode === targetTenantCode;
}
```

### Tenant Guard

Implement a guard to enforce tenant access:

```typescript
// guards/tenant.guard.ts
import {
  Injectable,
  CanActivate,
  ExecutionContext,
  ForbiddenException,
} from '@nestjs/common';
import { getCustomUserContext, hasTenantAccess } from '../helpers/context';

@Injectable()
export class TenantGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    const request = context.switchToHttp().getRequest();
    const invokeContext = request.invokeContext;
    const userContext = getCustomUserContext(invokeContext);

    // Get target tenant from path or body
    const targetTenant = request.params.tenantCode ||
                        request.body?.tenantCode ||
                        this.extractTenantFromPk(request.body?.pk);

    if (!targetTenant) {
      return true; // No tenant specified, will use user's tenant
    }

    if (!hasTenantAccess(userContext, targetTenant)) {
      throw new ForbiddenException(
        `Access denied to tenant: ${targetTenant}`,
      );
    }

    return true;
  }

  private extractTenantFromPk(pk: string | undefined): string | undefined {
    if (!pk) return undefined;
    const parts = pk.split('#');
    return parts.length >= 2 ? parts[1] : undefined;
  }
}
```

## Data Isolation Patterns {#data-isolation}

### Pattern 1: Tenant in Partition Key

Include tenant code in the partition key for complete isolation:

```typescript
// Standard tenant isolation pattern

const PRODUCT_PK_PREFIX = 'PRODUCT';

function generateProductPk(tenantCode: string): string {
  return `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;
}

// Example keys:
// PK: PRODUCT#tenant-a
// SK: 01HX7MBJK3V9WQBZ7XNDK5ZT2M

// Query all products for a tenant
async function listProductsByTenant(tenantCode: string) {
  const pk = generateProductPk(tenantCode);
  return dataService.listItemsByPk(pk);
}
```

### Pattern 2: Common Tenant for Shared Data

Use a common tenant code for data shared across all tenants:

```typescript
// Shared data pattern for master data and configurations

const COMMON_TENANT = 'common';

// System-wide settings
const settingsPk = `SETTINGS${KEY_SEPARATOR}${COMMON_TENANT}`;

// User data (users can belong to multiple tenants)
const userPk = `USER${KEY_SEPARATOR}${COMMON_TENANT}`;

// Example: Get system-wide email templates
async function getEmailTemplates() {
  return dataService.listItemsByPk(`TEMPLATE${KEY_SEPARATOR}${COMMON_TENANT}`);
}
```

### Pattern 3: User-Tenant Association

Handle users belonging to multiple tenants:

```typescript
// user/dto/user-tenant.dto.ts
export interface UserTenantAssociation {
  pk: string;           // USER_TENANT#common
  sk: string;           // {tenantCode}#{userCode}
  tenantCode: string;   // Owner tenant (COMMON_TENANT)
  attributes: {
    userCode: string;
    tenantCode: string; // Associated tenant code
    role: string;       // Role within this tenant
    isDefault: boolean; // Default tenant for user
  };
}

// user/user.service.ts
import { Injectable, ForbiddenException } from '@nestjs/common';
import { CommandService, DataService, IInvoke, KEY_SEPARATOR, generateId, VERSION_FIRST } from '@mbc-cqrs-serverless/core';
import { AuthService } from '../auth/auth.service';
import { UserTenantAssociation } from './dto/user-tenant.dto';

const COMMON_TENANT = 'common';

@Injectable()
export class UserService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly authService: AuthService,
  ) {}

  /**
   * Get all tenants a user belongs to
   */
  async getUserTenants(userCode: string): Promise<UserTenantAssociation[]> {
    const pk = `USER_TENANT${KEY_SEPARATOR}${COMMON_TENANT}`;

    // List all items under the PK, then filter by user code
    const result = await this.dataService.listItemsByPk(pk);

    return result.items.filter(item =>
      item.sk.endsWith(`${KEY_SEPARATOR}${userCode}`),
    );
  }

  /**
   * Add user to tenant
   */
  async addUserToTenant(
    userCode: string,
    tenantCode: string,
    role: string,
    invokeContext: IInvoke,
  ): Promise<void> {
    const pk = `USER_TENANT${KEY_SEPARATOR}${COMMON_TENANT}`;
    const sk = `${tenantCode}${KEY_SEPARATOR}${userCode}`;

    await this.commandService.publishSync({
      pk,
      sk,
      id: generateId(pk, sk),
      tenantCode: COMMON_TENANT,
      code: `${tenantCode}-${userCode}`,
      name: `User ${userCode} in ${tenantCode}`,
      type: 'USER_TENANT',
      version: VERSION_FIRST,
      attributes: {
        userCode,
        tenantCode,
        role,
        isDefault: false,
      },
    }, { invokeContext });
  }

  /**
   * Switch user's active tenant
   */
  async switchTenant(
    userCode: string,
    newTenantCode: string,
    invokeContext: IInvoke,
  ): Promise<{ token: string }> {
    // Verify user belongs to tenant
    const associations = await this.getUserTenants(userCode);
    const association = associations.find(a =>
      a.attributes.tenantCode === newTenantCode,
    );

    if (!association) {
      throw new ForbiddenException(
        `User does not belong to tenant: ${newTenantCode}`,
      );
    }

    // Generate new token with updated tenant context
    return this.authService.generateToken({
      userCode,
      tenantCode: newTenantCode,
      role: association.attributes.role,
    });
  }
}
```

## Cross-Tenant Operations {#cross-tenant-operations}

### Pattern 1: Data Sync Between Tenants

Sync data from one tenant to another (e.g., master data distribution):

```typescript
// sync/tenant-sync.service.ts
import { Injectable, Logger } from '@nestjs/common';
import { CommandService, DataService, IInvoke, KEY_SEPARATOR, generateId, VERSION_FIRST } from '@mbc-cqrs-serverless/core';

@Injectable()
export class TenantSyncService {
  private readonly logger = new Logger(TenantSyncService.name);

  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
  ) {}

  /**
   * Sync master data from source to target tenants
   */
  async syncMasterData(
    sourceTenantCode: string,
    targetTenantCodes: string[],
    entityType: string,
    invokeContext: IInvoke,
  ): Promise<{ synced: number; errors: string[] }> {
    const sourcePk = `${entityType}${KEY_SEPARATOR}${sourceTenantCode}`;
    const sourceData = await this.dataService.listItemsByPk(sourcePk);

    let synced = 0;
    const errors: string[] = [];

    for (const targetTenant of targetTenantCodes) {
      for (const item of sourceData.items) {
        try {
          await this.syncItem(item, targetTenant, invokeContext);
          synced++;
        } catch (error) {
          errors.push(`Failed to sync ${item.id} to ${targetTenant}: ${error.message}`);
        }
      }
    }

    this.logger.log(`Synced ${synced} items to ${targetTenantCodes.length} tenants`);
    return { synced, errors };
  }

  private async syncItem(
    sourceItem: any,
    targetTenantCode: string,
    invokeContext: IInvoke,
  ): Promise<void> {
    // Create new keys for target tenant
    const pkParts = sourceItem.pk.split(KEY_SEPARATOR);
    const entityType = pkParts[0];
    const targetPk = `${entityType}${KEY_SEPARATOR}${targetTenantCode}`;
    const targetId = generateId(targetPk, sourceItem.sk);

    await this.commandService.publishSync({
      pk: targetPk,
      sk: sourceItem.sk,
      id: targetId,
      tenantCode: targetTenantCode,
      code: sourceItem.code,
      name: sourceItem.name,
      type: sourceItem.type,
      version: VERSION_FIRST,
      attributes: {
        ...sourceItem.attributes,
        // Mark as synced from source
        syncedFrom: sourceItem.id,
      },
    }, { invokeContext });
  }
}
```

### Pattern 2: Cross-Tenant Reporting

Aggregate data across tenants for reporting:

```typescript
// reporting/cross-tenant-report.service.ts
import { Injectable } from '@nestjs/common';
import { PrismaService } from 'src/prisma';

interface SystemMetrics {
  totalProducts: number;
  productsByTenant: Array<{ tenantCode: string; count: number }>;
  recentOrdersCount: number;
}

interface TenantMetrics {
  tenantCode: string;
  products: number;
  orders: number;
  users: number;
}

@Injectable()
export class CrossTenantReportService {
  constructor(private readonly prismaService: PrismaService) {}

  /**
   * Get aggregated metrics across all tenants
   */
  async getSystemMetrics(): Promise<SystemMetrics> {
    const [totalProducts, productsByTenant, recentOrders] = await Promise.all([
      // Total count across all tenants
      this.prismaService.product.count({
        where: { isDeleted: false },
      }),

      // Count by tenant
      this.prismaService.product.groupBy({
        by: ['tenantCode'],
        _count: { id: true },
        where: { isDeleted: false },
      }),

      // Recent orders across all tenants (admin only)
      this.prismaService.order.findMany({
        where: { isDeleted: false },
        orderBy: { createdAt: 'desc' },
        take: 100,
      }),
    ]);

    return {
      totalProducts,
      productsByTenant: productsByTenant.map(t => ({
        tenantCode: t.tenantCode,
        count: t._count.id,
      })),
      recentOrdersCount: recentOrders.length,
    };
  }

  /**
   * Get tenant-specific metrics
   */
  async getTenantMetrics(tenantCode: string): Promise<TenantMetrics> {
    const [products, orders, users] = await Promise.all([
      this.prismaService.product.count({
        where: { tenantCode, isDeleted: false },
      }),
      this.prismaService.order.count({
        where: { tenantCode, isDeleted: false },
      }),
      this.prismaService.user.count({
        where: { tenantCode, isDeleted: false },
      }),
    ]);

    return { tenantCode, products, orders, users };
  }
}
```

## Tenant Configuration {#tenant-configuration}

### Tenant Settings Pattern

```typescript
// tenant/tenant-settings.service.ts
import { Injectable } from '@nestjs/common';
import { CommandService, DataService, IInvoke, KEY_SEPARATOR, generateId, VERSION_FIRST } from '@mbc-cqrs-serverless/core';

@Injectable()
export class TenantSettingsService {
  private readonly settingsCache = new Map<string, TenantSettings>();

  constructor(
    private readonly dataService: DataService,
    private readonly commandService: CommandService,
  ) {}

  /**
   * Get tenant settings with caching
   */
  async getSettings(tenantCode: string): Promise<TenantSettings> {
    // Check cache first
    if (this.settingsCache.has(tenantCode)) {
      return this.settingsCache.get(tenantCode)!;
    }

    const pk = `SETTINGS${KEY_SEPARATOR}${tenantCode}`;
    const sk = 'config';

    try {
      const settings = await this.dataService.getItem({ pk, sk });
      this.settingsCache.set(tenantCode, settings.attributes);
      return settings.attributes;
    } catch (error) {
      // Return default settings if not found
      return this.getDefaultSettings();
    }
  }

  /**
   * Update tenant settings
   */
  async updateSettings(
    tenantCode: string,
    settings: Partial<TenantSettings>,
    invokeContext: IInvoke,
  ): Promise<TenantSettings> {
    const currentSettings = await this.getSettings(tenantCode);
    const mergedSettings = { ...currentSettings, ...settings };

    const pk = `SETTINGS${KEY_SEPARATOR}${tenantCode}`;
    const sk = 'config';

    await this.commandService.publishSync({
      pk,
      sk,
      id: generateId(pk, sk),
      tenantCode,
      code: 'config',
      name: 'Tenant Configuration',
      type: 'SETTINGS',
      version: VERSION_FIRST,
      attributes: mergedSettings,
    }, { invokeContext });

    // Invalidate cache
    this.settingsCache.delete(tenantCode);

    return mergedSettings;
  }

  private getDefaultSettings(): TenantSettings {
    return {
      timezone: 'Asia/Tokyo',
      locale: 'ja',
      dateFormat: 'YYYY-MM-DD',
      currency: 'JPY',
      features: {
        exportEnabled: true,
        importEnabled: true,
        apiEnabled: true,
      },
    };
  }
}

export interface TenantSettings {
  timezone: string;
  locale: string;
  dateFormat: string;
  currency: string;
  features: {
    exportEnabled: boolean;
    importEnabled: boolean;
    apiEnabled: boolean;
  };
}
```

## Prisma Multi-Tenant Schema {#prisma-multi-tenant}

### RDS Schema for Multi-Tenant

```prisma
// prisma/schema.prisma

// Base fields for all entities
model Product {
  id         String   @id
  pk         String
  sk         String
  tenantCode String   // Tenant isolation field

  code       String
  name       String
  attributes Json?

  version    Int
  isDeleted  Boolean  @default(false)
  createdAt  DateTime
  createdBy  String   @default("")
  updatedAt  DateTime
  updatedBy  String   @default("")

  // Unique constraint includes tenant
  @@unique([tenantCode, code])
  @@unique([pk, sk])

  // Index for tenant queries
  @@index([tenantCode])
  @@index([tenantCode, name])
  @@index([tenantCode, createdAt])
}

// User-Tenant association
model UserTenant {
  id         String   @id
  pk         String
  sk         String

  userCode   String
  tenantCode String
  role       String
  isDefault  Boolean  @default(false)

  createdAt  DateTime
  updatedAt  DateTime

  @@unique([userCode, tenantCode])
  @@index([userCode])
  @@index([tenantCode])
}

// Tenant settings
model TenantSettings {
  id         String   @id
  tenantCode String   @unique
  settings   Json

  createdAt  DateTime
  updatedAt  DateTime
}
```

## Best Practices {#best-practices}

### 1. Always Include Tenant in Queries

```typescript
// Good: Tenant-scoped query
const products = await prismaService.product.findMany({
  where: {
    tenantCode,
    isDeleted: false,
  },
});

// Bad: Missing tenant scope (data leak risk)
const products = await prismaService.product.findMany({
  where: { isDeleted: false },
});
```

### 2. Validate Tenant Access

```typescript
// Always verify tenant access before operations
async updateProduct(
  productId: string,
  updateDto: UpdateProductDto,
  invokeContext: IInvoke,
): Promise<ProductDataEntity> {
  const { tenantCode } = getCustomUserContext(invokeContext);

  // Verify product belongs to user's tenant
  const existing = await this.prismaService.product.findUnique({
    where: { id: productId },
  });

  if (existing?.tenantCode !== tenantCode) {
    throw new ForbiddenException('Access denied');
  }

  // Proceed with update
  return this.publishCommand(updateDto, invokeContext);
}
```

### 3. Tenant-Aware Logging

```typescript
// Include tenant in all logs for debugging
this.logger.log({
  message: 'Processing order',
  tenantCode,
  orderId,
  userId: userContext.userId,
});
```

### 4. Separate System and Tenant Operations

```typescript
// Use separate endpoints for system-wide vs tenant operations

@Controller('api/admin/tenants')
@UseGuards(SystemAdminGuard)
export class TenantAdminController {
  // System admin operations across tenants
}

@Controller('api/products')
@UseGuards(TenantGuard)
export class ProductController {
  // Tenant-scoped operations
}
```

## TenantModule API Reference {#tenant-module-api}

The `@mbc-cqrs-serverless/tenant` module provides ready-to-use tenant management functionality.

### Installation

```bash
npm install @mbc-cqrs-serverless/tenant
```

### Module Registration

```typescript
import { TenantModule } from '@mbc-cqrs-serverless/tenant';

@Module({
  imports: [
    TenantModule.register({
      enableController: true,
      dataSyncHandlers: [TenantRdsSyncHandler], // Optional: sync to external systems
    }),
  ],
})
export class AppModule {}
```

### Module Options

| Option | Type | Description |
|--------|------|-------------|
| `enableController` | `boolean` | Enable REST endpoints for tenant CRUD operations |
| `dataSyncHandlers` | `Type<IDataSyncHandler>[]` | Optional handlers to sync tenant data to external systems (e.g., RDS) |

### TenantService Methods

#### `getTenant(key: DetailKey): Promise<DataModel>`

Retrieves tenant details based on the given key.

```typescript
const tenant = await tenantService.getTenant({
  pk: 'TENANT#mbc',
  sk: 'MASTER',
});
```

#### `createCommonTenant(dto, context): Promise<CommandModel>`

Creates a common tenant that is shared across the entire system.

```typescript
const tenant = await tenantService.createCommonTenant({
  name: 'Common',
}, { invokeContext });
```

#### `createTenant(dto, context): Promise<CommandModel>`

Creates a tenant for an individual entity.

```typescript
const tenant = await tenantService.createTenant({
  name: 'MBC tenant',
  code: 'mbc',
}, { invokeContext });
```

#### `updateTenant(key, dto, context): Promise<CommandModel>`

Updates an existing tenant's details.

```typescript
const tenant = await tenantService.updateTenant(
  { pk: 'TENANT#mbc', sk: 'MASTER' },
  { name: 'Updated MBC tenant' },
  { invokeContext },
);
```

#### `deleteTenant(key, context): Promise<CommandModel>`

Deletes a tenant based on the provided key.

```typescript
await tenantService.deleteTenant(
  { pk: 'TENANT#mbc', sk: 'MASTER' },
  { invokeContext },
);
```

#### `addTenantGroup(dto, context): Promise<CommandModel>`

Adds a group to a specific tenant.

```typescript
await tenantService.addTenantGroup({
  tenantCode: 'abc',
  groupId: '19',
  role: 'company',
}, { invokeContext });
```

#### `createTenantGroup(tenantGroupCode, dto, context): Promise<CommandModel>`

Creates a tenant within a specific tenant group.

```typescript
await tenantService.createTenantGroup(
  'group-001',
  {
    code: 'mbc',
    name: 'MBC Tenant',
    description: 'Tenant in group-001',
  },
  { invokeContext },
);
```

#### `customizeSettingGroups(dto, context): Promise<CommandModel>`

Customizes the settings of groups associated with a tenant.

```typescript
await tenantService.customizeSettingGroups({
  tenantCode: 'mbc',
  settingGroups: ['19', '20'],
  role: 'company',
}, { invokeContext });
```

## Related Documentation

- [Backend Development Guide](/docs/backend-development) - Core patterns
- [Key Patterns](/docs/key-patterns) - PK/SK design for multi-tenant
- [Authentication](/docs/authentication) - User authentication
- [Authentication — Group-Based Roles](/docs/authentication#group-based-roles) - Group-based role authorization using `IGroupRoleResolver` (v1.3.1+)
- [Tenant Module](/docs/tenant) - TenantModule configuration and interfaces


---

## Service Implementation Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/service-patterns

# Service Implementation Patterns

This guide explains how to implement service classes that handle CRUD operations in MBC CQRS Serverless. Services are the core of your business logic, coordinating between controllers, commands, and data access.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Build a service layer for a new domain entity
- Implement create, read, update, delete (CRUD) operations
- Handle multi-tenant data isolation
- Use optimistic locking for concurrent updates
- Implement batch operations for bulk data processing

## Problems This Pattern Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| Direct database access bypasses CQRS pattern | Use CommandService for writes, DataService for reads |
| No audit trail for data changes | Pass invokeContext to capture user and timestamp |
| Concurrent updates overwrite each other | Use version field for optimistic locking |
| Slow responses due to synchronous processing | Use publishAsync for non-blocking command publishing |

## Basic Service Structure {#basic-structure}

A typical service uses both `CommandService` for write operations and `DataService` for read operations:

```ts
import {
  CommandService,
  DataService,
  generateId,
  getUserContext,
  IInvoke,
  VERSION_FIRST,
  KEY_SEPARATOR,
} from "@mbc-cqrs-serverless/core";
import { Injectable } from "@nestjs/common";
import { ulid } from "ulid";

import { PrismaService } from "src/prisma";
import { ProductCommandDto } from "./dto/product-command.dto";
import { ProductDataEntity } from "./entity/product-data.entity";
import { CreateProductDto } from "./dto/create-product.dto";
import { UpdateProductDto } from "./dto/update-product.dto";

const PRODUCT_PK_PREFIX = "PRODUCT";

@Injectable()
export class ProductService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly prismaService: PrismaService,
  ) {}

  // CRUD methods will be implemented below
}
```

## Create Operation {#create-operation}

### Use Case: Create a New Product

Scenario: User submits a form to add a new product to the catalog.

Flow: Controller receives CreateProductDto → Service generates keys → Command published to DynamoDB → Data synced to RDS.

```ts
async create(
  createDto: CreateProductDto,
  opts: { invokeContext: IInvoke },
): Promise<ProductDataEntity | null> {
  // Get tenant context from the invoke context
  const { tenantCode } = getUserContext(opts.invokeContext);

  // Generate PK and SK
  const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;
  const sk = ulid(); // Use ULID for sortable unique ID
  const id = generateId(pk, sk);

  // Create command DTO
  const command = new ProductCommandDto({
    pk,
    sk,
    id,
    tenantCode,
    code: sk,
    type: "PRODUCT",
    name: createDto.name,
    version: VERSION_FIRST,
    attributes: {
      description: createDto.description,
      price: createDto.price,
      category: createDto.category,
      inStock: createDto.inStock ?? true,
    },
  });

  // Publish command (async - returns immediately)
  const item = await this.commandService.publishAsync(command, {
    invokeContext: opts.invokeContext,
  });

  // publishAsync returns null when command is a no-op (no changes detected)
  if (!item) return null;
  return new ProductDataEntity(item);
}
```

## Read Operations {#read-operations}

### Find One by Key

#### Use Case: Get Product Detail Page

Scenario: User navigates to a product detail page and needs the full product data.

When to use: Single-item lookup where you have the pk and sk.

```ts
async findOne(
  detailDto: { pk: string; sk: string },
): Promise<ProductDataEntity | undefined> {
  const item = await this.dataService.getItem(detailDto);
  if (!item) return undefined;
  return new ProductDataEntity(item);
}
```

### Find All with Pagination (from RDS)

#### Use Case: Product List with Filtering

Scenario: Display a paginated product list that users can filter by category or search.

Why RDS: DynamoDB is not optimized for complex queries. Use Prisma/RDS for filtering and full-text search.

```ts
async findAll(
  searchDto: {
    tenantCode: string;
    category?: string;
    inStock?: boolean;
    page?: number;
    limit?: number;
  },
): Promise<{ items: ProductDataEntity[]; total: number }> {
  const page = searchDto.page ?? 1;
  const limit = searchDto.limit ?? 20;
  const skip = (page - 1) * limit;

  // Build where clause
  const where: any = {
    tenantCode: searchDto.tenantCode,
    isDeleted: false,
  };

  if (searchDto.category) {
    where.category = searchDto.category;
  }

  if (searchDto.inStock !== undefined) {
    where.inStock = searchDto.inStock;
  }

  // Execute parallel queries for count and data
  const [total, items] = await Promise.all([
    this.prismaService.product.count({ where }),
    this.prismaService.product.findMany({
      where,
      take: limit,
      skip,
      orderBy: { createdAt: "desc" },
    }),
  ]);

  return {
    total,
    items: items.map((item) => new ProductDataEntity(item)),
  };
}
```

## Update Operation {#update-operation}

### Use Case: Edit Product Details

Scenario: User updates product name or price through an edit form.

Important: Include the version field to enable optimistic locking and prevent concurrent update conflicts.

```ts
import {
  CommandPartialInputModel,
  CommandService,
  DataService,
  IInvoke,
} from "@mbc-cqrs-serverless/core";
import { NotFoundException } from "@nestjs/common";

async update(
  detailDto: { pk: string; sk: string },
  updateDto: UpdateProductDto,
  opts: { invokeContext: IInvoke },
): Promise<ProductDataEntity | null> {
  // First, get the existing item
  const existing = await this.dataService.getItem(detailDto);

  if (!existing) {
    throw new NotFoundException("Product not found");
  }

  // Merge existing attributes with updates
  const updatedAttributes = {
    ...existing.attributes,
    ...updateDto.attributes,
  };

  // Create partial update command
  const command: CommandPartialInputModel = {
    pk: existing.pk,
    sk: existing.sk,
    version: existing.version, // Required for optimistic locking
    name: updateDto.name ?? existing.name,
    attributes: updatedAttributes,
  };

  // Publish partial update
  const item = await this.commandService.publishPartialUpdateAsync(command, {
    invokeContext: opts.invokeContext,
  });

  if (!item) return null;
  return new ProductDataEntity(item);
}
```

:::info Version Parameter Behavior
The `version` field in `publishPartialUpdateAsync()` controls how the existing item is retrieved:

- **`version > 0`**: Uses the specified version number. The command will fail if the version doesn't match (optimistic locking).
- **`version <= 0`** (e.g., `VERSION_LATEST = -1`): Automatically retrieves the latest version using `getLatestItem()`.

Use `existing.version` (as shown above) for strict optimistic locking. Use `VERSION_LATEST` (-1) when you want to always update the latest version regardless of what version you have cached.
:::

## Delete Operation (Soft Delete) {#delete-operation}

### Use Case: Remove Product from Catalog

Scenario: Admin removes a discontinued product.

Why Soft Delete: Data is marked as deleted (isDeleted=true) rather than physically removed, preserving audit history.

```ts
import {
  CommandPartialInputModel,
  CommandService,
  DataService,
  IInvoke,
} from "@mbc-cqrs-serverless/core";
import { NotFoundException } from "@nestjs/common";

async remove(
  detailDto: { pk: string; sk: string },
  opts: { invokeContext: IInvoke },
): Promise<ProductDataEntity | null> {
  // Get existing item
  const existing = await this.dataService.getItem(detailDto);

  if (!existing) {
    throw new NotFoundException("Product not found");
  }

  // Create soft delete command
  const command: CommandPartialInputModel = {
    pk: existing.pk,
    sk: existing.sk,
    version: existing.version,
    isDeleted: true,
  };

  const item = await this.commandService.publishPartialUpdateAsync(command, {
    invokeContext: opts.invokeContext,
  });

  if (!item) return null;
  return new ProductDataEntity(item);
}
```

## Complete Service Example {#complete-example}

Here is a complete service implementation:

```ts
import {
  CommandPartialInputModel,
  CommandService,
  DataService,
  generateId,
  getUserContext,
  VERSION_FIRST,
  KEY_SEPARATOR,
  IInvoke,
} from "@mbc-cqrs-serverless/core";
import { Injectable, NotFoundException } from "@nestjs/common";
import { ulid } from "ulid";

import { PrismaService } from "src/prisma";
import { ProductCommandDto } from "./dto/product-command.dto";
import { ProductDataEntity } from "./entity/product-data.entity";
import { ProductListEntity } from "./entity/product-list.entity";
import { CreateProductDto } from "./dto/create-product.dto";
import { UpdateProductDto } from "./dto/update-product.dto";
import { SearchProductDto } from "./dto/search-product.dto";
import { DetailDto } from "./dto/detail.dto";

const PRODUCT_PK_PREFIX = "PRODUCT";

@Injectable()
export class ProductService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly prismaService: PrismaService,
  ) {}

  /**
   * Create a new product
   */
  async create(
    createDto: CreateProductDto,
    opts: { invokeContext: IInvoke },
  ): Promise<ProductDataEntity | null> {
    const { tenantCode } = getUserContext(opts.invokeContext);

    const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;
    const sk = ulid();
    const id = generateId(pk, sk);

    const command = new ProductCommandDto({
      pk,
      sk,
      id,
      tenantCode,
      code: sk,
      type: "PRODUCT",
      name: createDto.name,
      version: VERSION_FIRST,
      attributes: {
        description: createDto.description,
        price: createDto.price,
        category: createDto.category,
        inStock: createDto.inStock ?? true,
      },
    });

    const item = await this.commandService.publishAsync(command, {
      invokeContext: opts.invokeContext,
    });

    // publishAsync returns null when the command is not dirty (no-op)
    return item ? new ProductDataEntity(item) : null;
  }

  /**
   * Find all products with filtering and pagination
   */
  async findAll(searchDto: SearchProductDto): Promise<ProductListEntity> {
    const page = searchDto.page ?? 1;
    const limit = searchDto.limit ?? 20;
    const skip = (page - 1) * limit;

    const where: any = {
      tenantCode: searchDto.tenantCode,
      isDeleted: false,
    };

    if (searchDto.category) {
      where.category = searchDto.category;
    }

    if (searchDto.inStock !== undefined) {
      where.inStock = searchDto.inStock;
    }

    if (searchDto.search) {
      where.OR = [
        { name: { contains: searchDto.search}},
        { description: { contains: searchDto.search}},
      ];
    }

    const [total, items] = await Promise.all([
      this.prismaService.product.count({ where }),
      this.prismaService.product.findMany({
        where,
        take: limit,
        skip,
        orderBy: { createdAt: "desc" },
      }),
    ]);

    return new ProductListEntity({
      total,
      items: items.map((item) => new ProductDataEntity(item)),
    });
  }

  /**
   * Find one product by key
   */
  async findOne(detailDto: DetailDto): Promise<ProductDataEntity> {
    const item = await this.dataService.getItem(detailDto);

    if (!item) {
      throw new NotFoundException("Product not found");
    }

    return new ProductDataEntity(item);
  }

  /**
   * Update a product
   */
  async update(
    detailDto: DetailDto,
    updateDto: UpdateProductDto,
    opts: { invokeContext: IInvoke },
  ): Promise<ProductDataEntity | null> {
    const existing = await this.dataService.getItem(detailDto);

    if (!existing) {
      throw new NotFoundException("Product not found");
    }

    const command: CommandPartialInputModel = {
      pk: existing.pk,
      sk: existing.sk,
      version: existing.version,
      name: updateDto.name ?? existing.name,
      attributes: {
        ...existing.attributes,
        ...updateDto.attributes,
      },
    };

    const item = await this.commandService.publishPartialUpdateAsync(command, {
      invokeContext: opts.invokeContext,
    });

    // publishPartialUpdateAsync returns null when command is a no-op (no changes detected)
    if (!item) return null;
    return new ProductDataEntity(item);
  }

  /**
   * Soft delete a product
   */
  async remove(
    detailDto: DetailDto,
    opts: { invokeContext: IInvoke },
  ): Promise<ProductDataEntity | null> {
    const existing = await this.dataService.getItem(detailDto);

    if (!existing) {
      throw new NotFoundException("Product not found");
    }

    const command: CommandPartialInputModel = {
      pk: existing.pk,
      sk: existing.sk,
      version: existing.version,
      isDeleted: true,
    };

    const item = await this.commandService.publishPartialUpdateAsync(command, {
      invokeContext: opts.invokeContext,
    });

    // publishPartialUpdateAsync returns null when command is a no-op (no changes detected)
    if (!item) return null;
    return new ProductDataEntity(item);
  }
}
```

## Batch Operations {#batch-operations}

### Use Case: Import Multiple Products

Scenario: Admin uploads a CSV file containing multiple products to import.

Solution: Process items in parallel using Promise.all for better performance.

```ts
async createBatch(
  items: CreateProductDto[],
  opts: { invokeContext: IInvoke },
): Promise<ProductDataEntity[]> {
  const { tenantCode } = getUserContext(opts.invokeContext);
  const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;

  // Create all commands
  const commands = items.map((item) => {
    const sk = ulid();
    return new ProductCommandDto({
      pk,
      sk,
      id: generateId(pk, sk),
      tenantCode,
      code: sk,
      type: "PRODUCT",
      name: item.name,
      version: VERSION_FIRST,
      attributes: {
        description: item.description,
        price: item.price,
        category: item.category,
        inStock: item.inStock ?? true,
      },
    });
  });

  // Publish all commands in parallel
  const results = await Promise.all(
    commands.map((command) =>
      this.commandService.publishAsync(command, {
        invokeContext: opts.invokeContext,
      }),
    ),
  );

  // Filter out null results (no-op commands) before mapping to entities
  return results.filter(Boolean).map((item) => new ProductDataEntity(item!));
}
```

## Chunked Batch Operations {#chunked-batch-operations}

### Use Case: Large Data Migration

Scenario: Migrating thousands of records from a legacy system.

Problem: Processing all at once may cause Lambda timeout or memory issues.

Solution: Process in chunks of 100 items to stay within Lambda limits.

```ts
async createLargeBatch(
  items: CreateProductDto[],
  opts: { invokeContext: IInvoke },
): Promise<ProductDataEntity[]> {
  const { tenantCode } = getUserContext(opts.invokeContext);
  const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${tenantCode}`;

  const chunkSize = 100;
  const results: ProductDataEntity[] = [];

  for (let i = 0; i < items.length; i += chunkSize) {
    const chunk = items.slice(i, i + chunkSize);

    const commands = chunk.map((item) => {
      const sk = ulid();
      return new ProductCommandDto({
        pk,
        sk,
        id: generateId(pk, sk),
        tenantCode,
        code: sk,
        type: "PRODUCT",
        name: item.name,
        version: VERSION_FIRST,
        attributes: item,
      });
    });

    const chunkResults = await Promise.all(
      commands.map((command) =>
        this.commandService.publishAsync(command, {
          invokeContext: opts.invokeContext,
        }),
      ),
    );

    results.push(...chunkResults.filter(Boolean).map((item) => new ProductDataEntity(item!)));
  }

  return results;
}
```

## Copy Operation {#copy-operation}

### Use Case: Clone Product to Different Tenant

Scenario: Multi-tenant SaaS where a template product needs to be copied to a new tenant.

Solution: Read source entity and create new entity with different tenant's keys.

```ts
import {
  CommandService,
  DataService,
  generateId,
  IInvoke,
  KEY_SEPARATOR,
  VERSION_FIRST,
} from "@mbc-cqrs-serverless/core";
import { NotFoundException } from "@nestjs/common";
import { ulid } from "ulid";

async copy(
  sourceKey: { pk: string; sk: string },
  targetTenantCode: string,
  opts: { invokeContext: IInvoke },
): Promise<ProductDataEntity> {
  // Get source item
  const source = await this.dataService.getItem(sourceKey);

  if (!source) {
    throw new NotFoundException("Source product not found");
  }

  // Create new keys for target tenant
  const pk = `${PRODUCT_PK_PREFIX}${KEY_SEPARATOR}${targetTenantCode}`;
  const sk = ulid();
  const id = generateId(pk, sk);

  // Create command with source data
  const command = new ProductCommandDto({
    pk,
    sk,
    id,
    tenantCode: targetTenantCode,
    code: sk,
    type: source.type,
    name: source.name,
    version: VERSION_FIRST,
    attributes: source.attributes,
  });

  const item = await this.commandService.publishAsync(command, {
    invokeContext: opts.invokeContext,
  });

  // New items with VERSION_FIRST always publish successfully — result is never null
  return new ProductDataEntity(item!);
}
```

## Using History Service {#history-service}

### Use Case: View Previous Versions of a Document

Scenario: Audit requirement to show what a document looked like at a specific version.

Solution: Use HistoryService to retrieve a specific version from the history table.

```ts
import {
  addSortKeyVersion,
  CommandService,
  DataService,
  HistoryService,
} from "@mbc-cqrs-serverless/core";
import { Injectable, NotFoundException } from "@nestjs/common";

import { PrismaService } from "src/prisma";
import { ProductDataEntity } from "./entity/product-data.entity";

@Injectable()
export class ProductService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly historyService: HistoryService,
    private readonly prismaService: PrismaService,
  ) {}

  async findByVersion(
    detailDto: { pk: string; sk: string },
    version: number,
  ): Promise<ProductDataEntity> {
    // Add version to SK
    const skWithVersion = addSortKeyVersion(detailDto.sk, version);

    // Try to get from history
    let item = await this.historyService.getItem({
      pk: detailDto.pk,
      sk: skWithVersion,
    });

    // Fallback to latest if not in history
    if (!item) {
      item = await this.dataService.getItem(detailDto);
    }

    if (!item) {
      throw new NotFoundException("Product not found");
    }

    return new ProductDataEntity(item);
  }
}
```

## Best Practices {#best-practices}

### 1. Always Use Invoke Context

Pass invoke context for audit trail:

```ts
await this.commandService.publishAsync(command, {
  invokeContext: opts.invokeContext,
});
```

### 2. Use Optimistic Locking

Include version in partial updates:

```ts
const command: CommandPartialInputModel = {
  pk: existing.pk,
  sk: existing.sk,
  version: existing.version, // This enables optimistic locking
  // ...
};
```

### 3. Prefer Async Operations

Use async methods for better responsiveness:

```ts
// Recommended: Returns immediately
await this.commandService.publishAsync(command, opts);

// Use only when you need to wait for processing
await this.commandService.publishSync(command, opts);
```

### 4. Combine DynamoDB and RDS Queries

Use DynamoDB for single-item reads, RDS for complex queries:

```ts
// Single item: Use DataService (DynamoDB)
const item = await this.dataService.getItem({ pk, sk });

// Complex query: Use Prisma (RDS)
const items = await this.prismaService.product.findMany({
  where: { category: "electronics", inStock: true },
  orderBy: { price: "asc" },
});
```


## Related Documentation

- [Backend Development](/docs/backend-development) - Core backend patterns
- [Controllers](/docs/controllers) - Controller layer that delegates to services
- [Command Service](/docs/command-service) - CommandService API reference
- [Data Service](/docs/data-service) - DataService query methods
- [Anti-Patterns](/docs/anti-patterns) - Patterns to avoid in service layer
- [Prisma](/docs/prisma) - ORM setup for RDS data sync
- [Database Selection Guide](/docs/database-selection-guide) - DynamoDB vs RDS
- [Version Conflict Guide](/docs/version-conflict-guide) - Handling HTTP 409 optimistic locking conflicts
- [API Integration Guide](/docs/api-integration-guide) - Calling external APIs and handling webhooks


---

# Modules

## API Reference

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/api-reference

# API Reference

The MBC CQRS Serverless framework provides a comprehensive set of modules for building enterprise-grade serverless applications. Each module is designed to handle specific concerns while maintaining consistency with the CQRS and Event Sourcing patterns.

## Module Overview {#module-overview}

```mermaid
graph TB
    subgraph "Core Modules"
        A["CommandModule"]
        B["SequencesModule"]
        C["TenantModule"]
    end

    subgraph "Feature Modules"
        D["TaskModule"]
        E["MasterModule"]
        F["ImportModule"]
        G["DirectoryStorageModule"]
        H["SurveyTemplateModule"]
    end

    subgraph "Support Modules"
        I["NotificationModule"]
        J["SettingModule"]
    end

    A --> B
    A --> C
    C --> D
    C --> E
    C --> F
    D --> I
```

## Core Modules {#core-modules}

| Module | Package | Description |
|------------|-------------|-----------------|
| Command Module | `@mbc-cqrs-serverless/core` | CQRS command handling, data synchronization, Event Sourcing |
| Sequence Module | `@mbc-cqrs-serverless/sequence` | Thread-safe sequential ID generation |
| Tenant Module | `@mbc-cqrs-serverless/tenant` | Multi-tenant data isolation and management |

## Feature Modules {#feature-modules}

| Module | Package | Description |
|------------|-------------|-----------------|
| Task Module | `@mbc-cqrs-serverless/task` | Async task execution with Step Functions |
| Master Module | `@mbc-cqrs-serverless/master` | Master data and settings management |
| Import Module | `@mbc-cqrs-serverless/import` | Large-scale CSV import with Distributed Map |
| Directory Module | `@mbc-cqrs-serverless/directory` | S3-backed file and folder management |
| Survey Template Module | `@mbc-cqrs-serverless/survey-template` | Survey template management |

## Support Modules {#support-modules}

| Module | Package | Description |
|------------|-------------|-----------------|
| Queue Module | `@mbc-cqrs-serverless/core` | SNS and SQS messaging (globally registered) |
| Notification Module | `@mbc-cqrs-serverless/core` | Real-time notifications via AppSync (GraphQL subscriptions default; Events API opt-in since v1.3.0) |
| Email Service | `@mbc-cqrs-serverless/core` | Send transactional emails via Amazon SES |
| Setting Module | `@mbc-cqrs-serverless/ui-setting` | User interface configuration storage |

## Quick Start {#quick-start}

Install the core package:

```bash
npm install @mbc-cqrs-serverless/core
```

Register the CommandModule in your application:

```typescript
import { Module } from '@nestjs/common';
import { CommandModule } from '@mbc-cqrs-serverless/core';

@Module({
  imports: [
    CommandModule.register({
      tableName: 'your-table-name',
    }),
  ],
})
export class YourModule {}
```

## Common Patterns {#common-patterns}

### Service Injection

All services are available for injection in your NestJS providers:

```typescript
import { Injectable } from '@nestjs/common';
import { CommandService, DataService } from '@mbc-cqrs-serverless/core';

@Injectable()
export class YourService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
  ) {}
}
```

### Multi-Tenant Context

Most operations require tenant context for data isolation:

```typescript
async createItem(tenantCode: string, data: CreateDto, invokeContext: IInvoke) {
  return this.commandService.publishAsync({
    pk: `ITEM#${tenantCode}`,
    sk: data.id,
    tenantCode,
    // ... other fields
  }, { invokeContext });
}
```

## Module Documentation {#module-documentation}

Explore each module's detailed documentation:

```mdx-code-block
import DocCardList from '@theme/DocCardList';

<DocCardList />
```


## Related Documentation

- [Command Service](/docs/command-service) - CommandService detailed documentation
- [Data Service](/docs/data-service) - DataService query methods
- [Notification Module](/docs/notification-module) - AppSync real-time notification documentation
- [Email Service](/docs/email-service) - SES email sending documentation
- [Interfaces](/docs/interfaces) - TypeScript interfaces reference
- [Modules](/docs/modules) - Available modules


---

## CommandService

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/command-service

# CommandService

## Overview {#overview}

The `CommandService` is a core component of the framework that facilitates the management and synchronization of commands. It primarily provides methods for publishing both full commands and partial commands, allowing for their processing either synchronously or asynchronously, thereby enhancing the overall efficiency and flexibility of command handling within the system.

## CommandModule Configuration {#commandmodule-configuration}

![CommandModule structure](./images/CommandModule.png)

The `CommandModule` is a dynamic module used to register data sync handlers and provide services associated with a table name. When importing this module, you must provide a specific option for use.

### Register Options

| Property                  | Description                                                      |
| ----------------------------- | -------------------------------------------------------------------- |
| `tableName: string`           | Provide table name                                               |
| `skipError?: boolean`         | Reserved for future use. Not yet implemented.                    |
| `dataSyncHandlers?: Type<IDataSyncHandler>[]` | Register data sync handlers                         |
| `disableDefaultHandler?: boolean` | If set to `true`, disables the default DynamoDB data sync handler|

### Registration Example

```typescript
import { CommandModule } from '@mbc-cqrs-serverless/core';
import { Module } from '@nestjs/common';

@Module({
  imports: [
    CommandModule.register({
      tableName: 'cat',
      dataSyncHandlers: [CatDataSyncRdsHandler],
    }),
  ],
})
export class CatModule {}
```

Here, the `CommandModule` registers with the `cat` table name and provides the `CatDataSyncRdsHandler` to the data sync handlers.

## Using CommandService {#using-commandservice}

In the example for the method below, assume you import the `CommandModule` into your module as follows:

```ts
import { CommandModule } from "@mbc-cqrs-serverless/core";
import { Module } from "@nestjs/common";

import { CatDataSyncRdsHandler } from "./handler/cat-rds.handler";
import { CatController } from "./cat.controller";
import { CatService } from "./cat.service";

@Module({
  imports: [
    CommandModule.register({
      tableName: "cat",
      dataSyncHandlers: [CatDataSyncRdsHandler],
    }),
  ],
  controllers: [CatController],
  providers: [CatService],
})
export class CatModule {}
```

Then, the `CommandService` and `DataService` will be ready for injection into other services for your use.

:::tip For Implementation Patterns
For complete CRUD implementation patterns using CommandService, see [Service Patterns](/docs/service-patterns).
:::

## Methods {#methods}

### *async* `publishAsync(input: CommandInputModel, options: ICommandOptions): Promise<CommandModel | null>` {#publishasync}

Utilize this method to publish a full command, as it will insert the command data into the **command** table.

The method provides immediate feedback by returning the command data right away, allowing you to proceed without waiting for the command to be processed. Subsequently, the command is handled asynchronously in the background, ensuring that your application remains responsive while the processing occurs.

**Return Value:** Returns `Promise<CommandModel | null>` — the CommandModel on success, or `null` when the command is not dirty (no changes detected compared to the existing command).

For example, you can publish a new cat command as below:

```ts
import { basename } from 'path';
import {
  generateId,
  getCommandSource,
  VERSION_FIRST,
} from "@mbc-cqrs-serverless/core";

// class CatCommandDto extends CommandDto {}

const catCommand = new CatCommandDto({
  pk: catPk,
  sk: catSk,
  tenantCode,
  id: generateId(catPk, catSk),
  code,
  type: "CAT",
  name: attributes.name,
  version: VERSION_FIRST,
  attributes,
});

const commandSource = getCommandSource(
  basename(__dirname),
  this.constructor.name,
  "createCatCommand"
);

const item = await this.commandService.publishAsync(catCommand, {
  source: commandSource,
  invokeContext,
});
```

### *async* `publishPartialUpdateAsync( input: CommandPartialInputModel, options: ICommandOptions): Promise<CommandModel | null>` {#publishpartialupdateasync}

This method allows you to create new command data based on the previous command with the same `pk` and `sk` (primary key) values.

Like `publishAsync`, this method immediately returns the updated command data without waiting for the command to be processed.

**Return Value:** Returns `Promise<CommandModel | null>` — the CommandModel on success, or `null` when the command is not dirty (no changes detected compared to the existing partial command).

For example, you want to update cat's name:

```ts
import { basename } from 'path';
import { generateId, getCommandSource } from "@mbc-cqrs-serverless/core";

// ...

const catCommand: CommandPartialInputModel = {
  pk: catPk,
  sk: catSk,
  version: storedItem.version,
  name: attributes.name,
};

const commandSource = getCommandSource(
  basename(__dirname),
  this.constructor.name,
  "updateCatCommand"
);

const item = await this.commandService.publishPartialUpdateAsync(catCommand, {
  invokeContext,
});
```

### *async* `publishSync( input: CommandInputModel, options: ICommandOptions): Promise<CommandModel | null>` {#publishsync-audit-trail}

This method serves as a synchronous counterpart to the `publishAsync` method, meaning that it will halt the execution of the code until the command has been fully processed. This ensures that you receive the result of the command before proceeding with any further operations in your code.

:::danger Breaking Change (v1.2.0)
Since [v1.2.0](/docs/changelog#v120), `publishSync()` and `publishPartialUpdateSync()` return `null` when the command is not dirty (no-op). Always null-check the result before accessing properties:

```ts
const result = await this.commandService.publishSync(command, { invokeContext });
if (!result) return; // no-op: command was not dirty, nothing was written
console.log(result.pk); // safe after null check
```
:::

:::info Version Note (v1.1.4+)
Since [v1.1.4](/docs/changelog#v114), `publishSync` writes a full audit trail matching the async pipeline:
- An immutable event is written to the Command table with `syncMode: 'SYNC'` marker
- The History table is populated, providing complete Event Sourcing parity
- Command lifecycle: `publish_sync:STARTED` → `finish:FINISHED` (or `publish_sync:FAILED` on error)
- Returns `null` when the command is not dirty (no-op), matching `publishAsync` behavior
- DynamoDB Stream filter excludes `syncMode=SYNC` records to prevent Step Functions double-execution

Prior to v1.1.4, `publishSync` bypassed the Command table to avoid triggering Step Functions, resulting in a missing audit trail and no History table entries.
:::

:::warning Known Issue (Fixed in v1.3.2)
In versions prior to v1.3.2, `publishSync` had two bugs: the versioned `sk` was not assigned to `command.sk` before handler dispatch (causing `IDataSyncHandler.up()` to receive the wrong sort key), and errors from `updateStatus` were silently masked.

See also: [Changelog v1.3.2](/docs/changelog#v132)
:::

Returns `null` if no changes are detected (dirty check optimization).

For example:

```ts
import {
  generateId,
  getCommandSource,
  VERSION_FIRST,
} from "@mbc-cqrs-serverless/core";

// class CatCommandDto extends CommandDto {}

const catCommand = new CatCommandDto({
  pk: catPk,
  sk: catSk,
  tenantCode,
  id: generateId(catPk, catSk),
  code,
  type: "CAT",
  name: attributes.name,
  version: VERSION_FIRST,
  attributes,
});

const commandSource = getCommandSource(
  basename(__dirname),
  this.constructor.name,
  "createCatCommandSync"
);

const item = await this.commandService.publishSync(catCommand, {
  source: commandSource,
  invokeContext,
});
```

### *async* `publishPartialUpdateSync( input: CommandPartialInputModel, options: ICommandOptions): Promise<CommandModel | null>`

This method is a synchronous version of the `publishPartialUpdateAsync` method. It will block the execution of the code until the command is processed.

:::danger Breaking Change (v1.2.0)
Since [v1.2.0](/docs/changelog#v120), this method returns `null` when the command is not dirty (no-op). Always null-check the result. See [publishSync null return](/docs/command-service#publishsync-audit-trail) for details.
:::

:::warning Version Matching
This method requires the `version` field in the input to match the current version of the existing item. If the item is not found or the version does not match, a `BadRequestException` is thrown with the message "Invalid input: item not found or version mismatch" (prior to v1.0.25, the message was "The input is not a valid, item not found or version not match").
:::

For example, you want to update cat's name:

```ts
import { basename } from 'path';
import { generateId, getCommandSource } from "@mbc-cqrs-serverless/core";

// ...

const catCommand: CommandPartialInputModel = {
  pk: catPk,
  sk: catSk,
  version: storedItem.version,
  name: attributes.name,
};

const commandSource = getCommandSource(
  basename(__dirname),
  this.constructor.name,
  "updateCatCommandSync"
);

const item = await this.commandService.publishPartialUpdateSync(catCommand, {
  source: commandSource,
  invokeContext,
});
```

### *async* `publish(input: CommandInputModel, options: ICommandOptions): Promise<CommandModel | null>` <span class="badge badge--danger">removed</span>

:::danger Removed in v1.1.0

This method was removed in [v1.1.0](/docs/changelog#v110). Use [`publishAsync` method](#publishasync) instead.

:::

For example, you can publish a new cat command as below:

```ts
import { basename } from 'path';
import {
  generateId,
  getCommandSource,
  VERSION_FIRST,
} from "@mbc-cqrs-serverless/core";

// class CatCommandDto extends CommandDto {}

const catCommand = new CatCommandDto({
  pk: catPk,
  sk: catSk,
  tenantCode,
  id: generateId(catPk, catSk),
  code,
  type: "CAT",
  name: attributes.name,
  version: VERSION_FIRST,
  attributes,
});

const commandSource = getCommandSource(
  basename(__dirname),
  this.constructor.name,
  "createCatCommand"
);

const item = await this.commandService.publish(catCommand, {
  source: commandSource,
  invokeContext,
});
```

The method returns the command data.

### *async* `publishPartialUpdate( input: CommandPartialInputModel, options: ICommandOptions): Promise<CommandModel | null>` <span class="badge badge--danger">removed</span>

:::danger Removed in v1.1.0

This method was removed in [v1.1.0](/docs/changelog#v110). Use [`publishPartialUpdateAsync` method](#publishpartialupdateasync) instead.

:::

This method allows you to create new command data based on the previous command.

For example, you want to update cat's name:

```ts
import { basename } from 'path';
import { generateId, getCommandSource } from "@mbc-cqrs-serverless/core";

// ...

const catCommand: CommandPartialInputModel = {
  pk: catPk,
  sk: catSk,
  version: storedItem.version,
  name: attributes.name,
};

const commandSource = getCommandSource(
  basename(__dirname),
  this.constructor.name,
  "updateCatCommand"
);

const item = await this.commandService.publishPartialUpdate(catCommand, {
  source: commandSource,
  invokeContext,
});
```

The method returns the updated command data.

### *async* `reSyncData(): Promise<void>`

If you want to reapply the data sync handler, this method is designed for you to use. You only need to call the function as follows:

```ts
await this.commandService.reSyncData();
```

### *async* `getItem(key: DetailKey): Promise<CommandModel | null>`

Retrieves a command item by its primary key. If the sort key does not include the version separator (`@`, e.g. `CAT#cat001@2`), it automatically calls `getLatestItem` to get the latest version. Returns `null` when no matching item is found.

```ts
import { DetailKey } from "@mbc-cqrs-serverless/core";

// Get a specific version of a command
const command = await this.commandService.getItem({
  pk: "CAT#tenant1",
  sk: "CAT#cat001@2", // Includes version number
});

// If no version in sk, automatically gets latest version
const latestCommand = await this.commandService.getItem({
  pk: "CAT#tenant1",
  sk: "CAT#cat001",
});
```

### *async* `getLatestItem(key: DetailKey): Promise<CommandModel | null>`

Retrieves the latest version of a command item by its primary key. This method uses a lookup algorithm that starts from the data table's version and searches up/down to find the most recent command version. Returns `null` when no matching item is found.

```ts
import { DetailKey } from "@mbc-cqrs-serverless/core";

const latestCommand = await this.commandService.getLatestItem({
  pk: "CAT#tenant1",
  sk: "CAT#cat001", // Sort key without version
});

if (latestCommand) {
  console.log(`Latest version: ${latestCommand.version}`);
}
```

### *async* `getNextCommand(currentKey: DetailKey): Promise<CommandModel | undefined>`

Retrieves the next version of a command based on the current command's key. Returns `undefined` if the next version does not exist. This is useful for processing command chains or implementing retry logic.

```ts
import { DetailKey } from "@mbc-cqrs-serverless/core";

const currentKey: DetailKey = {
  pk: "CAT#tenant1",
  sk: "CAT#cat001@2",
};

const nextCommand = await this.commandService.getNextCommand(currentKey);
// Returns command with sk: "CAT#cat001@3" if it exists, otherwise undefined
if (nextCommand) {
  // Process the next command
}
```

### *async* `updateStatus(key: DetailKey, status: string, notifyId?: string): Promise<void>`

Updates the status of a command and sends an SNS notification. This is commonly used to update task or process statuses and notify subscribers of the change.

```ts
import { DetailKey } from "@mbc-cqrs-serverless/core";

const key: DetailKey = {
  pk: "CAT#tenant1",
  sk: "CAT#cat001@1",
};

// Update status and send SNS notification
await this.commandService.updateStatus(key, "COMPLETED");

// With custom notification ID
await this.commandService.updateStatus(key, "FAILED", "custom-notify-id");
```

The SNS notification payload includes:
- `action`: `"command-status"`
- `pk`, `sk`: The command key
- `table`: The command table name
- `id`: Notification ID (custom or auto-generated)
- `tenantCode`: Extracted from pk
- `content`: Object containing `status` and `source`

### *async* `duplicate(key: DetailKey, options: ICommandOptions): Promise<CommandModel>`

Creates a duplicate of an existing command with an incremented version number. The duplicated command will have `source` set to `"duplicated"` and updated metadata (timestamp, user, IP).

```ts
import { DetailKey, getCommandSource } from "@mbc-cqrs-serverless/core";
import { basename } from "path";

const key: DetailKey = {
  pk: "CAT#tenant1",
  sk: "CAT#cat001@1",
};

const commandSource = getCommandSource(
  basename(__dirname),
  this.constructor.name,
  "duplicateCatCommand"
);

const duplicatedCommand = await this.commandService.duplicate(key, {
  source: commandSource,
  invokeContext,
});

// The duplicated command has:
// - version incremented by 1
// - source set to "duplicated"
// - updated timestamps and user info
```

### *async* `updateTaskToken(key: DetailKey, token: string): Promise<CommandModel>` {#updatetasktoken}

Stores an AWS Step Functions task token on a command item. This is used when integrating with Step Functions to enable callback patterns.

```ts
import { DetailKey } from "@mbc-cqrs-serverless/core";

const key: DetailKey = {
  pk: "CAT#tenant1",
  sk: "CAT#cat001@1",
};

// Store the Step Functions task token
await this.commandService.updateTaskToken(key, event.taskToken);

// Later, use the token to send task success/failure
// via SendTaskSuccessCommand or SendTaskFailureCommand
```

### *async* `updateTtl(key: DetailKey): Promise<any | null>`

Updates the TTL (Time To Live) of the previous version of a command. This is typically used internally to manage command history retention. Returns `null` if the version is too low or the previous command doesn't exist.

```ts
import { DetailKey } from "@mbc-cqrs-serverless/core";

const key: DetailKey = {
  pk: "CAT#tenant1",
  sk: "CAT#cat001@3", // Version 3
};

// Updates TTL of version 2 (previous version)
const result = await this.commandService.updateTtl(key);
```

:::note
This method is primarily used internally by the framework for command history management. Direct usage is rarely needed in application code.
:::

### `dataSyncHandlers` (getter): IDataSyncHandler[]

Returns the array of registered data sync handlers for this CommandService instance. This is useful when you need to inspect or iterate over the handlers programmatically.

```ts
// Get all registered data sync handlers
const handlers = this.commandService.dataSyncHandlers;

handlers.forEach((handler) => {
  console.log(`Handler: ${handler.constructor.name}, Type: ${handler.type}`);
});
```

### `getDataSyncHandler(name: string): IDataSyncHandler | undefined`

Retrieves a specific data sync handler by its class name. Returns `undefined` if no handler with the specified name is found.

```ts
// Get a specific handler by name
const rdsHandler = this.commandService.getDataSyncHandler('CatDataSyncRdsHandler');

if (rdsHandler) {
  // Use the handler directly
  await rdsHandler.up(commandModel);
}
```

### `isNotCommandDirty(item: CommandModel, input: CommandInputModel): boolean`

Compares an existing command item with a new input to determine if there are any actual changes. Returns `true` if the command is NOT dirty (no changes), returns `false` if there ARE changes.

This method is used internally by publish methods to skip unnecessary writes when no changes are detected. You can also use it directly to check if an update would result in any changes before calling publish.

```ts
// Check if an update would result in changes
const existingCommand = await this.commandService.getItem({ pk, sk });

if (existingCommand && this.commandService.isNotCommandDirty(existingCommand, newInput)) {
  // No changes detected, skip the update
  console.log('Command has no changes, skipping update');
  return existingCommand;
}

// Proceed with the update
const result = await this.commandService.publishAsync(newInput, options);
```

### `tableName` (getter/setter): string

Gets or sets the DynamoDB table name for this CommandService instance. The table name is configured when registering the `CommandModule`, but can be changed at runtime if needed.

```ts
// Get the current table name
const currentTable = this.commandService.tableName;
console.log(`Operating on table: ${currentTable}`);

// Set a different table name
this.commandService.tableName = 'another-table';
```

:::note
Changing the table name at runtime is an advanced use case. In most applications, you should configure the table name through `CommandModule.register()` and not change it afterwards.
:::

---

## Read-Your-Writes (RYW) Consistency {#read-your-writes}

:::info Version Note
Read-Your-Writes consistency was added in [v1.2.0](/docs/changelog#v120).
:::

### The Problem: Stale Reads After publishAsync

`publishAsync` returns immediately after writing to the Command table, then the DynamoDB Stream pipeline asynchronously syncs the data to the read model (Data table). This creates a short window where a subsequent read by the same user returns stale data — for example, a "Create Order" button submits successfully, the user is redirected to the order list, but the new order does not appear yet.

```text
User Action                 DynamoDB Stream          User Sees
──────────────────────────────────────────────────────────────────
POST /orders ──────────► publishAsync() ─────► Command table ✓
                                                      │
GET  /orders ──────────► DataService.list() ─► Data table   ✗  ← stale!
                                                      │
                         [Stream sync ~1-3s]          │
                                          ↓           ▼
GET  /orders ──────────► DataService.list() ─► Data table   ✓  ← fresh
```

### The Solution: Session-Based Merge

RYW bridges this gap by temporarily caching the version number of the pending command in a short-lived session table. When reading through `Repository`, the session entry is detected and the pending command is fetched from the Command table and merged into the response — making the write immediately visible to the user who made it.

```text
User Action                 With RYW                 User Sees
──────────────────────────────────────────────────────────────────
POST /orders ──────────► publishAsync()
                         ├─► Command table ✓
                         └─► Session table (TTL=5m)

GET  /orders ──────────► Repository.listItemsByPk()
                         ├─► Session table ─► found! version=3
                         ├─► Command table  ─► fetch pending cmd
                         └─► merge into result     ✓  ← fresh!
```

### How it Works (Internals)

1. **Write path** — after a successful `publishAsync`, `CommandService` writes a session entry to `{NODE_ENV}-{APP_NAME}-session` table:
   - PK: `{userId}#{tenantCode}`
   - SK: `{moduleTableName}#{itemId}`
   - `version`: the version number of the published command
   - `ttl`: current time + `RYW_SESSION_TTL_MINUTES` seconds (DynamoDB TTL auto-deletes the entry)
   - **Note**: if `RYW_SESSION_TTL_MINUTES` is unset, this write is skipped entirely. `Repository` reads still work correctly — they simply find no session entries and fall back to `DataService`.

2. **Read path** — `Repository` checks the session table before returning data:
   - For `getItem`: if a session entry exists, fetches the exact versioned command and merges it with any existing data item
   - For `listItemsByPk`: fetches all session entries for the user/tenant/module, then applies updates, deletes, and create-new prepends to the base list result
   - For `listItems` (external sources like RDS): same merge logic, with `transformCommand` to convert the command shape to the external query shape. Unlike `listItemsByPk` (which derives `tenantCode` from the `pk` argument), `listItems` derives `tenantCode` from `getUserContext(options.invokeContext)` — so `options` with a valid `invokeContext` is required for RYW to activate

3. **Session expiry** — entries expire automatically via DynamoDB TTL. Once the Stream sync completes (typically 1–3 seconds), the session entry is redundant and will be cleaned up within the TTL window.

### Proactive Session Cleanup (v1.2.6+) {#ryw-session-cleanup}

:::info Version Note
Proactive RYW session cleanup and the `getVersion` short-circuit were added in [v1.2.6](/docs/changelog#v126).
:::

Prior to v1.2.6, RYW sessions persisted until their TTL expired, even after the data table had absorbed the corresponding write. This created a "stale override" window: if another user or external system updated the same item to a newer version, the session would still cause the originating user to see their own older command merged on top of the data table — effectively reverting visible state until the TTL elapsed.

Since v1.2.6, `Repository` actively purges sessions in the background once the data table version meets or exceeds the session version. This guarantees that:

- The originating user immediately sees the latest data once the Stream sync completes — no more stale-override window
- Subsequent reads skip the unnecessary command-table lookup, reducing latency
- The session table stays small even when the configured TTL is generous

Cleanup is **fire-and-forget** — failures are logged as warnings (`Failed to delete RYW session (non-fatal): ...`) and never block the read path. All behavior is automatic when `RYW_SESSION_TTL_MINUTES` is enabled; no application code changes are required.

#### Optional: `getVersion` short-circuit for RDS read models

`Repository.listItems()` (the RDS path) now accepts an optional `mergeOptions.getVersion` callback. If your RDS rows already carry a `version` column, supplying this callback lets the merge loop skip the extra DynamoDB GetItem when the existing RDS row already proves caught-up:

```ts
await repository.listItems(
  () => rdsQuery(),
  {
    latestFlg: true,
    transformCommand: (cmd) => ({
      id: cmd.id,
      version: cmd.version,
      // ...map other CommandModel fields to your RDS row shape
    }),
    getVersion: (item) => item.version, // new in v1.2.6
  },
  options,
)
```

**Note:** `getVersion` only short-circuits the **update path** (when the session's `itemId` matches an existing RDS row). Create-new items (session present but not yet reflected in RDS) still fetch the command as before — there is no existing row to derive a version from.

### Enabling RYW {#enabling-ryw}

#### Step 1: Set the environment variable

Set [`RYW_SESSION_TTL_MINUTES`](/docs/environment-variables#ryw-session-configuration) to a positive integer. A value of `5` (minutes) is a safe default — it covers any Stream sync delay while keeping the session table small.

```bash
RYW_SESSION_TTL_MINUTES=5
```

If unset (or set to 0 or a non-number), the feature is completely disabled: session writes are skipped and `Repository` behaves identically to `DataService`.

#### Step 2: Create the session DynamoDB table

Add `dynamodbs/session.json` to your project (same location as your other table definitions):

```json
{
  "TableName": "${NODE_ENV}-${APP_NAME}-session",
  "BillingMode": "PAY_PER_REQUEST",
  "KeySchema": [
    { "AttributeName": "pk", "KeyType": "HASH" },
    { "AttributeName": "sk", "KeyType": "RANGE" }
  ],
  "AttributeDefinitions": [
    { "AttributeName": "pk", "AttributeType": "S" },
    { "AttributeName": "sk", "AttributeType": "S" }
  ],
  "TimeToLiveSpecification": {
    "AttributeName": "ttl",
    "Enabled": true
  }
}
```

The table name is automatically computed as `{NODE_ENV}-{APP_NAME}-session` (e.g. `dev-myapp-session`).

### Using Repository {#repository-api}

`Repository` is a drop-in replacement for `DataService` for read operations that need RYW consistency. It is exported from `@mbc-cqrs-serverless/core` (via `CommandModule`). Register it in your module and inject it in your service.

#### Module registration

```ts
import { CommandModule } from '@mbc-cqrs-serverless/core'

@Module({
  imports: [
    CommandModule.register({
      tableName: 'order',
      dataSyncHandlers: [OrderDataSyncHandler],
    }),
  ],
  providers: [OrderService],
  exports: [OrderService],
})
export class OrderModule {}
```

`Repository` is automatically provided and exported by `CommandModule.register()` — no extra configuration is needed.

#### `getItem` — single item with RYW merge

```ts
import { DetailKey, ICommandOptions, Repository } from '@mbc-cqrs-serverless/core'
import { Injectable } from '@nestjs/common'

@Injectable()
export class OrderService {
  constructor(private readonly repository: Repository) {}

  async getOrder(key: DetailKey, options: ICommandOptions) {
    // If the user just published an async command for this item,
    // the pending version is merged in — the user always sees their own write.
    return this.repository.getItem(key, options)
  }
}
```

#### `listItemsByPk` — DynamoDB list with RYW merge

Pass `{ latestFlg: true }` as the third argument to enable merging. If `mergeOptions` is omitted or `latestFlg` is `false`/`undefined`, the method behaves identically to `DataService.listItemsByPk`.

```ts
async listOrders(pk: string, options: ICommandOptions) {
  return this.repository.listItemsByPk(
    pk,
    { limit: 20, order: 'desc' },  // standard DynamoDB query options
    { latestFlg: true },            // enable RYW merge
    options,
  )
}
```

Merge behaviour per operation:

| Operation | Result |
|---|---|
| create-new | Prepended to the top of the list (sorted by `updatedAt` desc among multiple pending creates) |
| update | Replaced in-place — original sort position preserved |
| delete | Removed from the result |

:::note Sort order after create-new
Newly created items are prepended to the top of the list, not integrated into the caller's sort order (e.g. by `name` or `code`). They appear at the top until the DynamoDB Stream sync completes and the next read returns fully sorted data. This is intentional — RYW guarantees *visibility*, not sort position.
:::

#### `listItems` — external source (RDS / Elasticsearch) with RYW merge

For services that query an external source (e.g. RDS via TypeORM or Prisma), use `listItems` with a `transformCommand` function to convert the pending command into the same shape as your query result.

```ts
import { IMergeOptions, ICommandOptions, Repository } from '@mbc-cqrs-serverless/core'
import { Injectable } from '@nestjs/common'
import { OrderDto } from './dto/order.dto'

@Injectable()
export class OrderService {
  constructor(
    private readonly repository: Repository,
    private readonly orderRepository: TypeOrmOrderRepository,
  ) {}

  async searchOrders(
    filter: OrderFilterDto,
    options: ICommandOptions,
  ): Promise<{ total: number; items: OrderDto[] }> {
    const mergeOptions: IMergeOptions<OrderDto> = {
      latestFlg: true,

      // Convert a pending CommandModel into an OrderDto
      transformCommand: (cmd, existing) => ({
        id: cmd.id,
        code: cmd.code,
        name: cmd.name,
        status: cmd.attributes?.status ?? existing?.status,
        // carry over join fields that don't exist in the command
        customerName: existing?.customerName ?? '',
        createdAt: cmd.createdAt,
        updatedAt: cmd.updatedAt,
      }),

      // Only prepend create-new items that match the current search filter
      matchesFilter: (item) =>
        !filter.status || item.status === filter.status,
    }

    return this.repository.listItems(
      // The base query — runs as normal
      () => this.orderRepository.search(filter),
      mergeOptions,
      options,
    )
  }
}
```

:::note Pagination with listItems
`total` is adjusted after merge (incremented for create-new, decremented for delete). However, prepended items sit outside the RDS `LIMIT`/`OFFSET` window, so on page 2+ there may be a one-item overlap or gap until the Stream sync completes. For most UX patterns (redirect-after-write, optimistic UI) this is unnoticeable.
:::

### Behaviour Summary

| Scenario | `RYW_SESSION_TTL_MINUTES` unset | `RYW_SESSION_TTL_MINUTES=5` |
|---|---|---|
| `getItem` — item just created | Returns stale (empty) | Returns pending command data |
| `getItem` — after Stream sync | Returns fresh data | Returns fresh data (session expired or not found) |
| `listItemsByPk` with `latestFlg` | Returns stale list | Returns list with pending item prepended |
| Performance overhead | None | 1–2 extra DynamoDB reads per pending item |
| Impact on existing code | None | None — `DataService` is unchanged |

### Limitations and Trade-offs

- **Visibility guarantee, not ordering**: Pending create-new items appear at the top of lists, not in the caller's sort order.
- **Single-user scope**: RYW only applies to the user who published the command. Other users still see the eventual-consistent read until the Stream sync completes.
- **`listItems` pagination overlap**: On paginated external queries (RDS), a create-new item may appear on both page 1 (prepended) and page 2 (after sync). This resolves on the next full reload.
- **Session table cost**: Each `publishAsync` call writes one DynamoDB item per updated entity. With `RYW_SESSION_TTL_MINUTES=5` the items are small and short-lived. Cost is negligible for typical workloads.


## Related Documentation

- [Data Service](/docs/data-service) - Querying data with DynamoDB
- [Unit Testing](/docs/unit-test) - Unit testing CommandService with mocks
- [Service Patterns](/docs/service-patterns) - Complete CRUD service implementation patterns
- [Event Handling Patterns](/docs/event-handling-patterns) - Creating data sync handlers
- [Version Conflict Guide](/docs/version-conflict-guide) - Handling optimistic locking conflicts
- [Interfaces](/docs/interfaces) - TypeScript interfaces for CommandInputModel and more
- [Versioning Rules](/docs/version-rules) - VERSION_FIRST, version sequences, and optimistic locking semantics
- [Serialization](/docs/serialization) - Serialization of command data with class-transformer


---

## DataService

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/data-service

# DataService

## Overview {#overview}

The `DataService` is the query side of the CQRS pattern, providing efficient read operations for data stored in DynamoDB. It handles all read operations from the data table (the read model) which is optimized for queries.

:::tip Read-Your-Writes Consistency
`DataService` reads from the DynamoDB data table, which is updated asynchronously via DynamoDB Streams. If you need a user to immediately see their own writes (before the stream propagates), use `Repository` instead — it is a drop-in replacement for `DataService` that adds RYW session caching. See [Read-Your-Writes in CommandService](/docs/command-service#read-your-writes) for setup and usage.
:::

```mermaid
graph LR
    subgraph "CQRS Query Side"
        A["Application"] --> B["DataService"]
        B --> C["Data Table"]
        C --> D["Query Results"]
    end
```

Before using the DataService, you need to set up the CommandModule as described in [the CommandService section](/docs/command-service).

## Methods {#methods}

### *async* `getItem(key: DetailKey): Promise<DataModel | undefined>`

The `getItem` method returns a set of attributes for the item with the given detail/primary key. If there is no matching item, `getItem` returns `undefined`.

Example:

```ts
import { DataService, DataModel } from '@mbc-cqrs-serverless/core';
import { Injectable, NotFoundException } from '@nestjs/common';

@Injectable()
export class CatService {
  constructor(private readonly dataService: DataService) {}

  async getCat(pk: string, sk: string): Promise<CatDataEntity> {
    const item = await this.dataService.getItem({ pk, sk });

    if (!item) {
      throw new NotFoundException('Cat not found');
    }
    return new CatDataEntity(item as CatDataEntity);
  }
}
```

### *async* `listItemsByPk(pk: string, opts?: ListItemsOptions): Promise<DataListEntity>`

The `listItemsByPk` method returns one or more items matching the partition key. It supports filtering, pagination, and sorting.

#### Basic Usage

List all items by primary key (`pk`):

```ts
const res = await this.dataService.listItemsByPk(pk);
return new CatListEntity(res);
```

#### With Sort Key Filter

List items by primary key (`pk`) and use a filter expression on the sort key (`sk`). For example, get items where the sort key starts with `CAT#` and limit to 100 items:

```ts
import { KEY_SEPARATOR } from '@mbc-cqrs-serverless/core';

const query = {
  sk: {
    skExpression: 'begins_with(sk, :typeCode)',
    skAttributeValues: {
      ':typeCode': `CAT${KEY_SEPARATOR}`,
    },
  },
  limit: 100,
};
const res = await this.dataService.listItemsByPk(pk, query);
return new CatDataListEntity(res);
```

#### Pagination

Implement pagination using `startFromSk` and `limit`:

```ts
async listCatsWithPagination(
  tenantCode: string,
  pageSize: number,
  lastSk?: string
): Promise<{ items: CatDataEntity[]; lastSk?: string }> {
  const pk = `CAT#${tenantCode}`;

  const result = await this.dataService.listItemsByPk(pk, {
    limit: pageSize,
    startFromSk: lastSk,
  });

  return {
    items: result.items.map(item => new CatDataEntity(item)),
    lastSk: result.lastSk,
  };
}
```

#### Sort Key Operators

The following sort key expressions are supported:

| Operator | Expression | Description |
|-----------|------------|-------------|
| Equals | `sk = :value` | Exact match |
| Begins With | `begins_with(sk, :prefix)` | Prefix match |
| Between | `sk BETWEEN :start AND :end` | Range query |
| Less Than | `sk < :value` | Less than comparison |
| Greater Than | `sk > :value` | Greater than comparison |

Example with range query:

```ts
const query = {
  sk: {
    skExpression: 'sk BETWEEN :start AND :end',
    skAttributeValues: {
      ':start': 'ORDER#2024-01-01',
      ':end': 'ORDER#2024-12-31',
    },
  },
};
const res = await this.dataService.listItemsByPk(pk, query);
```

### *async* `publish(cmd: CommandModel): Promise<DataModel>`

The `publish` method publishes command data to the data table. This is typically called internally by the framework's data sync handlers, but can be used directly when implementing custom synchronization logic.

:::note
This method is primarily used internally by the framework. In most cases, you should use `CommandService.publishSync()` or `CommandService.publishAsync()` which automatically handles data synchronization.
:::

```ts
import {
  CommandModel,
  DataModel,
  DataService,
  DataSyncHandler,
  IDataSyncHandler,
} from "@mbc-cqrs-serverless/core";
import { Injectable } from "@nestjs/common";

// Custom data sync handler example
@DataSyncHandler('your-command-table-name')
@Injectable()
export class CustomDataSyncHandler implements IDataSyncHandler {
  constructor(private readonly dataService: DataService) {}

  async up(cmd: CommandModel): Promise<DataModel> {
    // Publish command to data table
    const dataModel = await this.dataService.publish(cmd);

    // Additional synchronization to external systems
    await this.syncToExternalSystem(dataModel);

    return dataModel;
  }

  async down(cmd: CommandModel): Promise<void> {
    // Handle rollback if needed
  }

  private async syncToExternalSystem(data: DataModel): Promise<void> {
    // Custom sync logic
  }
}
```

The method:
- Converts CommandModel to DataModel format
- Removes version suffix from sort key
- Preserves original creation metadata (createdAt, createdBy, createdIp)
- Updates modification metadata (updatedAt, updatedBy, updatedIp)
- Stores the data in the data table

## Common Patterns {#common-patterns}

### Search by Code

Find an item by its unique code within a tenant:

```ts
async findByCode(tenantCode: string, code: string): Promise<CatDataEntity | undefined> {
  const pk = `CAT#${tenantCode}`;
  const sk = `CAT#${code}`;

  const item = await this.dataService.getItem({ pk, sk });
  return item ? new CatDataEntity(item) : undefined;
}
```

### List with Type Filter

List items filtered by type:

```ts
async listByType(tenantCode: string, type: string): Promise<CatDataEntity[]> {
  const pk = `CAT#${tenantCode}`;

  const result = await this.dataService.listItemsByPk(pk, {
    sk: {
      skExpression: 'begins_with(sk, :type)',
      skAttributeValues: {
        ':type': `${type}#`,
      },
    },
  });

  return result.items.map(item => new CatDataEntity(item));
}
```

### Error Handling

Handle common query errors gracefully:

```ts
import {
  Injectable,
  InternalServerErrorException,
  Logger,
  NotFoundException,
} from '@nestjs/common';
import { DataService } from '@mbc-cqrs-serverless/core';

@Injectable()
export class CatService {
  private readonly logger = new Logger(CatService.name);

  constructor(private readonly dataService: DataService) {}

  async getItemSafely(pk: string, sk: string): Promise<CatDataEntity> {
    try {
      const item = await this.dataService.getItem({ pk, sk });

      if (!item) {
        throw new NotFoundException(`Item not found: ${pk}/${sk}`);
      }

      return new CatDataEntity(item);
    } catch (error) {
      if (error instanceof NotFoundException) {
        throw error;
      }
      // Log and rethrow unexpected errors
      this.logger.error('Unexpected error querying item:', error);
      throw new InternalServerErrorException('Failed to retrieve item');
    }
  }
}
```

## Type Definitions {#type-definitions}

### DetailKey

```ts
interface DetailKey {
  pk: string;  // Partition key
  sk: string;  // Sort key
}
```

### ListItemsOptions

`ListItemsOptions` is an inline type definition in the method signature, not a separately exported interface. The type structure is as follows:

```ts
{
  sk?: {
    skExpression: string;
    skAttributeValues: Record<string, string>;
    skAttributeNames?: Record<string, string>;
  };
  startFromSk?: string;
  limit?: number;       // Default: 10
  order?: 'asc' | 'desc';
}
```

### DataListEntity

`DataListEntity` is a class (not an interface) that wraps list query results. It provides a constructor for easy instantiation:

```ts
class DataListEntity {
  items: DataEntity[];   // Array of data entities
  lastSk?: string;       // Sort key for pagination cursor
  total?: number;        // Total count (if available)

  constructor(data: Partial<DataListEntity>);
}
```

The constructor accepts a partial object, allowing you to create instances from query results:

```ts
const result = await this.dataService.listItemsByPk(pk);
const listEntity = new DataListEntity(result);
```

## HistoryService {#history-service}

The `HistoryService` provides access to the history table, which stores all previous versions of commands. Use it when you need to retrieve a specific historical version of an entity for audit trails or rollback scenarios.

```ts
import {
  HistoryService,
  addSortKeyVersion,
} from '@mbc-cqrs-serverless/core';
import { Injectable, NotFoundException } from '@nestjs/common';

@Injectable()
export class ProductService {
  constructor(private readonly historyService: HistoryService) {}

  async findVersion(pk: string, sk: string, version: number) {
    const skWithVersion = addSortKeyVersion(sk, version);
    const item = await this.historyService.getItem({ pk, sk: skWithVersion });

    if (!item) {
      throw new NotFoundException(`Version ${version} not found`);
    }
    return item;
  }
}
```

### *async* `getItem(key: DetailKey): Promise<DataModel | undefined>`

Retrieves a specific versioned item from the history table. The sort key must include the version suffix (use `addSortKeyVersion` to build it). Returns `undefined` if the version does not exist.

:::note
The history table uses the same key structure as the data table, but the sort key includes the version suffix: `sk@version`. Always use `addSortKeyVersion(sk, version)` to construct the key.
:::

## Best Practices {#best-practices}

1. **Use projection expressions**: Only retrieve the attributes you need to reduce data transfer
2. **Implement pagination**: Always paginate large result sets to avoid memory issues
3. **Cache frequently accessed data**: Consider caching static or slowly changing data
4. **Use appropriate key design**: Design your keys to support your query patterns efficiently
5. **Handle not found cases**: Always check if the item exists before using it


## Related Documentation

- [Command Service](/docs/command-service) - Writing commands with CommandService
- [Unit Testing](/docs/unit-test) - Unit testing DataService with mocks
- [Service Patterns](/docs/service-patterns) - Complete service layer patterns
- [Key Patterns](/docs/key-patterns) - DynamoDB key design for efficient queries
- [Entity Patterns](/docs/entity-patterns) - Entity definition with DataEntity
- [Serialization Helpers](/docs/serialization) - Converting DynamoDB structures to API response format
- [Data Sync Handler Examples](/docs/data-sync-handler-examples) - Using DataService.publish() in sync handlers


---

## Directory

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/directory

# Directory

Directory management functionality with S3 integration for the MBC CQRS Serverless framework.

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/directory
```

## Overview {#overview}

The Directory package provides comprehensive file and folder management in a multi-tenant CQRS architecture. It integrates with Amazon S3 for file storage and supports granular access permissions.

## Features {#features}

- **Directory CRUD Operations**: Create, read, update, and delete folders and files
- **S3 Integration**: Full file management with Amazon S3
- **Access Permissions**: Granular permissions for specific folders and files
- **Multi-tenant Support**: Tenant-isolated directory management
- **Event-Driven Architecture**: Built on CQRS pattern with command/event handling
- **RESTful API**: Complete REST API for directory operations
- **Version History**: Track and restore previous versions of files and folders

## Basic Setup {#basic-setup}

### Module Configuration

```typescript
import { DirectoryStorageModule } from '@mbc-cqrs-serverless/directory';
import { Module } from '@nestjs/common';
import { PrismaService } from './prisma.service';

@Module({
  imports: [
    DirectoryStorageModule.register({
      enableController: true,  // Enable REST API endpoints
      prismaService: PrismaService,  // Required (the directory service injects it)
      dataSyncHandlers: [],  // Optional data sync handlers
    }),
  ],
})
export class AppModule {}
```

## Configurable table name {#configurable-table-name}

By default the module uses the `directory` DynamoDB table. You can override the table name and related identifiers with backward-compatible options — omitting them keeps the current behavior. Both `register` and `registerAsync` accept them.

| Option | Default | Description |
|--------|---------|-------------|
| `tableName` | `directory` | Raw DynamoDB base table name. Physical tables become `${NODE_ENV}-${APP_NAME}-${tableName}` with `-command` / `-data` / `-history` suffixes. |
| `pkPrefix` | `DIRECTORY` | Partition-key prefix (before the `#` separator). |
| `prismaModelName` | `directory` | Prisma model accessor used for RDS reads. |

```typescript
// Opt in to running the directory module as "document"
DirectoryStorageModule.register({
  enableController: true,
  prismaService: PrismaService,
  tableName: 'document',
  pkPrefix: 'DOCUMENT',
  prismaModelName: 'document',
});

// Async configuration — the factory must resolve and return the PrismaService instance
DirectoryStorageModule.registerAsync({
  tableName: 'document',
  pkPrefix: 'DOCUMENT',
  prismaModelName: 'document',
  imports: [PrismaModule],
  inject: [PrismaService],
  useFactory: (prisma) => ({ prismaService: prisma }),
});
```

:::warning Set the three options together
Changing only `tableName` leaves the partition key as `DIRECTORY#` and reads `prismaService.directory`, which is inconsistent. Set `tableName`, `pkPrefix`, and `prismaModelName` together.
:::

### Provisioning and data migration

Using a custom table name requires application-side provisioning:

1. **DynamoDB:** add the raw base name (e.g. `"document"`) — not the `-command`/`-data`/`-history` variants — to `prisma/dynamodbs/cqrs.json`, then run `npm run migrate:ddb`. This creates the three physical tables. A custom name must be added manually (only the master module's postinstall auto-adds its default). Mirror the tables in your IaC.
2. **RDS:** add the matching Prisma model (e.g. `model Document { ... }`) to `schema.prisma`, then run `npm run migrate:rds`.
3. **Data:** the migrate commands only create empty tables. Copying existing data from `directory-*` / `DIRECTORY#` / the `directory` model to the new targets is your responsibility.

:::info Version Note
Configurable table names (`tableName`, `pkPrefix`, `prismaModelName`) and `registerAsync` were added in [version 1.4.0](/docs/changelog#v140).
:::

## API Endpoints {#api-endpoints}

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/directory/` | Create a new file or folder |
| GET | `/api/directory/summary` | Get tenant file size summary |
| GET | `/api/directory/:id` | Get details for a specific file or folder |
| GET | `/api/directory/:id/history` | Get version history of a file or folder |
| POST | `/api/directory/:id/history/:version/restore` | Restore a specific version |
| PUT | `/api/directory/:id/restore` | Restore a temporarily deleted item |
| PATCH | `/api/directory/:id` | Update a specific file or folder |
| PATCH | `/api/directory/:id/permission` | Update permissions for a file or folder |
| PATCH | `/api/directory/:id/rename` | Rename a file or folder |
| PATCH | `/api/directory/:id/copy` | Copy a file or folder |
| PATCH | `/api/directory/:id/move` | Move a file or folder |
| DELETE | `/api/directory/:id` | Soft delete a file or folder |
| DELETE | `/api/directory/:id/bin` | Permanently delete a file and remove from S3 |
| POST | `/api/directory/file/view` | Generate a presigned URL for viewing a file |
| POST | `/api/directory/file` | Generate a presigned URL for uploading a file |

## Creating Folders {#creating-folders}

```typescript
import { DirectoryService, DirectoryCreateDto, DirectoryDataEntity } from '@mbc-cqrs-serverless/directory';
import { IInvoke } from '@mbc-cqrs-serverless/core';
import { Injectable } from '@nestjs/common';

@Injectable()
export class FolderService {
  constructor(private readonly directoryService: DirectoryService) {}

  async createFolder(
    createDto: DirectoryCreateDto,
    invokeContext: IInvoke,
  ): Promise<DirectoryDataEntity> {
    return this.directoryService.create(createDto, { invokeContext });
  }
}
```

## Uploading Files {#uploading-files}

```typescript
async uploadFile(
  createDto: DirectoryCreateDto,
  invokeContext: IInvoke,
): Promise<DirectoryDataEntity> {
  // File upload is handled through the create method with file content
  return this.directoryService.create(createDto, { invokeContext });
}
```

## Listing Contents {#listing-contents}

```typescript
async getDirectory(
  detailDto: DetailDto,
  invokeContext: IInvoke,
  queryDto: DirectoryDetailDto,
): Promise<DirectoryDataEntity> {
  return this.directoryService.findOne(detailDto, { invokeContext }, queryDto);
}

async getDirectoryHistory(
  detailDto: DetailDto,
  invokeContext: IInvoke,
  queryDto: DirectoryDetailDto,
): Promise<DirectoryDataListEntity> {
  return this.directoryService.findHistory(detailDto, { invokeContext }, queryDto);
}
```

## File Operations {#file-operations}

```typescript
// Get file attributes
async getFileAttributes(detailDto: DetailDto): Promise<DirectoryAttributes> {
  return this.directoryService.getItemAttributes(detailDto);
}

// Get file item
async getFile(detailDto: DetailDto): Promise<DirectoryDataEntity> {
  return this.directoryService.getItem(detailDto);
}

// Soft delete (marks as deleted)
async removeItem(
  detailDto: DetailDto,
  invokeContext: IInvoke,
  queryDto: DirectoryDetailDto,
): Promise<DirectoryDataEntity> {
  return this.directoryService.remove(detailDto, { invokeContext }, queryDto);
}

// Permanently remove file and delete from S3
async removeFile(
  detailDto: DetailDto,
  invokeContext: IInvoke,
  queryDto: DirectoryDetailDto,
): Promise<DirectoryDataEntity> {
  return this.directoryService.removeFile(detailDto, { invokeContext }, queryDto);
}
```

## Updating Items {#updating-items}

```typescript
import { DirectoryUpdateDto } from '@mbc-cqrs-serverless/directory';

async updateItem(
  detailDto: DetailDto,
  updateDto: DirectoryUpdateDto,
  invokeContext: IInvoke,
): Promise<DirectoryDataEntity> {
  return this.directoryService.update(detailDto, updateDto, { invokeContext });
}
```

## Renaming Items {#renaming-items}

```typescript
import { DirectoryRenameDto } from '@mbc-cqrs-serverless/directory';

async renameItem(
  detailDto: DetailDto,
  renameDto: DirectoryRenameDto,
  invokeContext: IInvoke,
): Promise<DirectoryDataEntity> {
  return this.directoryService.rename(detailDto, renameDto, { invokeContext });
}
```

## Managing Permissions {#managing-permissions}

### Permission Types

The directory package supports different permission types:

```typescript
enum FilePermission {
  GENERAL = 'GENERAL',      // General access for everyone
  RESTRICTED = 'RESTRICTED', // Restricted to specific users
  DOMAIN = 'DOMAIN',        // Restricted to specific email domain
  TENANT = 'TENANT',        // Restricted to tenant members
}

enum FileRole {
  READ = 'READ',
  WRITE = 'WRITE',
  DELETE = 'DELETE',
  CHANGE_PERMISSION = 'CHANGE_PERMISSION',
  TAKE_OWNERSHIP = 'TAKE_OWNERSHIP',
}

enum EmailType {
  EMAIL = 'EMAIL',           // Individual email address
  EMAIL_GROUP = 'EMAIL_GROUP', // Email group or distribution list
}
```

### Directory Attributes

The DirectoryAttributes interface defines the metadata for files and folders:

```typescript
interface DirectoryAttributes {
  expirationTime?: string;   // Expiration time for the item
  fileSize?: number;         // File size in bytes
  fileType?: string;         // MIME type of the file
  parentId?: string;         // Parent folder ID
  owner: OwnerDto;           // Owner information
  s3Key?: string;            // S3 object key
  ancestors?: string[];      // Array of ancestor folder IDs
  inheritance?: boolean;     // Whether to inherit parent permissions
  tags?: string[];           // Tags for categorization
  permission?: PermissionDto; // Permission settings
}

interface OwnerDto {
  email: string;   // Owner's email address
  ownerId: string; // Owner's user ID
}

interface PermissionDto {
  type: FilePermission;        // Permission type
  role: FileRole;              // Default role for this permission
  domain?: DomainDto;          // Domain restriction (for DOMAIN type)
  users?: UserPermissionDto[]; // User-specific permissions (for RESTRICTED type)
}

interface DomainDto {
  email: string; // Email domain (e.g., "example.com")
}

interface UserPermissionDto {
  email: string;    // User's email address
  role: FileRole;   // Role assigned to this user
  id: string;       // User ID
  type: EmailType;  // Email type (EMAIL or EMAIL_GROUP)
}
```

### Updating Permissions

```typescript
import { DirectoryUpdatePermissionDto } from '@mbc-cqrs-serverless/directory';

async updatePermission(
  detailDto: DetailDto,
  updateDto: DirectoryUpdatePermissionDto,
  invokeContext: IInvoke,
): Promise<DirectoryDataEntity> {
  return this.directoryService.updatePermission(detailDto, updateDto, { invokeContext });
}
```

### Checking Permissions

`hasPermission()` returns `true` when the user holds at least one of the required roles on the item. `getEffectiveRole()` returns the highest role the user holds, or `null` if they have no access.

```typescript
// Returns true if user holds any of the required roles on the item
async hasPermission(
  itemId: DetailDto,
  requiredRole: FileRole[],
  user?: { email?: string; tenant?: string },
): Promise<boolean> {
  return this.directoryService.hasPermission(itemId, requiredRole, user);
}

// Returns the effective FileRole the user holds, or null if no access
async getEffectiveRole(
  itemId: DetailDto,
  user?: { email?: string; tenant?: string },
): Promise<FileRole | null> {
  return this.directoryService.getEffectiveRole(itemId, user);
}
```

## Moving and Copying {#moving-copying}

### Move Item

```typescript
import { DirectoryMoveDto } from '@mbc-cqrs-serverless/directory';

async moveItem(
  detailDto: DetailDto,
  moveDto: DirectoryMoveDto,
  invokeContext: IInvoke,
): Promise<DirectoryDataEntity> {
  return this.directoryService.move(detailDto, moveDto, { invokeContext });
}
```

### Copy Item

```typescript
import { DirectoryCopyDto } from '@mbc-cqrs-serverless/directory';

async copyItem(
  detailDto: DetailDto,
  copyDto: DirectoryCopyDto,
  invokeContext: IInvoke,
): Promise<DirectoryDataEntity> {
  return this.directoryService.copy(detailDto, copyDto, { invokeContext });
}
```

## Version History {#version-history}

### Restore Previous Version

```typescript
async restoreVersion(
  detailDto: DetailDto,
  version: string,
  queryDto: DirectoryDetailDto,
  invokeContext: IInvoke,
): Promise<DirectoryDataEntity> {
  return this.directoryService.restoreHistoryItem(detailDto, version, queryDto, { invokeContext });
}
```

### Restore Temporarily Deleted Item

```typescript
async restoreTemporary(
  detailDto: DetailDto,
  queryDto: DirectoryDetailDto,
  invokeContext: IInvoke,
): Promise<DirectoryDataEntity> {
  return this.directoryService.restoreTemporary(detailDto, queryDto, { invokeContext });
}
```

## Directory DTOs {#directory-dtos}

The directory package provides several DTOs for different operations:

### DirectoryCreateDto

```typescript
interface DirectoryCreateDto {
  name: string;              // Item name
  type: string;              // Item type (e.g., 'folder', 'file')
  attributes?: DirectoryAttributes; // Optional attributes
}
```

### DirectoryUpdateDto

```typescript
interface DirectoryUpdateDto {
  email: string;                    // Requester's email for permission check
  name?: string;                    // New name (optional)
  isDeleted?: boolean;              // Deletion flag
  attributes?: DirectoryAttributes; // Updated attributes
}
```

### DirectoryRenameDto

```typescript
interface DirectoryRenameDto {
  name: string;  // New name
  email: string; // Requester's email for permission check
}
```

### DirectoryMoveDto

```typescript
interface DirectoryMoveDto {
  parentId?: string; // Target parent folder ID
  email: string;     // Requester's email for permission check
}
```

### DirectoryCopyDto

```typescript
interface DirectoryCopyDto {
  path: string;       // S3 path for the copied file
  parentId?: string;  // Target parent folder ID
  email: string;      // Requester's email for permission check
}
```

### DirectoryDetailDto

```typescript
interface DirectoryDetailDto {
  email: string; // Requester's email for permission check
}
```

### DirectoryUpdatePermissionDto

```typescript
interface DirectoryUpdatePermissionDto {
  email: string;     // Requester's email for permission check
  attributes?: {
    permission?: PermissionDto; // New permission settings
    inheritance?: boolean;      // Whether to inherit parent permissions
  };
}
```

## Directory Structure {#directory-structure}

Example directory structure:

```text
/
├── documents/
│   ├── reports/
│   │   ├── 2024-Q1-report.pdf
│   │   └── 2024-Q2-report.pdf
│   └── contracts/
│       └── contract-001.pdf
├── images/
│   ├── logo.png
│   └── banner.jpg
└── templates/
    └── invoice-template.docx
```

## Multi-tenant Isolation {#multi-tenant-isolation}

Directories are automatically isolated by tenant through the invoke context:

```typescript
@Controller('api/directory')
export class DirectoryController {
  constructor(private readonly directoryService: DirectoryService) {}

  @Get(':id')
  async findOne(
    @INVOKE_CONTEXT() invokeContext: IInvoke,
    @DetailKeys() detailDto: DetailDto,
    @Query() queryDto: DirectoryDetailDto,
  ): Promise<DirectoryDataEntity> {
    // Tenant isolation is handled through the pk structure
    return this.directoryService.findOne(detailDto, { invokeContext }, queryDto);
  }
}
```

## Event Handling {#event-handling}

Handle directory data synchronization using data sync handlers:

```typescript
import { CommandModel, IDataSyncHandler } from '@mbc-cqrs-serverless/core';
import { Injectable } from '@nestjs/common';
import { PrismaService } from 'src/prisma';

@Injectable()
export class DirectoryDataSyncHandler implements IDataSyncHandler {
  constructor(private readonly prisma: PrismaService) {}

  async up(cmd: CommandModel): Promise<any> {
    // Called automatically on every command event — sync to RDS, notify users, update indexes, etc.
    await this.prisma.directory.upsert({
      where: { sk: cmd.sk },
      create: { sk: cmd.sk, pk: cmd.pk, name: cmd.name, ...cmd.attributes },
      update: { name: cmd.name, ...cmd.attributes },
    });
  }

  async down(cmd: CommandModel): Promise<any> {
    // Reserved for manual rollback — not called automatically by the framework
    await this.prisma.directory.delete({ where: { sk: cmd.sk } });
  }
}
```

## Best Practices {#best-practices}

1. **Use Folders for Organization**: Create a logical folder structure for easy navigation
2. **Set Permissions Early**: Configure permissions when creating directories
3. **Handle Large Files**: For large files, use presigned URLs for direct S3 upload
4. **Clean Up**: Implement retention policies for temporary files
5. **Audit Trail**: Use events to maintain an audit trail of all operations
6. **Use Soft Delete**: Prefer soft delete (remove) over permanent delete (removeFile) for data recovery


## Related Documentation

- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant file isolation
- [Environment Variables](/docs/environment-variables) - S3 configuration
- [Interfaces](/docs/interfaces) - Directory interfaces
- [Data Sync Handler Examples](/docs/data-sync-handler-examples) - Sync directory events to RDS


---

## EmailService

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/email-service

# EmailService

## Description {#description}

This service is designed to send emails using [AWS SES (Simple Email Service)](https://aws.amazon.com/ses/).

## Usage {#usage}

`EmailService` is exported from `@mbc-cqrs-serverless/core` and is registered as a global provider automatically by the framework. Inject it into any service using the standard NestJS constructor injection:

```typescript
import { EmailService, EmailNotification } from '@mbc-cqrs-serverless/core';
import { Injectable } from '@nestjs/common';

@Injectable()
export class NotificationService {
  constructor(private readonly emailService: EmailService) {}

  async sendWelcomeEmail(email: string, name: string): Promise<void> {
    await this.emailService.sendEmail({
      toAddrs: [email],
      subject: `Welcome, ${name}!`,
      body: `<p>Thank you for joining.</p>`,
    });
  }
}
```

Set the `SES_REGION` and optionally `SES_FROM_EMAIL` environment variables for SES configuration. See [Environment Variables](/docs/environment-variables) for details.

## Methods {#methods}

### *async* `sendEmail(msg: EmailNotification): Promise<any>`

Composes an email message and immediately queues it for sending. Returns `Promise<SendEmailCommandOutput>` — the AWS SES response includes a `MessageId` string you can capture for tracking:

```ts
const result = await this.emailService.sendEmail({
  toAddrs: ["recipient@example.com"],
  subject: "Hello",
  body: "<p>World</p>",
});
console.log(result.MessageId); // Log MessageId for email tracking
```

#### Basic Example

```ts
const email = "cat@example.com";
const subject = "Welcome to MBC CQRS Serverless framework!";
const body = "<p>Enjoy</p>";

await this.emailService.sendEmail({
  toAddrs: [email],
  subject,
  body,
});
```

#### With CC and BCC

```ts
await this.emailService.sendEmail({
  toAddrs: ["recipient@example.com"],
  ccAddrs: ["cc@example.com"],
  bccAddrs: ["bcc@example.com"],
  subject: "Meeting Invitation",
  body: "<p>Please join our meeting.</p>",
});
```

#### With Attachments

You can attach files to emails by providing an array of attachment objects:

```ts
await this.emailService.sendEmail({
  toAddrs: ["recipient@example.com"],
  subject: "Report Attached",
  body: "<p>Please find the attached report.</p>",
  attachments: [
    {
      filename: "report.pdf",
      content: pdfBuffer,
      contentType: "application/pdf",
    },
  ],
});
```

#### Multiple Attachments

```ts
await this.emailService.sendEmail({
  toAddrs: ["recipient@example.com"],
  subject: "Documents",
  body: "<p>Please find the attached documents.</p>",
  attachments: [
    {
      filename: "document.pdf",
      content: pdfBuffer,
      contentType: "application/pdf",
    },
    {
      filename: "image.jpg",
      content: imageBuffer,
      contentType: "image/jpeg",
    },
    {
      filename: "data.csv",
      content: csvBuffer,
      contentType: "text/csv",
    },
  ],
});
```

## EmailNotification Interface {#email-notification-interface}

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `fromAddr` | `string` | No | Sender email address (uses default if not specified) |
| `toAddrs` | `string[]` | Yes | List of recipient email addresses |
| `ccAddrs` | `string[]` | No | CC recipients |
| `bccAddrs` | `string[]` | No | BCC recipients |
| `subject` | `string` | Yes | Email subject line |
| `body` | `string` | Yes | Email body as HTML |
| `replyToAddrs` | `string[]` | No | Reply-to addresses |
| `attachments` | `Attachment[]` | No | File attachments |
| `emailTags` | `EmailTag[]` | No | AWS SES tags for categorization and filtering |

## Attachment Interface {#attachment-interface}

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `filename` | `string` | Yes | Filename shown to recipient |
| `content` | `Buffer` | Yes | File content as Buffer |
| `contentType` | `string` | No | MIME type (e.g., 'application/pdf') |

### *async* `sendInlineTemplateEmail(msg: TemplatedEmailNotification): Promise<any>` {#send-inline-template-email}

:::info Version Note
`sendInlineTemplateEmail()` was added in [version 1.0.23](/docs/changelog#v1023).
:::

Sends a templated email using `{{variableName}}` placeholders in the subject and body. Unlike SES registered templates, the template is inlined in the request — no pre-registration required.

```ts
import { EmailService, TemplatedEmailNotification } from '@mbc-cqrs-serverless/core';

await this.emailService.sendInlineTemplateEmail({
  toAddrs: ['user@example.com'],
  template: {
    subject: '{{orderType}} Confirmation — Order {{orderId}}',
    html: '<h1>Hello {{name}}!</h1><p>Your order #{{orderId}} is confirmed.</p>',
    text: 'Hello {{name}}, your order #{{orderId}} is confirmed.',
  },
  data: {
    name: 'Jane Doe',
    orderId: '12345',
    orderType: 'Purchase',
  },
});
```

For the full interface definition and advanced template features (whitespace trimming, nested data), see [Notification Module — Inline Template Emails](/docs/notification-module#inline-template-emails).

## Testing {#testing}

Mock `EmailService` in unit tests to avoid making real SES calls:

```typescript
// In your test module setup
const mockEmailService = {
  sendEmail: jest.fn().mockResolvedValue({ MessageId: 'test-message-id' }),
};

const module = await Test.createTestingModule({
  providers: [
    YourService,
    { provide: EmailService, useValue: mockEmailService },
  ],
}).compile();

// Assert the email was sent with the expected parameters
expect(mockEmailService.sendEmail).toHaveBeenCalledWith(
  expect.objectContaining({
    toAddrs: ['user@example.com'],
    subject: expect.stringContaining('Welcome'),
  }),
);
```

## Related Documentation

- [Notification Module](/docs/notification-module) - Real-time notifications with AppSync
- [Environment Variables](/docs/environment-variables) - SES configuration environment variables
- [Interfaces](/docs/interfaces) - EmailNotification interface reference
- [Unit Testing](/docs/unit-test) - Unit testing patterns for services


---

## Master

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/master

# Master


The Master Service provides functionality for managing master data and settings in a multi-tenant environment.
## Overview {#overview}

The Master Service consists of two main components:


### Master Setting Service
- Implements hierarchical settings management
- Supports creation of settings at all levels
- Provides update and delete operations for tenant settings
- Implements cascading settings retrieval


### Master Data Service
- Implements CRUD operations for master data entities
- Provides list and retrieval functionality
- Includes code validation capabilities
- Ensures data integrity across tenant boundaries

## Architecture {#architecture}

```mermaid
graph TB
    subgraph "Settings Hierarchy"
        A["COMMON"] --> B["Tenant"]
        B --> C["Group"]
        C --> D["User"]
    end

    subgraph "Master Data"
        E["MasterDataService"] --> F["Code Tables"]
        E --> G["Categories"]
        E --> H["Lookup Values"]
    end
```

## Settings Hierarchy Levels {#settings-hierarchy}

The Master Setting Service implements a four-level hierarchy. Settings cascade from the most specific level toward the most general — `getSetting` returns the first match found:

| Level | Scope | Created with | Use case |
|-----------|-----------|-----------------|-------------|
| **Common** | System-wide default | `createCommonTenantSetting` | Baseline values shared by all tenants |
| **Tenant** | Single tenant | `createTenantSetting` | Tenant-specific overrides of common defaults |
| **Group** | Tenant group | `createGroupSetting` | Group-level overrides within a tenant |
| **User** | Individual user | `createUserSetting` | Personal preferences within a tenant |

`getSetting` resolves a setting code in this order: **User → Group → Tenant → Common**. If no setting exists at any level, a `NotFoundException` is thrown.

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/master
```

## Basic Usage {#basic-usage}

The solution for customizing the behavior of the `MasterModule` is to pass it an options `object` in the static `register()` method.

### Module Options

| Option | Type | Description |
|--------|------|-------------|
| `enableController` | `boolean` | Enable or disable default master controller |
| `dataSyncHandlers` | `Type<IDataSyncHandler>[]` | Optional handlers to sync master data to external systems (e.g., RDS) |
| `prismaService` | `Type<any>` | Prisma service for RDS-backed queries. Required when `enableController: true` |

:::warning prismaService Requirement
When `enableController: true`, the `prismaService` parameter is **required**. The module will throw an error at startup if `prismaService` is not provided when the controller is enabled.
:::

```ts
import { MasterModule } from '@mbc-cqrs-serverless/master'

@Module({
  imports: [ MasterModule.register({
      enableController: true,
      dataSyncHandlers: [MasterDataRdsSyncHandler],
      prismaService: PrismaService,
    })],
  controllers: [],
  exports: [],
})

```

## API Reference {#api-reference}

### MasterSettingService
The MasterSettingService interface manages settings at various levels: user, group, tenant, and common. It allows retrieving, updating, creating, and deleting settings.

#### `getSetting(dto: GetSettingDto, context: { invokeContext: IInvoke }): Promise<MasterSettingEntity>`
Retrieves a specific setting based on the provided setting code.
```ts
const masterSetting = await this.masterSettingService.getSetting(
  {
    code: "service",
  },
  { invokeContext }
);
```

#### `createCommonTenantSetting(dto: CommonSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>`
Creates a common tenant setting that is shared across the system.
```ts
const masterSetting = await this.masterSettingService.createCommonTenantSetting(
  {
    name: "common setting",
    code: "service",
    settingValue: {
      region: "US",
      plan: "common"
    }
  },
  { invokeContext }
);
```

#### `createTenantSetting(dto: TenantSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>`
Creates a tenant-specific setting.
```ts
const masterSetting = await this.masterSettingService.createTenantSetting(
  {
    name: "tenant setting",
    code: "service",
    tenantCode: "mbc",
    settingValue: {
      region: "US",
      plan: "tenant"
    }
  },
  { invokeContext }
);
```

#### `createGroupSetting(dto: GroupSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>`
Creates a group-specific setting within a tenant.
```ts
const masterSetting = await this.masterSettingService.createGroupSetting(
  {
    name: "group setting",
    code: "service",
    tenantCode: "mbc",
    groupId: "12",
    settingValue: {
      region: "US",
      plan: "USER"
    }
  },
  { invokeContext }
);
```
#### `createUserSetting(dto: UserSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>`
Creates a user-specific setting within a tenant.
```ts
const masterSetting = await this.masterSettingService.createUserSetting(
  {
    name: "user setting",
    code: "service",
    tenantCode: "mbc",
    userId: "92ca4f68-9ac6-4080-9ae2-2f02a86206a4",
    settingValue: {
      region: "US",
      plan: "USER"
    }
  },
  { invokeContext }
);
```


#### `updateSetting(key: DetailKey, dto: UpdateSettingDto, context: { invokeContext: IInvoke }): Promise<CommandModel>`
Updates an existing setting.
```ts
const masterSetting = await this.masterSettingService.updateSetting(
  {
    pk: "MASTER#abc",
    sk: "MASTER_SETTING#service"
  },
  {
    name: 'Example Master Setting',
    settingValue: {
      homepage: "url",
      desc: "string"
    }
  },
  { invokeContext }
);
```

#### `deleteSetting(key: DetailKey, context: { invokeContext: IInvoke }): Promise<CommandModel>`
Deletes a specific setting based on the provided key.
```ts
const masterSetting = await this.masterSettingService.deleteSetting(
  {
    pk: "MASTER#abc",
    sk: "MASTER_SETTING#service"
  },
  { invokeContext }
);
```

#### `list(searchDto: MasterSettingSearchDto, invokeContext: IInvoke): Promise<MasterRdsListEntity>`
Lists master settings with pagination and filtering. Requires RDS (Prisma) configuration.
```ts
const result = await this.masterSettingService.list(
  {
    name: "service",           // Partial match for name
    code: "SVC",               // Partial match for code
    keyword: "description",    // Search in attributes.description
    page: 1,
    pageSize: 10,
    orderBys: ["-createdAt"],
  },
  invokeContext
);
```

#### `getDetail(key: DetailDto): Promise<MasterRdsEntity>`
Retrieves detailed master setting. Throws NotFoundException if not found.
```ts
const masterSetting = await this.masterSettingService.getDetail({
  pk: "MASTER#mbc",
  sk: "MASTER_SETTING#service"
});
```

#### `create(createDto: CommonSettingDto, invokeContext: IInvoke): Promise<CommandModel>`
Creates a new tenant setting. Wrapper for createTenantSetting with automatic tenant code extraction from context.
```ts
const masterSetting = await this.masterSettingService.create(
  {
    code: "service",
    name: "Service Setting",
    settingValue: { key: "value" }
  },
  invokeContext
);
```

#### `createBulk(createDto: CommonSettingBulkDto, invokeContext: IInvoke): Promise<CommandModel[]>`
Creates multiple settings at once.

:::warning Create-only Operation
`createBulk` internally calls `create` for each item, which throws a `BadRequestException` if the setting already exists (e.g., `"Setting already exists: {code}"`). This method cannot be used to update existing settings. If you need upsert behavior (create or update), see the [Upsert Pattern](#upsert-pattern) section below.
:::

```ts
const settings = await this.masterSettingService.createBulk(
  {
    items: [
      { code: "setting1", name: "Setting 1", settingValue: {} },
      { code: "setting2", name: "Setting 2", settingValue: {} }
    ]
  },
  invokeContext
);
```

#### `update(key: DetailDto, updateDto: MasterSettingUpdateDto, invokeContext: IInvoke): Promise<CommandModel | null>`
Updates a master setting.
```ts
const result = await this.masterSettingService.update(
  { pk: "MASTER#mbc", sk: "MASTER_SETTING#service" },
  {
    name: "Updated Setting",
    attributes: { newKey: "newValue" }
  },
  invokeContext
);
```

#### `delete(key: DetailDto, invokeContext: IInvoke): Promise<CommandModel | null>`
Deletes a master setting. Wrapper for deleteSetting.
```ts
await this.masterSettingService.delete(
  { pk: "MASTER#mbc", sk: "MASTER_SETTING#service" },
  invokeContext
);
```

#### `checkExistCode(code: string, invokeContext: IInvoke): Promise<boolean>`
Checks if a setting code already exists for the current tenant.
```ts
const exists = await this.masterSettingService.checkExistCode("service", invokeContext);
if (exists) {
  // Handle duplicate code
}
```

#### `copy(masterCopyDto: MasterCopyDto, opts: { invokeContext: IInvoke }): Promise<any>`
Copies master settings and data to other tenants asynchronously using Step Functions. This is useful for initializing new tenants with existing master data.
```ts
const task = await this.masterSettingService.copy(
  {
    masterSettingId: "MASTER#mbc#MASTER_SETTING#service",
    targetTenants: ["tenant1", "tenant2"],
    copyType: CopyType.BOTH,   // CopyType.SETTING_ONLY, CopyType.DATA_ONLY, or CopyType.BOTH
    dataCopyOption: {
      mode: DataCopyMode.ALL,  // or DataCopyMode.PARTIAL
      // id: ["id1", "id2"]    // Required when mode is PARTIAL
    }
  },
  { invokeContext }
);
// Returns a task entity - the copy operation runs asynchronously
```

Copy types:
- `CopyType.SETTING_ONLY`: Copies only the setting
- `CopyType.DATA_ONLY`: Copies only the data
- `CopyType.BOTH`: Copies both setting and data

Data copy modes (used when copyType is DATA_ONLY or BOTH):
- `DataCopyMode.ALL`: Copies all master data under the setting
- `DataCopyMode.PARTIAL`: Copies only specified IDs

### MasterDataService
The MasterDataService service provides methods to manage master data and operations. This includes listing, retrieving, creating, updating, and deleting data, as well as checking for the existence of specific codes.

#### `list(searchDto: MasterDataSearchDto): Promise<MasterDataListEntity>`
Lists master data based on the provided search criteria. Note: This method does not require an invoke context.
```ts
const masterData = await this.masterDataService.list({
  tenantCode: "mbc",
  settingCode: "service"
});
```

#### `get(key: DetailDto): Promise<MasterDataEntity>`
Get a master data by pk and sk.

```ts
const masterData = await this.masterDataService.get(
  {
    pk:"MASTER#abc", 
    sk:"service#01"
  }
);
```

  
#### `create(data: CreateMasterDataDto, context: { invokeContext: IInvoke }): Promise<MasterDataEntity>`

Creates a new master data entity

```ts
const masterData = await this.masterDataService.create(
  {
    code: 'MASTER001',
    name: 'Example Master Data',
    settingCode: "service",
    tenantCode: "common",
    attributes: {
      homepage: "http://mbc.com",
      desc: "description for mbc"
    }
  },
  { invokeContext }
);
```

#### `update(key: DetailDto, updateDto: UpdateDataSettingDto, context: { invokeContext: IInvoke }): Promise<MasterDataEntity>`
Updates existing master data.

```ts
const masterData = await this.masterDataService.update(
  {
    pk: "MASTER#abc",
    sk: "service#01"
  },
  {
    name: 'Example Master Data',
    attributes: {
      homepage: "http://mbc.com",
      desc: "description for mbc"
    }
  },
  { invokeContext }
);
```


#### `delete(key: DetailDto, opts: { invokeContext: IInvoke }): Promise<MasterDataEntity>`
Deletes specific master data based on the provided key.
```ts
const masterData = await this.masterDataService.delete(
  {
    pk: "MASTER#abc",
    sk: "service#01"
  },
  { invokeContext }
);
```

#### `checkExistCode(tenantCode: string, type: string, code: string): Promise<boolean>`
Checks if a specific code exists within the given tenant and type.

```ts
const exists = await this.masterDataService.checkExistCode("mbc", "service", "01");
if (exists) {
  // Handle existing code
}
```

#### `getDetail(key: DetailDto): Promise<MasterRdsEntity>`
Retrieves detailed master data including related information. Throws NotFoundException if not found.

```ts
const masterData = await this.masterDataService.getDetail({
  pk: "MASTER#mbc",
  sk: "service#01"
});
```

#### `createSetting(createDto: MasterDataCreateDto, invokeContext: IInvoke): Promise<MasterDataEntity>`
Creates a new master data entity with automatic sequence generation if not provided.

:::warning Create-only Operation
`createSetting` throws a `BadRequestException` if the master data already exists (e.g., `"Master data already exists"`). If you need upsert behavior (create or update), see the [Upsert Pattern](#upsert-pattern) section below.
:::

```ts
const masterData = await this.masterDataService.createSetting(
  {
    code: 'MASTER001',
    name: 'Example Master Data',
    settingCode: "service",
    tenantCode: "mbc",
    attributes: {
      homepage: "http://mbc.com",
      desc: "description for mbc"
    }
  },
  invokeContext
);
```

#### `createBulk(createDto: MasterDataCreateBulkDto, invokeContext: IInvoke): Promise<MasterDataEntity[]>`
Creates multiple master data entities in bulk.

:::warning Create-only Operation
`createBulk` internally calls `createSetting` for each item. It throws a `BadRequestException` if any item already exists. If you need upsert behavior, see the [Upsert Pattern](#upsert-pattern) section below.
:::

```ts
const masterDataList = await this.masterDataService.createBulk(
  {
    items: [
      {
        code: 'MASTER001',
        name: 'First Master Data',
        settingCode: "service",
        tenantCode: "mbc",
        attributes: {}
      },
      {
        code: 'MASTER002',
        name: 'Second Master Data',
        settingCode: "service",
        tenantCode: "mbc",
        attributes: {}
      }
    ]
  },
  invokeContext
);
```

#### `updateSetting(key: DetailDto, updateDto: MasterDataUpdateDto, invokeContext: IInvoke): Promise<MasterDataEntity>`
Updates an existing master data entity.

```ts
const masterData = await this.masterDataService.updateSetting(
  {
    pk: "MASTER#mbc",
    sk: "service#01"
  },
  {
    name: 'Updated Master Data',
    attributes: {
      homepage: "http://updated-mbc.com"
    }
  },
  invokeContext
);
```

#### `deleteSetting(key: DetailDto, invokeContext: IInvoke): Promise<MasterDataEntity>`
Deletes a master data entity by key.

```ts
const result = await this.masterDataService.deleteSetting(
  {
    pk: "MASTER#mbc",
    sk: "service#01"
  },
  invokeContext
);
```

#### `listByRds(searchDto: CustomMasterDataSearchDto, context: { invokeContext: IInvoke }): Promise<MasterRdsListEntity>`
Searches master data in RDS with filtering and pagination. This method is used when Prisma service is configured.

```ts
const result = await this.masterDataService.listByRds(
  {
    settingCode: "service",    // Exact match for master type code
    keyword: "example",        // Partial match (case-insensitive) for name
    code: "001",               // Partial match (case-insensitive) for master code
    page: 1,
    pageSize: 10,
    orderBys: ["seq", "masterCode"],
  },
  { invokeContext }
);
```

##### Search Parameters {#search-parameters}

| Parameter | Type | Required | Match Type | Description |
|---------------|----------|--------------|----------------|-----------------|
| `settingCode` | `string` | No | Exact match | Filter by master type code (masterTypeCode) |
| `keyword` | `string` | No | Partial match (case-insensitive) | Filter by name field |
| `code` | `string` | No | Partial match (case-insensitive) | Filter by master code |
| `page` | `number` | No | - | Page number (default: 1) |
| `pageSize` | `number` | No | - | Items per page (default: 10) |
| `orderBys` | `string[]` | No | - | Sort order (default: ["seq", "masterCode"]) |
| `isDeleted` | `boolean` | No | Exact match | Filter by deletion status |

:::warning Known Issue (Fixed in v1.0.17)
In versions prior to v1.0.17, the `settingCode` parameter incorrectly used partial matching (`contains`) instead of exact matching. This caused unintended search results - for example, searching for "PRODUCT" would also return "PRODUCT_TYPE" and "MY_PRODUCT".

If you are using v1.0.16 or earlier and need exact matching for `settingCode`, upgrade to v1.0.17 or later.

See also: [Changelog v1.0.17](/docs/changelog#v1017)
:::

## Built-in Upsert API {#upsert-pattern}

The framework provides built-in upsert methods that automatically handle both creating new records and updating existing ones. These methods check DynamoDB for existing data and decide whether to create or update, skipping unchanged records for efficiency.

:::info Version Note
Built-in upsert methods (`upsert`, `upsertBulk`, `upsertSetting`, `upsertTenantSetting`) were added in [version 1.1.2](/docs/changelog#v112). In earlier versions, you need to implement custom upsert logic (see [Legacy Upsert Pattern](#legacy-upsert-pattern) below).
:::

### MasterSettingService Upsert Methods

#### `upsertTenantSetting(dto: TenantSettingDto, options: { invokeContext: IInvoke }): Promise<CommandModel>`
Creates or updates a tenant setting. If the setting exists and has changes, it updates. If the setting exists but is unchanged, it returns the existing data without creating a new command. If the setting is deleted, it recreates it.

```ts
const result = await this.masterSettingService.upsertTenantSetting(
  {
    tenantCode: "mbc",
    code: "service",
    name: "Service Setting",
    settingValue: { region: "US", plan: "Premium" },
  },
  { invokeContext }
);
```

#### `upsertSetting(createDto: CommonSettingDto, invokeContext: IInvoke): Promise<CommandModel>`
Wrapper for `upsertTenantSetting` with automatic tenant code extraction from context.

```ts
const result = await this.masterSettingService.upsertSetting(
  {
    code: "service",
    name: "Service Setting",
    settingValue: { region: "US", plan: "Premium" },
  },
  invokeContext
);
```

#### `upsertBulk(createDto: CommonSettingBulkDto, invokeContext: IInvoke): Promise<CommandModel[]>`
Upserts multiple settings sequentially. Items are processed one by one to avoid race conditions.

```ts
const results = await this.masterSettingService.upsertBulk(
  {
    items: [
      { code: "setting1", name: "Setting 1", settingValue: { key: "value1" } },
      { code: "setting2", name: "Setting 2", settingValue: { key: "value2" } },
    ]
  },
  invokeContext
);
```

### MasterDataService Upsert Methods

#### `upsert(createDto: CreateMasterDataDto, opts: { invokeContext: IInvoke }): Promise<MasterDataEntity>`
Creates or updates a master data entity. Behaves the same as `create` but does not throw when the record already exists.

```ts
const result = await this.masterDataService.upsert(
  {
    code: 'MASTER001',
    name: 'Example Master Data',
    settingCode: "service",
    tenantCode: "mbc",
    attributes: { homepage: "http://mbc.com" },
  },
  { invokeContext }
);
```

#### `upsertSetting(createDto: MasterDataCreateDto, invokeContext: IInvoke): Promise<MasterDataEntity>`
Wrapper for `upsert` with automatic sequence generation and tenant code extraction.

```ts
const result = await this.masterDataService.upsertSetting(
  {
    code: 'MASTER001',
    name: 'Example Master Data',
    settingCode: "service",
    attributes: { homepage: "http://mbc.com" },
  },
  invokeContext
);
```

#### `upsertBulk(createDto: MasterDataCreateBulkDto, invokeContext: IInvoke): Promise<MasterDataEntity[]>`
Upserts multiple master data entities sequentially. Items are processed one by one to avoid seq race conditions.

```ts
const results = await this.masterDataService.upsertBulk(
  {
    items: [
      { code: 'DATA001', name: 'First Data', settingCode: "service", attributes: {} },
      { code: 'DATA002', name: 'Second Data', settingCode: "service", attributes: {} },
    ]
  },
  invokeContext
);
```

### Unified Bulk Upsert API (MasterBulkController) {#unified-bulk-upsert}

When the controller is enabled (`enableController: true`), the framework provides a unified `/api/master-bulk/` endpoint that can handle both settings and data in a single request. Items are routed based on the presence of `settingCode`:

- **With `settingCode`**: Routed to `MasterDataService.upsertBulk`
- **Without `settingCode`**: Routed to `MasterSettingService.upsertBulk`

```ts
// POST /api/master-bulk/
const requestBody = {
  items: [
    // This item has settingCode → treated as master data
    {
      name: "Data Item",
      code: "DATA001",
      settingCode: "UserList",
      seq: 1,
      attributes: { field: "value" },
    },
    // This item has no settingCode → treated as master setting
    {
      name: "Setting Item",
      code: "SettingA",
      attributes: { description: "A setting" },
    },
  ]
};
```

The response preserves the original input order. Tenant code validation is enforced: if `tenantCode` is specified in an item, it must match the authenticated user's tenant.

#### Request Body

| Field | Type | Required | Description |
|-----------|----------|--------------|-----------------|
| `items` | `MasterBulkItemDto[]` | Yes | Array of items to upsert (max 100) |

#### MasterBulkItemDto

| Field | Type | Required | Description |
|-----------|----------|--------------|-----------------|
| `name` | `string` | Yes | Name of the setting or data |
| `code` | `string` | Yes | Code of the setting or data |
| `tenantCode` | `string` | No | Tenant code (must match authenticated user's tenant if specified) |
| `settingCode` | `string` | No | If present, item is treated as master data; otherwise as master setting |
| `seq` | `number` | No | Sort order (used for master data) |
| `attributes` | `object` | Yes | Attributes object. For settings, this is used as settingValue |

### Upsert Behavior Details {#upsert-behavior}

The upsert methods follow these rules:

1. **New record**: If no existing record is found, creates a new one (version starts at 0)
2. **Existing record with changes**: If the record exists and the input differs, updates it using the existing version number
3. **Existing record unchanged**: If the record exists and the input is identical, skips the update and returns the existing data
4. **Deleted record**: If the record exists but is marked as deleted (`isDeleted: true`), recreates it using the existing version number

### Legacy Upsert Pattern {#legacy-upsert-pattern}

:::warning Deprecated Pattern
The custom upsert pattern below was required in versions prior to 1.1.2. For new projects, use the [built-in upsert methods](#upsert-pattern) instead.
:::

For versions prior to 1.1.2, implement a custom upsert service that checks for existing records before deciding whether to call create or update. See the [v1.1.1 documentation](https://github.com/mbc-net/mbc-cqrs-serverless/tree/v1.1.1) for the full legacy pattern.


## Related Documentation

- [Tenant](/docs/tenant) - Tenant management
- [Configuring](/docs/configuring) - Sequence rotation settings
- [Service Patterns](/docs/service-patterns) - Master data service patterns
- [Master Web](/docs/master-web) - Frontend master data management


---

## Notification

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/notification-module

# Notification

The NotificationModule provides two types of notification capabilities in the MBC CQRS Serverless framework:

- **Real-time notifications** via AWS AppSync for WebSocket-based updates
- **Email notifications** via AWS SES for sending emails

## Architecture {#architecture}

```mermaid
graph TB
    subgraph "Real-time Notifications"
        A["DynamoDB Stream"] --> B["NotificationEventHandler"]
        B --> C["AppSyncService\n(GraphQL Subscription)"]
        B --> C2["AppSyncEventsService\n(Events API, opt-in)"]
        C --> D["AppSync GraphQL"]
        C2 --> D2["AppSync Events API"]
        D --> E["WebSocket Clients"]
        D2 --> E
    end

    subgraph "Email Notifications"
        F["Application Code"] --> G["EmailService"]
        G --> H["AWS SES"]
        H --> I["Email Recipients"]
    end
```

## Real-time Notifications {#real-time-notifications}

### Overview

Real-time notifications are automatically sent when data changes occur in DynamoDB. The system uses AWS AppSync to deliver notifications to subscribed WebSocket clients.

### INotification Interface

The notification payload structure:

```ts
interface INotification {
  id: string;        // Unique notification ID
  table: string;     // Source DynamoDB table name
  pk: string;        // Partition key of the changed item
  sk: string;        // Sort key of the changed item
  tenantCode: string; // Tenant code for filtering notifications
  action: string;    // Type of change: 'INSERT', 'MODIFY', 'REMOVE'
  content?: object;  // Optional payload with changed data
}
```

### AppSyncService

The `AppSyncService` sends real-time notifications to AppSync for WebSocket delivery.

#### Method: `sendMessage(msg: INotification): Promise<void>`

Sends a notification to AppSync via GraphQL mutation. The notification is delivered to all subscribed WebSocket clients.

:::info Version Note
The return type of `sendMessage` changed from `Promise<any>` to `Promise<void>` in [version 1.3.0](/docs/changelog#v130). If your tests mock this method with `mockResolvedValue(null)`, update them to `mockResolvedValue(undefined)`. See the [v1.3.0 migration guide](/docs/migration/v1.3.0) for details.
:::

```ts
await this.appSyncService.sendMessage({
  id: "unique-id",
  table: "my-table",
  pk: "ITEM#tenant1",
  sk: "ITEM#001",
  tenantCode: "tenant1",
  action: "MODIFY",
  content: { status: "updated" },
});
```

#### Configuration

Set the following environment variables:

```bash
APPSYNC_ENDPOINT=https://xxxxx.appsync-api.ap-northeast-1.amazonaws.com/graphql
APPSYNC_API_KEY=da2-xxxxxxxxxx  # Optional: Use API key auth instead of IAM
```

#### Usage

```ts
import { Injectable } from "@nestjs/common";
import { AppSyncService, INotification } from "@mbc-cqrs-serverless/core";

@Injectable()
export class MyService {
  constructor(private readonly appSyncService: AppSyncService) {}

  async notifyClients() {
    const notification: INotification = {
      id: "notification-123",
      table: "my-table",
      pk: "ITEM#tenant1",
      sk: "ITEM#item001",
      tenantCode: "tenant1",
      action: "MODIFY",
      content: { status: "updated" },
    };

    await this.appSyncService.sendMessage(notification);
  }
}
```

#### Authentication

The AppSyncService supports two authentication methods:

1. **API Key**: Set `APPSYNC_API_KEY` environment variable
2. **IAM Signature V4**: Used automatically when API key is not set

### Automatic Notifications

The framework automatically sends notifications when data changes through:

1. DynamoDB Streams trigger the `NotificationEventHandler`
2. Handler extracts change information and creates `INotification`
3. `AppSyncService.sendMessage()` delivers to AppSync
4. Connected clients receive updates via WebSocket subscription

### NotificationEvent

The `NotificationEvent` class represents a notification event from SQS. It implements `IEvent` and wraps an SQS record containing notification data.

```ts
import { NotificationEvent } from "@mbc-cqrs-serverless/core";

class NotificationEvent implements IEvent, SQSRecord {
  source: string;
  messageId: string;
  receiptHandle: string;
  body: string;              // JSON string containing INotification data
  attributes: SQSRecordAttributes;
  messageAttributes: SQSMessageAttributes;
  md5OfBody: string;
  eventSource: string;
  eventSourceARN: string;
  awsRegion: string;

  // Creates a NotificationEvent from an SQS record
  fromSqsRecord(record: SQSRecord): NotificationEvent;
}
```

### NotificationEventHandler

The `NotificationEventHandler` is the built-in event handler that processes `NotificationEvent` and sends notifications to AppSync. It is automatically registered when using the notification module.

```ts
import { EventHandler, IEventHandler, NotificationEvent } from "@mbc-cqrs-serverless/core";

@EventHandler(NotificationEvent)
export class NotificationEventHandler implements IEventHandler<NotificationEvent> {
  async execute(event: NotificationEvent): Promise<void> {
    // Parses the notification from event body
    // Sends to AppSync via sendMessage()
  }
}
```

You typically don't need to interact with this handler directly - it works automatically when notifications are published to the SQS queue.

## AppSync Events API (opt-in) {#appsync-events-service}

:::info Version Note
`AppSyncEventsService` and dual-publish support were added in [version 1.3.0](/docs/changelog#v130).
:::

### Overview

The `AppSyncEventsService` provides an alternative (or complementary) real-time transport based on the **AWS AppSync Events API** — a schema-free HTTP pub/sub service. Unlike the GraphQL Subscription transport, it requires no GraphQL schema and clients subscribe using wildcard channel paths.

Opt in by setting `NOTIFICATION_TRANSPORTS=appsync-event`. When `NOTIFICATION_TRANSPORTS=appsync-graphql,appsync-event` and both endpoints are set, the framework **dual-publishes** to both transports simultaneously, enabling a zero-downtime migration.

### Method: `sendMessage(msg: INotification): Promise<void>`

Publishes a notification to an AppSync Events channel. The notification is delivered to all subscribed clients.

```ts
await this.appSyncEventsService.sendMessage({
  id: "command-123",
  table: "orders-table",
  pk: "ORDER#tenant1",
  sk: "ORDER#001",
  tenantCode: "tenant1",
  action: "MODIFY",
  content: { status: "confirmed" },
});
```

### Usage

```ts
import { Injectable } from "@nestjs/common";
import { AppSyncEventsService, INotification } from "@mbc-cqrs-serverless/core";

@Injectable()
export class MyService {
  constructor(private readonly appSyncEventsService: AppSyncEventsService) {}

  async notifyClients() {
    const notification: INotification = {
      id: "notification-456",
      table: "my-table",
      pk: "ITEM#tenant1",
      sk: "ITEM#item001",
      tenantCode: "tenant1",
      action: "MODIFY",
      content: { status: "updated" },
    };

    await this.appSyncEventsService.sendMessage(notification);
  }
}
```

### Channel Structure

Every notification is published to a single most-specific channel. Clients subscribe at whatever level of granularity they need using the AppSync Events wildcard (`/*`):

```text
/{namespace}/{tenantCode}/{action}/{sanitizedId}
  seg 1        seg 2       seg 3    seg 4
```

| Client goal | Subscribe to |
|-----------------|-----------------|
| All events for a tenant | `/{namespace}/{tenantCode}/*` |
| Filtered by action | `/{namespace}/{tenantCode}/{action}/*` |
| Track one specific command | `/{namespace}/{tenantCode}/{action}/{sanitizedId}` |

### Configuration

```bash
# Enable the Events API transport (Events API only)
NOTIFICATION_TRANSPORTS=appsync-event
APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
# Optional: must match a pre-created namespace in your AppSync Event API
APPSYNC_EVENTS_NAMESPACE=default
```

See [AppSync Events Environment Variables](/docs/environment-variables#appsync-events-env) for the full reference.

### Migration from GraphQL Subscription

Use the dual-publish mode to migrate clients gradually without downtime:

**Phase 1 — Dual-publish (both transports active):**
```bash
NOTIFICATION_TRANSPORTS=appsync-graphql,appsync-event
APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
APPSYNC_EVENTS_NAMESPACE=default
APPSYNC_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/graphql  # still set
```

**Phase 2 — Events API only (after all clients have migrated):**
```bash
NOTIFICATION_TRANSPORTS=appsync-event
APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
APPSYNC_EVENTS_NAMESPACE=default
# APPSYNC_ENDPOINT removed
```

### CDK Infrastructure

Add `appsyncEvents` to your `Config` to provision the `EventApi` and `ChannelNamespace` automatically:

```typescript
// infra/config/config.ts
export const config: Config = {
  // ...
  appsyncEvents: {
    enabled: true,
    namespace: 'default',       // optional, defaults to 'default'
    apiKeyExpireDays: 365,      // optional, defaults to 365
  },
}
```

The CDK stack will output `AppSyncEventsHttpEndpoint` and `AppSyncEventsNamespace`, and will automatically inject `NOTIFICATION_TRANSPORTS`, `APPSYNC_EVENTS_ENDPOINT`, and `APPSYNC_EVENTS_NAMESPACE` into Lambda and ECS.

### Authentication

The `AppSyncEventsService` supports two authentication methods for publishing:

1. **IAM SigV4 (recommended for Lambda/ECS)**: Used automatically for publishing. Lambda and ECS task roles are granted `appsync:EventPublish` by the CDK stack via `grantPublish()`.
2. **API Key**: Used by browser clients for subscribing. Set in the client (e.g., Amplify `apiKey` config). Not required on the server side.

### Client-Side Subscription (Browser) {#client-side-subscription}

Browser clients subscribe to AppSync Events channels using the AWS Amplify v6 `events` API. The channel path determines which notifications you receive — use the `/*` wildcard to subscribe at any granularity.

#### Setup with AWS Amplify v6

```bash
npm install aws-amplify
```

```typescript
import { Amplify } from 'aws-amplify';
import { events } from 'aws-amplify/data';

// Configure Amplify once at app startup (e.g., in _app.tsx or main.ts)
Amplify.configure({
  API: {
    Events: {
      endpoint: 'https://YOUR_APPSYNC_EVENTS_ENDPOINT/event',
      region: 'ap-northeast-1',
      defaultAuthMode: 'apiKey',
      apiKey: 'YOUR_API_KEY',  // Output by CDK as AppSyncEventsApiKey
    },
  },
});
```

#### Subscribe to Notifications

```typescript
interface INotification {
  id: string;
  table: string;       // e.g., "dev-myapp-order-data"
  pk: string;          // Partition key of the changed item
  sk: string;          // Sort key of the changed item
  tenantCode: string;
  action: string;      // INSERT | MODIFY | REMOVE
  content?: object;    // Optional change payload
}

// Subscribe to all notifications for a tenant
const channel = await events.connect('/default/tenant001/*');

const subscription = channel.subscribe({
  next: ({ data }: { data: INotification }) => {
    console.log(`${data.action} on ${data.table}: pk=${data.pk}`);
    // Refresh UI or update local state
  },
  error: (err) => {
    console.error('Subscription error:', err);
  },
});

// Unsubscribe when the component unmounts
subscription.unsubscribe();
```

#### React Hook Example

```typescript
import { useEffect, useRef } from 'react';
import { events } from 'aws-amplify/data';

function useOrderNotifications(tenantCode: string, orderId: string) {
  const subscriptionRef = useRef<{ unsubscribe(): void } | null>(null);

  useEffect(() => {
    // Subscribe to a specific order
    const channel = `/default/${tenantCode}/MODIFY/${orderId.replace(/#/g, '_')}`;

    events.connect(channel).then((conn) => {
      subscriptionRef.current = conn.subscribe({
        next: ({ data }) => {
          console.log('Order updated:', data);
          // Trigger a refetch or update local state
        },
        error: (err) => console.error(err),
      });
    });

    return () => {
      subscriptionRef.current?.unsubscribe();
    };
  }, [tenantCode, orderId]);
}
```

:::tip Channel Path Format
The sanitized item ID in the channel path replaces `#` with `_`. For example, `ORDER#ORD001` becomes `ORDER_ORD001`. Use `sk.replace(/#/g, '_')` on the client side to compute the exact channel path.
:::

## Custom Notification Transports (opt-in) {#custom-transports}

:::info Version Note
The `@NotificationTransport` decorator for custom transports was added in [version 1.3.0](/docs/changelog#v130).
:::

You can register custom notification transports to publish to any external system (e.g., Slack, PagerDuty, custom WebSocket servers) without modifying framework code.

### Implementing a Custom Transport

```typescript
import {
  INotificationTransport,
  INotification,
  NotificationTransport,
} from '@mbc-cqrs-serverless/core';

// Do not add @Injectable() — @NotificationTransport() already registers a singleton provider
@NotificationTransport()
export class SlackNotificationTransport implements INotificationTransport {
  async sendMessage(msg: INotification): Promise<void> {
    // Send notification to Slack or any custom endpoint
    await fetch(process.env.SLACK_WEBHOOK_URL, {
      method: 'POST',
      body: JSON.stringify({ text: `Change in ${msg.table}: ${msg.action}` }),
    });
  }
}
```

:::warning Transport Registration Guidelines
- **Do not add `@Injectable()`** on the same class — `@NotificationTransport()` already registers it as a singleton provider. Using both annotations causes a DI scope conflict (AP026).
- **Register in module `providers`**: Add the class to your module's `providers` array.
- **Failures propagate**: Errors thrown in `sendMessage` are not swallowed by the framework. Implement retry/fallback logic inside the transport class.
:::

### Selecting Transports

Active transports are controlled by the `NOTIFICATION_TRANSPORTS` environment variable (comma-separated). Custom transports are always active alongside any built-in transports. Set the env var to control which built-in transports are active:

```bash
NOTIFICATION_TRANSPORTS=appsync-graphql  # Only GraphQL Subscriptions (default)
NOTIFICATION_TRANSPORTS=appsync-event    # Only Events API
NOTIFICATION_TRANSPORTS=appsync-graphql,appsync-event  # Both built-in transports
```

## Email Notifications {#email-notifications}

### EmailService

The `EmailService` sends emails using AWS SES.

#### Configuration

```bash
SES_FROM_EMAIL=noreply@your-domain.com  # Required: Default sender address
SES_REGION=ap-northeast-1                # Optional: SES region
SES_ENDPOINT=                            # Optional: Custom endpoint for LocalStack
```

#### Basic Usage

```ts
import { Injectable } from "@nestjs/common";
import { EmailService, EmailNotification } from "@mbc-cqrs-serverless/core";

@Injectable()
export class MyService {
  constructor(private readonly emailService: EmailService) {}

  async sendWelcomeEmail(userEmail: string) {
    const email: EmailNotification = {
      toAddrs: [userEmail],
      subject: "Welcome to Our Service",
      body: "<h1>Welcome!</h1><p>Thank you for signing up.</p>",
    };

    await this.emailService.sendEmail(email);
  }
}
```

#### Email with Attachments

```ts
import { EmailNotification, Attachment } from "@mbc-cqrs-serverless/core";
import * as fs from "fs";

const pdfBuffer = fs.readFileSync("report.pdf");

const email: EmailNotification = {
  toAddrs: ["user@example.com"],
  subject: "Monthly Report",
  body: "<p>Please find attached your monthly report.</p>",
  attachments: [
    {
      filename: "report.pdf",
      content: pdfBuffer,
      contentType: "application/pdf",
    },
  ],
};

await this.emailService.sendEmail(email);
```

### Inline Template Emails {#inline-template-emails}

The `sendInlineTemplateEmail()` method allows you to send templated emails with dynamic data substitution, without requiring pre-registered SES templates.

:::info Version Note
Inline template emails (`sendInlineTemplateEmail()`) were added in [version 1.0.23](/docs/changelog#v1023).
:::

#### Basic Usage

```ts
import { Injectable } from "@nestjs/common";
import { EmailService, TemplatedEmailNotification } from "@mbc-cqrs-serverless/core";

@Injectable()
export class MyService {
  constructor(private readonly emailService: EmailService) {}

  async sendWelcomeEmail(user: { name: string; email: string }) {
    const notification: TemplatedEmailNotification = {
      toAddrs: [user.email],
      template: {
        subject: "Welcome, {{name}}!",
        html: "<h1>Hello {{name}}</h1><p>Welcome to our service!</p>",
        text: "Hello {{name}}, Welcome to our service!", // Optional plain text version
      },
      data: {
        name: user.name,
      },
    };

    await this.emailService.sendInlineTemplateEmail(notification);
  }
}
```

#### Template Syntax

Templates use `{{variableName}}` placeholders that are replaced with values from the `data` object:

```ts
const notification: TemplatedEmailNotification = {
  toAddrs: ["user@example.com"],
  template: {
    subject: "Order {{orderId}} Confirmation",
    html: `
      <h1>Thank you, {{customerName}}!</h1>
      <p>Your order #{{orderId}} has been confirmed.</p>
      <p>Total: {{currency}}{{totalAmount}}</p>
    `,
  },
  data: {
    customerName: "John Doe",
    orderId: "12345",
    currency: "$",
    totalAmount: "99.99",
  },
};
```

#### Advanced Template Features {#advanced-template-features}

:::info Version Note
Nested property access and Unicode key support were added in [version 1.0.25](/docs/changelog#v1025).
:::

##### Nested Property Access

You can access nested object properties using dot notation:

```ts
const notification: TemplatedEmailNotification = {
  toAddrs: ["user@example.com"],
  template: {
    subject: "Welcome {{user.profile.firstName}}!",
    html: `
      <p>Hello {{user.profile.firstName}} {{user.profile.lastName}},</p>
      <p>Your verification code is: {{auth.otp}}</p>
    `,
  },
  data: {
    user: {
      profile: {
        firstName: "John",
        lastName: "Doe",
      },
    },
    auth: {
      otp: "123456",
    },
  },
};
```

##### Unicode and Japanese Key Support

Template variables support Unicode characters, including Japanese keys:

```ts
const notification: TemplatedEmailNotification = {
  toAddrs: ["user@example.com"],
  template: {
    subject: "{{注文.確認番号}} - Order Confirmation",
    html: `
      <p>{{顧客.名前}} 様</p>
      <p>ご注文番号: {{注文.確認番号}}</p>
      <p>商品: {{注文.詳細.品名}}</p>
    `,
  },
  data: {
    "顧客": {
      "名前": "山田 太郎",
    },
    "注文": {
      "確認番号": "ORD-2024-001",
      "詳細": {
        "品名": "ワイヤレスイヤホン",
      },
    },
  },
};
```

##### Whitespace in Placeholders

Whitespace inside placeholders is automatically trimmed, so a placeholder with surrounding spaces is equivalent to one without (see the example below):

```ts
// Both of these work identically
template: {
  subject: "Hello {{ name }}!",  // Whitespace is trimmed
  html: "<p>Hello {{name}}!</p>", // No whitespace
}
```

##### Missing Variables

If a variable is not found in the data object, the placeholder is preserved in the output. This helps identify missing data during development:

```ts
// If 'missingKey' is not in data, the placeholder is preserved as-is
template: {
  html: "<p>Value: {{missingKey}}</p>",
}
```

##### Limitations

The following limitations apply to template variable names (for security reasons):

| Limitation | Value | Reason |
|----------------|-----------|------------|
| Maximum variable name length | 255 characters | Prevents ReDoS (Regular Expression Denial of Service) attacks |

Variable names exceeding 255 characters will not be replaced and will remain as literal placeholders in the output.

#### TemplatedEmailNotification Interface

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `fromAddr` | `string` | No | Sender email (uses SES_FROM_EMAIL if not set) |
| `toAddrs` | `string[]` | Yes | List of recipient email addresses |
| `ccAddrs` | `string[]` | No | CC recipients |
| `bccAddrs` | `string[]` | No | BCC recipients |
| `replyToAddrs` | `string[]` | No | Reply-to addresses |
| `template` | `InlineTemplateContent` | Yes | Template with subject, HTML, and optional text |
| `data` | `Record<string, any>` | Yes | Data object for template variable substitution |
| `configurationSetName` | `string` | No | SES configuration set name for tracking |
| `emailTags` | `EmailTag[]` | No | Tags for email categorization (SES Email Tags) |

#### InlineTemplateContent Interface

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `subject` | `string` | Yes | Email subject line (supports template variables) |
| `html` | `string` | Yes | HTML body (supports template variables) |
| `text` | `string` | No | Plain text body (supports template variables) |

#### Local Development

When running locally without SES access, the method automatically falls back to manual template compilation, allowing you to test email flows during development.

#### EmailNotification Interface

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `fromAddr` | `string` | No | Sender email (uses SES_FROM_EMAIL if not set) |
| `toAddrs` | `string[]` | Yes | List of recipient email addresses |
| `ccAddrs` | `string[]` | No | CC recipients |
| `bccAddrs` | `string[]` | No | BCC recipients |
| `subject` | `string` | Yes | Email subject line |
| `body` | `string` | Yes | Email body as HTML |
| `replyToAddrs` | `string[]` | No | Reply-to addresses |
| `attachments` | `Attachment[]` | No | File attachments |
| `emailTags` | `EmailTag[]` | No | Tags for email categorization (SES Email Tags) |

### Email Tags {#email-tags}

Email tags allow you to categorize and track emails sent through AWS SES. Tags are useful for filtering emails in SES analytics, CloudWatch, and event destinations.

:::info Version Note
EmailTags support was added in [version 1.1.0](/docs/changelog#v110).
:::

#### Basic Usage

```ts
import { EmailService, EmailNotification, EmailTag } from "@mbc-cqrs-serverless/core";

const email: EmailNotification = {
  toAddrs: ["user@example.com"],
  subject: "Order Confirmation",
  body: "<p>Your order has been confirmed.</p>",
  emailTags: [
    { name: "category", value: "order-confirmation" },
    { name: "tenant", value: "tenant-123" },
    { name: "environment", value: "production" },
  ],
};

await this.emailService.sendEmail(email);
```

#### EmailTag Interface

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `name` | `string` | Yes | Tag name (e.g., 'category', 'campaign') |
| `value` | `string` | Yes | Tag value for categorization |

#### Use Cases

- **Campaign tracking**: Tag emails by marketing campaign to analyze performance
- **Tenant isolation**: Tag by tenant code for multi-tenant email analytics
- **Email type categorization**: Distinguish transactional emails from promotional ones
- **Environment tagging**: Track emails across development, staging, and production

#### Attachment Interface

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `filename` | `string` | Yes | Filename shown to recipient |
| `content` | `Buffer` | Yes | File content as Buffer |
| `contentType` | `string` | No | MIME type (e.g., 'application/pdf') |

## Related Documentation

- [Email Service](/docs/email-service) - SES email sending
- [Event Handling Patterns](/docs/event-handling-patterns) - How notifications integrate with events
- [Environment Variables](/docs/environment-variables) - AppSync and SES configuration
- [Queue](/docs/queue) - SQS for notification queuing
- [Common Issues — AppSync Events API not publishing](/docs/common-issues#appsync-events-not-publishing) - Troubleshooting AppSync Events API


---

## Sequence

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/sequence

# Sequence

## 1. Purpose {#purpose}

`SequencesModule` is a service for managing dynamic sequences in the system using DynamoDB as the primary database.

This service is designed to:

- Generate unique sequence numbers based on parameters such as sequence type, tenant, or date.
- Automatically reset sequences based on cycles like:
  - Daily.
  - Monthly.
  - Yearly.
  - Fiscal Yearly.

Format sequence numbers according to specific system requirements (e.g., TODO-PERSONAL-72-001).
Ensure data consistency and integrity in multi-tenant systems.

## How It Works {#how-it-works}

```mermaid
sequenceDiagram
    participant Client
    participant SequencesService
    participant DynamoDB

    Client->>SequencesService: generateSequenceItem(dto)
    SequencesService->>DynamoDB: UpdateItem ADD counter 1
    Note over DynamoDB: Atomic increment
    DynamoDB-->>SequencesService: New counter value
    SequencesService->>SequencesService: Format ID with pattern
    SequencesService-->>Client: SequenceEntity
```

## 2. Usage {#usage}


The solution for customizing the behavior of the `SequencesModule` is to pass it an options `object` in the static `register()` method. The options object contains only one property:

- `enableController`: enable or disable default sequence controller.

We will create a simple example demonstrating how to use the sequence module and customize authentication for the sequence controller.

```ts
// seq.controller.ts
import { SequencesController } from "@mbc-cqrs-serverless/sequence";
import { Controller } from "@nestjs/common";
import { ApiTags } from "@nestjs/swagger";
import { Auth } from "src/auth/auth.decorator";
import { ROLE } from "src/auth/role.enum";

@Controller("api/sequence")
@ApiTags("sequence")
@Auth(ROLE.ADMIN)
export class SeqController extends SequencesController {}
```

```ts
// seq.module.ts
import { SequencesModule } from "@mbc-cqrs-serverless/sequence";
import { Module } from "@nestjs/common";

import { SeqController } from "./seq.controller";

@Module({
  imports: [SequencesModule.register({ enableController: false })],
  controllers: [SeqController],
  exports: [SequencesModule],
})
export class SeqModule {}
```

Besides the controller, we can directly use `SequencesService` to generate sequences by injecting the service.

The `SequencesService` has four public methods (two current, one deprecated, one removed in v1.1.0):

### *async* `generateSequenceItem(dto: GenerateFormattedSequenceDto, options?: {invokeContext: IInvoke}): Promise<SequenceEntity>` {#generate-sequence-item}


Generates a new sequence based on the parameters provided in the GenerateFormattedSequenceDto object.

#### Parameters

`dto: GenerateFormattedSequenceDto`
The data transfer object that customizes the behavior of the sequence generation. Its properties include:

- `date?: Date`
  - Default: Current date.
  - Description: Specifies the date for which the sequence is generated.

- `rotateBy?: RotateByEnum`
  - Default: NONE.
  - Options
    - FISCAL_YEARLY (`'fiscal_yearly'`)
    - YEARLY (`'yearly'`)
    - MONTHLY (`'monthly'`)
    - DAILY (`'daily'`)
    - NONE (`'none'`)
  - Description: Determines when the sequence counter resets to 1.
  - Rotation strategy reference:

    | Strategy | Counter resets when | Example |
    |---|---|---|
    | `NONE` | Never — counter increments indefinitely | `1, 2, 3, … 9999` |
    | `DAILY` | The calendar date changes | Resets each midnight |
    | `MONTHLY` | The calendar month changes | Resets on the 1st of each month |
    | `YEARLY` | The calendar year changes | Resets every January 1st |
    | `FISCAL_YEARLY` | The fiscal year changes (start month controlled by `startMonth`) | Resets at fiscal year start; defaults to April (Japanese convention) |

- `tenantCode: string`
  - Required: Yes.
  - Description: Identifies the tenant and type code for the intended usage.

- `typeCode: string`
  - Required: Yes.
  - Description: Identifies the type code for the sequence.
  
- `params?: SequenceParamsDto`
  - Required: No.
  - Description: Defines parameters to identify the sequence.
    ```ts
    import { IsString, IsOptional } from 'class-validator';

    export class SequenceParamsDto {
      @IsString()
      code1: string

      @IsString()
      @IsOptional()
      code2?: string

      @IsOptional()
      @IsString()
      code3?: string

      @IsOptional()
      @IsString()
      code4?: string

      @IsOptional()
      @IsString()
      code5?: string

      constructor(partial: Partial<SequenceParamsDto>) {
        Object.assign(this, partial)
      }
    }
    ```

- `prefix?: string`
  - Required: No.
  - Description: Optional prefix to prepend to the formatted sequence. The prefix is added before the formatted pattern.
  - Example: If prefix is `'INV-'` and format produces `'2024-001'`, the result will be `'INV-2024-001'`.

- `postfix?: string`
  - Required: No.
  - Description: Optional postfix to append to the formatted sequence. The postfix is added after the formatted pattern.
  - Example: If postfix is `'-DRAFT'` and format produces `'2024-001'`, the result will be `'2024-001-DRAFT'`.

####  Response
The return value of this function is of type `SequenceEntity` as follows:
  ```ts
  export class SequenceEntity {
    id: string
    no: number
    formattedNo: string
    issuedAt: Date

    constructor(partial: Partial<SequenceEntity>) {
      Object.assign(this, partial)
    }
  }
  ```

####  Customizable
By default, the returned data includes the formattedNo field with the format `%%no%%`, where `no` represents the sequence number. If you want to define your own custom format, you can update the master data in DynamoDB with the following parameters:

- PK: `MASTER${KEY_SEPARATOR}${tenantCode}`
- SK: `MASTER_DATA${KEY_SEPARATOR}${typeCode}`


The data structure should be as follows:
  ```json
    {
      "format": "string",
      "startMonth": "number",
      "registerDate": "string"
    }
  ```

#### Example

For example, if you want to add `code1` to `code5`, `year`, `month`, `day`, `date`, `no` as well as `fiscal_year`, into your format, the format would look like this:
```json
{
  "format": "%%code2#:0>7%%-%%fiscal_year#:0>2%%-%%code3%%%%no#:0>3%%"
} 
```
In this format:
- Variables are written inside `%% <param> %%.`
- The `#:0>N` suffix pads the value to `N` characters wide with leading zeros (e.g., `#:0>3` turns `5` into `005`). Omit the suffix to use the value as-is.

Format spec reference:

| Suffix | Meaning | Input `5` | Result |
|---|---|---|---|
| (none) | No padding — raw value | `5` | `5` |
| `#:0>3` | Pad to width 3 with leading zeros | `5` | `005` |
| `#:0>7` | Pad to width 7 with leading zeros | `5` | `0000005` |

For instance:

- `%%code2#:0>7%%` ensures code2 is formatted to be 7 characters long, padding with leading zeros if necessary.
- `%%fiscal_year#:0>2%% `formats fiscal_year to a length of 2 characters.
- `%%code3%%` represents the code3 value as it is.
- `%%no#:0>3%%` ensures the sequence number (no) is formatted to be 3 digits long, padded with leading zeros if necessary.

If you want to calculate the fiscal_year starting from any specific month, you can add the `startMonth` field. For example, if you want the fiscal year to start from March, the format would look like this:
```json
{
  "format": "%%code2#:0>7%%-%%fiscal_year#:0>2%%-%%code3%%%%no#:0>3%%",
  "startMonth": 3
}
```
In this case:
- startMonth: Defines the month to start the fiscal year (e.g., 3 for March). Defaults to 4 (April), following the Japanese fiscal year convention (April–March).

If you want to calculate the fiscal year starting from a specific date (e.g. 2005-01-01), you can add the `registerDate` field, like this:

```json
{
  "format": "%%code2#:0>7%%-%%fiscal_year#:0>2%%-%%code3%%%%no#:0>3%%",
  "registerDate": "2005-01-01"
}
```

In this case:
- registerDate: Defines the exact start date of the fiscal year (e.g., "2005-01-01").

This allows you to customize the fiscal year calculation according to your specific business needs.

### *async* `generateSequenceItemWithProvideSetting(dto: GenerateFormattedSequenceWithProvidedSettingDto, options?: {invokeContext: IInvoke}): Promise<SequenceEntity>` {#generate-sequence-item-with-provide-setting}

This method allows you to generate a sequence with custom settings directly provided in the DTO, without requiring master data configuration in DynamoDB.

#### Parameters

`dto: GenerateFormattedSequenceWithProvidedSettingDto`
The data transfer object that contains both sequence parameters and format settings. Its properties include:

- `date?: Date`
  - Default: Current date.
  - Description: Specifies the date for which the sequence is generated.

- `rotateBy?: RotateByEnum`
  - Default: NONE.
  - Options: FISCAL_YEARLY, YEARLY, MONTHLY, DAILY, NONE
  - Description: Determines when the sequence counter resets. See the rotation strategy table in `generateSequenceItem` above.

- `tenantCode: string`
  - Required: Yes.
  - Description: Identifies the tenant for the sequence.

- `typeCode: string`
  - Required: Yes.
  - Description: Identifies the type code for the sequence.

- `params?: SequenceParamsDto`
  - Required: No.
  - Description: Defines parameters to identify the sequence (code1 to code5).

- `prefix?: string`
  - Required: No.
  - Description: Optional prefix to prepend to the formatted sequence.

- `postfix?: string`
  - Required: No.
  - Description: Optional postfix to append to the formatted sequence.

- `format: string`
  - Required: Yes.
  - Description: Format string defining the structure of the generated sequence. Example: `%%code1%%-%%no#:0>5%%`.

- `registerDate?: string`
  - Required: No.
  - Description: Optional registration date (ISO 8601 format) to influence fiscal year calculation.

- `startMonth?: number`
  - Required: No.
  - Description: Starting month of the fiscal year (1-12). Defaults to 4 (April) if not provided.

#### Example

```ts
import { RotateByEnum } from "@mbc-cqrs-serverless/sequence";

const result = await this.sequencesService.generateSequenceItemWithProvideSetting(
  {
    tenantCode: 'tenant001',
    typeCode: 'INVOICE',
    format: '%%code1%%-%%no#:0>5%%',
    rotateBy: RotateByEnum.YEARLY,
    params: { code1: 'INV' },
  },
  { invokeContext },
);
// Returns: { formattedNo: 'INV-00001', no: 1, ... }
```

Use this method when you need dynamic sequence settings that vary per request rather than fixed master data configuration.

Example with prefix and postfix:

```ts
import { RotateByEnum } from "@mbc-cqrs-serverless/sequence";

const result = await this.sequencesService.generateSequenceItemWithProvideSetting(
  {
    tenantCode: 'tenant001',
    typeCode: 'ORDER',
    format: '%%fiscal_year%%-%%no#:0>4%%',
    rotateBy: RotateByEnum.FISCAL_YEARLY,
    startMonth: 4,
    params: { code1: 'ORD' },
    prefix: 'ORD-',    // Prepended to formatted sequence
    postfix: '-DRAFT', // Appended to formatted sequence
  },
  { invokeContext },
);
// Returns: { formattedNo: 'ORD-2024-0001-DRAFT', no: 1, ... }
```

### *async* `getCurrentSequence(key: DetailKey): Promise<DataEntity>` <span class="badge badge--warning">deprecated</span>

:::info

Deprecated, for removal: This API element is subject to removal in a future version.

:::

### *async* `genNewSequence( dto: GenerateSequenceDto, options: {invokeContext: IInvoke}): Promise<DataEntity>` <span class="badge badge--danger">removed</span> {#gen-new-sequence-removed}

:::danger Removed in v1.1.0

This method was removed in [v1.1.0](/docs/changelog#v110). Use [`generateSequenceItem`](#generate-sequence-item) or [`generateSequenceItemWithProvideSetting`](#generate-sequence-item-with-provide-setting) instead.

:::


## Related Documentation

- [Configuring](/docs/configuring) - SequencesModule configuration options
- [Master](/docs/master) - Master data settings for sequence format
- [Key Patterns](/docs/key-patterns) - PK/SK design using sequences as sort keys
- [Build a Todo App](/docs/build-todo-app) - Practical example using sequences
- [Interfaces](/docs/interfaces) - SequencesModuleOptions interface


---

## Serialization Helpers

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/serialization

# Serialization Helpers

## Overview {#overview}
The MBC CQRS Serverless Framework provides helper functions for converting between internal DynamoDB structures and external flat structures. These helpers ensure consistent data transformation while maintaining type safety.
## Data Structure Conversion {#data-structure-conversion}

### Internal DynamoDB Structure
```typescript
{
  pk: "PROJECT#tenant001",
  sk: "proj-001",
  name: "Test Project",
  attributes: {
    details: {
      status: "active",
      category: "development"
    }
  }
}
```

### External Flat Structure
```typescript
{
  id: "PROJECT#tenant001#proj-001",  // Combination of pk and sk
  code: "proj-001",                   // Same as sk
  name: "Test Project",               // First level in DynamoDB
  details: {                          // Flattened from attributes
    status: "active",
    category: "development"
  }
}
```

## Usage {#usage}

### Converting Internal to External Format
```typescript
import { serializeToExternal } from '@mbc-cqrs-serverless/core';

const internal = {
  pk: "PROJECT#tenant001",
  sk: "proj-001",
  name: "Test Project",
  attributes: {
    details: {
      status: "active",
      category: "development"
    }
  }
};

const external = serializeToExternal(internal);
```

### Converting External to Internal Format
```typescript
import { deserializeToInternal, DataEntity } from '@mbc-cqrs-serverless/core';

const external = {
  id: "PROJECT#tenant001#proj-001",
  code: "proj-001",
  name: "Test Project",
  details: {
    status: "active",
    category: "development"
  }
};

// Use DataEntity for data table entities, CommandEntity for command table entities
const internal = deserializeToInternal(external, DataEntity);
```

:::tip Fallback Behavior
When deserializing, if the `id` field doesn't contain the `#` separator to split into `pk` and `sk`, the `code` field is used as the `sk` value. Any fields not in the metadata field list are automatically placed in the `attributes` object.
:::

## API Reference {#api-reference}

### serializeToExternal
```typescript
function serializeToExternal<T extends CommandEntity | DataEntity>(
  item: T | null | undefined,
  options?: SerializerOptions
): Record<string, any> | null

interface SerializerOptions {
  keepAttributes?: boolean;  // Reserved for future use
  flattenDepth?: number;     // Reserved for future use
}
```

Parameters:
- `item`: Internal entity (CommandEntity or DataEntity).
- `options`: Optional serialization options (reserved for future use).

Returns:
- Flattened external structure or null if input is null/undefined

:::note
The `SerializerOptions` interface is defined for future extensibility but is not currently used by the function. The function always flattens attributes to the top level.
:::

### deserializeToInternal
```typescript
function deserializeToInternal<T extends CommandEntity | DataEntity>(
  data: Record<string, any> | null | undefined,
  EntityClass: new () => T
): T | null
```

Parameters:
- `data`: External flat structure
- `EntityClass`: Entity class to instantiate (CommandEntity or DataEntity)

Returns:
- Internal entity instance or null if input is null/undefined

## Field Mapping {#field-mapping}

### Metadata Fields
| Field | Description |
|-------|-------------|
| id | Primary key |
| cpk | Command table primary key|
| csk | Command table sort key |
| pk | Data table primary key |
| sk | Data table sort key |
| tenantCode | Tenant code |
| type | Entity type (embedded in pk, e.g., "PROJECT") |
| seq | Sort order |
| code | Code (may be used as part of sk) |
| name | Name |
| version | Version number |
| isDeleted | Deletion flag |
| createdBy | Creator's user ID or username |
| createdIp | Creator's IP address |
| createdAt | Creation timestamp |
| updatedBy | Updater's user ID or username (set at creation) |
| updatedIp | Updater's IP address (set at creation) |
| updatedAt | Update timestamp (set at creation). |
| status | Status (for CQRS processing). |
| ttl | DynamoDB TTL timestamp (Unix epoch seconds) |

### Serialization Mapping
| Internal Field | External Field | Description |
|---------------|----------------|-------------|
| pk + sk | id | Combined primary key for unique identification |
| cpk | cpk | Command table primary key |
| csk | csk | Command table sort key |
| pk | pk | Data table primary key |
| sk | sk | Data table sort key |
| sk | code | Sort key used as code identifier |
| tenantCode | tenantCode | Tenant identifier |
| type | type | Entity type (e.g., PROJECT) |
| seq | seq | Sequence number for ordering |
| name | name | Entity name (first level property) |
| version | version | Entity version for optimistic locking |
| isDeleted | isDeleted | Soft delete flag |
| createdBy | createdBy | User ID or name of creator |
| createdIp | createdIp | IP address of creator |
| createdAt | createdAt | Creation timestamp |
| updatedBy | updatedBy | User ID or name of last updater |
| updatedIp | updatedIp | IP address of last updater |
| updatedAt | updatedAt | Last update timestamp |
| status | status | CQRS processing status |
| ttl | ttl | DynamoDB TTL timestamp (Unix epoch seconds) |
| attributes.* | * | Flattened attributes from internal structure |


## Related Documentation

- [Data Service](/docs/data-service) - Using DataService with serialization
- [Entity Patterns](/docs/entity-patterns) - Entity structure for serialization
- [Data Sync Handler Examples](/docs/data-sync-handler-examples) - Sync with deserialization


---

## Task

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/tasks

# Task

The Task package provides comprehensive task management functionality in the MBC CQRS Serverless framework. It enables:

- Asynchronous task execution
- Task status tracking
- Progress monitoring
- Error handling and retries
- Task queue management
- Task history and logging

## Architecture {#architecture}

```mermaid
sequenceDiagram
    participant Client
    participant TaskService
    participant DynamoDB
    participant StepFunctions
    participant Lambda

    Client->>TaskService: createTask() / createStepFunctionTask()
    TaskService->>DynamoDB: Save task (CREATED)
    TaskService->>StepFunctions: Start execution
    StepFunctions-->>TaskService: Execution ARN
    TaskService-->>Client: TaskEntity

    loop For each sub-task
        StepFunctions->>Lambda: Execute sub-task
        Lambda->>DynamoDB: Update status (PROCESSING)
        Lambda->>Lambda: Process
        Lambda->>DynamoDB: Update status (COMPLETED/FAILED)
    end

    StepFunctions->>DynamoDB: Update parent task status
```

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/task
```

## Usage {#usage}

There are 2 types of task processing:

- Single task processing
- Task processing with Step Functions

### Single task processing

1. Define task event

```ts
import { TaskQueueEvent } from "@mbc-cqrs-serverless/task";

export class TaskEvent extends TaskQueueEvent {}
```

2. Define task event handler

```ts
import { EventHandler, IEventHandler } from "@mbc-cqrs-serverless/core";
import { Logger } from "@nestjs/common";

import { TaskEvent } from "./task.event";

@EventHandler(TaskEvent)
export class TaskEventHandler implements IEventHandler<TaskEvent> {
  private readonly logger = new Logger(TaskEventHandler.name);

  constructor() {}

  async execute(event: TaskEvent): Promise<any> {
    this.logger.debug("executing task event::", event);

    //

    this.logger.debug(`Process task completed: ${event.taskEvent.eventID}`);
    return "Result after process";
  }
}
```

3. Implement `ITaskQueueEventFactory`

```ts
import {
  ITaskQueueEventFactory,
  TaskQueueEvent,
} from "@mbc-cqrs-serverless/task";
import { TaskEvent } from "src/sample/handler/task.event";

export class TaskQueueEventFactory implements ITaskQueueEventFactory {
  async transformTask(event: TaskQueueEvent): Promise<any[]> {
    return [new TaskEvent().fromSqsRecord(event)];
  }
}
```

4. Custom `TaskModule`

```ts
import { TaskModule } from "@mbc-cqrs-serverless/task";
import { Module } from "@nestjs/common";
import { TaskEventHandler } from "src/sample/handler/task.handler";

import { TaskQueueEventFactory } from "./task-queue-event-factory";

@Module({
  imports: [
    TaskModule.register({
      taskQueueEventFactory: TaskQueueEventFactory,
      enableController: true, // Optional: enable REST endpoints for task management
    }),
  ],
  providers: [TaskEventHandler],
  exports: [TaskModule],
})
export class CustomTaskModule {}
```

5. Custom `EventFactoryAddedTask`

```ts
import { EventFactory, IEvent } from "@mbc-cqrs-serverless/core";
import { EventFactoryAddedTask, TaskEvent } from "@mbc-cqrs-serverless/task";
import { Logger } from "@nestjs/common";
import { DynamoDBStreamEvent } from "aws-lambda";

@EventFactory()
export class CustomEventFactory extends EventFactoryAddedTask {
  private readonly logger = new Logger(CustomEventFactory.name);
  async transformDynamodbStream(event: DynamoDBStreamEvent): Promise<IEvent[]> {
    const curEvents = await super.transformDynamodbStream(event);
    const taskEvents = event.Records.map((record) => {
      if (
        record.eventSourceARN.endsWith("tasks") ||
        record.eventSourceARN.includes("tasks" + "/stream/")
      ) {
        if (record.eventName === "INSERT") {
          return new TaskEvent().fromDynamoDBRecord(record);
        }
      }
      return undefined;
    })
      .filter((event) => !!event)
      .filter((event) => event.taskEntity.sk.split("#").length < 3);

    return [...curEvents, ...taskEvents];
  }
}
```

6. Create a Task

```ts
const task = await this.taskService.createTask(
  {
    taskType: "data-export",
    tenantCode: "mbc",
    name: "Export user data",
    input: { userId: "123", format: "csv" },
  },
  { invokeContext }
);
```

### Task processing with Step Functions

1. Define Step Functions task event

```ts
import { StepFunctionTaskEvent } from "@mbc-cqrs-serverless/task";

export class SfnTaskEvent extends StepFunctionTaskEvent {}
```

2. Define Step Functions task event handler

```ts
import {
  EventHandler,
  IEventHandler,
} from "@mbc-cqrs-serverless/core";
import { Logger } from "@nestjs/common";

import { SfnTaskEvent } from "./sfn-task.event";

@EventHandler(SfnTaskEvent)
export class SfnTaskEventHandler implements IEventHandler<SfnTaskEvent> {
  private readonly logger = new Logger(SfnTaskEventHandler.name);

  constructor() {}

  async execute(event: SfnTaskEvent): Promise<any> {
    this.logger.debug("executing task event::", event);

    //

    return "Result after process";
  }
}
```

3. Implement `ITaskQueueEventFactory`

```ts
import {
  ITaskQueueEventFactory,
  StepFunctionTaskEvent,
} from "@mbc-cqrs-serverless/task";
import { SfnTaskEvent } from "src/sample/handler/sfn-task.event";

export class TaskQueueEventFactory implements ITaskQueueEventFactory {
  async transformStepFunctionTask(event: StepFunctionTaskEvent): Promise<any[]> {
    return [new SfnTaskEvent(event)];
  }
}
```

4. Custom `TaskModule`

```ts
import { TaskModule } from "@mbc-cqrs-serverless/task";
import { Module } from "@nestjs/common";
import { TaskEventHandler } from "src/sample/handler/task.handler";

import { TaskQueueEventFactory } from "./task-queue-event-factory";

@Module({
  imports: [
    TaskModule.register({
      taskQueueEventFactory: TaskQueueEventFactory,
      enableController: true, // Optional: enable REST endpoints for task management
    }),
  ],
  providers: [TaskEventHandler],
  exports: [TaskModule],
})
export class CustomTaskModule {}
```

5. Custom `EventFactoryAddedTask`

```ts
import { EventFactory, IEvent } from "@mbc-cqrs-serverless/core";
import { EventFactoryAddedTask, TaskEvent } from "@mbc-cqrs-serverless/task";
import { Logger } from "@nestjs/common";
import { DynamoDBStreamEvent } from "aws-lambda";

@EventFactory()
export class CustomEventFactory extends EventFactoryAddedTask {
  private readonly logger = new Logger(CustomEventFactory.name);
  async transformDynamodbStream(event: DynamoDBStreamEvent): Promise<IEvent[]> {
    const curEvents = await super.transformDynamodbStream(event);
    const taskEvents = event.Records.map((record) => {
      if (
        record.eventSourceARN.endsWith("tasks") ||
        record.eventSourceARN.includes("tasks" + "/stream/")
      ) {
        if (record.eventName === "INSERT") {
          return new TaskEvent().fromDynamoDBRecord(record);
        }
      }
      return undefined;
    })
      .filter((event) => !!event)
      .filter((event) => event.taskEntity.sk.split("#").length < 3);

    return [...curEvents, ...taskEvents];
  }
}
```

6. Create a Step Functions task

```ts
const item = [
  { key: "value1" },
  { key: "value2" },
  { key: "value3" },
  { key: "value4" },
  { key: "value5" },
  { key: "value6" },
];

await this.taskService.createStepFunctionTask(
  {
    input: item,
    taskType: "cat",
    tenantCode: "mbc",
  },
  { invokeContext }
);
```

## API Reference {#api-reference}

### TaskService Methods

#### `createTask(dto: CreateTaskDto, options: { invokeContext: IInvoke }): Promise<TaskEntity>`

Creates a new task for single task processing.

```ts
const task = await this.taskService.createTask(
  {
    taskType: "data-export",
    tenantCode: "mbc",
    name: "Export user data",
    input: { userId: "123", format: "csv" },
  },
  { invokeContext }
);
```

#### `createStepFunctionTask(dto: CreateTaskDto, options: { invokeContext: IInvoke }): Promise<TaskEntity>`

Creates a new task for Step Functions processing. The input array will be processed as subtasks.

```ts
const task = await this.taskService.createStepFunctionTask(
  {
    taskType: "batch-process",
    tenantCode: "mbc",
    name: "Process batch items",
    input: [{ id: 1 }, { id: 2 }, { id: 3 }],
  },
  { invokeContext }
);
```

#### `getTask(key: DetailKey): Promise<TaskEntity>`

Retrieves a task by its primary key.

```ts
const task = await this.taskService.getTask({
  pk: "TASK#mbc",
  sk: "data-export#01HXYZ123",
});
```

#### `listItemsByPk(tenantCode: string, type?: string, options?: ListTaskOptions): Promise<TaskListEntity>`

Lists tasks by tenant code and type.

**ListTaskOptions:**
```ts
interface ListTaskOptions {
  sk?: {
    skExpression: string;
    skAttributeValues: Record<string, string>;
    skAttributeNames?: Record<string, string>;
  };
  startFromSk?: string;  // For pagination
  limit?: number;
  order?: 'asc' | 'desc';
}
```

```ts
// List all tasks for a tenant
const tasks = await this.taskService.listItemsByPk("mbc", "TASK", {
  limit: 10,
  order: "desc",
});

// List Step Function tasks
const sfnTasks = await this.taskService.listItemsByPk("mbc", "SFN_TASK");

// Paginate through results
const nextPage = await this.taskService.listItemsByPk("mbc", "TASK", {
  startFromSk: tasks.lastSk,
  limit: 10,
});
```

#### `createSubTask(event: TaskQueueEvent): Promise<TaskEntity[]>`

Creates subtasks from a parent task's input array. Each item in the input array becomes a separate subtask.

```ts
// Typically called within a TaskQueueEvent handler
const subTasks = await this.taskService.createSubTask(event);
// Returns array of TaskEntity for each input item
```

#### `getAllSubTask(subTask: DetailKey): Promise<TaskEntity[]>`

Retrieves all subtasks for a parent task.

```ts
const subTasks = await this.taskService.getAllSubTask({
  pk: "SFN_TASK#mbc",
  sk: "batch-process#01HXYZ123#0", // Any subtask key
});
// Returns all subtasks under the parent task
```

#### `updateStatus(key: DetailKey, status: string, attributes?: { result?: any; error?: any }, notifyId?: string): Promise<void>`

Updates the status of a task and sends an SNS notification.

```ts
// Mark task as completed
await this.taskService.updateStatus(
  { pk: "TASK#mbc", sk: "data-export#01HXYZ123" },
  "COMPLETED",
  { result: { exportedRows: 100 } }
);

// Mark task as failed
await this.taskService.updateStatus(
  { pk: "TASK#mbc", sk: "data-export#01HXYZ123" },
  "FAILED",
  { error: { message: "Export failed", code: "EXPORT_ERROR" } }
);
```

#### `updateSubTaskStatus(key: DetailKey, status: string, attributes?: { result?: any; error?: any }, notifyId?: string): Promise<void>`

Updates the status of a subtask and sends an SNS notification with action `"sub-task-status"`.

```ts
await this.taskService.updateSubTaskStatus(
  { pk: "SFN_TASK#mbc", sk: "batch-process#01HXYZ123#0" },
  "COMPLETED",
  { result: { processedItem: { id: 1 } } }
);
```

#### `updateStepFunctionTask(key: DetailKey, attributes?: Record<string, any>, status?: string, notifyId?: string): Promise<void>`

Updates a Step Function task with attributes and status, then sends an SNS notification.

```ts
await this.taskService.updateStepFunctionTask(
  { pk: "SFN_TASK#mbc", sk: "batch-process#01HXYZ123" },
  { executionArn: "arn:aws:states:..." },
  "PROCESSING"
);
```

#### `publishAlarm(event: TaskQueueEvent | StepFunctionTaskEvent, errorDetails: any): Promise<void>`

Publishes an alarm notification via SNS when an error occurs during task processing. This method is typically called from error handlers in task processing workflows.

```ts
try {
  // Process task
  await this.processTask(event);
} catch (error) {
  // Send alarm notification
  await this.taskService.publishAlarm(event, {
    message: error.message,
    stack: error.stack,
  });
  throw error;
}
```

The alarm notification includes:
- Task key (`pk`, `sk`)
- Tenant code
- Error details
- Action type: `"sfn-alarm"`

#### `formatTaskStatus(tasks: TaskEntity[]): Promise<object>`

Formats the task status by calculating subtask counts and aggregating status information. Useful for displaying task progress in UI.

```ts
// Get all subtasks for a parent task
const subTasks = await this.taskService.getAllSubTask({
  pk: "SFN_TASK#mbc",
  sk: "batch-process#01HXYZ123#0"
});

const formattedStatus = await this.taskService.formatTaskStatus(subTasks);
// Returns:
// {
//   subTaskCount: 10,           // Total number of subtasks
//   subTaskSucceedCount: 7,     // Number of completed subtasks
//   subTaskFailedCount: 1,      // Number of failed subtasks
//   subTaskRunningCount: 2,     // Number of in-progress subtasks
//   subTasks: [                 // Array of subtask summaries
//     { pk: "...", sk: "...", status: "COMPLETED" },
//     ...
//   ]
// }
```

The return object structure:

```ts
{
  subTaskCount: number;        // Total subtask count
  subTaskSucceedCount: number; // COMPLETED subtasks
  subTaskFailedCount: number;  // FAILED subtasks
  subTaskRunningCount: number; // PROCESSING subtasks
  subTasks: Array<{            // Subtask summary array
    pk: string;
    sk: string;
    status: string;
  }>;
}
```

### Task Status Values

| Status | Description |
|------------|-----------------|
| `CREATED` | Task has been created but not yet started |
| `QUEUED` | Task has been queued for processing |
| `STARTED` | Task execution has started |
| `PROCESSING` | Task is currently being processed |
| `FINISHED` | Task execution has finished |
| `COMPLETED` | Task finished successfully |
| `ERRORED` | Task encountered an error during execution |
| `FAILED` | Task failed with an error |

### CreateTaskDto

The `CreateTaskDto` class defines the structure for creating a new task:

```ts
interface CreateTaskDto {
  tenantCode: string;  // Required: Tenant identifier
  taskType: string;    // Required: Type/category of the task
  name?: string;       // Optional: Display name (defaults to taskType)
  input: Record<string, any>;  // Required: Task input data
}
```

:::info Input Format for Step Functions
When using `createStepFunctionTask()`, the `input` field must be an **array**. Each item in the array becomes a separate subtask that will be processed by the Step Functions Map state. For single task processing with `createTask()`, the input can be any object.
:::

### ITaskQueueEventFactory Interface

The `ITaskQueueEventFactory` interface defines optional methods for transforming task events. You only need to implement the method(s) relevant to your use case:

```ts
interface ITaskQueueEventFactory<TEvent extends IEvent = any> {
  transformTask?(event: TaskQueueEvent): Promise<TEvent[]>;           // Optional: For single task processing
  transformStepFunctionTask?(event: StepFunctionTaskEvent): Promise<TEvent[]>;  // Optional: For Step Function task processing
}
```

Note: Both methods are optional. Implement `transformTask` for single task processing, or `transformStepFunctionTask` for Step Function task processing, or both if your application uses both types.


## Related Documentation

- [Import/Export Patterns](/docs/import-export-patterns) - Step Functions integration for imports
- [Architecture: Step Functions](/docs/architecture/step-functions) - Workflow orchestration
- [Queue Module](/docs/queue) - SNS notifications used by task status updates
- [Interfaces](/docs/interfaces) - StepFunctionsEvent interface


---

## Tenant

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/tenant

# Tenant

The TenantModule provides multi-tenant management capabilities in the MBC CQRS Serverless framework. It enables creating, updating, and managing tenants and their group configurations.

## Architecture {#architecture}

```mermaid
graph TB
    subgraph "Tenant Management"
        A["TenantService"] --> B["CommandService"]
        A --> C["DataService"]
        B --> D["DynamoDB"]
        C --> D
    end

    subgraph "Tenant Hierarchy"
        E["Common Tenant"] --> F["Tenant"]
        F --> G["Tenant Group"]
    end
```

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/tenant
```

:::info Tenant Code Format
Tenant codes are case-insensitive. The `getUserContext()` function in `@mbc-cqrs-serverless/core` normalizes all tenant codes to lowercase. When creating tenants, use lowercase codes (e.g., `tenant001`, `acme-corp`) for consistency.

**Upgrading from v1.0.x?** See the [v1.1.0 Migration Guide](/docs/migration/v1.1.0) for data migration instructions.
:::

## Module Registration {#module-registration}

```ts
import { Module } from '@nestjs/common';
import { TenantModule } from "@mbc-cqrs-serverless/tenant";
import { TenantDataSyncHandler } from './tenant-data-sync.handler'; // Your IDataSyncHandler implementation

@Module({
  imports: [
    TenantModule.register({
      enableController: true, // Enable built-in REST controller
      dataSyncHandlers: [TenantDataSyncHandler], // Optional: Custom sync handlers
    }),
  ],
})
export class AppModule {}
```

## Module Options {#module-options}

| Option | Type | Required | Description |
|------------|----------|--------------|-----------------|
| `enableController` | `boolean` | No | Enable or disable the built-in TenantController |
| `dataSyncHandlers` | `Type<IDataSyncHandler>[]` | No | Custom handlers for syncing tenant data to external systems |

## API Reference {#api-reference}

### TenantService Methods

#### `getTenant(key: DetailKey): Promise<DataModel>`

Retrieves a tenant by its primary key.

```ts
import { Injectable } from "@nestjs/common";
import { TenantService } from "@mbc-cqrs-serverless/tenant";

@Injectable()
export class MyService {
  constructor(private readonly tenantService: TenantService) {}

  async findTenant(pk: string, sk: string) {
    const tenant = await this.tenantService.getTenant({ pk, sk });
    return tenant;
  }
}
```

#### `createCommonTenant(dto: CommonTenantCreateDto, context): Promise<CommandModel>`

Creates a common tenant that serves as the base configuration for all tenants.

```ts
const commonTenant = await this.tenantService.createCommonTenant(
  {
    name: "Common Settings",
    attributes: {
      defaultLanguage: "en",
      timezone: "UTC",
    },
  },
  { invokeContext }
);
```

#### `createTenant(dto: TenantCreateDto, context): Promise<CommandModel>`

Creates a new tenant with the specified code and configuration.

```ts
const tenant = await this.tenantService.createTenant(
  {
    code: "tenant001",
    name: "Tenant One",
    attributes: {
      industry: "technology",
      plan: "enterprise",
    },
  },
  { invokeContext }
);
```

#### `updateTenant(key: DetailKey, dto: TenantUpdateDto, context): Promise<CommandModel>`

Updates an existing tenant's information.

```ts
const updatedTenant = await this.tenantService.updateTenant(
  { pk: "TENANT#tenant001", sk: "MASTER" },
  {
    name: "Updated Tenant Name",
    attributes: {
      plan: "premium",
    },
  },
  { invokeContext }
);
```

#### `deleteTenant(key: DetailKey, context): Promise<CommandModel>`

Soft deletes a tenant by setting isDeleted to true.

```ts
const deletedTenant = await this.tenantService.deleteTenant(
  { pk: "TENANT#tenant001", sk: "MASTER" },
  { invokeContext }
);
```

#### `addTenantGroup(dto: TenantGroupAddDto, context): Promise<CommandModel>`

Adds a group to a tenant with the specified role.

```ts
const result = await this.tenantService.addTenantGroup(
  {
    tenantCode: "tenant001",
    groupId: "group001",
    role: "admin",
  },
  { invokeContext }
);
```

#### `customizeSettingGroups(dto: TenantGroupUpdateDto, context): Promise<CommandModel>`

Customizes the setting groups for a specific tenant role.

```ts
const result = await this.tenantService.customizeSettingGroups(
  {
    tenantCode: "tenant001",
    role: "admin",
    settingGroups: ["group001", "group002", "group003"],
  },
  { invokeContext }
);
```

#### `createTenantGroup(tenantGroupCode: string, dto: TenantCreateDto, context): Promise<CommandModel>`

Creates a sub-tenant or tenant group under an existing tenant.

```ts
const tenantGroup = await this.tenantService.createTenantGroup(
  "tenant001", // Parent tenant code
  {
    code: "department-a",
    name: "Department A",
    attributes: {
      department: "engineering",
    },
  },
  { invokeContext }
);
```

## DTOs {#dtos}

### TenantCreateDto

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `code` | `string` | Yes | Unique tenant code |
| `name` | `string` | Yes | Tenant display name |
| `attributes` | `object` | No | Additional tenant attributes |

### TenantGroupAddDto

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `tenantCode` | `string` | Yes | Target tenant code |
| `groupId` | `string` | Yes | Group identifier to add |
| `role` | `string` | Yes | Role for the group |

### TenantGroupUpdateDto

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `tenantCode` | `string` | Yes | Target tenant code |
| `role` | `string` | Yes | Role to update |
| `settingGroups` | `string[]` | Yes | New setting groups array |

### CommonTenantCreateDto

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `name` | `string` | Yes | Common tenant display name |
| `attributes` | `object` | No | Additional attributes |

### TenantUpdateDto

| Property | Type | Required | Description |
|--------------|----------|--------------|-----------------|
| `code` | `string` | No | Tenant code (optional for update) |
| `name` | `string` | No | Tenant display name |
| `attributes` | `object` | No | Additional tenant attributes |

## Interfaces {#interfaces}

### ITenantService

The `ITenantService` interface defines the contract for tenant management operations. You can use this interface for dependency injection or creating mock implementations for testing.

```ts
import { ITenantService } from "@mbc-cqrs-serverless/tenant";
```

The interface includes the following methods:

- `getTenant(key: DetailKey): Promise<DataModel>`
- `createTenant(dto: TenantCreateDto, context): Promise<CommandModel>`
- `updateTenant(key: DetailKey, dto: TenantUpdateDto, context): Promise<CommandModel>`
- `deleteTenant(key: DetailKey, context): Promise<CommandModel>`
- `createCommonTenant(dto: CommonTenantCreateDto, context): Promise<CommandModel>`
- `addTenantGroup(dto: TenantGroupAddDto, context): Promise<CommandModel>`
- `customizeSettingGroups(dto: TenantGroupUpdateDto, context): Promise<CommandModel>`

:::note
The `createTenantGroup` method is available on `TenantService` but is not part of the `ITenantService` interface.
:::

## Related Documentation

- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant isolation patterns
- [Authentication](/docs/authentication) - Tenant-based authentication
- [Key Patterns](/docs/key-patterns) - Tenant key design
- [Interfaces](/docs/interfaces) - TenantModule interfaces


---

## UI Setting

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/ui-setting

# UI Setting

The UI Setting package provides a flexible framework for managing dynamic application settings without code changes. It enables administrators to define custom fields and users to store data conforming to those schemas.

## When to Use This Package {#when-to-use}

Use this package when you need to:

- Allow admins to define custom forms without developer intervention
- Store tenant-specific configuration (themes, preferences, limits)
- Create user-editable notification or email template settings
- Build configurable dropdown lists or master data tables

## Problems This Package Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| Every new setting requires code deployment | Define schemas dynamically via API |
| Settings structure differs between tenants | Multi-tenant schema support |
| No validation for user-entered settings | Field definitions enforce data types and constraints |
| Hard to build admin UI for settings | REST API with schema introspection |

## Core Concepts {#core-concepts}

The module operates with two main components:

1. **Settings**: Define the schema/structure for data entries. Each setting has a code, name, and a list of fields that describe the data structure.

2. **Data Settings**: Actual data entries that conform to a setting's schema. Each data setting belongs to a specific setting code.

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/ui-setting
```

## Module Configuration {#module-configuration}

Register the `SettingModule` in your application:

```typescript
import { Module } from '@nestjs/common';
import { SettingModule } from '@mbc-cqrs-serverless/ui-setting';

@Module({
  imports: [
    SettingModule.register({
      enableSettingController: true,  // Enable REST API for settings
      enableDataController: true,     // Enable REST API for data settings
    }),
  ],
})
export class AppModule {}
```

### Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| `enableSettingController` | boolean | Enable the settings REST API controller |
| `enableDataController` | boolean | Enable the data settings REST API controller |

## Setting Service {#setting-service}

The `SettingService` manages setting definitions.

### Available Methods

```typescript
import { Injectable } from '@nestjs/common';
import { SettingService } from '@mbc-cqrs-serverless/ui-setting';

@Injectable()
export class MyService {
  constructor(private readonly settingService: SettingService) {}

  async example() {
    // List all settings for a tenant
    const settings = await this.settingService.list(tenantCode);

    // Get a specific setting
    const setting = await this.settingService.get({ pk, sk });

    // Create a new setting
    const newSetting = await this.settingService.create(
      tenantCode,
      createDto,
      { invokeContext }
    );

    // Update a setting
    const updated = await this.settingService.update(
      { pk, sk },
      updateDto,
      { invokeContext }
    );

    // Delete a setting
    const deleted = await this.settingService.delete(
      { pk, sk },
      { invokeContext }
    );

    // Check if a setting code exists
    const exists = await this.settingService.checkExistSettingCode(
      tenantCode,
      code
    );
  }
}
```

### Creating a Setting

```typescript
import { CreateSettingDto } from '@mbc-cqrs-serverless/ui-setting';

const createDto: CreateSettingDto = {
  code: 'user-preferences',
  name: 'User Preferences',
  attributes: {
    description: 'User preference settings',
    fields: [
      {
        physicalName: 'theme',
        name: 'Theme',
        dataType: 'string',
        isRequired: true,
        isShowedOnList: true,
        defaultValue: 'light',
      },
      {
        physicalName: 'language',
        name: 'Language',
        dataType: 'string',
        isRequired: true,
        isShowedOnList: true,
        defaultValue: 'en',
      },
      {
        physicalName: 'pageSize',
        name: 'Page Size',
        dataType: 'number',
        isRequired: false,
        isShowedOnList: false,
        min: '10',
        max: '100',
        defaultValue: '20',
      },
    ],
  },
};
```

### Field Definition

Each field in a setting can have the following properties:

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `physicalName` | string | Yes | Unique identifier for the field |
| `name` | string | Yes | Display name |
| `description` | string | No | Field description |
| `dataType` | string | Yes | Data type (string, number, boolean, etc.) |
| `min` | string | No | Minimum value for numeric fields |
| `max` | string | No | Maximum value for numeric fields |
| `length` | string | No | Maximum length for string fields |
| `maxRow` | number | No | Maximum rows for multi-line text |
| `defaultValue` | string | No | Default value for the field |
| `isRequired` | boolean | Yes | Whether the field is required |
| `isShowedOnList` | boolean | Yes | Whether to display in list views |
| `dataFormat` | string | No | Format specification for the data |

## Data Setting Service {#data-setting-service}

The `DataSettingService` manages data entries for defined settings.

### Available Methods

```typescript
import { Injectable } from '@nestjs/common';
import { DataSettingService } from '@mbc-cqrs-serverless/ui-setting';

@Injectable()
export class MyService {
  constructor(private readonly dataSettingService: DataSettingService) {}

  async example() {
    // List data settings (optionally filter by setting code)
    const dataList = await this.dataSettingService.list(
      tenantCode,
      { settingCode: 'user-preferences' }
    );

    // Get a specific data setting
    const data = await this.dataSettingService.get({ pk, sk });

    // Create a new data setting
    const newData = await this.dataSettingService.create(
      tenantCode,
      createDto,
      { invokeContext }
    );

    // Update a data setting
    const updated = await this.dataSettingService.update(
      { pk, sk },
      updateDto,
      { invokeContext }
    );

    // Delete a data setting
    const deleted = await this.dataSettingService.delete(
      { pk, sk },
      { invokeContext }
    );

    // Check if a data code exists
    const exists = await this.dataSettingService.checkExistCode(
      tenantCode,
      settingCode,
      code
    );
  }
}
```

### Creating Data Setting

```typescript
const createDto: CreateDataSettingDto = {
  settingCode: 'user-preferences',
  code: 'user-001',
  name: 'User 001 Preferences',
  attributes: {
    theme: 'dark',
    language: 'ja',
    pageSize: 50,
  },
};
```

## REST API Endpoints {#rest-api-endpoints}

When controllers are enabled, the following endpoints are available:

### Setting Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/master-setting` | List all settings |
| GET | `/api/master-setting/:pk/:sk` | Get a specific setting |
| POST | `/api/master-setting` | Create a new setting |
| PUT | `/api/master-setting/:pk/:sk` | Update a setting |
| DELETE | `/api/master-setting/:pk/:sk` | Delete a setting |
| POST | `/api/master-setting/check-exist/:code` | Check if a setting code exists |

### Data Setting Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/master-data` | List all data settings |
| GET | `/api/master-data/:pk/:sk` | Get a specific data setting |
| POST | `/api/master-data` | Create a new data setting |
| PUT | `/api/master-data/:pk/:sk` | Update a data setting |
| DELETE | `/api/master-data/:pk/:sk` | Delete a data setting |
| POST | `/api/master-data/check-exist/:settingCode/:code` | Check if a data setting code exists |

### Unified Bulk Upsert Endpoint

:::info Version Note
The unified bulk upsert endpoint was added in [version 1.1.2](/docs/changelog#v112).
:::

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/master-bulk/` | Upsert settings and data in a single request |

This endpoint accepts a mixed array of settings and data items. Items with `settingCode` are routed to the data service; items without are routed to the setting service. See [Unified Bulk Upsert API](/docs/master#unified-bulk-upsert) for details.

## Multi-Tenant Support {#multi-tenant-support}

The module automatically handles multi-tenant data isolation. Each tenant's settings and data are stored with tenant-specific keys:

```typescript
// Settings are stored with tenant-prefixed keys:
// pk: MASTER#<tenantCode>
// sk: MASTER_SETTING#<code>

// Data settings are stored with setting-prefixed keys:
// pk: MASTER#<tenantCode>
// sk: <settingCode>#<code>
```

## Example Use Cases {#example-use-cases}

### Use Case 1: User Notification Preferences

Scenario: Each user can configure their notification preferences (email on/off, SMS on/off).

Implementation: Create a "notification-settings" schema, then store each user's preferences as data entries.

```typescript
@Injectable()
export class AppConfigService {
  constructor(
    private readonly settingService: SettingService,
    private readonly dataSettingService: DataSettingService,
  ) {}

  async initializeDefaultSettings(tenantCode: string, invokeContext: IInvoke) {
    // Create a setting schema for notification preferences
    const settingDto: CreateSettingDto = {
      code: 'notification-settings',
      name: 'Notification Settings',
      attributes: {
        description: 'Configure notification preferences',
        fields: [
          {
            physicalName: 'emailEnabled',
            name: 'Email Notifications',
            dataType: 'boolean',
            isRequired: true,
            isShowedOnList: true,
            defaultValue: 'true',
          },
          {
            physicalName: 'smsEnabled',
            name: 'SMS Notifications',
            dataType: 'boolean',
            isRequired: true,
            isShowedOnList: true,
            defaultValue: 'false',
          },
        ],
      },
    };

    await this.settingService.create(tenantCode, settingDto, { invokeContext });
  }

  async getUserNotificationSettings(
    tenantCode: string,
    userId: string,
  ) {
    const { items } = await this.dataSettingService.list(tenantCode, {
      settingCode: 'notification-settings',
    });

    return items.find(item => item.code === userId);
  }
}
```


## Related Documentation

- [Modules](/docs/modules) - Framework module overview
- [Master](/docs/master) - Master data management
- [Frontend Project Structure](/docs/frontend-project-structure) - UI integration
- [Interfaces](/docs/interfaces) - UI setting interfaces


---

## Versioning Rules

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/version-rules

# Versioning Rules

The MBC CQRS Serverless Framework implements optimistic locking using version numbers to ensure data consistency in distributed systems. This guide explains the versioning rules and provides examples of their implementation.

## Basic Rules {#basic-rules}

1. Sequential Versioning for Same PK/SK   
   - The first command for a pk/sk is sent with version 0 (`VERSION_FIRST`); the stored item then becomes version 1, and later versions increase sequentially
   - Each update increments the version number by 1
   - Only the first request with a given version will succeed
   - Subsequent requests with the same version will fail with a conflict error

2. Independent Version Sequences
   - Different pk/sk combinations each start their own version sequence from 1
   - Version sequences are managed independently for each pk/sk combination
   - This allows parallel operations on different items without version conflicts

3. Optimistic Locking
   - Used to prevent concurrent updates to the same item
   - Version number is automatically incremented with each update
   - Throws BadRequestException on version conflicts (publishSync)
   - Throws ConditionalCheckFailedException for concurrent duplicate key writes (DynamoDB-level)
   - Ensures data consistency in distributed environments

## VERSION Constants {#version-constants}

### VERSION_FIRST — New Entity

Use `VERSION_FIRST` (= `0`) as the version when creating a new entity. The framework verifies the item does not yet exist, then stores it at version `1`.

```typescript
import { VERSION_FIRST } from '@mbc-cqrs-serverless/core';

await this.commandService.publishAsync(
  {
    pk: 'ORDER#tenant001',
    sk: 'ORD-001',
    version: VERSION_FIRST, // Create new entity — framework stores at version 1
    type: 'ORDER',
    tenantCode: 'tenant001',
    attributes: { total: 150 },
  },
  { invokeContext },
);
```

### VERSION_LATEST — Skip Version Check

Use `VERSION_LATEST` (= `-1`) to instruct the framework to auto-resolve to the latest version, bypassing optimistic locking ("last writer wins"). Use only when concurrent conflicts are acceptable and the latest value always wins.

```typescript
import { VERSION_LATEST } from '@mbc-cqrs-serverless/core';

await this.commandService.publishPartialUpdateAsync(
  {
    pk: 'ORDER#tenant001',
    sk: 'ORD-001',
    version: VERSION_LATEST, // Update without version check — last writer wins
    attributes: { status: 'shipped' },
  },
  { invokeContext },
);
```

:::warning
`VERSION_LATEST` bypasses optimistic locking. If two concurrent requests both use `VERSION_LATEST`, the second write silently overwrites the first. Reserve it for idempotent fields (e.g., status flags) where the latest value is always correct.
:::

## Implementation Examples {#implementation-examples}

### Basic Version Handling

```typescript
describe('Version Handling', () => {
  it('should handle sequential versions correctly', async () => {
    // Initial create with version 0
    const createPayload = {
      pk: 'TEST#tenant001',
      sk: 'TEST#item-1',
      id: 'TEST#tenant001#TEST#item-1',
      name: 'Version Test',
      version: 0,
      type: 'TEST',
    }

    const createRes = await request(config.apiBaseUrl)
      .post('/items')
      .send(createPayload)

    expect(createRes.statusCode).toBe(201)
    expect(createRes.body.version).toBe(1)

    // Update with correct version
    const updatePayload = {
      ...createPayload,
      version: 1,
      name: 'Updated Name',
    }

    const updateRes = await request(config.apiBaseUrl)
      .put(`/items/${createPayload.id}`)
      .send(updatePayload)

    expect(updateRes.statusCode).toBe(200)
    expect(updateRes.body.version).toBe(2)
  })
})
```

### Version Conflict Handling

```typescript
describe('Version Conflicts', () => {
  it('should handle concurrent updates correctly', async () => {
    const createPayload = {
      pk: 'TEST#tenant001',
      sk: 'TEST#conflict-1',
      id: 'TEST#tenant001#TEST#conflict-1',
      name: 'Conflict Test',
      version: 0,
      type: 'TEST',
    }

    // First create the item
    const createRes = await request(config.apiBaseUrl)
      .post('/items')
      .send(createPayload)

    expect(createRes.statusCode).toBe(201)

    const updatePayload = {
      ...createPayload,
      version: 1,
      name: 'Updated Name',
    }

    // First update with version 1 succeeds
    const res1 = await request(config.apiBaseUrl)
      .put(`/items/${createPayload.id}`)
      .send(updatePayload)

    // Second update with same version 1 fails
    const res2 = await request(config.apiBaseUrl)
      .put(`/items/${createPayload.id}`)
      .send(updatePayload)

    expect(res1.statusCode).toBe(200)
    expect(res2.statusCode).toBe(409) // Conflict
  })
})
```

### Independent Version Sequences

```typescript
describe('Independent Versioning', () => {
  it('should maintain independent version sequences', async () => {
    const item1 = {
      pk: 'TEST#seq1',
      sk: 'TEST#item-1',
      id: 'TEST#seq1#TEST#item-1',
      name: 'Sequence 1',
      version: 0,
      type: 'TEST',
    }

    const item2 = {
      pk: 'TEST#seq2',
      sk: 'TEST#item-1',
      id: 'TEST#seq2#TEST#item-1',
      name: 'Sequence 2',
      version: 0,
      type: 'TEST',
    }

    // Both items start at version 1
    const res1 = await request(config.apiBaseUrl)
      .post('/items')
      .send(item1)

    const res2 = await request(config.apiBaseUrl)
      .post('/items')
      .send(item2)

    expect(res1.body.version).toBe(1)
    expect(res2.body.version).toBe(1)

    // Update first item
    const updateRes = await request(config.apiBaseUrl)
      .put(`/items/${item1.id}`)
      .send({ ...item1, version: 1 })

    expect(updateRes.body.version).toBe(2)

    // Second item still at version 1
    const getRes = await request(config.apiBaseUrl)
      .get(`/items/${item2.id}`)

    expect(getRes.body.version).toBe(1)
  })
})
```

## Best Practices {#best-practices}

1. Always include version number in update operations
2. Handle version conflict errors gracefully in your application
3. Use appropriate retry strategies for handling conflicts
4. Consider implementing exponential backoff for retries
5. Document version handling in your API documentation


## Related Documentation

- [Command Service](/docs/command-service) - publishSync with version handling
- [Error Catalog](/docs/error-catalog) - Version conflict errors
- [Version Conflict Guide](/docs/version-conflict-guide) - Retry strategies and recovery patterns
- [Service Patterns](/docs/service-patterns) - Optimistic locking patterns


---

# Infrastructure

## CDK Infrastructure

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/architecture/cdk-infrastructure

# CDK Infrastructure

This document describes the AWS infrastructure provisioned by the MBC CQRS Serverless framework using AWS CDK. Understanding this architecture helps you customize deployments and troubleshoot issues.

## System Architecture Overview

The following diagram shows the complete AWS infrastructure created by the framework:

```mermaid
flowchart TB
    subgraph Internet
        Client[Client Applications]
    end

    subgraph CDN["Content Delivery"]
        CF_API[CloudFront<br/>API Distribution]
        CF_Static[CloudFront<br/>Static Assets]
    end

    subgraph Auth["Authentication"]
        Cognito[Cognito User Pool]
        CognitoClient[User Pool Client]
    end

    subgraph API["API Layer"]
        APIGW[API Gateway<br/>HTTP API]
        AppSync[AppSync<br/>GraphQL API]
    end

    subgraph Compute["Compute Layer"]
        Lambda[Lambda Function<br/>NestJS Application]
        Layer[Lambda Layer<br/>Dependencies]
    end

    subgraph Orchestration["Workflow Orchestration"]
        SFN_Cmd[Command Handler<br/>State Machine]
        SFN_Task[Task Handler<br/>State Machine]
        SFN_Import[Import CSV<br/>State Machine]
    end

    subgraph Messaging["Event-Driven Messaging"]
        SNS_Main[SNS Main Topic]
        SNS_Alarm[SNS Alarm Topic]
        SQS_Task[Task Queue]
        SQS_Notify[Notification Queue]
        SQS_SubTask[Sub-Task Queue]
        SQS_Import[Import Queue]
        SQS_DLQ[Dead Letter Queue]
    end

    subgraph Storage["Data Storage"]
        DDB[(DynamoDB<br/>Event Store)]
        S3_Data[(S3 DDB Bucket)]
        S3_Public[(S3 Public Bucket)]
        RDS[(RDS Aurora<br/>PostgreSQL)]
    end

    subgraph Streams["Change Data Capture"]
        DDB_Stream[DynamoDB Streams]
    end

    subgraph Network["Network"]
        VPC[VPC]
        Subnets[Private Subnets]
        SG[Security Groups]
    end

    subgraph Monitoring["Observability"]
        CW_Logs[CloudWatch Logs]
        XRay[X-Ray Tracing]
        CW_Alarms[CloudWatch Alarms]
    end

    Client --> CF_API
    Client --> CF_Static
    CF_API --> APIGW
    CF_Static --> S3_Public

    APIGW --> Cognito
    APIGW --> Lambda
    AppSync --> Lambda

    Lambda --> Layer
    Lambda --> DDB
    Lambda --> S3_Data
    Lambda --> RDS
    Lambda --> SNS_Main
    Lambda --> SFN_Cmd
    Lambda --> SFN_Task
    Lambda --> SFN_Import

    SNS_Main --> SQS_Task
    SNS_Main --> SQS_Notify
    SNS_Main --> SQS_SubTask
    SNS_Main --> SQS_Import
    SNS_Alarm --> SQS_DLQ

    SQS_Task --> Lambda
    SQS_Notify --> Lambda
    SQS_SubTask --> Lambda
    SQS_Import --> Lambda

    DDB --> DDB_Stream
    DDB_Stream --> Lambda

    SFN_Cmd --> Lambda
    SFN_Task --> Lambda
    SFN_Import --> Lambda
    SFN_Import --> S3_Data

    Lambda --> VPC
    VPC --> Subnets
    Subnets --> SG

    Lambda --> CW_Logs
    Lambda --> XRay
    SFN_Cmd --> CW_Logs
    SFN_Task --> CW_Logs
    SFN_Import --> CW_Logs
```

## AWS Resources Created

### Authentication (Cognito)

Amazon Cognito provides user authentication and authorization:

```mermaid
flowchart LR
    subgraph Cognito
        UP[User Pool]
        UPC[User Pool Client]
        CustomAttrs[Custom Attributes]
    end

    subgraph Attributes
        tenant[tenant]
        company[company_code]
        member[member_id]
        roles[roles]
    end

    UP --> UPC
    UP --> CustomAttrs
    CustomAttrs --> tenant
    CustomAttrs --> company
    CustomAttrs --> member
    CustomAttrs --> roles
```

**CDK Implementation:**

```typescript
import * as cognito from 'aws-cdk-lib/aws-cognito';

// Create User Pool
const userPool = new cognito.UserPool(this, 'UserPool', {
  userPoolName: `${env}-${appName}-user-pool`,
  selfSignUpEnabled: false,
  signInAliases: {
    username: true,
    preferredUsername: true,
  },
  passwordPolicy: {
    minLength: 6,
    requireLowercase: false,
    requireUppercase: false,
    requireDigits: false,
    requireSymbols: false,
  },
  mfa: cognito.Mfa.OFF,
  accountRecovery: cognito.AccountRecovery.NONE,
  deletionProtection: true,
  customAttributes: {
    tenant: new cognito.StringAttribute({ maxLen: 50, mutable: true }),
    company_code: new cognito.StringAttribute({ maxLen: 50, mutable: true }),
    member_id: new cognito.StringAttribute({ maxLen: 2048, mutable: true }),
    roles: new cognito.StringAttribute({ mutable: true }),
  },
});

// Create User Pool Client
const userPoolClient = userPool.addClient('UserPoolClient', {
  authFlows: {
    userPassword: true,
    userSrp: true,
  },
});
```

### API Gateway

HTTP API provides RESTful endpoints with Cognito authorization:

```mermaid
flowchart TB
    subgraph Routes
        Health["GET / (Public)"]
        Event["POST /event/{proxy+} (IAM)"]
        API["* /{proxy+} (Cognito)"]
    end

    subgraph Authorization
        NoAuth[No Auth]
        IAMAuth[IAM Authorizer]
        CognitoAuth[Cognito Authorizer]
    end

    Health --> NoAuth
    Event --> IAMAuth
    API --> CognitoAuth
```

**CDK Implementation:**

```typescript
import * as apigatewayv2 from 'aws-cdk-lib/aws-apigatewayv2';
import * as apigatewayv2Integrations from 'aws-cdk-lib/aws-apigatewayv2-integrations';
import * as apigatewayv2Authorizers from 'aws-cdk-lib/aws-apigatewayv2-authorizers';

// Create HTTP API
const httpApi = new apigatewayv2.HttpApi(this, 'HttpApi', {
  apiName: `${env}-${appName}-api`,
  corsPreflight: {
    allowOrigins: ['*'],
    allowMethods: [apigatewayv2.CorsHttpMethod.ANY],
    allowHeaders: ['*'],
    maxAge: cdk.Duration.hours(1),
  },
});

// Lambda integration
const lambdaIntegration = new apigatewayv2Integrations.HttpLambdaIntegration(
  'LambdaIntegration',
  lambdaFunction
);

// Cognito authorizer
const cognitoAuthorizer = new apigatewayv2Authorizers.HttpUserPoolAuthorizer(
  'CognitoAuthorizer',
  userPool,
  { userPoolClients: [userPoolClient] }
);

// Public health check route
httpApi.addRoutes({
  path: '/',
  methods: [apigatewayv2.HttpMethod.GET],
  integration: lambdaIntegration,
});

// Protected API routes
httpApi.addRoutes({
  path: '/{proxy+}',
  methods: [
    apigatewayv2.HttpMethod.GET,
    apigatewayv2.HttpMethod.POST,
    apigatewayv2.HttpMethod.PUT,
    apigatewayv2.HttpMethod.DELETE,
    apigatewayv2.HttpMethod.PATCH,
  ],
  integration: lambdaIntegration,
  authorizer: cognitoAuthorizer,
});
```

### Lambda Function

The main compute layer runs your NestJS application:

**CDK Implementation:**

```typescript
import * as lambda from 'aws-cdk-lib/aws-lambda';

// Create Lambda Layer for dependencies
const lambdaLayer = new lambda.LayerVersion(this, 'MainLayer', {
  layerVersionName: `${env}-${appName}-main-layer`,
  code: lambda.Code.fromAsset('dist_layer'),
  compatibleRuntimes: [lambda.Runtime.NODEJS_20_X],
  compatibleArchitectures: [lambda.Architecture.ARM_64],
});

// Create Lambda Function
const lambdaFunction = new lambda.Function(this, 'LambdaApi', {
  functionName: `${env}-${appName}-lambda-api`,
  runtime: lambda.Runtime.NODEJS_20_X,
  architecture: lambda.Architecture.ARM_64,
  handler: 'main.handler',
  code: lambda.Code.fromAsset('dist'),
  memorySize: 512,
  timeout: cdk.Duration.seconds(30),
  layers: [lambdaLayer],
  tracing: lambda.Tracing.ACTIVE,
  loggingFormat: lambda.LoggingFormat.JSON,
  vpc: vpc,
  vpcSubnets: { subnets: privateSubnets },
  securityGroups: securityGroups,
  environment: {
    NODE_OPTIONS: '--enable-source-maps',
    TZ: 'Asia/Tokyo',
    NODE_ENV: env,
    APP_NAME: appName,
    LOG_LEVEL: 'info',
    S3_BUCKET_NAME: ddbBucket.bucketName,
    SNS_TOPIC_ARN: mainSnsTopic.topicArn,
    COGNITO_USER_POOL_ID: userPool.userPoolId,
    DATABASE_URL: databaseUrl,
  },
});
```

### SNS and SQS (Event-Driven Messaging)

Message routing with filtering for different event types:

```mermaid
flowchart TB
    SNS[SNS Main Topic]

    subgraph Filters
        F1["action = 'task-execute'"]
        F2["action IN ['command-status', 'task-status']"]
        F3["action = 'sub-task-status'"]
        F4["action = 'import-execute'"]
    end

    subgraph Queues
        Q1[Task Queue]
        Q2[Notification Queue]
        Q3[Sub-Task Queue]
        Q4[Import Queue]
        DLQ[Dead Letter Queue]
    end

    SNS --> F1 --> Q1
    SNS --> F2 --> Q2
    SNS --> F3 --> Q3
    SNS --> F4 --> Q4
    Q1 -.->|Failed messages| DLQ
```

**CDK Implementation:**

```typescript
import * as sns from 'aws-cdk-lib/aws-sns';
import * as sqs from 'aws-cdk-lib/aws-sqs';
import * as subscriptions from 'aws-cdk-lib/aws-sns-subscriptions';

// Create SNS Topics
const mainSnsTopic = new sns.Topic(this, 'MainSnsTopic', {
  topicName: `${env}-${appName}-main-sns`,
});

const alarmSnsTopic = new sns.Topic(this, 'AlarmSnsTopic', {
  topicName: `${env}-${appName}-alarm-sns`,
});

// Create Dead Letter Queue
const taskDlq = new sqs.Queue(this, 'TaskDLQ', {
  queueName: `${env}-${appName}-task-dead-letter-queue`,
});

// Create Task Queue with DLQ
const taskQueue = new sqs.Queue(this, 'TaskQueue', {
  queueName: `${env}-${appName}-task-action-queue`,
  deadLetterQueue: {
    queue: taskDlq,
    maxReceiveCount: 5,
  },
});

// Create Notification Queue
const notificationQueue = new sqs.Queue(this, 'NotificationQueue', {
  queueName: `${env}-${appName}-notification-queue`,
});

// Create Sub-task Status Queue
const subTaskStatusQueue = new sqs.Queue(this, 'SubTaskStatusQueue', {
  queueName: `${env}-${appName}-sub-task-status-queue`,
});

// Create Import Queue
const importQueue = new sqs.Queue(this, 'ImportQueue', {
  queueName: `${env}-${appName}-import-action-queue`,
});

// Subscribe queues with message filtering
mainSnsTopic.addSubscription(
  new subscriptions.SqsSubscription(taskQueue, {
    filterPolicy: {
      action: sns.SubscriptionFilter.stringFilter({
        allowlist: ['task-execute'],
      }),
    },
    rawMessageDelivery: true,
  })
);

mainSnsTopic.addSubscription(
  new subscriptions.SqsSubscription(notificationQueue, {
    filterPolicy: {
      action: sns.SubscriptionFilter.stringFilter({
        allowlist: ['command-status', 'task-status'],
      }),
    },
    rawMessageDelivery: true,
  })
);

mainSnsTopic.addSubscription(
  new subscriptions.SqsSubscription(subTaskStatusQueue, {
    filterPolicy: {
      action: sns.SubscriptionFilter.stringFilter({
        allowlist: ['sub-task-status'],
      }),
    },
    rawMessageDelivery: true,
  })
);

mainSnsTopic.addSubscription(
  new subscriptions.SqsSubscription(importQueue, {
    filterPolicy: {
      action: sns.SubscriptionFilter.stringFilter({
        allowlist: ['import-execute'],
      }),
    },
    rawMessageDelivery: true,
  })
);
```

### S3 Buckets

Storage for application data and static assets:

**CDK Implementation:**

```typescript
import * as s3 from 'aws-cdk-lib/aws-s3';

// DynamoDB attributes bucket
const ddbBucket = new s3.Bucket(this, 'DdbAttributesBucket', {
  bucketName: `${env}-${appName}-ddb-attributes`,
  versioned: false,
  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
  removalPolicy: cdk.RemovalPolicy.DESTROY,
  cors: [
    {
      allowedMethods: [
        s3.HttpMethods.GET,
        s3.HttpMethods.PUT,
        s3.HttpMethods.POST,
      ],
      allowedOrigins: ['*'],
      allowedHeaders: ['*'],
      maxAge: 3000,
    },
  ],
});

// Public assets bucket
const publicBucket = new s3.Bucket(this, 'PublicBucket', {
  bucketName: `${env}-${appName}-public`,
  versioned: false,
  blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
  removalPolicy: cdk.RemovalPolicy.DESTROY,
});

// Grant Lambda access
ddbBucket.grantReadWrite(lambdaFunction);
publicBucket.grantReadWrite(lambdaFunction);
```

### CloudFront Distributions

CDN for API and static assets with geo-restrictions:

**CDK Implementation:**

```typescript
import * as cloudfront from 'aws-cdk-lib/aws-cloudfront';
import * as origins from 'aws-cdk-lib/aws-cloudfront-origins';

// Origin Access Identity for S3
const oai = new cloudfront.OriginAccessIdentity(this, 'OAI');
publicBucket.grantRead(oai);

// Static assets distribution
const staticDistribution = new cloudfront.Distribution(this, 'StaticDistribution', {
  defaultBehavior: {
    origin: new origins.S3Origin(publicBucket, {
      originAccessIdentity: oai,
    }),
    viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    cachePolicy: cloudfront.CachePolicy.CACHING_OPTIMIZED,
    allowedMethods: cloudfront.AllowedMethods.ALLOW_GET_HEAD,
  },
  priceClass: cloudfront.PriceClass.PRICE_CLASS_200,
  geoRestriction: cloudfront.GeoRestriction.allowlist('JP', 'VN'),
});

// API distribution
const apiDistribution = new cloudfront.Distribution(this, 'ApiDistribution', {
  defaultBehavior: {
    origin: new origins.HttpOrigin(httpApiDomain, {
      customHeaders: {
        'X-Origin-Verify': originVerifyToken,
      },
    }),
    viewerProtocolPolicy: cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    cachePolicy: cloudfront.CachePolicy.CACHING_DISABLED,
    originRequestPolicy: cloudfront.OriginRequestPolicy.ALL_VIEWER_EXCEPT_HOST_HEADER,
    responseHeadersPolicy: cloudfront.ResponseHeadersPolicy.CORS_ALLOW_ALL_ORIGINS,
    allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
  },
  priceClass: cloudfront.PriceClass.PRICE_CLASS_200,
  geoRestriction: cloudfront.GeoRestriction.allowlist('JP', 'VN'),
});
```

### AppSync (GraphQL API)

Real-time GraphQL API with subscriptions:

**CDK Implementation:**

```typescript
import * as appsync from 'aws-cdk-lib/aws-appsync';

// Create AppSync API
const graphqlApi = new appsync.GraphqlApi(this, 'GraphqlApi', {
  name: `${env}-${appName}-realtime`,
  definition: appsync.Definition.fromFile('asset/schema.graphql'),
  authorizationConfig: {
    defaultAuthorization: {
      authorizationType: appsync.AuthorizationType.API_KEY,
      apiKeyConfig: {
        expires: cdk.Expiration.after(cdk.Duration.days(365)),
      },
    },
    additionalAuthorizationModes: [
      { authorizationType: appsync.AuthorizationType.IAM },
      {
        authorizationType: appsync.AuthorizationType.USER_POOL,
        userPoolConfig: { userPool },
      },
    ],
  },
  xrayEnabled: true,
});

// None data source for local resolvers
const noneDataSource = graphqlApi.addNoneDataSource('NoneDataSource');

// Mutation resolver
noneDataSource.createResolver('SendMessageResolver', {
  typeName: 'Mutation',
  fieldName: 'sendMessage',
  requestMappingTemplate: appsync.MappingTemplate.fromString(`
    {
      "version": "2017-02-28",
      "payload": $util.toJson($context.arguments.message)
    }
  `),
  responseMappingTemplate: appsync.MappingTemplate.fromString(
    '$util.toJson($context.result)'
  ),
});
```

### AppSync Events API (opt-in) {#appsync-events-api}

:::info Version Note
AppSync Events API CDK provisioning (`appsyncEvents` config key) was added in [version 1.3.0](/docs/changelog#v130).
:::

An alternative real-time transport using AWS AppSync Events API (schema-free HTTP pub/sub). Opt in by adding `appsyncEvents` to your environment config:

**Config type definition** (`infra/config/type.ts`):

```typescript
export interface Config {
  // ...
  appsyncEvents?: {
    enabled: boolean;       // Set to true to provision the Event API
    namespace?: string;     // Channel namespace name (default: 'default')
    apiKeyExpireDays?: number;  // API key TTL in days (default: 365)
  };
}
```

**Environment config example** (`infra/config/dev/index.ts`):

```typescript
const config: Config = {
  env: 'dev',
  appName: 'your-app',
  // ...
  appsyncEvents: {
    enabled: true,
    namespace: 'default',
    apiKeyExpireDays: 365,
  },
};
```

**CDK Stack Behavior:**

When `appsyncEvents.enabled` is `true`, the CDK stack automatically:

1. Provisions an `aws_appsync.EventApi` with IAM + API Key auth
2. Creates a `ChannelNamespace` matching the configured `namespace`
3. Injects three environment variables into Lambda and ECS:
   - `NOTIFICATION_TRANSPORTS=appsync-event`
   - `APPSYNC_EVENTS_ENDPOINT=https://xxx.appsync-api.region.amazonaws.com/event`
   - `APPSYNC_EVENTS_NAMESPACE=<namespace>`
4. Grants `appsync:EventPublish` to Lambda and ECS task roles via `grantPublish()`

**Stack Outputs:**

| Output | Description |
|-----------|-----------------|
| `AppSyncEventsHttpEndpoint` | HTTP endpoint for server-side publishing |
| `AppSyncEventsNamespace` | Active channel namespace |
| `AppSyncEventsApiKey` | API key for browser client subscriptions |

See [AppSync Events API documentation](/docs/notification-module#appsync-events-service) for server-side usage and [Client-Side Subscription](/docs/notification-module#client-side-subscription) for browser integration.

### Step Functions State Machines

Workflow orchestration for long-running processes:

```mermaid
flowchart TB
    subgraph CommandSM["Command Handler State Machine"]
        C1[check_version] --> C2{Version OK?}
        C2 -->|Yes| C3[set_ttl_command]
        C2 -->|No| C4[wait_prev_command]
        C2 -->|Error| CF[Fail]
        C4 --> C3
        C3 --> C5[history_copy]
        C5 --> C6[transform_data]
        C6 --> C7[sync_data_all<br/>Map State]
        C7 --> C8[finish]
        C8 --> CS[Success]
    end

    subgraph TaskSM["Task Handler State Machine"]
        T1[Map State<br/>Concurrency: 2]
        T1 --> T2[iterator]
        T2 --> T3[Complete]
    end

    subgraph ImportSM["Import CSV State Machine"]
        I1[Distributed Map<br/>Concurrency: 50]
        I1 --> I2[csv_rows_handler]
        I2 --> I3[Complete]
    end
```

**CDK Implementation:**

```typescript
import * as sfn from 'aws-cdk-lib/aws-stepfunctions';
import * as tasks from 'aws-cdk-lib/aws-stepfunctions-tasks';

// Helper function to create Lambda invoke tasks
const createLambdaTask = (
  stateName: string,
  integrationPattern: sfn.IntegrationPattern = sfn.IntegrationPattern.REQUEST_RESPONSE
) => {
  const payload: Record<string, any> = {
    'source': 'step-function',
    'context.$': '$$',
    'input.$': '$',
  };

  if (integrationPattern === sfn.IntegrationPattern.WAIT_FOR_TASK_TOKEN) {
    payload['taskToken'] = sfn.JsonPath.taskToken;
  }

  return new tasks.LambdaInvoke(this, stateName, {
    lambdaFunction,
    payload: sfn.TaskInput.fromObject(payload),
    stateName,
    outputPath: '$.Payload[0][0]',
    integrationPattern,
    retryOnServiceExceptions: true,
  });
};

// Define states
const fail = new sfn.Fail(this, 'fail', {
  stateName: 'fail',
  causePath: '$.cause',
  errorPath: '$.error',
});

const success = new sfn.Succeed(this, 'success', {
  stateName: 'success',
});

const finish = createLambdaTask('finish').next(success);

// Map state for parallel data sync
const syncData = createLambdaTask('sync_data');
const syncDataAll = new sfn.Map(this, 'sync_data_all', {
  stateName: 'sync_data_all',
  maxConcurrency: 0, // Unlimited
  itemsPath: sfn.JsonPath.stringAt('$'),
})
  .itemProcessor(syncData)
  .next(finish);

const transformData = createLambdaTask('transform_data').next(syncDataAll);
const historyCopy = createLambdaTask('history_copy').next(transformData);
const setTtlCommand = createLambdaTask('set_ttl_command').next(historyCopy);

// Callback pattern for async waiting
const waitPrevCommand = createLambdaTask(
  'wait_prev_command',
  sfn.IntegrationPattern.WAIT_FOR_TASK_TOKEN
).next(setTtlCommand);

// Version check choice
const checkVersionResult = new sfn.Choice(this, 'check_version_result')
  .when(sfn.Condition.numberEquals('$.result', 0), setTtlCommand)
  .when(sfn.Condition.numberEquals('$.result', 1), waitPrevCommand)
  .when(sfn.Condition.numberEquals('$.result', -1), fail)
  .otherwise(waitPrevCommand);

const checkVersion = createLambdaTask('check_version').next(checkVersionResult);

// Create log group
const commandSfnLogGroup = new logs.LogGroup(this, 'CommandSfnLogGroup', {
  logGroupName: `/aws/vendedlogs/states/${prefix}-command-handler-logs`,
  removalPolicy: cdk.RemovalPolicy.DESTROY,
  retention: logs.RetentionDays.SIX_MONTHS,
});

// Create state machine
const commandStateMachine = new sfn.StateMachine(this, 'CommandStateMachine', {
  stateMachineName: `${prefix}command-handler`,
  definitionBody: sfn.DefinitionBody.fromChainable(checkVersion),
  tracingEnabled: true,
  logs: {
    destination: commandSfnLogGroup,
    level: sfn.LogLevel.ALL,
  },
});
```

### DynamoDB Event Sources

Configure DynamoDB Streams to trigger Lambda:

**CDK Implementation:**

```typescript
import * as lambdaEventSources from 'aws-cdk-lib/aws-lambda-event-sources';

// Tables to monitor for changes
const tableNames = ['tasks', 'sample-command', 'import_tmp'];

for (const tableName of tableNames) {
  // Lookup existing table
  const tableDesc = new cdk.custom_resources.AwsCustomResource(
    this,
    `${tableName}-desc`,
    {
      onCreate: {
        service: 'DynamoDB',
        action: 'describeTable',
        parameters: { TableName: `${prefix}${tableName}` },
        physicalResourceId: cdk.custom_resources.PhysicalResourceId.fromResponse(
          'Table.TableArn'
        ),
      },
      policy: cdk.custom_resources.AwsCustomResourcePolicy.fromSdkCalls({
        resources: cdk.custom_resources.AwsCustomResourcePolicy.ANY_RESOURCE,
      }),
    }
  );

  const table = dynamodb.Table.fromTableAttributes(this, `${tableName}-table`, {
    tableArn: tableDesc.getResponseField('Table.TableArn'),
    tableStreamArn: tableDesc.getResponseField('Table.LatestStreamArn'),
  });

  // Add event source with INSERT filter
  lambdaFunction.addEventSource(
    new lambdaEventSources.DynamoEventSource(table, {
      startingPosition: lambda.StartingPosition.TRIM_HORIZON,
      batchSize: 1,
      filters: [
        lambda.FilterCriteria.filter({
          eventName: lambda.FilterRule.isEqual('INSERT'),
        }),
      ],
    })
  );
}
```

## Environment Configuration

The framework supports multiple deployment environments:

### Configuration Structure

```typescript
// config/type.ts
export interface Config {
  env: 'dev' | 'stg' | 'prod';
  appName: string;

  domain: {
    http: string;      // e.g., api.example.com
    appsync: string;   // e.g., graphql.example.com
  };

  userPoolId?: string;  // Optional: use existing Cognito pool

  vpc: {
    id: string;
    subnetIds: string[];
    securityGroupIds: string[];
  };

  rds: {
    accountSsmKey: string;  // SSM parameter for DB credentials
    endpoint: string;
    dbName: string;
  };

  logLevel?: {
    lambdaSystem?: 'INFO' | 'DEBUG';
    lambdaApplication?: 'TRACE' | 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
    level?: 'verbose' | 'debug' | 'info' | 'warn' | 'error';
  };

  frontBaseUrl: string;
  fromEmailAddress: string;
  wafArn?: string;  // Optional: WAF for CloudFront

  ecs?: {
    maxInstances: number;
    minInstances: number;
    cpu: number;
    memory: number;
    cpuThreshold?: number;
    autoRollback?: boolean;
  };
}
```

### Environment Examples

**Development:**

```typescript
// config/dev/index.ts
export const config: Config = {
  env: 'dev',
  appName: 'myapp',
  logLevel: {
    lambdaSystem: 'DEBUG',
    lambdaApplication: 'TRACE',
    level: 'verbose',
  },
  // ... other config
};
```

**Production:**

```typescript
// config/prod/index.ts
export const config: Config = {
  env: 'prod',
  appName: 'myapp',
  logLevel: {
    lambdaSystem: 'DEBUG',
    lambdaApplication: 'INFO',
    level: 'info',
  },
  ecs: {
    maxInstances: 2,
    minInstances: 1,
    cpu: 2048,
    memory: 4096,
    cpuThreshold: 70,
    autoRollback: true,
  },
  // ... other config
};
```

## IAM Permissions

The Lambda function is granted the following permissions:

```mermaid
flowchart TB
    Lambda[Lambda Function]

    subgraph Permissions
        Cognito[Cognito Admin]
        S3[S3 Read/Write]
        SNS[SNS Publish]
        SQS[SQS Send]
        DDB[DynamoDB CRUD]
        SFN[Step Functions Execute]
        SES[SES Send Email]
        SSM[SSM/KMS Access]
        AppSync[AppSync Mutation]
    end

    Lambda --> Cognito
    Lambda --> S3
    Lambda --> SNS
    Lambda --> SQS
    Lambda --> DDB
    Lambda --> SFN
    Lambda --> SES
    Lambda --> SSM
    Lambda --> AppSync
```

**CDK Implementation:**

```typescript
// Cognito permissions
lambdaFunction.addToRolePolicy(
  new iam.PolicyStatement({
    actions: [
      'cognito-idp:AdminGetUser',
      'cognito-idp:AdminCreateUser',
      'cognito-idp:AdminDeleteUser',
      'cognito-idp:AdminUpdateUserAttributes',
      'cognito-idp:AdminSetUserPassword',
      'cognito-idp:AdminResetUserPassword',
      'cognito-idp:AdminEnableUser',
      'cognito-idp:AdminDisableUser',
      'cognito-idp:AdminAddUserToGroup',
    ],
    resources: [userPool.userPoolArn],
  })
);

// DynamoDB permissions
lambdaFunction.addToRolePolicy(
  new iam.PolicyStatement({
    actions: [
      'dynamodb:PutItem',
      'dynamodb:UpdateItem',
      'dynamodb:GetItem',
      'dynamodb:Query',
    ],
    resources: [`arn:aws:dynamodb:${region}:${account}:table/${prefix}*`],
  })
);

// Step Functions permissions
lambdaFunction.addToRolePolicy(
  new iam.PolicyStatement({
    actions: [
      'states:StartExecution',
      'states:GetExecutionHistory',
      'states:DescribeExecution',
    ],
    resources: [commandStateMachine.stateMachineArn],
  })
);

// SES permissions
lambdaFunction.addToRolePolicy(
  new iam.PolicyStatement({
    actions: ['ses:SendEmail'],
    resources: ['*'],
  })
);

// Grant S3, SNS, SQS access
ddbBucket.grantReadWrite(lambdaFunction);
publicBucket.grantReadWrite(lambdaFunction);
mainSnsTopic.grantPublish(lambdaFunction);
alarmSnsTopic.grantPublish(lambdaFunction);
taskQueue.grantSendMessages(lambdaFunction);
notificationQueue.grantSendMessages(lambdaFunction);
```

## Deployment Outputs

After deployment, the following outputs are available:

| Output | Description |
|--------|-------------|
| `userPoolId` | Cognito User Pool ID |
| `userPoolClientId` | Cognito App Client ID |
| `graphqlApiUrl` | AppSync GraphQL endpoint |
| `graphqlApiKey` | AppSync API key |
| `httpApiUrl` | HTTP API endpoint |
| `httpDistributionDomain` | CloudFront custom domain |
| `stateMachineArn` | Command Handler State Machine ARN |
| `sfnTaskStateMachineArn` | Task Handler State Machine ARN |

## CI/CD Pipeline

The framework includes a CodePipeline for automated deployments:

```mermaid
flowchart LR
    subgraph Source
        GitHub[GitHub Repository]
    end

    subgraph Build
        Test[Run Tests]
        Synth[CDK Synth]
    end

    subgraph Deploy
        Dev[Dev Environment]
        Stg[Staging Environment]
        Prod[Production Environment]
    end

    GitHub -->|develop branch| Test
    GitHub -->|staging branch| Test
    GitHub -->|main branch| Test
    Test --> Synth
    Synth -->|develop| Dev
    Synth -->|staging| Stg
    Synth -->|main| Prod
```

## Best Practices

### Security

1. **VPC Isolation**: Deploy Lambda in private subnets
2. **Secrets Management**: Store credentials in SSM Parameter Store with KMS encryption
3. **API Security**: Use Cognito for authentication, IAM for internal routes
4. **S3 Security**: Block all public access, use CloudFront OAI

### Performance

1. **Lambda Optimization**: Use ARM64 architecture with optimized layers
2. **CloudFront Caching**: Cache static assets, disable caching for API
3. **Connection Pooling**: Use RDS Proxy for database connections

### Monitoring

1. **CloudWatch Logs**: JSON formatted logs with structured data
2. **X-Ray Tracing**: Enable distributed tracing for debugging
3. **CloudWatch Alarms**: Set up alerts for failures and latency

## Related Documentation

- [Step Functions](/docs/architecture/step-functions) - Workflow orchestration details
- [System Overview](/docs/architecture/system-overview) - High-level architecture
- [Deployment Guide](/docs/deployment-guide) - Deploying CDK infrastructure to AWS
- [Installation](/docs/installation) - Getting started guide


---

## Step Functions

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/architecture/step-functions

# Step Functions

AWS Step Functions provides serverless workflow orchestration for coordinating distributed applications. In the MBC CQRS Serverless framework, Step Functions are used for:

- Long-running workflow orchestration
- Saga pattern implementation for distributed transactions
- Parallel batch processing with Distributed Map
- Asynchronous task coordination with callback patterns

## Architecture Overview

```mermaid
flowchart TB
    subgraph Triggers
        DDBStream[DynamoDB Streams]
        SQS[SQS Queue]
        API[API Gateway]
    end

    subgraph StepFunctions
        CommandSM[Command State Machine]
        TaskSM[Task State Machine]
        ImportSM[Import CSV State Machine]
    end

    subgraph Processing
        Lambda[Lambda Functions]
        DDB[(DynamoDB)]
        S3[(S3)]
    end

    DDBStream --> CommandSM
    DDBStream --> TaskSM
    SQS --> ImportSM
    API --> CommandSM

    CommandSM --> Lambda
    TaskSM --> Lambda
    ImportSM --> Lambda

    Lambda --> DDB
    Lambda --> S3
```

## State Machines

The framework provides three pre-configured state machines:

### Command State Machine

Handles data synchronization workflows with version control and parallel processing.

```mermaid
flowchart LR
    A[check_version] --> B{version ok?}
    B -->|Yes| C[set_ttl_command]
    B -->|No| D[wait_prev_command]
    D --> C
    C --> E[history_copy]
    E --> F[transform_data]
    F --> G[sync_data_all]
    G --> H[finish]
```

Key features:

- **Version checking**: Ensures command ordering and prevents conflicts
- **Async callback**: Waits for previous commands using task tokens
- **Parallel sync**: Uses Map state to sync data across multiple targets
- **TTL management**: Automatically sets expiration on records

### Task State Machine

Executes parallel sub-tasks with controlled concurrency.

```mermaid
flowchart LR
    A[Start] --> B[Map State]
    B --> C[iteration 1]
    B --> D[iteration 2]
    B --> E[iteration N]
    C --> F[End]
    D --> F
    E --> F
```

Key features:

- **Controlled concurrency**: Limits parallel executions (default: 2)
- **Status tracking**: Real-time task status updates
- **Error handling**: Automatic failure detection and reporting

### Import CSV State Machine

Processes large CSV files using AWS Distributed Map for massive parallelism.

```mermaid
flowchart TB
    A[Start] --> B[Read CSV from S3]
    B --> C[Distributed Map]
    C --> D[Batch 1]
    C --> E[Batch 2]
    C --> F[Batch N]
    D --> G[Transform & Validate]
    E --> G
    F --> G
    G --> H[Create Commands]
    H --> I[End]
```

Key features:

- **S3 native integration**: Reads CSV directly from S3
- **Batch processing**: Groups rows for efficient processing
- **High concurrency**: Supports up to 50 concurrent batch processors
- **EXPRESS execution**: Uses express workflows for child state machines

## System Configuration Example

The following diagram shows how Step Functions integrate with other AWS services in a typical production environment:

```mermaid
flowchart TB
    subgraph Client
        Web[Web Application]
        Mobile[Mobile App]
    end

    subgraph APILayer["API Layer"]
        APIGW[API Gateway]
        AppSync[AppSync GraphQL]
    end

    subgraph Compute["Compute Layer"]
        Lambda[Lambda Function<br/>NestJS Application]
    end

    subgraph StepFunctions["Step Functions"]
        CommandSFN[Command Handler<br/>State Machine]
        TaskSFN[Task Handler<br/>State Machine]
        ImportSFN[Import CSV<br/>State Machine]
    end

    subgraph EventDriven["Event-Driven Layer"]
        SNS[SNS Topics]
        SQS[SQS Queues]
        DDBStream[DynamoDB Streams]
    end

    subgraph Storage["Storage Layer"]
        DDB[(DynamoDB<br/>Event Store)]
        S3[(S3<br/>File Storage)]
        RDS[(RDS Aurora<br/>Read Models)]
    end

    subgraph Monitoring["Monitoring"]
        CWLogs[CloudWatch Logs]
        XRay[X-Ray Tracing]
        CWAlarms[CloudWatch Alarms]
    end

    Web --> APIGW
    Mobile --> APIGW
    Web --> AppSync
    APIGW --> Lambda
    AppSync --> Lambda

    Lambda --> DDB
    Lambda --> S3
    Lambda --> RDS
    Lambda --> SNS

    DDBStream --> Lambda
    DDB --> DDBStream
    SNS --> SQS
    SQS --> Lambda

    Lambda --> CommandSFN
    Lambda --> TaskSFN
    Lambda --> ImportSFN

    CommandSFN --> Lambda
    TaskSFN --> Lambda
    ImportSFN --> Lambda
    ImportSFN --> S3

    CommandSFN --> CWLogs
    TaskSFN --> CWLogs
    ImportSFN --> CWLogs
    Lambda --> XRay
    CWLogs --> CWAlarms
```

### Data Flow Example

Here is a typical data flow for a command execution with Step Functions:

```mermaid
sequenceDiagram
    participant Client
    participant API as API Gateway
    participant Lambda
    participant DDB as DynamoDB
    participant Stream as DynamoDB Stream
    participant SFN as Step Functions
    participant SNS
    participant SQS

    Client->>API: POST /orders
    API->>Lambda: Invoke
    Lambda->>DDB: PutItem (Command)
    DDB-->>Lambda: Success
    Lambda-->>API: 202 Accepted
    API-->>Client: Order Created

    DDB->>Stream: INSERT Event
    Stream->>Lambda: Trigger
    Lambda->>SFN: StartExecution

    loop Each State
        SFN->>Lambda: Invoke (state handler)
        Lambda->>DDB: Read/Write
        Lambda-->>SFN: State Output
    end

    SFN->>Lambda: Finish State
    Lambda->>SNS: Publish Event
    SNS->>SQS: Route Message
    SQS->>Lambda: Process Async
```

## CDK Implementation Examples

### Complete Command State Machine

The following CDK code shows how to create a complete command handler state machine:

```typescript
import * as cdk from 'aws-cdk-lib';
import * as sfn from 'aws-cdk-lib/aws-stepfunctions';
import * as tasks from 'aws-cdk-lib/aws-stepfunctions-tasks';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as logs from 'aws-cdk-lib/aws-logs';
import { Construct } from 'constructs';

export class CommandStateMachineConstruct extends Construct {
  public readonly stateMachine: sfn.StateMachine;

  constructor(scope: Construct, id: string, props: { lambdaFunction: lambda.IFunction }) {
    super(scope, id);

    const { lambdaFunction } = props;

    // Helper function to create Lambda invoke tasks
    const createLambdaTask = (
      stateName: string,
      integrationPattern: sfn.IntegrationPattern = sfn.IntegrationPattern.REQUEST_RESPONSE
    ) => {
      const payload: Record<string, any> = {
        'source': 'step-function',
        'context.$': '$$',
        'input.$': '$',
      };

      // Add task token for callback pattern
      if (integrationPattern === sfn.IntegrationPattern.WAIT_FOR_TASK_TOKEN) {
        payload['taskToken'] = sfn.JsonPath.taskToken;
      }

      return new tasks.LambdaInvoke(this, stateName, {
        lambdaFunction,
        payload: sfn.TaskInput.fromObject(payload),
        stateName,
        outputPath: '$.Payload[0][0]',
        integrationPattern,
        retryOnServiceExceptions: true,
      });
    };

    // Define states
    const fail = new sfn.Fail(this, 'fail', {
      stateName: 'fail',
      causePath: '$.cause',
      errorPath: '$.error',
    });

    const success = new sfn.Succeed(this, 'success', {
      stateName: 'success',
    });

    // Create task states
    const finish = createLambdaTask('finish').next(success);

    const syncData = createLambdaTask('sync_data');

    // Map state for parallel data sync
    const syncDataAll = new sfn.Map(this, 'sync_data_all', {
      stateName: 'sync_data_all',
      maxConcurrency: 0, // Unlimited concurrency
      itemsPath: sfn.JsonPath.stringAt('$'),
    })
      .itemProcessor(syncData)
      .next(finish);

    const transformData = createLambdaTask('transform_data').next(syncDataAll);
    const historyCopy = createLambdaTask('history_copy').next(transformData);
    const setTtlCommand = createLambdaTask('set_ttl_command').next(historyCopy);

    // Callback pattern for waiting on previous command
    const waitPrevCommand = createLambdaTask(
      'wait_prev_command',
      sfn.IntegrationPattern.WAIT_FOR_TASK_TOKEN
    ).next(setTtlCommand);

    // Choice state for version checking
    const checkVersionResult = new sfn.Choice(this, 'check_version_result', {
      stateName: 'check_version_result',
    })
      .when(sfn.Condition.numberEquals('$.result', 0), setTtlCommand)
      .when(sfn.Condition.numberEquals('$.result', 1), waitPrevCommand)
      .when(sfn.Condition.numberEquals('$.result', -1), fail)
      .otherwise(waitPrevCommand);

    const checkVersion = createLambdaTask('check_version').next(checkVersionResult);

    // Create log group
    const logGroup = new logs.LogGroup(this, 'StateMachineLogGroup', {
      logGroupName: '/aws/vendedlogs/states/command-handler-logs',
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      retention: logs.RetentionDays.SIX_MONTHS,
    });

    // Create state machine
    this.stateMachine = new sfn.StateMachine(this, 'CommandHandlerStateMachine', {
      stateMachineName: 'command-handler',
      comment: 'Handles command stream processing with version control',
      definitionBody: sfn.DefinitionBody.fromChainable(checkVersion),
      tracingEnabled: true,
      logs: {
        destination: logGroup,
        level: sfn.LogLevel.ALL,
      },
    });
  }
}
```

### Task State Machine with Controlled Concurrency

```typescript
export class TaskStateMachineConstruct extends Construct {
  public readonly stateMachine: sfn.StateMachine;

  constructor(scope: Construct, id: string, props: { lambdaFunction: lambda.IFunction }) {
    super(scope, id);

    const { lambdaFunction } = props;

    // Iterator task for each item
    const iteratorTask = new tasks.LambdaInvoke(this, 'iterator', {
      lambdaFunction,
      payload: sfn.TaskInput.fromObject({
        'source': 'step-function',
        'context.$': '$$',
        'input.$': '$',
      }),
      stateName: 'iterator',
      outputPath: '$.Payload[0][0]',
    });

    // Map state with concurrency limit
    const mapState = new sfn.Map(this, 'TaskMapState', {
      stateName: 'map_state',
      maxConcurrency: 2, // Process 2 items at a time
      inputPath: '$',
      itemsPath: sfn.JsonPath.stringAt('$'),
    }).itemProcessor(iteratorTask);

    // Create log group
    const logGroup = new logs.LogGroup(this, 'TaskLogGroup', {
      logGroupName: '/aws/vendedlogs/states/task-handler-logs',
      removalPolicy: cdk.RemovalPolicy.DESTROY,
      retention: logs.RetentionDays.SIX_MONTHS,
    });

    // Create state machine
    this.stateMachine = new sfn.StateMachine(this, 'TaskHandlerStateMachine', {
      stateMachineName: 'task-handler',
      comment: 'Handles parallel task execution with concurrency control',
      definitionBody: sfn.DefinitionBody.fromChainable(mapState),
      timeout: cdk.Duration.minutes(15),
      tracingEnabled: true,
      logs: {
        destination: logGroup,
        level: sfn.LogLevel.ALL,
      },
    });
  }
}
```

### Distributed Map for CSV Import

For processing large CSV files, use Distributed Map which provides native S3 integration:

```typescript
import { Map as SfnMap, ProcessorMode, ProcessorConfig, IChainable, JsonPath } from 'aws-cdk-lib/aws-stepfunctions';

// Types for Distributed Map S3 item reader configuration
interface DistributedMapItemReader {
  Resource: string;
  ReaderConfig?: {
    InputType: 'CSV' | 'JSON' | 'MANIFEST';
    CSVHeaderLocation?: 'FIRST_ROW' | 'GIVEN';
    CSVHeaders?: string[];
    MaxItems?: number;
  };
  Parameters?: Record<string, string>;
}

// Types for Distributed Map batch processing configuration
interface DistributedMapItemBatcher {
  MaxInputBytesPerBatch?: number;
  MaxItemsPerBatch?: number;
  BatchInput?: Record<string, string>;
}

// Custom Distributed Map class for S3 CSV processing
export class DistributedMap extends SfnMap {
  public itemReader?: DistributedMapItemReader;
  public itemBatcher?: DistributedMapItemBatcher;
  public label?: string;

  public override toStateJson(): object {
    const mapStateJson = super.toStateJson();
    return {
      ...mapStateJson,
      ItemReader: this.itemReader,
      ItemBatcher: this.itemBatcher,
      Label: this.label,
    };
  }

  public itemProcessor(processor: IChainable, config: ProcessorConfig = {}): DistributedMap {
    super.itemProcessor(processor, {
      ...config,
      mode: ProcessorMode.DISTRIBUTED,
    });
    return this;
  }

  public setItemReader(itemReader: DistributedMapItemReader): DistributedMap {
    this.itemReader = itemReader;
    return this;
  }

  public setItemBatcher(itemBatcher: DistributedMapItemBatcher): DistributedMap {
    this.itemBatcher = itemBatcher;
    return this;
  }

  public setLabel(label: string): DistributedMap {
    this.label = label;
    return this;
  }
}

// Usage in your stack
const csvRowsHandler = new tasks.LambdaInvoke(this, 'csv_rows_handler', {
  lambdaFunction,
  payload: sfn.TaskInput.fromObject({
    'source': 'step-function',
    'context.$': '$$',
    'input.$': '$',
  }),
  stateName: 'csv_rows_handler',
});

const importCsvDefinition = new DistributedMap(this, 'import-csv', {
  maxConcurrency: 50, // Process up to 50 batches in parallel
})
  .setLabel('import-csv')
  .setItemReader({
    Resource: 'arn:aws:states:::s3:getObject',
    ReaderConfig: {
      InputType: 'CSV',
      CSVHeaderLocation: 'FIRST_ROW',
    },
    Parameters: {
      'Bucket.$': '$.bucket',
      'Key.$': '$.key',
    },
  })
  .setItemBatcher({
    MaxInputBytesPerBatch: 10,
    BatchInput: {
      'Attributes.$': '$',
    },
  })
  .itemProcessor(csvRowsHandler, {
    executionType: sfn.ProcessorType.EXPRESS, // Use EXPRESS for child executions
  });

const importCsvStateMachine = new sfn.StateMachine(this, 'ImportCsvStateMachine', {
  stateMachineName: 'import-csv',
  comment: 'Processes large CSV files with distributed batch processing',
  definitionBody: sfn.DefinitionBody.fromChainable(importCsvDefinition),
  tracingEnabled: true,
});
```

### Event Source Configuration

Configure DynamoDB Streams and SQS to trigger Step Functions:

```typescript
// DynamoDB Stream event source
const tableNames = ['tasks', 'commands', 'import_tmp'];

for (const tableName of tableNames) {
  const table = dynamodb.Table.fromTableAttributes(this, `${tableName}-table`, {
    tableArn: `arn:aws:dynamodb:${region}:${account}:table/${prefix}${tableName}`,
    tableStreamArn: `arn:aws:dynamodb:${region}:${account}:table/${prefix}${tableName}/stream/*`,
  });

  lambdaFunction.addEventSource(
    new lambdaEventSources.DynamoEventSource(table, {
      startingPosition: lambda.StartingPosition.TRIM_HORIZON,
      batchSize: 1,
      filters: [
        lambda.FilterCriteria.filter({
          eventName: lambda.FilterRule.isEqual('INSERT'),
        }),
      ],
    })
  );
}

// SQS event sources
const queues = ['task-action-queue', 'notification-queue', 'import-action-queue'];

for (const queueName of queues) {
  const queue = sqs.Queue.fromQueueArn(
    this,
    queueName,
    `arn:aws:sqs:${region}:${account}:${prefix}${queueName}`
  );

  lambdaFunction.addEventSource(
    new lambdaEventSources.SqsEventSource(queue, {
      batchSize: 1,
    })
  );
}
```

## Implementation Guide

### Step 1: Infrastructure Setup

The framework automatically provisions Step Functions infrastructure using AWS CDK. Key resources include:

```typescript
// State machine definition in CDK
const commandStateMachine = new sfn.StateMachine(this, 'CommandHandler', {
  stateMachineName: 'command',
  definitionBody: sfn.DefinitionBody.fromChainable(definition),
  timeout: Duration.minutes(15),
  tracingEnabled: true,
  logs: {
    destination: logGroup,
    level: sfn.LogLevel.ALL,
  },
});
```

### Step 2: Define Step Function Events

Create event classes that extend the base Step Function event:

```typescript
import { IEvent } from '@mbc-cqrs-serverless/core';
import { StepFunctionsContext } from '@mbc-cqrs-serverless/core';

export class CustomWorkflowEvent implements IEvent {
  source: string;
  context: StepFunctionsContext;
  input?: WorkflowInput;
  taskToken?: string;
}
```

### Step 3: Implement Event Handlers

Create handlers that process Step Function events:

```typescript
import { EventHandler, IEventHandler, StepFunctionStateInput } from '@mbc-cqrs-serverless/core';
import { Logger } from '@nestjs/common';

@EventHandler(CustomWorkflowEvent)
export class CustomWorkflowHandler implements IEventHandler<CustomWorkflowEvent> {
  private readonly logger = new Logger(CustomWorkflowHandler.name);

  async execute(event: CustomWorkflowEvent): Promise<StepFunctionStateInput> {
    const stateName = event.context.State.Name;

    switch (stateName) {
      case 'initialize':
        return this.handleInitialize(event);
      case 'process':
        return this.handleProcess(event);
      case 'finalize':
        return this.handleFinalize(event);
      default:
        throw new Error(`Unknown state: ${stateName}`);
    }
  }

  private async handleInitialize(event: CustomWorkflowEvent) {
    // Initialization logic
    return { status: 'initialized', data: event.input };
  }

  private async handleProcess(event: CustomWorkflowEvent) {
    // Processing logic
    return { status: 'processed' };
  }

  private async handleFinalize(event: CustomWorkflowEvent) {
    // Finalization logic
    return { status: 'completed' };
  }
}
```

### Step 4: Configure Event Factory

Register your Step Function events in the event factory:

```typescript
import { EventFactory, IEvent, StepFunctionsEvent } from '@mbc-cqrs-serverless/core';

@EventFactory()
export class CustomEventFactory {
  async transformStepFunction(event: StepFunctionsEvent<any>): Promise<IEvent[]> {
    const stateMachineName = event.context.StateMachine.Name;

    if (stateMachineName.includes('custom-workflow')) {
      return [new CustomWorkflowEvent(event)];
    }

    return [];
  }
}
```

### Step 5: Trigger State Machine Execution

Start a state machine execution from your service:

```typescript
import { StepFunctionService } from '@mbc-cqrs-serverless/core';
import { Injectable } from '@nestjs/common';

@Injectable()
export class WorkflowService {
  constructor(private readonly sfnService: StepFunctionService) {}

  async startWorkflow(input: WorkflowInput): Promise<string> {
    const executionArn = await this.sfnService.startExecution({
      stateMachineArn: process.env.WORKFLOW_STATE_MACHINE_ARN,
      input: JSON.stringify(input),
      name: `workflow-${Date.now()}`,
    });

    return executionArn;
  }
}
```

## Use Cases

### Use Case 1: Data Synchronization

Synchronize data across multiple tables with version control and conflict resolution.

**Scenario**: When a command is created, sync the data to multiple read models.

```typescript
// Trigger: DynamoDB Stream INSERT event
// Flow: check_version -> set_ttl -> history_copy -> transform -> sync_all -> finish

await this.commandService.publishAsync(
  {
    pk: 'ORDER#tenant1',
    sk: 'ORDER#order123',
    id: 'order-uuid',
    code: 'order123',
    name: 'Order',
    type: 'ORDER',
    version: 1,
    tenantCode: 'tenant1',
    attributes: { status: 'confirmed', total: 1000 },
  },
  { invokeContext },
);
// This triggers the command state machine automatically
```

### Use Case 2: Batch Task Processing

Execute multiple related tasks in parallel with controlled concurrency.

**Scenario**: Process multiple items in a batch job with status tracking.

```typescript
// Create tasks that will be processed by the task state machine
const items = [
  { itemId: 'item1', action: 'process' },
  { itemId: 'item2', action: 'process' },
  { itemId: 'item3', action: 'process' },
];

await this.taskService.createStepFunctionTask({
  input: items,
  taskType: 'batch-processor',
  tenantCode: 'tenant1',
}, { invokeContext });
```

### Use Case 3: Large-Scale CSV Import

Import millions of rows from CSV files with distributed processing.

**Scenario**: Import a large CSV file from S3 with validation and transformation.

```typescript
import { ProcessingMode } from '@mbc-cqrs-serverless/import';

// Trigger CSV import via API or direct invocation
await this.importService.createCsvImport({
  s3Bucket: 'my-bucket',
  s3Key: 'imports/data.csv',
  tableName: 'products',
  processingMode: ProcessingMode.STEP_FUNCTION,
});

// The import-csv state machine will:
// 1. Read CSV from S3
// 2. Batch rows (default: 10 per batch)
// 3. Process up to 50 batches concurrently
// 4. Transform and validate each row
// 5. Create import commands
```

### Use Case 4: Async Callback Pattern

Wait for external events using task tokens.

**Scenario**: Wait for approval before proceeding with a workflow.

```typescript
// In your state machine definition
{
  "WaitForApproval": {
    "Type": "Task",
    "Resource": "arn:aws:states:::lambda:invoke.waitForTaskToken",
    "Parameters": {
      "FunctionName": "${LambdaFunction}",
      "Payload": {
        "taskToken.$": "$$.Task.Token",
        "requestId.$": "$.requestId"
      }
    },
    "Next": "ProcessApproval"
  }
}

// In your handler, store the task token
async handleWaitForApproval(event: ApprovalEvent) {
  await this.approvalService.createApprovalRequest({
    requestId: event.input.requestId,
    taskToken: event.taskToken, // Store for later callback
  });
}

// When approval is received, resume the workflow
async approveRequest(requestId: string) {
  const request = await this.approvalService.getRequest(requestId);

  await this.sfnService.sendTaskSuccess({
    taskToken: request.taskToken,
    output: JSON.stringify({ approved: true }),
  });
}
```

## Callback Patterns with Task Tokens

The framework implements callback patterns using AWS Step Functions task tokens for coordinating long-running workflows and waiting for external events.

### How Callback Patterns Work

When a Step Function state uses the `WAIT_FOR_TASK_TOKEN` integration pattern, the execution pauses until an external process sends a success or failure response with the task token.

```mermaid
sequenceDiagram
    participant SFN as Step Functions
    participant Lambda
    participant DDB as DynamoDB
    participant External as External Process

    SFN->>Lambda: Invoke with taskToken
    Lambda->>DDB: Store taskToken
    Lambda-->>SFN: Return (execution pauses)
    Note over SFN: Waiting for callback...
    External->>Lambda: Trigger callback
    Lambda->>DDB: Retrieve taskToken
    Lambda->>SFN: SendTaskSuccess(taskToken)
    Note over SFN: Execution resumes
    SFN->>Lambda: Continue to next state
```

### StepFunctionService Implementation

The `StepFunctionService` provides methods for starting executions and resuming paused workflows:

```typescript
import { Injectable } from '@nestjs/common';
import {
  SFNClient,
  SendTaskSuccessCommand,
  StartExecutionCommand,
} from '@aws-sdk/client-sfn';

@Injectable()
export class StepFunctionService {
  private readonly client: SFNClient;

  constructor(private readonly config: ConfigService) {
    this.client = new SFNClient({
      endpoint: config.get<string>('SFN_ENDPOINT'),
      region: config.get<string>('SFN_REGION'),
    });
  }

  // Start a new state machine execution
  startExecution(arn: string, input: any, name?: string) {
    return this.client.send(
      new StartExecutionCommand({
        stateMachineArn: arn,
        name: name && name.length <= 80 ? name : undefined,
        input: JSON.stringify(input),
      }),
    );
  }

  // Resume a paused execution using task token
  async resumeExecution(taskToken: string, output: any = {}) {
    // Wrap output in the expected format for Lambda integration
    const wrappedOutput = {
      Payload: [[output]],
    };

    return await this.client.send(
      new SendTaskSuccessCommand({
        taskToken: taskToken,
        output: JSON.stringify(wrappedOutput),
      }),
    );
  }
}
```

### Version-Based Command Chaining

The command state machine uses callback patterns to ensure commands are processed in version order:

```typescript
// Wait for previous command to complete using task token
protected async waitConfirmToken(
  event: DataSyncCommandSfnEvent,
): Promise<StepFunctionStateInput> {
  // Store task token in DynamoDB for later callback
  await this.commandService.updateTaskToken(event.commandKey, event.taskToken);
  return {
    result: {
      token: event.taskToken,
    },
  };
}

// When a command finishes, check if next version is waiting
protected async checkNextToken(
  event: DataSyncCommandSfnEvent,
): Promise<StepFunctionStateInput> {
  const nextCommand = await this.commandService.getNextCommand(
    event.commandKey,
  );

  if (!nextCommand) {
    return null; // No next command, chain ends
  }

  if (nextCommand.taskToken) {
    // Resume the waiting command
    try {
      await this.sfnService.resumeExecution(nextCommand.taskToken, {
        result: 'resumed_by_prev_version',
        prevVersion: event.commandRecord.version,
      });
    } catch (e) {
      this.logger.warn(
        `Could not resume command v${nextCommand.version}: ${e.message}`,
      );
    }
  }

  return null;
}
```

### CDK Configuration for Callback Pattern

Configure the state to wait for task token in your CDK stack:

```typescript
// Create a state that waits for callback
const waitPrevCommand = new tasks.LambdaInvoke(this, 'wait_prev_command', {
  lambdaFunction,
  payload: sfn.TaskInput.fromObject({
    'input.$': '$',
    'context.$': '$$',
    'taskToken': sfn.JsonPath.taskToken, // Include task token in payload
  }),
  stateName: 'wait_prev_command',
  outputPath: '$.Payload[0][0]',
  // Use WAIT_FOR_TASK_TOKEN integration pattern
  integrationPattern: sfn.IntegrationPattern.WAIT_FOR_TASK_TOKEN,
});
```

## Long-Running Workflow Strategies

The framework provides several strategies for handling long-running workflows:

### ZIP Import Orchestration

For complex multi-file imports, the framework uses a hierarchical orchestration pattern:

```mermaid
flowchart TB
    subgraph ZipOrchestrator["ZIP Orchestrator State Machine"]
        A[Start] --> B[Extract ZIP]
        B --> C[Map: Process Each CSV]
        C --> D1[CSV 1: trigger_single_csv_and_wait]
        C --> D2[CSV 2: trigger_single_csv_and_wait]
        C --> D3[CSV N: trigger_single_csv_and_wait]
        D1 --> E[finalize_zip_job]
        D2 --> E
        D3 --> E
        E --> F[End]
    end

    subgraph CsvStateMachine["CSV State Machine (per file)"]
        G[csv_loader] --> H[Distributed Map]
        H --> I[csv_rows_handler x N]
        I --> J[finalize_parent_job]
    end

    D1 -.->|taskToken| G
    J -.->|SendTaskSuccess| D1
```

### Task Token Propagation for Child Workflows

When triggering child workflows, the parent stores the task token for later callback:

```typescript
import { ProcessingMode } from '@mbc-cqrs-serverless/import';

// Trigger a child CSV job and wait for completion
private async triggerSingleCsvJob(event: ZipImportSfnEvent) {
  const s3Key = event.input?.s3Key || event.input;
  const { taskToken } = event; // Task token from parent workflow
  const { masterJobKey, parameters } = event.context.Execution.Input;

  // Create CSV job with stored task token
  await this.importService.createCsvJobWithTaskToken(
    {
      processingMode: ProcessingMode.STEP_FUNCTION,
      bucket: parameters.bucket,
      key: s3Key,
      tenantCode: parameters.tenantCode,
      tableName: tableName,
    },
    taskToken, // Store for callback when CSV processing completes
    masterJobKey,
  );
}
```

### Workflow Timeout Configuration

Set appropriate timeouts for long-running workflows:

```typescript
const taskStateMachine = new sfn.StateMachine(this, 'task-handler', {
  stateMachineName: 'task-handler',
  definitionBody: sfn.DefinitionBody.fromChainable(sfnTaskMapState),
  timeout: cdk.Duration.minutes(15), // Overall workflow timeout
  tracingEnabled: true,
  logs: {
    destination: logGroup,
    level: sfn.LogLevel.ALL,
  },
});
```

## Integration with Import/Export Patterns

The framework integrates Step Functions with the import module for scalable data processing:

### CSV Import Flow

The CSV import uses a two-phase approach with Step Functions:

```typescript
// Phase 1: Create import job and trigger Step Function
async handleCsvImport(
  dto: CreateCsvImportDto,
  options: ICommandOptions,
): Promise<ImportEntity[] | ImportEntity> {
  if (dto.processingMode === ProcessingMode.DIRECT) {
    // Process directly in Lambda (for small files)
    return this._processCsvDirectly(dto, options);
  } else {
    // Create job and let Step Function handle processing
    return this.createCsvJob(dto, options);
  }
}

// Phase 2: Step Function handler processes rows
@EventHandler(CsvImportSfnEvent)
export class CsvImportSfnEventHandler {
  async handleStepState(event: CsvImportSfnEvent): Promise<any> {
    if (event.context.State.Name === 'csv_loader') {
      // Count total rows and initialize job
      const totalRows = await this.countCsvRows(input);
      await this.importService.updateImportJob(parentKey, {
        set: { totalRows },
      });
      return this.loadCsv(input);
    }

    if (event.context.State.Name === 'finalize_parent_job') {
      return this.finalizeParentJob(event);
    }

    // Process batch of rows
    const items = event.input.Items;
    for (const item of items) {
      const transformedData = await strategy.transform(item);
      await strategy.validate(transformedData);
      await this.importService.createImport(createImportDto, options);
    }
  }
}
```

### Progress Tracking with Atomic Counters

The import service uses atomic DynamoDB counters for accurate progress tracking:

```typescript
// Atomically increment progress counters
async incrementParentJobCounters(
  parentKey: DetailKey,
  childSucceeded: boolean,
): Promise<ImportEntity> {
  const countersToIncrement: { [key: string]: number } = {
    processedRows: 1,
  };
  if (childSucceeded) {
    countersToIncrement.succeededRows = 1;
  } else {
    countersToIncrement.failedRows = 1;
  }

  // Use atomic update expression
  const command = new UpdateItemCommand({
    TableName: this.tableName,
    Key: marshall(parentKey),
    UpdateExpression: 'SET #processedRows = if_not_exists(#processedRows, :start) + :inc',
    ExpressionAttributeNames: { '#processedRows': 'processedRows' },
    ExpressionAttributeValues: marshall({ ':start': 0, ':inc': 1 }),
    ReturnValues: 'ALL_NEW',
  });

  const response = await this.dynamoDbService.client.send(command);
  const updatedEntity = unmarshall(response.Attributes) as ImportEntity;

  // Check if job is complete and update final status
  if (updatedEntity.totalRows > 0 && updatedEntity.processedRows >= updatedEntity.totalRows) {
    const finalStatus = updatedEntity.failedRows > 0
      ? ImportStatusEnum.FAILED
      : ImportStatusEnum.COMPLETED;
    await this.updateStatus(parentKey, finalStatus);
  }

  return updatedEntity;
}
```

### Processing Mode Selection

Choose the appropriate processing mode based on data size:

| Processing Mode | Use Case | Max Rows | Concurrency |
|---------------------|--------------|--------------|-----------------|
| `DIRECT` | Small files, immediate feedback | ~1,000 | Single Lambda |
| `STEP_FUNCTION` | Large files, background processing | Millions | Up to 50 |

```typescript
import { ProcessingMode } from '@mbc-cqrs-serverless/import';

// Example: Selecting processing mode based on file size
const processingMode = estimatedRows > 1000
  ? ProcessingMode.STEP_FUNCTION
  : ProcessingMode.DIRECT;

await importService.handleCsvImport({
  bucket: 'my-bucket',
  key: 'data/large-file.csv',
  tableName: 'products',
  tenantCode: 'tenant1',
  processingMode,
}, { invokeContext });
```

## Step Functions Context

Every Step Function event includes context information about the execution:

```typescript
interface StepFunctionsContext {
  Execution: {
    Id: string;        // Execution ARN
    Input: object;     // Original input
    Name: string;      // Execution name
    RoleArn: string;   // IAM role
    StartTime: string; // ISO timestamp
  };
  State: {
    EnteredTime: string; // When this state started
    Name: string;        // Current state name
    RetryCount: number;  // Retry attempt number
  };
  StateMachine: {
    Id: string;   // State machine ARN
    Name: string; // State machine name
  };
}
```

## Error Handling

Implement robust error handling in your state machines:

### Handler-Level Error Handling

The framework provides built-in error handling patterns for Step Function handlers:

```typescript
// Command event handler with status tracking and error handling
@Injectable()
export class CommandEventHandler {
  async execute(
    event: DataSyncCommandSfnEvent,
  ): Promise<StepFunctionStateInput | StepFunctionStateInput[]> {
    // Update status to STARTED before processing
    await this.commandService.updateStatus(
      event.commandKey,
      getCommandStatus(event.stepStateName, CommandStatus.STATUS_STARTED),
      event.commandRecord.requestId,
    );

    try {
      const ret = await this.handleStepState(event);
      // Update status to FINISHED on success
      await this.commandService.updateStatus(
        event.commandKey,
        getCommandStatus(event.stepStateName, CommandStatus.STATUS_FINISHED),
        event.commandRecord.requestId,
      );
      return ret;
    } catch (error) {
      // Update status to FAILED and publish alarm on error
      await this.commandService.updateStatus(
        event.commandKey,
        getCommandStatus(event.stepStateName, CommandStatus.STATUS_FAILED),
        event.commandRecord.requestId,
      );
      await this.publishAlarm(event, (error as Error).stack);
      throw error;
    }
  }
}
```

### Task Error Handling with Continuation

For task handlers, the framework supports continuing execution even after errors:

```typescript
// Task handler with error handling that allows workflow continuation
@EventHandler(StepFunctionTaskEvent)
export class TaskSfnEventHandler implements IEventHandler<StepFunctionTaskEvent> {
  async execute(event: StepFunctionTaskEvent): Promise<any> {
    const taskKey = event.taskKey;

    try {
      await this.taskService.updateSubTaskStatus(taskKey, TaskStatusEnum.PROCESSING);
      const events = await this.eventFactory.transformStepFunctionTask(event);
      const result = await Promise.all(
        events.map((event) => this.eventBus.execute(event)),
      );
      // Update status to COMPLETED on success
      await this.taskService.updateSubTaskStatus(taskKey, TaskStatusEnum.COMPLETED, {
        result,
      });
    } catch (error) {
      // Update status to FAILED and publish alarm, but don't throw
      this.logger.error(error);
      await Promise.all([
        this.taskService.updateSubTaskStatus(taskKey, TaskStatusEnum.FAILED, {
          error: (error as Error).stack,
        }),
        this.taskService.publishAlarm(event, (error as Error).stack),
      ]);
      // Note: Error is not re-thrown to allow Step Function to continue
      // throw error // Uncomment to fail the entire workflow on error
    }
  }
}
```

### Alarm Publishing

The framework publishes alarms to SNS for monitoring and alerting:

```typescript
// Publish alarm notification to SNS topic
async publishAlarm(
  event: DataSyncCommandSfnEvent,
  errorDetails: any,
): Promise<void> {
  const alarm: INotification = {
    action: 'sfn-alarm',
    id: `${event.commandKey.pk}#${event.commandKey.sk}`,
    table: this.options.tableName,
    pk: event.commandKey.pk,
    sk: event.commandKey.sk,
    tenantCode: event.commandKey.pk.substring(
      event.commandKey.pk.indexOf('#') + 1,
    ),
    content: {
      errorMessage: errorDetails,
      sfnId: event.context.Execution.Id,
    },
  };
  await this.snsService.publish<INotification>(alarm, this.alarmTopicArn);
}
```

### State machine error handling configuration:

```json
{
  "ProcessStep": {
    "Type": "Task",
    "Resource": "${LambdaArn}",
    "Retry": [
      {
        "ErrorEquals": ["States.TaskFailed"],
        "IntervalSeconds": 2,
        "MaxAttempts": 3,
        "BackoffRate": 2
      }
    ],
    "Catch": [
      {
        "ErrorEquals": ["States.ALL"],
        "Next": "HandleError",
        "ResultPath": "$.error"
      }
    ],
    "Next": "NextStep"
  }
}
```

## Best Practices

### Design Principles

1. **Idempotency**: Design each state to be safely retryable
2. **Single Responsibility**: Each state should do one thing well
3. **Timeout Configuration**: Set appropriate timeouts for each state
4. **Logging**: Enable comprehensive logging for debugging

### Performance Optimization

1. **Use Express Workflows**: For high-volume, short-duration workflows
2. **Batch Processing**: Group items to reduce state transitions
3. **Concurrency Limits**: Set appropriate limits to prevent throttling
4. **S3 Integration**: Use native S3 integration for large data processing

### Monitoring

1. **CloudWatch Metrics**: Monitor execution counts, failures, and duration
2. **X-Ray Tracing**: Enable distributed tracing for debugging
3. **CloudWatch Logs**: Capture detailed execution logs
4. **Alarms**: Set up alerts for failure rates and execution times

## Related Documentation

- [Task Module](/docs/tasks) - Task management with Step Functions
- [Import/Export Patterns](/docs/import-export-patterns) - CSV import with Distributed Map
- [Event Sourcing](/docs/architecture/event-sourcing) - Event-driven architecture
- [CQRS Flow](/docs/architecture/cqrs-flow) - Command and query separation


---

## DynamoDB

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/dynamodb

# DynamoDB

## Overview {#overview}

MBC CQRS Serverless uses DynamoDB as its primary data store, implementing CQRS and Event Sourcing patterns through a structured table design. Understanding the table structure is essential for building efficient applications.

## Table Architecture {#table-architecture}

```mermaid
graph TB
    subgraph "Table Types"
        A["Command Table<br/>entity-command"]
        B["Data Table<br/>entity-data"]
        C["History Table<br/>entity-history"]
    end

    subgraph "System Tables"
        D["tasks"]
        E["sequences"]
        F["import_tmp"]
    end

    A -->|"DynamoDB Streams"| B
    A -->|"Event Sourcing"| C
```

In the MBC CQRS Serverless, DynamoDB tables are organized into the following types:

### Entity Tables

| Table Type | Naming Convention | Purpose |
|------------|-------------------|---------|
| Command Table | `entity-command` | Stores write commands (write model) |
| Data Table | `entity-data` | Stores current state (read model) |
| History Table | `entity-history` | Stores all versions for Event Sourcing |

:::info Deployed Table Names
The actual table names are prefixed with the environment and application name: `{NODE_ENV}-{APP_NAME}-{entity}-{type}` (for example `dev-myapp-order-command`). The names above are the logical suffixes used by `CommandModule.register({ tableName })`.
:::

### System Tables

| Table | Purpose |
|--------|---------|
| `tasks` | Stores information about long-running asynchronous tasks |
| `sequences` | Holds sequence data for ID generation |
| `import_tmp` | Stores temporary data for import operations via Step Functions |
| `session` | Tracks Read-Your-Writes sessions (v1.2.0+) |

## Table Definition {#table-definition}

Table definitions are stored in the `prisma/dynamodbs` folder. To add a new entity table:

### Step 1: Define Table in Configuration

Add the table name to `prisma/dynamodbs/cqrs.json`:

```json
["cat", "dog", "order"]
```

### Step 2: Run Migration

For local development:

```bash
# Migrate DynamoDB tables only
npm run migrate:ddb

# Migrate both DynamoDB and RDS
npm run migrate
```

### System Table Definitions {#system-table-definitions}

System tables (`tasks`, `sequences`, `import_tmp`, `session`) have their own JSON definition files in the `prisma/dynamodbs/` folder. These are automatically created during migration:

| File | Table | Purpose |
|------|---------|---------|
| `tasks.json` | `tasks` | Task management with DynamoDB Streams |
| `sequences.json` | `sequences` | Sequence ID generation |
| `import_tmp.json` | `import_tmp` | Temporary import data with DynamoDB Streams for [ImportModule](/docs/import) |
| `session.json` | `session` | Read-Your-Writes session tracking (v1.2.0+), see [Command Service](/docs/command-service#read-your-writes) |

:::info Version Note
The `import_tmp.json` template was added in [version 1.1.1](/docs/changelog#v111). If you created your project with an earlier version and use the ImportModule, you need to add this file manually. See [Common Issues](/docs/common-issues#missing-import-tmp-table) for details.
:::

## Key Design Patterns {#key-design-patterns}

### Standard Key Structure

All entity tables use a composite primary key. The DATA table and COMMAND table use the same `pk` format but differ in `sk`:

| Table | Key | Format | Example |
|-------|-----|--------|---------|
| DATA / HISTORY | `pk` | `TYPE#tenantCode` | `ORDER#ACME` |
| DATA / HISTORY | `sk` | `TYPE#code` | `ORDER#ORD-000001` |
| COMMAND | `pk` | `TYPE#tenantCode` | `ORDER#ACME` |
| COMMAND | `sk` | `TYPE#code@version` | `ORDER#ORD-000001@1` |

The COMMAND table sort key includes an `@{version}` suffix appended by the framework. Use `removeSortKeyVersion(sk)` (imported from `@mbc-cqrs-serverless/core`) to strip it when querying the DATA table.

### Entity Key Examples

```typescript
// Order entity
const orderKey = {
  pk: `ORDER#${tenantCode}`,
  sk: `ORDER#${orderId}`,
};

// User entity
const userKey = {
  pk: `USER#${tenantCode}`,
  sk: `USER#${userId}`,
};

// Hierarchical data (e.g., organization)
const departmentKey = {
  pk: `ORG#${tenantCode}`,
  sk: `DEPT#${parentId}#${deptId}`,
};
```

## Table Attributes {#table-attributes}

### Common Attributes

All entity tables share these common attributes:

| Attribute | Type | Description |
|-----------|------|-------------|
| `pk` | String | Partition key |
| `sk` | String | Sort key |
| `id` | String | Unique identifier (`pk#sk`, @version stripped from sk) |
| `code` | String | Business code |
| `name` | String | Display name |
| `tenantCode` | String | Tenant identifier |
| `type` | String | Entity type |
| `version` | Number | Version for optimistic locking |
| `attributes` | Map | Custom entity attributes |
| `createdBy` | String | Creator user ID |
| `createdIp` | String | Creator IP address |
| `createdAt` | String | Creation timestamp (ISO 8601) |
| `updatedBy` | String | Last modifier user ID |
| `updatedIp` | String | Last modifier IP address |
| `updatedAt` | String | Last update timestamp (ISO 8601) |
| `seq` | Number | Sequence number for ordering |

### Command and Data Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `source` | String | Command source identifier |
| `requestId` | String | Request tracking ID |

## Secondary Indexes {#secondary-indexes}

### Adding Global Secondary Indexes

The default table configuration does not include GSIs. You can add them based on your query patterns. A common pattern is adding a code-index for fast lookups by business code:

Example GSI definition (add to your table configuration):

```json
{
  "GlobalSecondaryIndexes": [
    {
      "IndexName": "code-index",
      "KeySchema": [
        { "AttributeName": "tenantCode", "KeyType": "HASH" },
        { "AttributeName": "code", "KeyType": "RANGE" }
      ],
      "Projection": { "ProjectionType": "ALL" }
    }
  ]
}
```

Example usage with custom GSI:

```typescript
// Find entity by code (requires code-index GSI)
const params = {
  TableName: 'entity-data',
  IndexName: 'code-index',
  KeyConditionExpression: 'tenantCode = :tenant AND code = :code',
  ExpressionAttributeValues: {
    ':tenant': tenantCode,
    ':code': entityCode,
  },
};
```

## Best Practices {#best-practices}

### Key Design

1. **Keep partition keys broad**: Distribute data evenly across partitions
2. **Use hierarchical sort keys**: Enable efficient range queries
3. **Include tenant in partition key**: Ensure data isolation

### Query Optimization

1. **Use Query over Scan**: Always use partition key in queries
2. **Limit result sets**: Use pagination for large datasets
3. **Project needed attributes**: Only retrieve required fields

### Capacity Planning

1. **Use on-demand capacity**: Recommended for unpredictable workloads
2. **Monitor consumed capacity**: Set up CloudWatch alarms
3. **Consider DAX**: For read-heavy workloads requiring microsecond latency

## Local Development {#local-development}

### DynamoDB Local

The framework includes DynamoDB Local for development:

```bash
# Start DynamoDB Local (included in docker-compose)
docker-compose up -d dynamodb-local

# Access DynamoDB Local Admin UI
open http://localhost:8001
```

### Environment Variables

```bash
# Local DynamoDB endpoint
DYNAMODB_ENDPOINT=http://localhost:8000
DYNAMODB_REGION=ap-northeast-1
```

## Related Documentation

- [Key Patterns](/docs/key-patterns): Detailed key design strategies
- [Entity Patterns](/docs/entity-patterns): Entity modeling guidelines
- [Database Selection Guide](/docs/database-selection-guide): When to use DynamoDB vs RDS
- [Sequence](/docs/sequence): Sequence ID generation
- [CommandService](/docs/command-service): Command handling and data sync


---

## Prisma

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/prisma

# Prisma

In MBC CQRS Serverless, we use prisma as an ORM. It helps developers be more productive when working with databases.

A common scenario when working with Prisma is needing to make changes to the database, such as creating tables, updating fields in tables, etc. Follow these steps:

1. Update prisma/schema.prisma file.
2. For local development, create and apply migrations with command npm run migrate:dev.

## Setup {#setup}

### PrismaService

The `mbc new` CLI command generates a `PrismaService` in `src/prisma/prisma.service.ts`. It extends `PrismaClient` and integrates with NestJS's module lifecycle:

```typescript
// src/prisma/prisma.service.ts (generated by CLI)
import { Injectable, Logger, OnModuleInit, Inject, Optional } from '@nestjs/common';
import { Prisma, PrismaClient } from '@prisma/client';

@Injectable()
export class PrismaService
  extends PrismaClient<Prisma.PrismaClientOptions, 'query' | 'error'>
  implements OnModuleInit
{
  private readonly logger = new Logger(PrismaService.name);

  async onModuleInit() {
    // Lazy connection by default — avoids holding connections between Lambda invocations
    // Set explicitConnect: true in prismaServiceOptions only if you need startup connection
  }
}
```

### Register in AppModule {#register-prisma-module}

Register `PrismaModule` as a global module in `src/main.module.ts` so `PrismaService` is available in all modules without re-importing:

```typescript
import { Module } from '@nestjs/common';
import { PrismaModule } from './prisma';

@Module({
  imports: [
    PrismaModule.forRoot({
      isGlobal: true,            // Make PrismaService available everywhere without re-importing
      prismaServiceOptions: {
        explicitConnect: false,  // Recommended for Lambda: lazy connection per invocation
        prismaOptions: {
          log: process.env.NODE_ENV !== 'local' ? ['error'] : ['info', 'error', 'warn', 'query'],
        },
      },
    }),
    // ... other modules
  ],
})
export class MainModule {}
```

:::info Lambda Connection Management
Set `explicitConnect: false` (the default) for Lambda functions. Prisma establishes the RDS connection lazily on the first query and does not hold it between invocations. Use RDS Proxy in production to pool connections across concurrent Lambdas and prevent connection exhaustion.
:::

## Migration Scripts {#migration-scripts}

| Command | When to use | What it does |
|------------|-----------------|-----------------|
| `npm run migrate:dev` | Local development only | Creates a new Prisma migration file and applies it to the local RDS database. Use this when you change `schema.prisma`. |
| `npm run migrate` | Local setup and CI | Applies existing Prisma migrations to RDS (without creating new ones), then runs DynamoDB table migration. Use this after cloning or pulling. |
| `npm run migrate:ddb` | DynamoDB only | Creates or updates DynamoDB tables defined in `prisma/dynamodbs/*.json` without touching the RDS schema. |

:::warning

For local development, please make sure to set the correct `DATABASE_URL` environment variable.

```bash
# Example
DATABASE_URL="mysql://root:RootCqrs@localhost:3306/cqrs"
```

:::

> You could view [prisma-client documentation](https://www.prisma.io/docs/orm/prisma-client) for more information

## Design table convention {#design-table-convention}

When creating an RDS table that maps to a DynamoDB table, ensure you add the necessary fields and indexes to the RDS table accordingly. The `cpk`/`csk` fields store the original command table keys (used to link back to the DynamoDB command record). Include them when you need full traceability from RDS to DynamoDB; omit them if you only need the data table keys (`pk`/`sk`).

```prisma
model YourEntity {
  id         String   @id
  cpk        String // Command PK
  csk        String // Command SK
  pk         String // Data PK
  sk         String // Data SK
  tenantCode String   @map("tenant_code") // Tenant code
  seq        Int      @default(0) // Sort order, uses sequence feature
  code       String // Record code
  name       String // Record name
  version    Int // Version
  isDeleted  Boolean  @default(false) @map("is_deleted") // Deleted flag
  createdBy  String   @default("") @map("created_by") // Created by
  createdIp  String   @default("") @map("created_ip") // Created IP, supports IPv6
  createdAt  DateTime @default(now()) @map("created_at") @db.Timestamp(0) // Created at
  updatedBy  String   @default("") @map("updated_by") // Updated by
  updatedIp  String   @default("") @map("updated_ip") // Updated IP, supports IPv6
  updatedAt  DateTime @updatedAt @map("updated_at") @db.Timestamp(0) // Updated at

  // domain-specific properties

  // relations

  // index
  @@unique([cpk, csk])
  @@unique([pk, sk])
  @@unique([tenantCode, code])
  @@index([tenantCode, name])
}
```


## Related Documentation

- [Database Selection Guide](/docs/database-selection-guide) - Choosing between DynamoDB and RDS
- [Data Sync Handler Examples](/docs/data-sync-handler-examples) - Sync DynamoDB data to RDS
- [Environment Variables](/docs/environment-variables) - Database connection configuration
- [Deployment Guide](/docs/deployment-guide) - Database migration in deployment


---

# Frontend Development

## API Integration Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/api-integration-patterns

# API Integration Patterns

This guide explains how to connect frontend applications to MBC CQRS Serverless backends using auto-generated TypeScript SDKs. Type-safe API integration catches errors at compile time and provides excellent developer experience with autocomplete.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Connect a Next.js frontend to an MBC CQRS Serverless API
- Generate TypeScript types from OpenAPI specification
- Add authentication headers automatically to API requests
- Handle API errors consistently across the application
- Support multi-tenant API calls with tenant headers

## Problems This Pattern Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| Frontend types don't match backend API | Generate SDK from OpenAPI spec - types always match |
| Forgetting to add auth token to requests | Use interceptors to add headers automatically |
| Inconsistent error handling across components | Centralize error handling in API wrapper |
| Tenant header missing in some requests | Add tenant interceptor that reads from store |
| Hard to update when API changes | Regenerate SDK with one command |

## SDK Generation Setup {#sdk-generation-setup}

### Use Case: Generate Type-Safe API Client

Scenario: Backend team updates the API, and you need frontend types to match.

Solution: Generate SDK from OpenAPI specification file that backend exports.

### Installing Dependencies

```bash
npm install @hey-api/client-fetch
npm install -D @hey-api/openapi-ts
```

### Configuration

```typescript
// openapi-ts.config.ts
import { defineConfig } from '@hey-api/openapi-ts';

export default defineConfig({
  client: '@hey-api/client-fetch',
  input: './openapi.json', // or URL to OpenAPI spec
  output: {
    path: 'src/services/sdk',
    format: 'prettier',
  },
  services: {
    asClass: true,
  },
  types: {
    enums: 'javascript',
  },
});
```

### Package.json Scripts

```json
{
  "scripts": {
    "generate-sdk": "openapi-ts",
    "generate-sdk:watch": "openapi-ts --watch"
  }
}
```

## Generated SDK Structure {#generated-sdk-structure}

After running `npm run generate-sdk`, the following files are created:

```text
src/services/sdk/
├── client/
│   └── client.ts          # HTTP client configuration
├── types.gen.ts           # Generated TypeScript types
├── services.gen.ts        # Generated service classes
└── index.ts               # Main exports
```

### Generated Types Example

These types are generated from your OpenAPI spec and match your backend exactly:

```typescript
// src/services/sdk/types.gen.ts (auto-generated)
export interface Product {
  id: string;
  pk: string;
  sk: string;
  code: string;
  name: string;
  price: number;
  status: ProductStatus;
  attributes: ProductAttributes;
  version: number;
  createdAt: string;
  updatedAt: string;
}

export interface CreateProductDto {
  code: string;
  name: string;
  price: number;
  attributes?: ProductAttributes;
}

export interface UpdateProductDto {
  name?: string;
  price?: number;
  status?: ProductStatus;
  attributes?: ProductAttributes;
  version: number; // Required for optimistic locking
}

export interface ProductListResponse {
  items: Product[];
  count: number;
  hasMore: boolean;
}
```

### Generated Services Example

Service classes provide typed methods for each API endpoint:

```typescript
// src/services/sdk/services.gen.ts (auto-generated)
export class ProductService {
  static list(options?: { query?: ProductListParams }): Promise<ProductListResponse>;
  static get(options: { path: { pk: string; sk: string}}): Promise<Product>;
  static create(options: { body: CreateProductDto }): Promise<Product>;
  static update(options: { path: { pk: string; sk: string }; body: UpdateProductDto }): Promise<Product>;
  static delete(options: { path: { pk: string; sk: string}}): Promise<void>;
}
```

## Client Configuration {#client-configuration}

### Use Case: Add Authentication to All Requests

Scenario: Every API request needs a Bearer token from Cognito.

Problem: Manually adding headers to each request is error-prone.

Solution: Use interceptors to add authentication header automatically.

```typescript
// src/lib/api/client.ts
import { client } from '@/services/sdk/client';
import { fetchAuthSession } from 'aws-amplify/auth';
import { getTenantCode as getTenantFromStore } from '@/store/tenant';

// Configure the base URL
client.setConfig({
  baseUrl: process.env.NEXT_PUBLIC_API_URL,
});

// Add authentication interceptor
client.interceptors.request.use(async (request) => {
  try {
    const session = await fetchAuthSession();
    const token = session.tokens?.idToken?.toString();

    if (token) {
      request.headers.set('Authorization', `Bearer ${token}`);
    }
  } catch (error) {
    console.error('Failed to get auth token:', error);
  }

  return request;
});

// Add tenant header interceptor
client.interceptors.request.use((request) => {
  const tenantCode = getTenantFromStore(); // Get from Zustand store
  if (tenantCode) {
    request.headers.set('X-Tenant-Code', tenantCode);
  }
  return request;
});

// Add error handling interceptor
client.interceptors.response.use((response) => {
  if (!response.ok) {
    // Handle specific error codes
    if (response.status === 401) {
      // Redirect to login
      window.location.href = '/login';
    }
  }
  return response;
});

export { client };
```

### Use Case: Create API Wrapper with Error Handling

Scenario: Components need clean APIs that throw meaningful errors.

Problem: Generated SDK returns `{ data, error }` which requires handling in every component.

Solution: Create wrapper functions that throw on errors for use with React Query.

```typescript
// src/services/api/products.ts
import { ProductService, CreateProductDto, UpdateProductDto } from '@/services/sdk';
import type { Product, ProductListResponse } from '@/services/sdk';

export interface ProductFilters {
  status?: string;
  category?: string;
  search?: string;
  page?: number;
  limit?: number;
}

export const productApi = {
  async list(filters: ProductFilters = {}): Promise<ProductListResponse> {
    const { data, error } = await ProductService.list({
      query: {
        status: filters.status,
        category: filters.category,
        q: filters.search,
        page: filters.page ?? 1,
        limit: filters.limit ?? 20,
      },
    });

    if (error) {
      throw new Error(error.message || 'Failed to fetch products');
    }

    return data;
  },

  async get(pk: string, sk: string): Promise<Product> {
    const { data, error } = await ProductService.get({
      path: { pk, sk },
    });

    if (error) {
      throw new Error(error.message || 'Failed to fetch product');
    }

    return data;
  },

  async create(dto: CreateProductDto): Promise<Product> {
    const { data, error } = await ProductService.create({
      body: dto,
    });

    if (error) {
      throw new Error(error.message || 'Failed to create product');
    }

    return data;
  },

  async update(pk: string, sk: string, dto: UpdateProductDto): Promise<Product> {
    const { data, error } = await ProductService.update({
      path: { pk, sk },
      body: dto,
    });

    if (error) {
      throw new Error(error.message || 'Failed to update product');
    }

    return data;
  },

  async delete(pk: string, sk: string): Promise<void> {
    const { error } = await ProductService.delete({
      path: { pk, sk },
    });

    if (error) {
      throw new Error(error.message || 'Failed to delete product');
    }
  },
};
```

## React Query Integration {#react-query-integration}

### Use Case: Data Fetching with Caching

Scenario: Display product list and detail pages with efficient caching.

Solution: Create React Query hooks that use the API wrapper.

```typescript
// src/hooks/useProducts.ts
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
import { productApi, ProductFilters } from '@/services/api/products';
import type { CreateProductDto, UpdateProductDto } from '@/services/sdk';

export const productKeys = {
  all: ['products'] as const,
  lists: () => [...productKeys.all, 'list'] as const,
  list: (filters: ProductFilters) => [...productKeys.lists(), filters] as const,
  details: () => [...productKeys.all, 'detail'] as const,
  detail: (pk: string, sk: string) => [...productKeys.details(), pk, sk] as const,
};

export function useProducts(filters: ProductFilters = {}) {
  return useQuery({
    queryKey: productKeys.list(filters),
    queryFn: () => productApi.list(filters),
    staleTime: 60 * 1000, // 1 minute
  });
}

export function useProduct(pk: string, sk: string) {
  return useQuery({
    queryKey: productKeys.detail(pk, sk),
    queryFn: () => productApi.get(pk, sk),
    enabled: !!pk && !!sk,
  });
}

export function useCreateProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: (dto: CreateProductDto) => productApi.create(dto),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: productKeys.lists() });
    },
  });
}

export function useUpdateProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ pk, sk, dto }: { pk: string; sk: string; dto: UpdateProductDto }) =>
      productApi.update(pk, sk, dto),
    onSuccess: (_, { pk, sk }) => {
      queryClient.invalidateQueries({ queryKey: productKeys.lists() });
      queryClient.invalidateQueries({ queryKey: productKeys.detail(pk, sk) });
    },
  });
}

export function useDeleteProduct() {
  const queryClient = useQueryClient();

  return useMutation({
    mutationFn: ({ pk, sk }: { pk: string; sk: string }) =>
      productApi.delete(pk, sk),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: productKeys.lists() });
    },
  });
}
```

### Use Case: Product List with Filtering

Scenario: Display filterable, paginated product table.

```typescript
// src/containers/products/ProductList.tsx
'use client';

import { useProducts, useDeleteProduct } from '@/hooks/useProducts';
import { Button } from '@/components/ui/Button';
import { Table } from '@/components/ui/Table';
import { useState } from 'react';

export function ProductList() {
  const [filters, setFilters] = useState({ page: 1, limit: 20 });
  const { data, isLoading, error } = useProducts(filters);
  const deleteProduct = useDeleteProduct();

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  const handleDelete = async (pk: string, sk: string) => {
    if (confirm('Are you sure you want to delete this product?')) {
      await deleteProduct.mutateAsync({ pk, sk });
    }
  };

  return (
    <Table
      data={data?.items ?? []}
      columns={[
        { key: 'code', header: 'Code' },
        { key: 'name', header: 'Name' },
        { key: 'price', header: 'Price' },
        { key: 'status', header: 'Status' },
        {
          key: 'actions',
          header: 'Actions',
          render: (row) => (
            <Button
              variant="danger"
              size="sm"
              onClick={() => handleDelete(row.pk, row.sk)}
              loading={deleteProduct.isPending}
            >
              Delete
            </Button>
          ),
        },
      ]}
      pagination={{
        page: filters.page,
        limit: filters.limit,
        total: data?.count ?? 0,
        onChange: (page) => setFilters((f) => ({ ...f, page })),
     }}
    />
  );
}
```

## Error Handling {#error-handling}

### Use Case: Structured Error Responses

Scenario: Backend returns structured errors with field-level validation details.

Solution: Create error types that match backend response format.

```typescript
// src/types/api-errors.ts
export interface ApiError {
  statusCode: number;
  message: string;
  error?: string;
  details?: Record<string, string[]>;
}

export class ApiException extends Error {
  constructor(
    public statusCode: number,
    message: string,
    public details?: Record<string, string[]>
  ) {
    super(message);
    this.name = 'ApiException';
  }
}
```

### Use Case: Centralized Error Handler

Scenario: Convert various error types to consistent ApiException.

```typescript
// src/lib/api/error-handler.ts
import { ApiException } from '@/types/api-errors';

export function handleApiError(error: unknown): never {
  if (error instanceof ApiException) {
    throw error;
  }

  if (error instanceof Error) {
    throw new ApiException(500, error.message);
  }

  throw new ApiException(500, 'An unexpected error occurred');
}

// Usage in API wrapper
export const productApi = {
  async list(filters: ProductFilters = {}): Promise<ProductListResponse> {
    try {
      const { data, error } = await ProductService.list({
        query: filters,
      });

      if (error) {
        throw new ApiException(
          error.statusCode ?? 500,
          error.message ?? 'Request failed',
          error.details
        );
      }

      return data;
    } catch (error) {
      handleApiError(error);
    }
  },
};
```

### Use Case: Display Errors with Field Details

Scenario: Show validation errors returned by the server.

```typescript
// src/components/ApiError.tsx
import { ApiException } from '@/types/api-errors';
import { Alert } from '@/components/ui/Alert';

interface ApiErrorProps {
  error: Error | null;
}

export function ApiError({ error }: ApiErrorProps) {
  if (!error) return null;

  const isApiException = error instanceof ApiException;

  return (
    <Alert variant="error">
      <p>{error.message}</p>
      {isApiException && error.details && (
        <ul className="mt-2 list-disc list-inside">
          {Object.entries(error.details).map(([field, messages]) => (
            <li key={field}>
              <strong>{field}:</strong> {messages.join(', ')}
            </li>
          ))}
        </ul>
      )}
    </Alert>
  );
}
```

## Multi-Tenant API Calls {#multi-tenant-api-calls}

### Use Case: Tenant Context for SaaS Applications

Scenario: User can switch between tenants, and all API calls should use the selected tenant.

Solution: Store tenant in context/store and add to API headers automatically.

```typescript
// src/contexts/TenantContext.tsx
'use client';

import { createContext, useContext, ReactNode } from 'react';
import type { Tenant } from '@/stores/useTenantStore';
import { useTenantStore } from '@/stores/useTenantStore';

interface TenantContextValue {
  tenantCode: string | null;
  setTenant: (code: string) => void;
}

const TenantContext = createContext<TenantContextValue | undefined>(undefined);

export function TenantProvider({ children }: { children: ReactNode }) {
  const { currentTenant, setCurrentTenant } = useTenantStore();

  return (
    <TenantContext.Provider
      value={{
        tenantCode: currentTenant?.code ?? null,
        setTenant: (code) => setCurrentTenant({ code } as Tenant),
     }}
    >
      {children}
    </TenantContext.Provider>
  );
}

export function useTenant() {
  const context = useContext(TenantContext);
  if (!context) {
    throw new Error('useTenant must be used within TenantProvider');
  }
  return context;
}
```

### Use Case: Tenant-Scoped Queries

Scenario: Product list should only show products for the current tenant.

```typescript
// src/hooks/useTenantProducts.ts
import { useQuery } from '@tanstack/react-query';
import { useTenant } from '@/contexts/TenantContext';
import { productApi } from '@/services/api/products';

export function useTenantProducts() {
  const { tenantCode } = useTenant();

  return useQuery({
    queryKey: ['products', tenantCode],
    queryFn: () => productApi.list(),
    enabled: !!tenantCode,
  });
}
```

## File Upload Integration {#file-upload-integration}

### Use Case: Upload Files to S3 via API

Scenario: User uploads product images that need to be stored in S3.

```typescript
// src/services/api/files.ts
import { FileService } from '@/services/sdk';

export const fileApi = {
  async upload(file: File, path: string): Promise<{ url: string }> {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('path', path);

    const { data, error } = await FileService.upload({
      body: formData,
    });

    if (error) {
      throw new Error(error.message || 'Upload failed');
    }

    return data;
  },

  async getPresignedUrl(key: string): Promise<{ url: string; expiresIn: number }> {
    const { data, error } = await FileService.getPresignedUrl({
      query: { key },
    });

    if (error) {
      throw new Error(error.message || 'Failed to get presigned URL');
    }

    return data;
  },
};
```

## Best Practices {#best-practices}

### 1. Always Regenerate SDK After Backend Changes

When: Backend team deploys API changes.

Why: Ensures frontend types match backend exactly.

```bash
# After backend API changes
npm run generate-sdk
```

### 2. Use Type Guards

When: Working with unknown data from external sources.

```typescript
function isProduct(data: unknown): data is Product {
  return (
    typeof data === 'object' &&
    data !== null &&
    'id' in data &&
    'pk' in data &&
    'sk' in data
  );
}
```

### 3. Handle Loading and Error States

When: Displaying data from API queries.

```typescript
function ProductDetail({ pk, sk }: { pk: string; sk: string }) {
  const { data, isLoading, error, refetch } = useProduct(pk, sk);

  if (isLoading) {
    return <Skeleton />;
  }

  if (error) {
    return (
      <ErrorState
        message={error.message}
        onRetry={() => refetch()}
      />
    );
  }

  if (!data) {
    return <NotFound />;
  }

  return <ProductView product={data} />;
}
```

### 4. Version Handling for Updates

When: Updating entities that use optimistic locking.

Why: MBC CQRS Serverless uses version field to prevent concurrent update conflicts.

```typescript
function useUpdateProductWithVersion() {
  const queryClient = useQueryClient();
  const updateProduct = useUpdateProduct();

  return {
    ...updateProduct,
    mutateAsync: async ({ pk, sk, dto }: UpdateParams) => {
      // Get current version from cache
      const cached = queryClient.getQueryData<Product>(
        productKeys.detail(pk, sk)
      );

      if (!cached) {
        throw new Error('Product not found in cache');
      }

      return updateProduct.mutateAsync({
        pk,
        sk,
        dto: { ...dto, version: cached.version },
      });
    },
  };
}
```

### 5. Retry Configuration

When: Configuring React Query client.

Why: Avoid retrying client errors (4xx) that will always fail.

```typescript
// src/lib/api/query-client.ts
import { QueryClient } from '@tanstack/react-query';

export const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000,
      retry: (failureCount, error) => {
        // Don't retry on 4xx errors
        if (error instanceof ApiException && error.statusCode < 500) {
          return false;
        }
        return failureCount < 3;
      },
    },
    mutations: {
      retry: false, // Don't retry mutations by default
    },
  },
});
```


## Related Documentation

- [API Integration Guide](/docs/api-integration-guide) - API integration guidance
- [Frontend Project Structure](/docs/frontend-project-structure) - Project organization
- [State Management Patterns](/docs/state-management-patterns) - Frontend state management
- [Form Handling Patterns](/docs/form-handling-patterns) - Form handling


---

## Form Handling Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/form-handling-patterns

# Form Handling Patterns

This guide explains how to build type-safe forms with validation using React Hook Form and Zod. These patterns ensure data integrity before sending to the API and provide clear feedback to users.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Build forms for creating and editing entities (products, users, orders)
- Validate user input before submitting to the API
- Display field-level error messages to users
- Handle complex forms with dynamic fields (order items, tags)
- Show conditional fields based on other form values

## Problems This Pattern Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| Invalid data sent to API | Zod validates before submission |
| Type mismatch between form and API | Infer TypeScript types from Zod schema |
| Form re-renders on every keystroke | React Hook Form uses uncontrolled inputs |
| Hard to show validation errors | Automatic error state per field |
| Dynamic fields are complex to manage | useFieldArray handles add/remove |

## Technology Stack {#technology-stack}

| Library | Purpose |
|---------|---------|
| React Hook Form | Form state management |
| Zod | Schema validation |
| @hookform/resolvers | Zod integration |
| shadcn/ui Form | Form UI components |

## Installation {#installation}

```bash
npm install react-hook-form zod @hookform/resolvers
```

## Form Component Architecture {#form-architecture}

The form system uses a layered component architecture:

| Component | Role |
|-----------|------|
| `Form` | Context provider that wraps the entire form (uses FormProvider from react-hook-form) |
| `FormField` | Connects a field to form state using Controller |
| `FormItem` | Container for a single form field (label, input, error) |
| `FormLabel` | Label that auto-connects to the field and shows error state |
| `FormControl` | Passes form field props to the input element |
| `FormMessage` | Displays validation error message |
| `FormDescription` | Optional help text for the field |

## Basic Form Structure {#basic-form-structure}

### Use Case: Product Create Form

Scenario: User needs to create a new product with code, name, price, and status.

Solution: Define schema with validation rules, use Form components for consistent error display.

### Zod Schema Definition

Define validation rules that match your API requirements:

```typescript
// src/schemas/product.schema.ts
import { z } from 'zod';

export const createProductSchema = z.object({
  code: z
    .string()
    .min(1, 'Code is required')
    .max(50, 'Code must be 50 characters or less')
    .regex(/^[A-Z0-9-]+$/, 'Code must be uppercase alphanumeric with hyphens'),
  name: z
    .string()
    .min(1, 'Name is required')
    .max(200, 'Name must be 200 characters or less'),
  price: z
    .number()
    .min(0, 'Price must be positive')
    .max(999999999, 'Price exceeds maximum'),
  description: z
    .string()
    .max(2000, 'Description must be 2000 characters or less')
    .optional(),
  categoryId: z.string().min(1, 'Category is required'),
  status: z.enum(['ACTIVE', 'INACTIVE', 'DRAFT']),
});

export type CreateProductInput = z.infer<typeof createProductSchema>;

// Update schema with optional fields and version
export const updateProductSchema = createProductSchema.partial().extend({
  version: z.number().int().min(0),
});

export type UpdateProductInput = z.infer<typeof updateProductSchema>;
```

### Form Component

Connect the schema to React Hook Form using Form components:

```typescript
// src/components/forms/ProductForm.tsx
'use client';

import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import {
  createProductSchema,
  CreateProductInput,
} from '@/schemas/product.schema';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Textarea } from '@/components/ui/textarea';
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@/components/ui/select';

interface ProductFormProps {
  onSubmit: (data: CreateProductInput) => Promise<void>;
  defaultValues?: Partial<CreateProductInput>;
  isLoading?: boolean;
}

export function ProductForm({
  onSubmit,
  defaultValues,
  isLoading,
}: ProductFormProps) {
  const form = useForm<CreateProductInput>({
    resolver: zodResolver(createProductSchema),
    defaultValues: {
      status: 'DRAFT',
      ...defaultValues,
    },
  });

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
        <FormField
          control={form.control}
          name="code"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Code</FormLabel>
              <FormControl>
                <Input {...field} disabled={isLoading} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="name"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Name</FormLabel>
              <FormControl>
                <Input {...field} disabled={isLoading} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="price"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Price</FormLabel>
              <FormControl>
                <Input
                  type="number"
                  {...field}
                  onChange={(e) => field.onChange(Number(e.target.value))}
                  disabled={isLoading}
                />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="description"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Description</FormLabel>
              <FormControl>
                <Textarea {...field} disabled={isLoading} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          control={form.control}
          name="status"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Status</FormLabel>
              <Select
                onValueChange={field.onChange}
                defaultValue={field.value}
                disabled={isLoading}
              >
                <FormControl>
                  <SelectTrigger>
                    <SelectValue placeholder="Select status" />
                  </SelectTrigger>
                </FormControl>
                <SelectContent>
                  <SelectItem value="DRAFT">Draft</SelectItem>
                  <SelectItem value="ACTIVE">Active</SelectItem>
                  <SelectItem value="INACTIVE">Inactive</SelectItem>
                </SelectContent>
              </Select>
              <FormMessage />
            </FormItem>
          )}
        />

        <Button
          type="submit"
          disabled={form.formState.isSubmitting || isLoading}
        >
          {form.formState.isSubmitting || isLoading ? 'Saving...' : 'Save'}
        </Button>
      </form>
    </Form>
  );
}
```

## Reusable Form Components {#reusable-components}

### Use Case: Consistent Form Field Styling

Scenario: All form fields should have consistent label, error display, and required indicator.

Solution: Create a custom wrapper component that uses shadcn/ui Form components.

```typescript
// src/components/form/CustomFormItem.tsx
'use client';

import * as React from 'react';
import { FormItem, FormLabel, FormMessage } from '@/components/ui/form';
import { cn } from '@/lib/utils';

export default function CustomFormItem({
  className,
  label,
  required,
  children,
}: {
  className?: string;
  label: string;
  children: React.ReactNode;
  required?: boolean;
}) {
  return (
    <FormItem className={cn('flex w-full flex-col gap-2', className)}>
      <FormLabel className="font-semibold">
        <span className="text-[hsl(var(--foreground))]">{label}</span>
        {required && <span className="text-destructive ml-1">*</span>}
      </FormLabel>
      <div className="relative flex-col">
        {children}
        <FormMessage className="mt-2 text-xs font-semibold" />
      </div>
    </FormItem>
  );
}
```

### Using CustomFormItem

```typescript
<FormField
  control={form.control}
  name="code"
  render={({ field }) => (
    <CustomFormItem label="Code" required>
      <FormControl>
        <Input {...field} />
      </FormControl>
    </CustomFormItem>
  )}
/>
```

### Input Component (Simple, No Error Prop)

Note: The Input component does NOT have an error prop. Error display is handled by FormMessage.

```typescript
// src/components/ui/input.tsx
import * as React from 'react';
import { cn } from '@/lib/utils';

export interface InputProps
  extends React.InputHTMLAttributes<HTMLInputElement> {}

const Input = React.forwardRef<HTMLInputElement, InputProps>(
  ({ className, type, ...props }, ref) => {
    return (
      <input
        type={type}
        className={cn(
          'flex h-10 w-full rounded-md border border-[hsl(var(--input))] bg-[hsl(var(--background))] px-3 py-2 text-sm ring-offset-[hsl(var(--background))] file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-[hsl(var(--muted-foreground))] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[hsl(var(--ring))] focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
          className
        )}
        ref={ref}
        {...props}
      />
    );
  }
);

Input.displayName = 'Input';

export { Input };
```

## Form Component Implementation {#form-implementation}

The Form components from shadcn/ui provide context-based error handling:

```typescript
// src/components/ui/form.tsx
import * as React from 'react';
import * as LabelPrimitive from '@radix-ui/react-label';
import { Slot } from '@radix-ui/react-slot';
import {
  Controller,
  ControllerProps,
  FieldPath,
  FieldValues,
  FormProvider,
  useFormContext,
} from 'react-hook-form';
import { cn } from '@/lib/utils';
import { Label } from './label';

// Form is just FormProvider re-exported
const Form = FormProvider;

// Context type for FormField
type FormFieldContextValue<
  TFieldValues extends FieldValues = FieldValues,
  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
> = {
  name: TName;
};

const FormFieldContext = React.createContext<FormFieldContextValue>(
  {} as FormFieldContextValue
);

// FormField wraps Controller and provides field context
const FormField = <
  TFieldValues extends FieldValues = FieldValues,
  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
>({
  ...props
}: ControllerProps<TFieldValues, TName>) => {
  return (
    <FormFieldContext.Provider value={{ name: props.name }}>
      <Controller {...props} />
    </FormFieldContext.Provider>
  );
};

// useFormField hook retrieves field state from context
const useFormField = () => {
  const fieldContext = React.useContext(FormFieldContext);
  const itemContext = React.useContext(FormItemContext);
  const { getFieldState, formState } = useFormContext();

  const fieldState = getFieldState(fieldContext.name, formState);

  if (!fieldContext) {
    throw new Error('useFormField should be used within <FormField>');
  }

  const { id } = itemContext;

  return {
    id,
    name: fieldContext.name,
    formItemId: `${id}-form-item`,
    formDescriptionId: `${id}-form-item-description`,
    formMessageId: `${id}-form-item-message`,
    ...fieldState,
  };
};

// Context type for FormItem
type FormItemContextValue = {
  id: string;
};

const FormItemContext = React.createContext<FormItemContextValue>(
  {} as FormItemContextValue
);

// FormItem provides unique ID via context
const FormItem = React.forwardRef<
  HTMLDivElement,
  React.HTMLAttributes<HTMLDivElement>
>(({ className, ...props }, ref) => {
  const id = React.useId();

  return (
    <FormItemContext.Provider value={{ id }}>
      <div ref={ref} className={cn('space-y-2', className)} {...props} />
    </FormItemContext.Provider>
  );
});
FormItem.displayName = 'FormItem';

// FormLabel shows error state via color
const FormLabel = React.forwardRef<
  React.ElementRef<typeof LabelPrimitive.Root>,
  React.ComponentPropsWithoutRef<typeof LabelPrimitive.Root>
>(({ className, ...props }, ref) => {
  const { error, formItemId } = useFormField();

  return (
    <Label
      ref={ref}
      className={cn(error && 'text-[hsl(var(--destructive))]', className)}
      htmlFor={formItemId}
      {...props}
    />
  );
});
FormLabel.displayName = 'FormLabel';

// FormControl passes aria attributes for accessibility
const FormControl = React.forwardRef<
  React.ElementRef<typeof Slot>,
  React.ComponentPropsWithoutRef<typeof Slot>
>(({ ...props }, ref) => {
  const { error, formItemId, formDescriptionId, formMessageId } = useFormField();

  return (
    <Slot
      ref={ref}
      id={formItemId}
      aria-describedby={
        !error
          ? `${formDescriptionId}`
          : `${formDescriptionId} ${formMessageId}`
      }
      aria-invalid={!!error}
      {...props}
    />
  );
});
FormControl.displayName = 'FormControl';

// FormDescription provides help text
const FormDescription = React.forwardRef<
  HTMLParagraphElement,
  React.HTMLAttributes<HTMLParagraphElement>
>(({ className, ...props }, ref) => {
  const { formDescriptionId } = useFormField();

  return (
    <p
      ref={ref}
      id={formDescriptionId}
      className={cn('text-sm text-[hsl(var(--muted-foreground))]', className)}
      {...props}
    />
  );
});
FormDescription.displayName = 'FormDescription';

// FormMessage automatically displays error from context
const FormMessage = React.forwardRef<
  HTMLParagraphElement,
  React.HTMLAttributes<HTMLParagraphElement>
>(({ className, children, ...props }, ref) => {
  const { error, formMessageId } = useFormField();
  const body = error ? String(error?.message) : children;

  if (!body) {
    return null;
  }

  return (
    <p
      ref={ref}
      id={formMessageId}
      className={cn(
        'text-sm font-medium text-[hsl(var(--destructive))]',
        className
      )}
      {...props}
    >
      {body}
    </p>
  );
});
FormMessage.displayName = 'FormMessage';

export {
  useFormField,
  Form,
  FormItem,
  FormLabel,
  FormControl,
  FormDescription,
  FormMessage,
  FormField,
};
```

## Advanced Form Patterns {#advanced-patterns}

### Use Case: Order Form with Multiple Items

Scenario: User creates an order with multiple line items. Items can be added or removed.

Problem: Managing array of fields with validation is complex.

Solution: useFieldArray provides add, remove, and update methods with proper validation.

```typescript
// src/components/forms/OrderForm.tsx
import { useForm, useFieldArray } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form';
import { Input } from '@/components/ui/input';
import { Button } from '@/components/ui/button';

const orderItemSchema = z.object({
  productId: z.string().min(1, 'Product is required'),
  quantity: z.number().min(1, 'Quantity must be at least 1'),
  price: z.number().min(0),
});

const orderSchema = z.object({
  customerId: z.string().min(1, 'Customer is required'),
  items: z.array(orderItemSchema).min(1, 'At least one item is required'),
  notes: z.string().optional(),
});

type OrderInput = z.infer<typeof orderSchema>;

export function OrderForm({
  onSubmit,
}: {
  onSubmit: (data: OrderInput) => void;
}) {
  const form = useForm<OrderInput>({
    resolver: zodResolver(orderSchema),
    defaultValues: {
      items: [{ productId: '', quantity: 1, price: 0 }],
    },
  });

  const { fields, append, remove } = useFieldArray({
    control: form.control,
    name: 'items',
  });

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>
        <FormField
          control={form.control}
          name="customerId"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Customer</FormLabel>
              <FormControl>
                <Input {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <div className="space-y-4">
          <h3>Order Items</h3>
          {fields.map((field, index) => (
            <div key={field.id} className="flex gap-4 items-end">
              <FormField
                control={form.control}
                name={`items.${index}.productId`}
                render={({ field }) => (
                  <FormItem>
                    <FormControl>
                      <Input {...field} placeholder="Product ID" />
                    </FormControl>
                    <FormMessage />
                  </FormItem>
                )}
              />
              <FormField
                control={form.control}
                name={`items.${index}.quantity`}
                render={({ field }) => (
                  <FormItem>
                    <FormControl>
                      <Input
                        type="number"
                        {...field}
                        onChange={(e) => field.onChange(Number(e.target.value))}
                        placeholder="Qty"
                      />
                    </FormControl>
                    <FormMessage />
                  </FormItem>
                )}
              />
              <Button type="button" variant="destructive" onClick={() => remove(index)}>
                Remove
              </Button>
            </div>
          ))}
          <Button
            type="button"
            variant="secondary"
            onClick={() => append({ productId: '', quantity: 1, price: 0 })}
          >
            Add Item
          </Button>
        </div>

        <Button type="submit">Create Order</Button>
      </form>
    </Form>
  );
}
```

### Use Case: Payment Form with Conditional Fields

Scenario: Form shows different fields based on payment method selection.

Problem: Need to watch a field value and conditionally render other fields.

Solution: useWatch subscribes to field changes without causing full form re-render.

```typescript
import { useForm, useWatch } from 'react-hook-form';
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@/components/ui/form';
import { Input } from '@/components/ui/input';
import {
  Select,
  SelectContent,
  SelectItem,
  SelectTrigger,
  SelectValue,
} from '@/components/ui/select';

function PaymentForm() {
  const form = useForm({
    defaultValues: {
      paymentMethod: 'credit_card',
      cardNumber: '',
      bankAccount: '',
    },
  });

  const paymentMethod = useWatch({
    control: form.control,
    name: 'paymentMethod',
  });

  return (
    <Form {...form}>
      <form>
        <FormField
          control={form.control}
          name="paymentMethod"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Payment Method</FormLabel>
              <Select onValueChange={field.onChange} defaultValue={field.value}>
                <FormControl>
                  <SelectTrigger>
                    <SelectValue />
                  </SelectTrigger>
                </FormControl>
                <SelectContent>
                  <SelectItem value="credit_card">Credit Card</SelectItem>
                  <SelectItem value="bank_transfer">Bank Transfer</SelectItem>
                </SelectContent>
              </Select>
              <FormMessage />
            </FormItem>
          )}
        />

        {paymentMethod === 'credit_card' && (
          <FormField
            control={form.control}
            name="cardNumber"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Card Number</FormLabel>
                <FormControl>
                  <Input {...field} placeholder="Card Number" />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
        )}

        {paymentMethod === 'bank_transfer' && (
          <FormField
            control={form.control}
            name="bankAccount"
            render={({ field }) => (
              <FormItem>
                <FormLabel>Bank Account</FormLabel>
                <FormControl>
                  <Input {...field} placeholder="Bank Account" />
                </FormControl>
                <FormMessage />
              </FormItem>
            )}
          />
        )}
      </form>
    </Form>
  );
}
```

## Form with React Query {#react-query}

### Use Case: Create Product with API Integration

Scenario: Submit form data to API and handle success/error states.

Solution: Container component combines form with React Query mutation.

```typescript
// src/containers/products/CreateProductForm.tsx
'use client';

import { useRouter } from 'next/navigation';
import { useCreateProduct } from '@/hooks/useProducts';
import { ProductForm } from '@/components/forms/ProductForm';
import { CreateProductInput } from '@/schemas/product.schema';
import { toast } from '@/components/ui/toast';

export function CreateProductForm() {
  const router = useRouter();
  const createProduct = useCreateProduct();

  const handleSubmit = async (data: CreateProductInput) => {
    try {
      await createProduct.mutateAsync(data);
      toast.success('Product created successfully');
      router.push('/products');
    } catch (error) {
      toast.error(
        error instanceof Error ? error.message : 'Failed to create product'
      );
    }
  };

  return (
    <ProductForm onSubmit={handleSubmit} isLoading={createProduct.isPending} />
  );
}
```

### Use Case: Edit Product with Pre-populated Data

Scenario: Load existing product data into form for editing.

Problem: Need to fetch data before rendering form with default values.

Solution: Container fetches data, passes to form as defaultValues.

```typescript
// src/containers/products/EditProductForm.tsx
'use client';

import { useRouter } from 'next/navigation';
import { useProduct, useUpdateProduct } from '@/hooks/useProducts';
import { ProductForm } from '@/components/forms/ProductForm';
import { UpdateProductInput } from '@/schemas/product.schema';
import { toast } from '@/components/ui/toast';
import { Skeleton } from '@/components/ui/skeleton';
import { NotFound } from '@/components/not-found';

interface EditProductFormProps {
  pk: string;
  sk: string;
}

export function EditProductForm({ pk, sk }: EditProductFormProps) {
  const router = useRouter();
  const { data: product, isLoading } = useProduct(pk, sk);
  const updateProduct = useUpdateProduct();

  const handleSubmit = async (data: UpdateProductInput) => {
    try {
      await updateProduct.mutateAsync({
        pk,
        sk,
        dto: { ...data, version: product!.version },
      });
      toast.success('Product updated successfully');
      router.push('/products');
    } catch (error) {
      toast.error(
        error instanceof Error ? error.message : 'Failed to update product'
      );
    }
  };

  if (isLoading) return <Skeleton />;
  if (!product) return <NotFound />;

  return (
    <ProductForm
      defaultValues={product}
      onSubmit={handleSubmit}
      isLoading={updateProduct.isPending}
    />
  );
}
```

## Complex Validation Patterns {#complex-validation}

### Use Case: Date Range Validation

Scenario: End date must be after start date.

Solution: Use Zod refine to validate across multiple fields.

```typescript
const dateRangeSchema = z
  .object({
    startDate: z.date(),
    endDate: z.date(),
  })
  .refine((data) => data.endDate >= data.startDate, {
    message: 'End date must be after start date',
    path: ['endDate'],
  });
```

### Use Case: Unique Code Validation

Scenario: Product code must not already exist in database.

Problem: Need to call API to check uniqueness.

Solution: Use async refine to validate against API.

```typescript
const uniqueCodeSchema = z.object({
  code: z
    .string()
    .min(1, 'Code is required')
    .refine(
      async (code) => {
        const exists = await checkCodeExists(code);
        return !exists;
      },
      { message: 'This code is already in use' }
    ),
});

// In the form
const form = useForm({
  resolver: zodResolver(uniqueCodeSchema),
  mode: 'onBlur', // Validate on blur for async validation
});
```

## Best Practices {#best-practices}

### 1. Colocate Schemas with Forms

Why: Keeps validation logic close to the form that uses it.

```text
src/
├── components/forms/
│   └── ProductForm/
│       ├── ProductForm.tsx
│       ├── ProductForm.schema.ts
│       └── index.ts
```

### 2. Use Mode Appropriately

Choose validation timing based on form complexity:

```typescript
// Validate on submit (default) - best for simple forms
useForm({ mode: 'onSubmit' });

// Validate on blur - best for forms with async validation
useForm({ mode: 'onBlur' });

// Validate on change - best for real-time feedback
useForm({ mode: 'onChange' });
```

### 3. Extract Common Schemas

Why: Reuse validation rules across multiple forms.

```typescript
// src/schemas/common.ts
export const requiredString = z.string().min(1, 'This field is required');
export const email = z.string().email('Invalid email address');
export const positiveNumber = z.number().positive('Must be positive');
```

### 4. Handle Server Errors

Scenario: Server returns field-level validation errors.

Solution: Use setError to display server errors on specific fields.

```typescript
function FormWithServerErrors() {
  const form = useForm();

  const onSubmit = async (data) => {
    try {
      await api.create(data);
    } catch (error) {
      if (error.details) {
        // Set field-level errors from server
        Object.entries(error.details).forEach(([field, messages]) => {
          form.setError(field, { message: messages[0] });
        });
      }
    }
  };

  return (
    <Form {...form}>
      <form onSubmit={form.handleSubmit(onSubmit)}>...</form>
    </Form>
  );
}
```


## Related Documentation

- [API Integration Patterns](/docs/api-integration-patterns) - API calls from forms
- [Survey Web](/docs/survey-web) - Form components for survey use case
- [Frontend Project Structure](/docs/frontend-project-structure) - Project organization
- [State Management Patterns](/docs/state-management-patterns) - Form state


---

## Frontend Project Structure

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/frontend-project-structure

# Frontend Project Structure

This guide explains how to organize a Next.js frontend application that integrates with an MBC CQRS Serverless backend. A well-structured project improves maintainability, enables team collaboration, and scales effectively as the application grows.

## When to Use This Guide {#when-to-use}

Use this guide when you are:

- Building a new frontend application that connects to an MBC CQRS Serverless API
- Migrating an existing React application to Next.js with App Router
- Setting up a multi-tenant SaaS application with Cognito authentication
- Creating an admin panel or dashboard for CQRS-based data management

## Problems This Structure Solves {#problems-solved}

| Problem | Solution |
|---------|----------|
| Mixing server and client code causes hydration errors | Separate containers (client) from pages (server) |
| API types get out of sync with backend | Use generated OpenAPI SDK in services/sdk |
| State management becomes chaotic | Separate server state (React Query) from client state (Zustand) |
| Components become too large and hard to test | Split into ui (presentation), forms (input), and containers (logic) |
| Authentication logic scattered across files | Centralize in lib/auth with Amplify configuration |

## Technology Stack {#technology-stack}

| Category | Technology | Purpose |
|----------|------------|---------|
| Framework | Next.js 15+ | React framework with App Router |
| Language | TypeScript | Type-safe development |
| State Management | Zustand | Client-side state management |
| Server State | TanStack React Query | Server state caching and synchronization |
| Forms | React Hook Form + Zod | Form handling with validation |
| Authentication | AWS Amplify | Cognito integration |
| API Client | OpenAPI SDK | Type-safe API calls |
| Styling | Tailwind CSS | Utility-first CSS |
| UI Components | Ant Design / Radix UI | Component library |

## Directory Structure {#directory-structure}

The following structure separates concerns clearly and scales well for medium to large applications:

```text
src/
├── app/                      # Next.js App Router pages
│   ├── (auth)/              # Authentication routes (login, etc.)
│   ├── (main)/              # Main application routes
│   │   ├── dashboard/       # Dashboard page
│   │   ├── products/        # Product management
│   │   │   ├── page.tsx     # List page
│   │   │   ├── [id]/        # Detail/Edit pages
│   │   │   └── new/         # Create page
│   │   └── settings/        # Settings pages
│   ├── layout.tsx           # Root layout
│   └── providers.tsx        # Global providers
│
├── components/              # Reusable UI components
│   ├── ui/                  # Base UI components
│   │   ├── Button/
│   │   ├── Input/
│   │   ├── Modal/
│   │   ├── Spinner/
│   │   └── Table/
│   ├── products/            # Product-specific components
│   │   └── ProductTable/
│   ├── forms/               # Form components
│   │   ├── ProductForm/
│   │   └── UserForm/
│   └── layouts/             # Layout components
│       ├── Header/
│       ├── Sidebar/
│       └── Footer/
│
├── containers/              # Feature-specific containers
│   ├── products/
│   │   ├── ProductList.tsx
│   │   ├── ProductDetail.tsx
│   │   └── ProductForm.tsx
│   └── users/
│       ├── UserList.tsx
│       └── UserDetail.tsx
│
├── services/                # API services
│   ├── sdk/                 # Generated OpenAPI SDK
│   │   ├── client/
│   │   ├── types.gen.ts
│   │   └── services.gen.ts
│   └── api/                 # API wrapper functions
│       ├── products.ts
│       └── users.ts
│
├── stores/                  # Zustand stores
│   ├── useAuthStore.ts
│   ├── useUIStore.ts
│   └── index.ts
│
├── hooks/                   # Custom React hooks
│   ├── useProducts.ts       # Product-related hooks
│   ├── useAuth.ts           # Authentication hooks
│   └── usePagination.ts     # Pagination hooks
│
├── lib/                     # Utility libraries
│   ├── auth/                # Auth utilities
│   ├── api/                 # API utilities
│   └── utils/               # General utilities
│
├── types/                   # TypeScript types
│   ├── api.ts               # API-related types
│   ├── models.ts            # Domain models
│   └── common.ts            # Common types
│
└── constants/               # Application constants
    ├── routes.ts            # Route constants
    └── config.ts            # Configuration constants
```

## Key Directory Explanations {#key-directories}

### app/ - Page Routes

Use Case: Define URL routes and page metadata. Pages should be thin wrappers that import containers.

Why: Next.js App Router uses file-based routing. Keeping pages simple allows containers to be tested independently.

### containers/ - Business Logic

Use Case: Handle data fetching, state management, and user interactions for specific features.

Why: Separating business logic from presentation makes components reusable and testable.

### components/ui/ - Design System

Use Case: Build consistent UI elements used across the application.

Why: A shared component library ensures visual consistency and reduces code duplication.

### services/sdk/ - API Types

Use Case: Auto-generated TypeScript types and API clients from OpenAPI specification.

Why: Ensures frontend types match backend exactly, catching type errors at compile time.

### stores/ - Client State

Use Case: Manage UI state like sidebar open/close, theme, selected tenant.

Why: Zustand provides simple, performant state management without boilerplate.

### hooks/ - React Query Hooks

Use Case: Wrap API calls with caching, loading states, and error handling.

Why: React Query handles server state complexity (caching, refetching, optimistic updates).

## App Router Structure {#app-router-structure}

### Route Groups

Use Case: Organize routes by authentication requirement without affecting URLs.

Example: (auth) group for login/register pages, (main) group for authenticated pages.

```typescript
// src/app/(auth)/login/page.tsx
// URL: /login - No authentication required

// src/app/(main)/dashboard/page.tsx
// URL: /dashboard - Requires authentication

// src/app/(main)/products/page.tsx
// URL: /products - Requires authentication
```

### Layout Pattern

Use Case: Share common UI elements (header, sidebar) across multiple pages.

Example: Main layout with navigation for all authenticated pages.

```typescript
// src/app/(main)/layout.tsx
import { Sidebar } from '@/components/layouts/Sidebar';
import { Header } from '@/components/layouts/Header';

export default function MainLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <div className="flex h-screen">
      <Sidebar />
      <div className="flex-1 flex flex-col">
        <Header />
        <main className="flex-1 overflow-auto p-6">
          {children}
        </main>
      </div>
    </div>
  );
}
```

### Page Pattern

Use Case: Define route entry points that delegate to containers.

Why: Pages handle metadata (title, description) while containers handle rendering logic.

```typescript
// src/app/(main)/products/page.tsx
import { ProductList } from '@/containers/products/ProductList';

export const metadata = {
  title: 'Products',
};

export default function ProductsPage() {
  return <ProductList />;
}
```

## Component Organization {#component-organization}

### UI Components

Use Case: Create reusable, styled components that accept props for customization.

Example: A Button component with variants for different contexts (primary action, danger, secondary).

```typescript
// src/components/ui/Button/Button.tsx
import { forwardRef } from 'react';
import { cva, type VariantProps } from 'class-variance-authority';
import { Spinner } from '@/components/ui/spinner';

const buttonVariants = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors',
  {
    variants: {
      variant: {
        primary: 'bg-blue-600 text-white hover:bg-blue-700',
        secondary: 'bg-gray-200 text-gray-900 hover:bg-gray-300',
        danger: 'bg-red-600 text-white hover:bg-red-700',
      },
      size: {
        sm: 'h-8 px-3 text-sm',
        md: 'h-10 px-4 text-base',
        lg: 'h-12 px-6 text-lg',
      },
    },
    defaultVariants: {
      variant: 'primary',
      size: 'md',
    },
  }
);

interface ButtonProps
  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
    VariantProps<typeof buttonVariants> {
  loading?: boolean;
}

export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
  ({ className, variant, size, loading, children, ...props }, ref) => {
    return (
      <button
        ref={ref}
        className={buttonVariants({ variant, size, className })}
        disabled={loading || props.disabled}
        {...props}
      >
        {loading && <Spinner className="mr-2" />}
        {children}
      </button>
    );
  }
);
```

### Container Components

Use Case: Combine data fetching, business logic, and UI composition for a feature.

Example: ProductList container that fetches products, handles loading/error states, and renders the list.

```typescript
// src/containers/products/ProductList.tsx
'use client';

import { useProducts } from '@/hooks/useProducts';
import { ProductTable } from '@/components/products/ProductTable';
import { Button } from '@/components/ui/button';
import { useRouter } from 'next/navigation';
import { LoadingSpinner } from '@/components/ui/loading-spinner';
import { ErrorMessage } from '@/components/ui/error-message';

export function ProductList() {
  const router = useRouter();
  const { data, isLoading, error } = useProducts();

  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;

  return (
    <div className="space-y-4">
      <div className="flex justify-between items-center">
        <h1 className="text-2xl font-bold">Products</h1>
        <Button onClick={() => router.push('/products/new')}>
          Add Product
        </Button>
      </div>
      <ProductTable products={data?.items ?? []} />
    </div>
  );
}
```

## Provider Setup {#provider-setup}

### Root Providers

Use Case: Configure global providers (React Query, Authentication) once at the app root.

Why: Providers wrap the entire application to share context across all pages.

```typescript
// src/app/providers.tsx
'use client';

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
import { Authenticator } from '@aws-amplify/ui-react';
import { useState } from 'react';

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(
    () =>
      new QueryClient({
        defaultOptions: {
          queries: {
            staleTime: 60 * 1000, // 1 minute
            retry: 1,
          },
        },
      })
  );

  return (
    <QueryClientProvider client={queryClient}>
      <Authenticator.Provider>
        {children}
      </Authenticator.Provider>
      <ReactQueryDevtools initialIsOpen={false} />
    </QueryClientProvider>
  );
}
```

### Root Layout

Use Case: Apply providers and global styles to all pages.

```typescript
// src/app/layout.tsx
import { Providers } from './providers';
import { configureAmplify } from '@/lib/auth/amplify';
import './globals.css';

// Configure Amplify on the server
configureAmplify();

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

## Environment Configuration {#environment-configuration}

### Environment Variables

Use Case: Configure different settings for development, staging, and production environments.

```bash
# .env.local

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3000

# AWS Cognito Configuration
NEXT_PUBLIC_AWS_REGION=ap-northeast-1
NEXT_PUBLIC_COGNITO_USER_POOL_ID=your-user-pool-id
NEXT_PUBLIC_COGNITO_CLIENT_ID=your-client-id

# Feature Flags
NEXT_PUBLIC_ENABLE_ANALYTICS=false
```

### Configuration Module

Use Case: Centralize configuration access with type safety and defaults.

```typescript
// src/lib/config.ts
export const config = {
  api: {
    baseUrl: process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000',
  },
  aws: {
    region: process.env.NEXT_PUBLIC_AWS_REGION ?? 'ap-northeast-1',
    cognito: {
      userPoolId: process.env.NEXT_PUBLIC_COGNITO_USER_POOL_ID ?? '',
      clientId: process.env.NEXT_PUBLIC_COGNITO_CLIENT_ID ?? '',
    },
  },
  features: {
    analytics: process.env.NEXT_PUBLIC_ENABLE_ANALYTICS === 'true',
  },
} as const;
```

## Best Practices {#best-practices}

### 1. Separate Server and Client Components

Problem: Using hooks in server components causes errors.

Solution: Mark components using hooks or browser APIs with 'use client'.

```typescript
// Server Component (default)
// src/app/(main)/products/page.tsx
import { ProductList } from '@/containers/products/ProductList';

export default function ProductsPage() {
  return <ProductList />;
}

// Client Component
// src/containers/products/ProductList.tsx
'use client';

import { useProducts } from '@/hooks/useProducts';
// ...
```

### 2. Use Path Aliases

Problem: Deep relative imports like '../../../components' are hard to read and refactor.

Solution: Configure path aliases for clean imports.

```json
// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/hooks/*": ["./src/hooks/*"],
      "@/services/*": ["./src/services/*"]
    }
  }
}
```

### 3. Consistent File Naming

| Type | Convention | Example |
|------|------------|---------|
| Components | PascalCase | `ProductCard.tsx` |
| Hooks | camelCase with use prefix | `useProducts.ts` |
| Utilities | camelCase | `formatDate.ts` |
| Types | PascalCase | `Product.ts` |
| Constants | UPPER_SNAKE_CASE | `API_ROUTES.ts` |

### 4. Export Patterns

Use Case: Create clean public APIs for directories.

```typescript
// src/components/ui/Button/index.ts
export { Button } from './Button';
export type { ButtonProps } from './Button';

// src/components/ui/index.ts
export * from './Button';
export * from './Input';
export * from './Modal';
```

### 5. Type-Safe Route Constants

Use Case: Avoid typos in route strings and enable autocomplete.

```typescript
// src/constants/routes.ts
export const ROUTES = {
  HOME: '/',
  DASHBOARD: '/dashboard',
  PRODUCTS: {
    LIST: '/products',
    NEW: '/products/new',
    DETAIL: (id: string) => `/products/${id}`,
    EDIT: (id: string) => `/products/${id}/edit`,
  },
  SETTINGS: '/settings',
} as const;
```


## Related Documentation

- [API Integration Patterns](/docs/api-integration-patterns) - API client patterns
- [State Management Patterns](/docs/state-management-patterns) - Frontend state
- [Authentication](/docs/authentication) - Cognito frontend integration
- [Master Web](/docs/master-web) - Master data frontend
- [UI Setting](/docs/ui-setting) - Dynamic UI settings and configuration management


---

## Master Web

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/master-web

# Master Web

Frontend component library for master data and settings management in MBC CQRS Serverless applications.

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/master-web
```

## Quick Start (Recommended Setup) {#quick-start}

:::tip Start Here
**This is the recommended way to integrate master-web with Next.js App Router.** Following this pattern will help you avoid common issues like `httpClient.get is not a function` errors.
:::

When using this library with Next.js App Router (v14+/v15), use the **Layout-based Provider Pattern**. Set up `AppProviders` in a `layout.tsx` file, and use dynamic imports for components in `page.tsx` files.

### Step 1: Create layout.tsx

Create a layout file that sets up the providers. This ensures the context is properly initialized before child components mount.

```tsx
// app/admin/[tenant]/master/layout.tsx
'use client'

import { useMemo } from 'react'
import dynamic from 'next/dynamic'
import { useParams } from 'next/navigation'
import axios from 'axios'
import { fetchAuthSession } from 'aws-amplify/auth'
import type { IUrlProvider } from '@mbc-cqrs-serverless/master-web/UrlProvider'

// Dynamic import of AppProviders (SSR disabled)
const AppProviders = dynamic(
  () =>
    import('@mbc-cqrs-serverless/master-web/AppProviders').then(
      (mod) => mod.AppProviders
    ),
  { ssr: false }
)

// Custom URL provider for your application's routing
class MasterUrlProvider implements IUrlProvider {
  protected readonly baseUrl: string
  public readonly SETTINGS_PAGE_URL: string
  public readonly ADD_SETTINGS_PAGE_URL: string
  public readonly EDIT_SETTINGS_PAGE_URL: string
  public readonly DATA_PAGE_URL: string
  public readonly ADD_DATA_PAGE_URL: string
  public readonly EDIT_DATA_PAGE_URL: string
  public readonly FAQ_CATEGORY_PAGE_URL: string
  public readonly TOP_URL: string

  constructor(tenantCode: string) {
    this.baseUrl = `/admin/${tenantCode}/master`
    this.SETTINGS_PAGE_URL = `${this.baseUrl}/master-setting`
    this.ADD_SETTINGS_PAGE_URL = `${this.baseUrl}/master-setting/new`
    this.EDIT_SETTINGS_PAGE_URL = this.SETTINGS_PAGE_URL
    this.DATA_PAGE_URL = `${this.baseUrl}/master-data`
    this.ADD_DATA_PAGE_URL = `${this.baseUrl}/master-data/new`
    this.EDIT_DATA_PAGE_URL = this.DATA_PAGE_URL
    this.FAQ_CATEGORY_PAGE_URL = `${this.baseUrl}/faq-category`
    this.TOP_URL = `/admin/${tenantCode}`
  }

  public getCopySettingPageUrl(id: string): string {
    return `${this.baseUrl}/master-setting/${id}/copy/new`
  }
  public getDetailedCopySettingPageUrl(id: string): string {
    return `${this.baseUrl}/master-setting/${id}/copy`
  }
}

export default function MasterLayout({ children }: { children: React.ReactNode }) {
  const params = useParams<{ tenant: string }>()
  const tenantCode = params?.tenant || 'common'

  const urlProvider = useMemo(() => new MasterUrlProvider(tenantCode), [tenantCode])

  // Create httpClient with Axios interceptor for automatic auth token injection
  const httpClient = useMemo(() => {
    const baseEndpoint = process.env.NEXT_PUBLIC_API_ENDPOINT || 'http://localhost:3010'
    const instance = axios.create({
      baseURL: `${baseEndpoint}/api`,
      headers: {
        'Content-Type': 'application/json',
        'x-tenant-code': tenantCode,
      },
    })

    instance.interceptors.request.use(async (config) => {
      try {
        const session = await fetchAuthSession()
        const token = session.tokens?.idToken?.toString()
        if (token) {
          config.headers.Authorization = `Bearer ${token}`
        }
      } catch {
        // Ignore auth errors
      }
      return config
    })

    return instance
  }, [tenantCode])

  const user = useMemo(() => ({ tenantCode, tenantRole: 'admin' }), [tenantCode])

  return (
    <AppProviders user={user} urlProvider={urlProvider} httpClient={httpClient}>
      <div className="p-6">{children}</div>
    </AppProviders>
  )
}
```

### Step 2: Create page.tsx

After setting up providers in the layout, each page component is simple:

```tsx
// app/admin/[tenant]/master/master-setting/page.tsx
'use client'

import dynamic from 'next/dynamic'
import MsLayout from '@mbc-cqrs-serverless/master-web/MsLayout'
import '@mbc-cqrs-serverless/master-web/styles.css'

const MasterSetting = dynamic(
  () => import('@mbc-cqrs-serverless/master-web/MasterSetting').then((mod) => mod.default),
  { ssr: false }
)

export default function MasterSettingPage() {
  return (
    <main>
      <MsLayout useLoading>
        <MasterSetting />
      </MsLayout>
    </main>
  )
}
```

### Step 3: Configure Environment Variables

```bash
# .env.local
NEXT_PUBLIC_API_ENDPOINT=http://localhost:3010
NEXT_PUBLIC_MASTER_APPSYNC_URL=https://xxxxxxxx.appsync-api.ap-northeast-1.amazonaws.com/graphql
NEXT_PUBLIC_MASTER_APPSYNC_APIKEY=da2-xxxxxxxxxxxxxxxxx
NEXT_PUBLIC_MASTER_APPSYNC_REGION=ap-northeast-1
```

### Why This Pattern?

| Benefit | Description |
|-------------|-----------------|
| **Avoids Context Isolation** | React Context in npm packages can become isolated. Layout ensures context is initialized first. |
| **Synchronous Initialization** | Using `useMemo` creates httpClient synchronously, avoiding race conditions. |
| **Automatic Auth Tokens** | Axios interceptors inject the latest auth token on every request. |
| **Simple Page Components** | Pages only need dynamic imports and component rendering. |

:::info For More Details
See [Next.js App Router Integration](#nextjs-app-router-integration) for alternative patterns, troubleshooting, and detailed explanations.
:::

## Overview {#overview}

The Master Web package (`@mbc-cqrs-serverless/master-web`) provides a complete set of React components for managing master data and settings. It integrates seamlessly with the backend Master Service and includes pre-built pages, forms, and data tables.

## Features {#features}

- **Master Settings Management**: View, create, edit, and delete master settings
- **Master Data Management**: CRUD operations for master data records
- **Rich Text Editor**: Built-in rich text editor for content fields
- **JSON Editor**: JSON editor for structured data fields
- **Data Tables**: Sortable, paginated tables with TanStack Table
- **Real-time Updates**: AWS AppSync integration for real-time data sync
- **Copy Functionality**: Clone master settings and data

## Main Components {#main-components}

:::info Import Options
Components can be imported from the main package or via sub-path imports:
```tsx
// Main package import
import { MasterSetting } from "@mbc-cqrs-serverless/master-web";

// Sub-path import
import MasterSetting from "@mbc-cqrs-serverless/master-web/MasterSetting";
```
:::

### MasterSetting

Displays a list of master settings with search, filter, and pagination capabilities.

```tsx
import { MasterSetting } from "@mbc-cqrs-serverless/master-web";
import "@mbc-cqrs-serverless/master-web/styles.css";

export default function MasterSettingsPage() {
  return <MasterSetting />;
}
```

### EditMasterSettings

Form component for creating and editing master settings.

```tsx
import { EditMasterSettings } from "@mbc-cqrs-serverless/master-web";

// The component takes no props — it reads pk and sk from the URL via useParams(), so place it under a route like [pk]/[sk]
export default function EditMasterSettingsPage() {
  return <EditMasterSettings />;
}
```

### CopyMasterSettings

Component for copying master settings to create new settings based on existing ones.

```tsx
import { CopyMasterSettings } from "@mbc-cqrs-serverless/master-web";

// The component takes no props — it reads pk and sk from the URL via useParams(), so place it under a route like [pk]/[sk]
export default function CopyMasterSettingsPage() {
  return <CopyMasterSettings />;
}
```

### NewCopyMasterSettings

Component for creating a new copy of master settings with a new identifier.

```tsx
import { NewCopyMasterSettings } from "@mbc-cqrs-serverless/master-web";

// The component takes no props — it reads pk and sk from the URL via useParams(), so place it under a route like [pk]/[sk]
export default function NewCopyMasterSettingsPage() {
  return <NewCopyMasterSettings />;
}
```

### DetailCopy

Component for viewing detailed copy information of master settings.

```tsx
import { DetailCopy } from "@mbc-cqrs-serverless/master-web";

// The component takes no props — it reads pk and sk from the URL via useParams(), so place it under a route like [pk]/[sk]
export default function DetailCopyPage() {
  return <DetailCopy />;
}
```

### MasterData

Displays master data records in a table format with CRUD operations.

```tsx
import { MasterData } from "@mbc-cqrs-serverless/master-web";

export default function MasterDataPage() {
  return <MasterData />;
}
```

### EditMasterData

Form component for creating and editing master data records. Automatically renders form controls based on the `fields` definition in the corresponding master setting's `attributes.fields`.

The component always displays `code` and `name` as fixed fields. Any additional fields defined in `attributes.fields` (other than `code` and `name`) are rendered as custom form controls based on their `uiComponent` type.

```tsx
import { EditMasterData } from "@mbc-cqrs-serverless/master-web";

// The component takes no props — it reads pk and sk from the URL via useParams(), so place it under a route like [pk]/[sk]
export default function EditMasterDataPage() {
  return <EditMasterData />;
}
```

### AddJsonData

JSON editor component for bulk importing master settings and master data via JSON. This component is used internally by `EditMasterSettings` for the JSON import tab.

:::warning Create-only by Default
`AddJsonData` uses hardcoded API URLs (`/master-setting/bulk` for settings, `/master-data/bulk` for data) which call the framework's `createBulk` method. This means re-importing JSON data for existing records will fail with a `BadRequestException`. To support upsert behavior, use an Axios interceptor to rewrite these URLs to custom upsert endpoints. See [Master - Upsert Pattern](/docs/master#upsert-pattern) for details.
:::

## Provider Setup {#provider-setup}

Wrap your application with the required providers for authentication and API access.

### AppProviders

The `AppProviders` component requires a `user` prop of type `UserContext` containing tenant information.

```tsx
import { AppProviders } from "@mbc-cqrs-serverless/master-web";
import type { UserContext } from "@mbc-cqrs-serverless/master-web";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  // UserContext contains tenant information
  const user: UserContext = {
    tenantCode: "your-tenant-code",
    tenantRole: "admin",
  };

  return (
    <AppProviders user={user}>
      {children}
    </AppProviders>
  );
}
```

### AppProviders Props

| Prop | Type | Required | Description |
|----------|----------|--------------|-----------------|
| `user` | `UserContext` | Yes | User context with tenant information |
| `httpClient` | `AxiosInstance` | No | Custom Axios instance for HTTP requests |
| `apolloClient` | `ApolloClient` | No | Custom Apollo Client instance |
| `urlProvider` | `IUrlProvider` | No | Custom URL provider instance |

### UserContext Type

The `UserContext` type defines the shape of the user object. You can use the `useUserContext` hook's return type or define a compatible type:

```tsx
type UserContext = {
  tenantCode: string;  // Tenant identifier
  tenantRole: string;  // User role within the tenant
};
```

:::info Type Usage
While `UserContext` is used internally, you can create a compatible object type for the `user` prop.
:::

## URL Provider {#url-provider}

The package provides a URL provider system for managing application URLs.

### IUrlProvider Interface

The `IUrlProvider` interface defines the contract for URL generation:

```tsx
import type { IUrlProvider } from "@mbc-cqrs-serverless/master-web";

// Interface definition
interface IUrlProvider {
  // Static URLs
  readonly SETTINGS_PAGE_URL: string;
  readonly ADD_SETTINGS_PAGE_URL: string;
  readonly EDIT_SETTINGS_PAGE_URL: string;
  readonly DATA_PAGE_URL: string;
  readonly ADD_DATA_PAGE_URL: string;
  readonly EDIT_DATA_PAGE_URL: string;
  readonly FAQ_CATEGORY_PAGE_URL: string;
  readonly TOP_URL: string;

  // Dynamic URL generators
  getCopySettingPageUrl(id: string): string;
  getDetailedCopySettingPageUrl(id: string): string;
}
```

### BaseUrlProvider Class

The `BaseUrlProvider` class provides a default implementation that can be extended:

```tsx
import { BaseUrlProvider, IUrlProvider } from "@mbc-cqrs-serverless/master-web/UrlProvider";

// Create a URL provider with a base segment
const urlProvider = new BaseUrlProvider("my-tenant");

// Access static URLs
console.log(urlProvider.SETTINGS_PAGE_URL);  // "/my-tenant/master-setting"
console.log(urlProvider.DATA_PAGE_URL);      // "/my-tenant/master-data"

// Generate dynamic URLs
console.log(urlProvider.getCopySettingPageUrl("123"));  // "/my-tenant/master-setting/123/copy/new"
```

:::info Sub-path Import
The `BaseUrlProvider` and `IUrlProvider` are available via the sub-path import `@mbc-cqrs-serverless/master-web/UrlProvider`. The `IUrlProvider` type is also exported from the main package.
:::

### Custom URL Provider

You can create a custom URL provider by extending `BaseUrlProvider` or implementing the `IUrlProvider` interface:

```tsx
import { AppProviders } from "@mbc-cqrs-serverless/master-web";
import { BaseUrlProvider } from "@mbc-cqrs-serverless/master-web/UrlProvider";

// Extend BaseUrlProvider for custom path structure
class CustomUrlProvider extends BaseUrlProvider {
  constructor(tenantCode: string) {
    super(`members/${tenantCode}`);
  }
}

// Use custom URL provider with AppProviders
const customUrlProvider = new CustomUrlProvider("my-tenant");

<AppProviders user={user} urlProvider={customUrlProvider}>
  {children}
</AppProviders>
```

## Custom Hooks {#custom-hooks}

### useApolloClient

Access the Apollo Client for GraphQL operations.

```tsx
import { useApolloClient } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const client = useApolloClient();
  // Use client for custom GraphQL queries
}
```

### useHttpClient

Access the HTTP client for REST API calls.

```tsx
import { useHttpClient } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const httpClient = useHttpClient();
  // Use httpClient for custom API requests
}
```

### useUserContext

Access the current user context with tenant information.

```tsx
import { useUserContext } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const { tenantCode, tenantRole } = useUserContext();
  // Access tenant information
  console.log(`Tenant: ${tenantCode}, Role: ${tenantRole}`);
}
```

### useLoadingStore

Manage global loading state across components.

```tsx
import { useLoadingStore } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const { isLoading, setLoading, closeLoading } = useLoadingStore();

  // Show loading indicator
  setLoading();

  // Hide loading indicator
  closeLoading();
}
```

### useUrlProvider

Access the URL provider for generating application URLs.

```tsx
import { useUrlProvider } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const urlProvider = useUrlProvider();

  // Use static URLs
  const settingsUrl = urlProvider.SETTINGS_PAGE_URL;

  // Generate dynamic URLs
  const copyUrl = urlProvider.getCopySettingPageUrl("item-123");
}
```

### useAppServices

Access all application services at once. Returns the HTTP client, Apollo client, user context, and URL provider.

```tsx
import { useAppServices } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const { httpClient, apolloClient, user, urlProvider } = useAppServices();

  // Use multiple services in one component
  const fetchData = async () => {
    const response = await httpClient.get("/api/data");
    // ...
  };
}
```

**Return Value:**

| Property | Type | Description |
|----------|------|-------------|
| `httpClient` | `AxiosInstance` | HTTP client for REST API calls |
| `apolloClient` | `ApolloClient` | Apollo client for GraphQL operations |
| `user` | `UserContext` | Current user context and authentication state |
| `urlProvider` | `IUrlProvider` | URL provider for generating URLs |

### useSubscribeCommandStatus

:::warning Internal API
This hook is not exported from the main package and is for internal use only. It may change without notice.
:::

Subscribe to AppSync command status updates. Used to track the progress and completion of backend commands.

```tsx
import { useSubscribeCommandStatus } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const { isListening, message, start } = useSubscribeCommandStatus(
    tenantCode,
    async (msg) => {
      if (msg) {
        // Command completed successfully
        console.log("Command finished:", msg);
      } else {
        // Command timed out
        console.log("Command timed out");
      }
    },
    true // Show processing toast
  );

  const handleSubmit = async () => {
    const requestId = await submitCommand();
    start(requestId, 30000); // Start listening with 30s timeout
  };
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `xTenantCode` | `string` | Tenant code for the subscription |
| `doneCallback` | `(msg: DecodedMessage \| null) => void` | Callback when command completes or times out |
| `isShowProcess` | `boolean` | Whether to show processing toast (default: true) |

**Return Value:**

| Property | Type | Description |
|----------|------|-------------|
| `isListening` | `boolean` | Whether actively listening for updates |
| `message` | `DecodedMessage \| null` | Latest received message |
| `start` | `(reqId: string, timeoutMs?: number) => void` | Start listening for a request ID |

### useSubscribeBulkCommandStatus

:::warning Internal API
This hook is not exported from the main package and is for internal use only. It may change without notice.
:::

Subscribe to bulk command status updates. Used when processing multiple items where each receives its own completion message.

```tsx
import { useSubscribeBulkCommandStatus } from "@mbc-cqrs-serverless/master-web";

function BulkOperationComponent() {
  const { isListening, messages, finishedCount, start, stop } =
    useSubscribeBulkCommandStatus(
      tenantCode,
      () => {
        // Handle timeout
        console.log("Bulk operation timed out");
      }
    );

  const handleBulkSubmit = async (items: Item[]) => {
    const requestId = await submitBulkCommand(items);
    start(requestId, 60000); // 60s timeout
  };

  // Check if all items are processed
  useEffect(() => {
    if (finishedCount === expectedCount) {
      stop();
      // All items processed
    }
  }, [finishedCount]);
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `xTenantCode` | `string` | Tenant code for the subscription |
| `onTimeout` | `() => void` | Optional callback when operation times out |

**Return Value:**

| Property | Type | Description |
|----------|------|-------------|
| `isListening` | `boolean` | Whether actively listening for updates |
| `messages` | `DecodedMessage[]` | All received messages |
| `finishedCount` | `number` | Number of completed items |
| `start` | `(reqId: string, timeoutMs?: number) => void` | Start listening for a request ID |
| `stop` | `() => void` | Manually stop listening |

### useHealthCheck

:::warning Internal API
This hook is not exported from the main package and is for internal use only. It may change without notice.
:::

Performs a health check API call on component mount. Controlled by the `NEXT_PUBLIC_ENABLE_HEALTH_CHECK` environment variable.

```tsx
import { useHealthCheck } from "@mbc-cqrs-serverless/master-web";

function App() {
  // Automatically calls health check endpoint on mount
  useHealthCheck();

  return <div>Application content</div>;
}
```

**Environment Variable:**

| Variable | Description |
|----------|-------------|
| `NEXT_PUBLIC_ENABLE_HEALTH_CHECK` | Set to "true" to enable health check calls |

### usePagination

:::warning Internal API
This hook is not exported from the main package and is for internal use only. It may change without notice.
:::

Comprehensive hook for handling pagination with search, sorting, and table views. Integrates with URL query parameters for persistent state.

```tsx
import { usePagination } from "@mbc-cqrs-serverless/master-web";
import { parseAsString } from "next-usequerystate";

interface SearchProps extends SearchPropsBase {
  name?: string;
  status?: string;
}

function DataListPage() {
  const {
    searchProps,
    paginate,
    onSubmitSearch,
    executeSearch,
    handlePaginationChange,
    handleSortChange,
  } = usePagination<DataRecord, SearchProps, Paginate<DataRecord>>({
    searchPropDefinitions: {
      name: parseAsString,
      status: parseAsString,
    },
    getData: async (queries) => {
      return await fetchData(queries);
    },
    rootPath: "/data-list",
    isSearchInit: true,
  });

  useEffect(() => {
    executeSearch();
  }, []);

  return (
    <DataTable
      data={paginate?.results ?? []}
      onPaginationChange={handlePaginationChange}
      onSortChange={handleSortChange}
    />
  );
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `searchPropDefinitions` | `UseQueryStatesKeysMap` | Query parameter definitions using next-usequerystate |
| `getData` | `(queries) => Promise<Paginate>` | Function to fetch paginated data from server |
| `getDataClient` | `(queries) => Promise<Array>` | Function for client-side data filtering |
| `isSearchInit` | `boolean` | Whether to search on initial load (default: true) |
| `rootPath` | `string` | Root path for the page (used for path validation) |
| `tableViews` | `TableView[]` | Optional predefined table view configurations |
| `getStorage` | `() => SearchProps` | Function to retrieve saved search conditions |
| `setStorage` | `(props) => void` | Function to save search conditions |
| `reset` | `UseFormReset` | Form reset function from react-hook-form |
| `setValue` | `UseFormSetValue` | Form setValue function from react-hook-form |
| `convertSearchProps` | `(props) => SearchProps` | Optional function to convert search props before executing search |
| `convertChangeQueries` | `(props) => SearchProps` | Optional function to convert query parameters before URL change |

**Return Value:**

| Property | Type | Description |
|----------|------|-------------|
| `searchProps` | `SearchProps` | Current search parameters |
| `queries` | `SearchProps` | URL query parameters |
| `setQueries` | `(props) => Promise<void>` | Update URL query parameters directly |
| `paginate` | `Paginate<T>` | Paginated results with count and data |
| `setPaginate` | `(paginate) => void` | Manually set paginate state |
| `setPaginateClient` | `(items, page?) => void` | Set paginate for client-side data |
| `getPaginateClient` | `(items) => Paginate` | Convert array to paginate object |
| `isCalledSearch` | `boolean` | Whether search has been triggered |
| `onSubmitSearch` | `(props) => Promise<void>` | Submit search with new parameters |
| `executeSearch` | `() => Promise<object>` | Execute search with current parameters |
| `searchUsingTableView` | `(props, tableView) => Promise<void>` | Search using a predefined table view |
| `getSearchQuery` | `() => SearchProps \| null` | Get current search query from URL or storage |
| `handlePaginationChange` | `OnChangeFn<PaginationState>` | Handler for page/size changes |
| `handleSortChange` | `OnChangeFn<SortingState>` | Handler for sort changes |
| `onResetSearchForm` | `() => Promise<void>` | Reset search form to empty values |

### usePaginationRange

:::warning Internal API
This hook and the `DOTS` constant are not exported from the main package and are for internal use only. They may change without notice.
:::

Calculates the page number range for pagination UI, including ellipsis for large page counts.

```tsx
import { usePaginationRange, DOTS } from "@mbc-cqrs-serverless/master-web";

function PaginationUI({ totalPages, currentPage }: Props) {
  const range = usePaginationRange({
    totalPageCount: totalPages,
    currentPage: currentPage,
    siblingCount: 1,
  });

  return (
    <nav>
      {range.map((item, index) => (
        item === DOTS ? (
          <span key={index}>...</span>
        ) : (
          <button key={index} onClick={() => goToPage(item as number)}>
            {item}
          </button>
        )
      ))}
    </nav>
  );
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `totalPageCount` | `number` | Total number of pages |
| `currentPage` | `number` | Current active page number |
| `siblingCount` | `number` | Number of page buttons to show on each side (default: 1) |

**Return Value:**

`(number | string)[]` - Array of page numbers and DOTS ("...") for ellipsis

### useLoadingForm

:::warning Internal API
This hook is not exported from the main package and is for internal use only. It may change without notice.
:::

Combines react-hook-form with global loading state. Provides form utilities along with loading state management.

```tsx
import { useLoadingForm } from "@mbc-cqrs-serverless/master-web";

interface FormData {
  name: string;
  email: string;
}

function MyForm() {
  const {
    form,
    control,
    handleSubmit,
    loading,
    loadingStore,
    errors,
  } = useLoadingForm<FormData>({
    defaultValues: {
      name: "",
      email: "",
    },
  });

  const onSubmit = async (data: FormData) => {
    loadingStore.setLoading();
    try {
      await saveData(data);
    } finally {
      loadingStore.closeLoading();
    }
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* Form fields */}
    </form>
  );
}
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `props` | `UseFormProps<T>` | react-hook-form useForm options |

**Return Value:**

| Property | Type | Description |
|----------|------|-------------|
| `form` | `UseFormReturn<T>` | Full react-hook-form instance |
| `control` | `Control<T>` | Form control for controlled components |
| `handleSubmit` | `UseFormHandleSubmit<T>` | Form submit handler |
| `watch` | `UseFormWatch<T>` | Watch form values |
| `getValues` | `UseFormGetValues<T>` | Get form values |
| `setValue` | `UseFormSetValue<T>` | Set form values |
| `reset` | `UseFormReset<T>` | Reset form |
| `trigger` | `UseFormTrigger<T>` | Trigger validation |
| `errors` | `FieldErrors<T>` | Form validation errors |
| `setError` | `UseFormSetError<T>` | Set form error manually |
| `loading` | `boolean` | Current loading state |
| `loadingStore` | `LoadingState` | Loading store with setLoading/closeLoading |
| `isValid` | `boolean` | Whether form is valid |

### useAsyncAction

:::warning Internal API
This hook is not exported from the main package and is for internal use only. It may change without notice.
:::

Execute async functions with automatic loading overlay. Shows global loading indicator during async operations.

```tsx
import { useAsyncAction } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const { performAction, isLoading } = useAsyncAction();

  const handleClick = async () => {
    const result = await performAction(async () => {
      // This runs with loading overlay
      return await fetchData();
    });
    console.log(result);
  };

  return (
    <button onClick={handleClick} disabled={isLoading}>
      Load Data
    </button>
  );
}
```

**Return Value:**

| Property | Type | Description |
|----------|------|-------------|
| `performAction` | `<T>(fn: () => Promise<T>) => Promise<T>` | Execute async function with loading overlay |
| `isLoading` | `boolean` | Current loading state |

### useNavigation

:::warning Internal API
This hook is not exported from the main package and is for internal use only. It may change without notice.
:::

Navigate between pages with automatic loading indicator. Wraps Next.js router with loading state management.

```tsx
import { useNavigation } from "@mbc-cqrs-serverless/master-web";

function MyComponent() {
  const { navigate, reload, hardNavigate } = useNavigation();

  return (
    <div>
      <button onClick={() => navigate("/dashboard")}>
        Go to Dashboard
      </button>
      <button onClick={() => reload()}>
        Refresh Page
      </button>
      <button onClick={() => hardNavigate("/external-page")}>
        Full Page Navigation
      </button>
    </div>
  );
}
```

**Return Value:**

| Property | Type | Description |
|----------|------|-------------|
| `navigate` | `(url: string) => void` | Navigate using Next.js router with loading indicator |
| `reload` | `() => void` | Refresh current page with loading indicator |
| `hardNavigate` | `(url: string) => void` | Full browser navigation (window.location) |

## UI Components {#ui-components}

The package includes several reusable UI components:

### JsonEditor

A JSON editor component for editing structured data. Uses the jsoneditor library with tree mode.

```tsx
import { JsonEditor } from "@mbc-cqrs-serverless/master-web";

function MyForm() {
  const [jsonData, setJsonData] = useState({ key: "value" });

  return (
    <JsonEditor
      json={jsonData}
      onChange={setJsonData}
    />
  );
}
```

#### JsonEditor Props

| Prop | Type | Required | Description |
|----------|----------|--------------|-----------------|
| `json` | `object` | Yes | The JSON data to display and edit |
| `onChange` | `(json: object) => void` | No | Callback when JSON content changes |

### RichTextEditor

A rich text editor for content fields. Built on React Quill with customizable toolbar.

```tsx
import { RichTextEditor } from "@mbc-cqrs-serverless/master-web";

function MyForm() {
  const [content, setContent] = useState("");

  return (
    <RichTextEditor
      value={content}
      onChange={setContent}
      placeholder="Enter your content here..."
    />
  );
}
```

#### RichTextEditor Props

| Prop | Type | Required | Description |
|----------|----------|--------------|-----------------|
| `value` | `string` | No | The HTML content for the editor (defaults to empty string) |
| `onChange` | `(value: string) => void` | Yes | Callback when content changes |
| `placeholder` | `string` | No | Placeholder text when editor is empty (defaults to empty string) |

### MsLayout

Layout component for master management pages. Provides loading overlay and toast notifications.

```tsx
import { MsLayout } from "@mbc-cqrs-serverless/master-web";

function MasterPage() {
  return (
    <MsLayout useLoading={true}>
      <MasterSetting />
    </MsLayout>
  );
}
```

#### MsLayout Props

| Prop | Type | Required | Description |
|----------|----------|--------------|-----------------|
| `useLoading` | `boolean` | Yes | Enable or disable the loading overlay |
| `children` | `React.ReactNode` | Yes | Child components to render |

### ConfirmButton

:::warning Internal API
This component is not exported from the main package and is for internal use only. It may change without notice.
:::

Button component that displays a confirmation dialog before executing an action. Useful for destructive operations like delete.

#### ConfirmButton Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `'default' \| 'sm' \| 'lg' \| 'icon'` | `'default'` | Button size |
| `triggerBtnText` | `string` | - | Text displayed on the trigger button |
| `title` | `string` | - | Title of the confirmation dialog |
| `cancelText` | `string` | - | Text for the cancel button |
| `confirmText` | `string` | - | Text for the confirm button |
| `loading` | `boolean` | `false` | Shows loading state on the button |
| `onConfirm` | `() => void` | - | Callback function when confirm is clicked |
| `className` | `string` | - | Additional CSS classes |
| `disabled` | `boolean` | `false` | Disables the button |
| `variant` | `string` | - | Button variant style |

```tsx
// Note: Internal import path - may change without notice
import ConfirmButton from "@mbc-cqrs-serverless/master-web/dist/components/buttons/ConfirmButton";

function DeleteAction() {
  const handleDelete = () => {
    // Perform delete operation
  };

  return (
    <ConfirmButton
      triggerBtnText="Delete"
      title="Are you sure you want to delete this item?"
      cancelText="Cancel"
      confirmText="Delete"
      variant="destructive"
      onConfirm={handleDelete}
    />
  );
}
```

### BackButton

:::warning Internal API
This component is not exported from the main package and is for internal use only. It may change without notice.
:::

Navigation button component for returning to the previous page or a specified location.

#### BackButton Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `onClickPrev` | `() => void` | - | Callback function when button is clicked |
| `className` | `string` | - | Additional CSS classes |

```tsx
// Note: Internal import path - may change without notice
import { BackButton } from "@mbc-cqrs-serverless/master-web/dist/components/buttons/back-button";
import { useRouter } from "next/navigation";

function DetailPage() {
  const router = useRouter();

  return (
    <div>
      {/* Page content */}
      <BackButton onClickPrev={() => router.back()} />
    </div>
  );
}
```

### DatePicker

:::warning Internal API
This component is not exported from the main package and is for internal use only. It may change without notice.
:::

Date selection component with calendar popup. Uses date-fns for formatting and Japanese locale support.

#### DatePicker Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `Date \| string` | - | Current selected date value |
| `onChange` | `(date?: string) => void` | - | Callback when date is selected (returns ISO string with timezone) |
| `disabled` | `boolean` | `false` | Disables the date picker |

```tsx
// Note: Internal import path - may change without notice
import DatePicker from "@mbc-cqrs-serverless/master-web/dist/components/form/DatePicker";
import { useState } from "react";

function DateForm() {
  const [date, setDate] = useState<string>();

  return (
    <DatePicker
      value={date}
      onChange={(newDate) => setDate(newDate)}
    />
  );
}
```

### FormSubmitButton

:::warning Internal API
This component is not exported from the main package and is for internal use only. It may change without notice.
:::

Submit button component designed to work with react-hook-form. Automatically handles form state, validation errors, and loading states.

#### FormSubmitButton Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `children` | `React.ReactNode` | - | Button content |
| `disabled` | `boolean` | `false` | Manually disable the button |
| `loading` | `boolean` | `false` | Shows loading state |
| `className` | `string` | - | Additional CSS classes |
| `disableDirty` | `boolean` | `false` | If true, button is enabled even when form is not dirty |

The button is automatically disabled when:
- There are validation errors in the form
- The form has not been modified (unless `disableDirty` is true)

```tsx
// Note: Internal import path - may change without notice
import FormSubmitButton from "@mbc-cqrs-serverless/master-web/dist/components/form/FormSubmitButton";
import { FormProvider, useForm } from "react-hook-form";
import { useState } from "react";

function MyForm() {
  const methods = useForm();
  const [isSubmitting, setIsSubmitting] = useState(false);

  return (
    <FormProvider {...methods}>
      <form onSubmit={methods.handleSubmit(onSubmit)}>
        {/* Form fields */}
        <FormSubmitButton loading={isSubmitting}>
          Save
        </FormSubmitButton>
      </form>
    </FormProvider>
  );
}
```

### DataTable

:::warning Internal API
This component is not exported from the main package and is for internal use only. It may change without notice.
:::

Full-featured data table component built on TanStack Table. Supports server-side pagination, sorting, row selection, and custom column definitions.

#### DataTable Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `columns` | `ColumnDef<TData, TValue>[]` | - | Column definitions using TanStack Table format |
| `data` | `TData[]` | - | Array of data to display |
| `pageCount` | `number` | - | Total number of pages |
| `rowCount` | `number` | - | Total number of rows |
| `pagination` | `PaginationState` | - | Current pagination state (pageIndex, pageSize) |
| `onPaginationChange` | `(pagination: PaginationState) => void` | - | Callback when pagination changes |
| `sorting` | `SortingState` | - | Current sorting state |
| `onSortingChange` | `(sorting: SortingState) => void` | - | Callback when sorting changes |
| `onClickRow` | `(row: TData) => void` | - | Callback when a row is clicked |
| `rowKey` | `keyof TData \| ((row: TData) => string)` | - | Key extractor for row identification |
| `rowSelection` | `RowSelectionState` | - | Current row selection state |
| `onRowSelectionChange` | `(state: RowSelectionState) => void` | - | Callback when row selection changes |

:::info State Types
`PaginationState`, `SortingState`, and `RowSelectionState` are TanStack Table types. `PaginationState` contains `pageIndex` and `pageSize` properties.
:::

#### DataTable Features

- Server-side pagination with page size options (10, 20, 50, 100)
- Jump to specific page functionality
- Column sorting
- Row selection
- Click handler for row navigation
- Empty state display
- Custom column widths via column meta

```tsx
// Note: Internal import path - may change without notice
import { DataTable } from "@mbc-cqrs-serverless/master-web/dist/components/table/data-table";
import { ColumnDef, OnChangeFn, PaginationState, SortingState } from "@tanstack/react-table";
import { useState } from "react";
import { useRouter } from "next/navigation";

type User = {
  id: string;
  name: string;
  email: string;
};

const columns: ColumnDef<User>[] = [
  {
    accessorKey: "name",
    header: "Name",
    meta: { size: "200px" },
  },
  {
    accessorKey: "email",
    header: "Email",
  },
];

function UserList() {
  const router = useRouter();
  const [pagination, setPagination] = useState<PaginationState>({
    pageIndex: 0,
    pageSize: 10,
  });
  const [sorting, setSorting] = useState<SortingState>([]);

  // Fetch data based on pagination and sorting
  const { data, pageCount, rowCount } = useUsers(pagination, sorting);

  return (
    <DataTable
      columns={columns}
      data={data}
      pageCount={pageCount}
      rowCount={rowCount}
      pagination={pagination}
      onPaginationChange={setPagination}
      sorting={sorting}
      onSortingChange={setSorting}
      rowKey="id"
      onClickRow={(row) => router.push(`/users/${row.id}`)}
    />
  );
}
```

### LoadingOverlay

:::warning Internal API
This component is not exported from the main package and is for internal use only. It may change without notice.
:::

Full-screen loading overlay component with spinner animation. Useful for indicating loading state during async operations.

#### LoadingOverlay Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `isLoading` | `boolean` | - | Controls visibility of the overlay |

```tsx
// Note: Internal import path - may change without notice
import LoadingOverlay from "@mbc-cqrs-serverless/master-web/dist/components/LoadingOverlay";
import { useState } from "react";

function MyPage() {
  const [isLoading, setIsLoading] = useState(false);

  const handleSubmit = async () => {
    setIsLoading(true);
    try {
      await saveData();
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <div>
      <LoadingOverlay isLoading={isLoading} />
      {/* Page content */}
    </div>
  );
}
```

## Environment Variables {#environment-variables}

Configure the following environment variables for the Master Web package:

| Variable | Description |
|----------|-------------|
| `NEXT_PUBLIC_MASTER_API_BASE` | Base URL for REST API endpoints |
| `NEXT_PUBLIC_MASTER_APPSYNC_URL` | AWS AppSync GraphQL endpoint URL |
| `NEXT_PUBLIC_MASTER_APPSYNC_APIKEY` | AWS AppSync API key for authentication |
| `NEXT_PUBLIC_MASTER_APPSYNC_REGION` | AWS region for AppSync |

### Example .env.local

```bash
NEXT_PUBLIC_MASTER_API_BASE=https://api.example.com
NEXT_PUBLIC_MASTER_APPSYNC_URL=https://xxxxxxxx.appsync-api.ap-northeast-1.amazonaws.com/graphql
NEXT_PUBLIC_MASTER_APPSYNC_APIKEY=da2-xxxxxxxxxxxxxxxxx
NEXT_PUBLIC_MASTER_APPSYNC_REGION=ap-northeast-1
```

## Styling {#styling}

Import the package styles in your application:

```tsx
import "@mbc-cqrs-serverless/master-web/styles.css";
```

The components use Tailwind CSS for styling. Ensure your project has Tailwind CSS configured.

## Next.js App Router Integration {#nextjs-app-router-integration}

:::info Version Note
In [v0.0.42](/docs/web-changelog#v0042), React/Next.js were externalized as peer dependencies, resolving the Context isolation issue that caused `httpClient.get is not a function` errors. If you are using v0.0.41 or earlier, upgrade to v0.0.42 or later for the fix.
:::

When using master-web components with Next.js App Router (v14+/v15), there are important considerations for handling Server-Side Rendering (SSR) and client-side state.

### SSR Compatibility Issue

The JsonEditor component uses the `jsoneditor` library internally, which requires browser APIs (`self`, `window`) that are not available during SSR. This causes errors like:

```text
ReferenceError: self is not defined
```

### Solution: Dynamic Import with SSR Disabled

Use Next.js dynamic imports with `ssr: false` to load master-web components only on the client side:

```tsx
'use client'

import dynamic from 'next/dynamic'
import { useMemo } from 'react'

// Create wrapper component that handles dynamic import
function MasterSettingWrapper({ httpClient, urlProvider, user }) {
  // Dynamic import inside component for proper context handling
  const MasterSetting = useMemo(
    () =>
      dynamic(() => import('@mbc-cqrs-serverless/master-web/MasterSetting'), {
        ssr: false,
        loading: () => <div>Loading...</div>,
      }),
    []
  )

  return (
    <AppProviders user={user} httpClient={httpClient} urlProvider={urlProvider}>
      <MasterSetting />
    </AppProviders>
  )
}
```

:::warning Important
Define the dynamic import inside a wrapper component (using `useMemo`) rather than at the module level. This ensures the AppProviders context is properly available when the component mounts.
:::

### Recommended Pattern: Layout-based Provider Pattern

**The most recommended implementation pattern** is to use Next.js App Router's `layout.tsx` to set up AppProviders. This pattern reliably avoids the `httpClient.get is not a function` error.

#### Why Layout Pattern is Recommended

1. **Solves React Context Isolation Issues**: React Context bundled in npm packages can become isolated from the application's context. By setting up providers in the Layout, the Context is guaranteed to be initialized before child components mount.

2. **Synchronous httpClient Initialization**: By using `useMemo`, the httpClient is created synchronously without async state management (useState + useEffect).

3. **Automatic Auth Token Injection**: Using Axios interceptors, the latest auth token is automatically retrieved for each request.

#### Implementation Example: layout.tsx

```tsx
// app/admin/[tenant]/master/layout.tsx
'use client'

import { useMemo } from 'react'
import dynamic from 'next/dynamic'
import { useParams } from 'next/navigation'
import axios from 'axios'
import { fetchAuthSession } from 'aws-amplify/auth'
import type { IUrlProvider } from '@mbc-cqrs-serverless/master-web/UrlProvider'
import '@mbc-cqrs-serverless/master-web/styles.css'
import '@/modules/common/components/ConfigureAmplifyClientSide'

// Dynamic import of AppProviders (SSR disabled)
const AppProviders = dynamic(
  () =>
    import('@mbc-cqrs-serverless/master-web/AppProviders').then(
      (mod) => mod.AppProviders
    ),
  { ssr: false }
)

// Multi-tenant URL provider
class MasterUrlProvider implements IUrlProvider {
  protected readonly baseUrl: string

  public readonly SETTINGS_PAGE_URL: string
  public readonly ADD_SETTINGS_PAGE_URL: string
  public readonly EDIT_SETTINGS_PAGE_URL: string
  public readonly DATA_PAGE_URL: string
  public readonly ADD_DATA_PAGE_URL: string
  public readonly EDIT_DATA_PAGE_URL: string
  public readonly FAQ_CATEGORY_PAGE_URL: string
  public readonly TOP_URL: string

  constructor(tenantCode: string) {
    this.baseUrl = `/admin/${tenantCode}/master`

    this.SETTINGS_PAGE_URL = `${this.baseUrl}/master-setting`
    this.ADD_SETTINGS_PAGE_URL = `${this.baseUrl}/master-setting/new`
    this.EDIT_SETTINGS_PAGE_URL = this.SETTINGS_PAGE_URL
    this.DATA_PAGE_URL = `${this.baseUrl}/master-data`
    this.ADD_DATA_PAGE_URL = `${this.baseUrl}/master-data/new`
    this.EDIT_DATA_PAGE_URL = this.DATA_PAGE_URL
    this.FAQ_CATEGORY_PAGE_URL = `${this.baseUrl}/faq-category`
    this.TOP_URL = `/admin/${tenantCode}`
  }

  public getCopySettingPageUrl(id: string): string {
    return `${this.baseUrl}/master-setting/${id}/copy/new`
  }

  public getDetailedCopySettingPageUrl(id: string): string {
    return `${this.baseUrl}/master-setting/${id}/copy`
  }
}

export default function MasterLayout({
  children,
}: {
  children: React.ReactNode
}) {
  const params = useParams<{ tenant: string }>()
  const tenantCode = params?.tenant || 'common'

  // Create URL provider synchronously with useMemo
  const urlProvider = useMemo(() => new MasterUrlProvider(tenantCode), [tenantCode])

  // Create httpClient synchronously with useMemo (interceptor auto-injects auth token)
  const httpClient = useMemo(() => {
    const baseEndpoint = process.env.NEXT_PUBLIC_API_ENDPOINT || 'http://localhost:3010'
    const instance = axios.create({
      baseURL: `${baseEndpoint}/api`,
      headers: {
        'Content-Type': 'application/json',
        'x-tenant-code': tenantCode,
      },
    })

    // Interceptor to get auth token
    instance.interceptors.request.use(async (config) => {
      try {
        const session = await fetchAuthSession()
        const token = session.tokens?.idToken?.toString()
        if (token) {
          config.headers.Authorization = `Bearer ${token}`
        }
      } catch {
        // Ignore auth errors
      }
      return config
    })

    return instance
  }, [tenantCode])

  const user = useMemo(
    () => ({
      tenantCode,
      tenantRole: 'admin',
    }),
    [tenantCode]
  )

  return (
    <AppProviders user={user} urlProvider={urlProvider} httpClient={httpClient}>
      <div className="p-6">{children}</div>
    </AppProviders>
  )
}
```

#### Page Component Implementation

After setting up providers in the Layout, each page component becomes simple:

```tsx
// app/admin/[tenant]/master/master-setting/page.tsx
'use client'

import dynamic from 'next/dynamic'
import MsLayout from '@mbc-cqrs-serverless/master-web/MsLayout'

const MasterSetting = dynamic(
  () => import('@mbc-cqrs-serverless/master-web/MasterSetting').then((mod) => mod.default),
  { ssr: false }
)

export default function MasterSettingPage() {
  return (
    <main>
      <MsLayout useLoading>
        <MasterSetting />
      </MsLayout>
    </main>
  )
}
```

```tsx
// app/admin/[tenant]/master/master-setting/new/page.tsx
'use client'

import dynamic from 'next/dynamic'
import MsLayout from '@mbc-cqrs-serverless/master-web/MsLayout'

const EditMasterSettings = dynamic(
  () => import('@mbc-cqrs-serverless/master-web/EditMasterSettings').then((mod) => mod.default),
  { ssr: false }
)

export default function NewMasterSettingPage() {
  return (
    <main>
      <MsLayout useLoading>
        <EditMasterSettings />
      </MsLayout>
    </main>
  )
}
```

:::tip Key Points
- **layout.tsx**: Set up AppProviders, httpClient, and urlProvider
- **page.tsx**: Simply render components with dynamic imports
- **MsLayout**: Provides loading overlay and toast notifications
:::

### AWS Amplify v6 Integration

The default httpClient in master-web uses AWS Amplify v5 APIs (`Auth.currentSession()`). If your project uses AWS Amplify v6, you must provide a custom httpClient.

The Layout-based Provider Pattern example above uses Amplify v6's `fetchAuthSession` with Axios interceptors. This is the recommended approach.

#### Alternative Pattern: Configuration in Page Component

Alternative implementation if you don't use the Layout pattern:

```tsx
'use client'

import { useState, useEffect, useCallback, useMemo } from 'react'
import axios, { AxiosInstance } from 'axios'
import * as Auth from 'aws-amplify/auth'  // Amplify v6 import
import { AppProviders } from '@mbc-cqrs-serverless/master-web/AppProviders'
import { BaseUrlProvider } from '@mbc-cqrs-serverless/master-web/UrlProvider'
import dynamic from 'next/dynamic'

interface MasterTemplateProps {
  tenantCode: string
}

// Custom URL provider for multi-tenant routing
class MasterUrlProvider extends BaseUrlProvider {
  constructor(tenantCode: string) {
    // BaseUrlProvider adds leading slash, so omit it here
    super(`admin/${tenantCode}/master`)
  }
}

// Wrapper component for proper context handling
function MasterSettingWrapper({
  httpClient,
  urlProvider,
  user,
}: {
  httpClient: AxiosInstance
  urlProvider: MasterUrlProvider
  user: { tenantCode: string; tenantRole: string }
}) {
  const MasterSetting = useMemo(
    () =>
      dynamic(() => import('@mbc-cqrs-serverless/master-web/MasterSetting'), {
        ssr: false,
        loading: () => <div>Loading component...</div>,
      }),
    []
  )

  return (
    <AppProviders user={user} httpClient={httpClient} urlProvider={urlProvider}>
      <MasterSetting />
    </AppProviders>
  )
}

export function MasterTemplate({ tenantCode }: MasterTemplateProps) {
  const [httpClient, setHttpClient] = useState<AxiosInstance | null>(null)
  const [isReady, setIsReady] = useState(false)

  // Setup httpClient with Amplify v6 authentication
  const setupHttpClient = useCallback(async () => {
    let authToken = ''
    try {
      // Amplify v6 API for fetching auth session
      const session = await Auth.fetchAuthSession()
      authToken = session.tokens?.idToken?.toString() || ''
    } catch {
      // Handle unauthenticated state
    }

    const client = axios.create({
      baseURL: process.env.NEXT_PUBLIC_API_ENDPOINT || 'http://localhost:3010',
      headers: {
        'Content-Type': 'application/json',
        'x-tenant-code': tenantCode,
        ...(authToken && { Authorization: `Bearer ${authToken}` }),
      },
    })

    setHttpClient(client)
    setIsReady(true)
  }, [tenantCode])

  useEffect(() => {
    setupHttpClient()
  }, [setupHttpClient])

  const urlProvider = useMemo(() => new MasterUrlProvider(tenantCode), [tenantCode])

  const user = useMemo(
    () => ({
      tenantCode,
      tenantRole: 'admin',
    }),
    [tenantCode]
  )

  // Wait for httpClient to be ready before rendering
  if (!isReady || !httpClient) {
    return <div>Loading...</div>
  }

  return (
    <MasterSettingWrapper
      httpClient={httpClient}
      urlProvider={urlProvider}
      user={user}
    />
  )
}
```

### Multi-Tenant Routing Setup

For multi-tenant applications, set up dynamic routes with tenant code in the URL:

#### Directory Structure

```text
app/
└── admin/
    └── [tenant]/
        └── master/
            ├── layout.tsx                      # AppProviders setup (recommended)
            ├── page.tsx                        # Master top page
            ├── master-setting/
            │   ├── page.tsx                    # Settings list
            │   ├── new/
            │   │   └── page.tsx                # Create new setting
            │   └── [pk]/
            │       └── [sk]/
            │           └── page.tsx            # Edit setting
            └── master-data/
                ├── page.tsx                    # Data list
                ├── new/
                │   └── page.tsx                # Create new data
                └── [pk]/
                    └── [sk]/
                        └── page.tsx            # Edit data
```

#### Page Component Example

```tsx
// app/admin/[tenant]/master/master-setting/page.tsx
import { MasterTemplate } from '@/modules/master/templates/MasterTemplate'

export default async function MasterSettingPage({
  params,
}: {
  params: Promise<{ tenant: string }>
}) {
  const { tenant } = await params

  return <MasterTemplate tenantCode={tenant} />
}
```

### Common Issues and Solutions

#### `httpClient.get is not a function` Error

This error occurs when the httpClient is not properly initialized before the component tries to use it.

**Causes**:
- React Context in npm packages becomes isolated from the application's context
- httpClient is initialized asynchronously and not ready when the component mounts

**Solutions**:

1. **Use Layout-based Provider Pattern (Recommended)**: See the recommended pattern above
2. **Use a wrapper component pattern**: Ensure httpClient is ready
3. **Add explicit `isReady` state check**: Check before rendering AppProviders
4. **Define dynamic imports inside the wrapper component**: Not at module level

#### URL Routing Issues

If URLs are generated incorrectly (e.g., `//admin/...` instead of `/admin/...`), check the BaseUrlProvider configuration:

```tsx
// ❌ Wrong - double slash issue
class MasterUrlProvider extends BaseUrlProvider {
  constructor(tenantCode: string) {
    super(`/admin/${tenantCode}/master`)  // Leading slash causes issue
  }
}

// ✅ Correct - no leading slash
class MasterUrlProvider extends BaseUrlProvider {
  constructor(tenantCode: string) {
    super(`admin/${tenantCode}/master`)  // BaseUrlProvider adds the slash
  }
}
```

#### Implementing IUrlProvider Directly

When implementing the `IUrlProvider` interface directly without extending `BaseUrlProvider`, you need to explicitly define all URL properties. See the Layout-based Provider Pattern example above for reference.

## Dependencies {#dependencies}

Key dependencies used by this package:

- React 18.x
- Next.js 14.x / 15.x
- TanStack React Table 8.x
- Apollo Client
- Radix UI components
- Tailwind CSS 3.x
- react-hook-form
- Zod for validation

## Changelog {#changelog}

:::info Version History
See [Web Packages Changelog](/docs/web-changelog) for all version history and release notes.
:::


## Related Documentation

- [Master](/docs/master) - Backend master data service
- [Frontend Project Structure](/docs/frontend-project-structure) - Project structure
- [API Integration Patterns](/docs/api-integration-patterns) - API patterns
- [UI Setting](/docs/ui-setting) - Dynamic UI settings and configuration management


---

## State Management Patterns

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/state-management-patterns

# State Management Patterns

This guide explains how to manage different types of state in frontend applications. Understanding when to use each tool prevents common problems like stale data, unnecessary re-renders, and complex debugging.

## When to Use This Guide {#when-to-use}

Use this guide when you need to:

- Cache API responses and keep them synchronized with the server
- Share UI state (sidebar, theme, modals) across components
- Handle loading and error states for data fetching
- Implement optimistic updates for better user experience
- Manage multi-tenant context in a SaaS application

## Choosing the Right Tool {#choosing-tools}

The most common mistake is using one tool for all state. Different types of state have different requirements:

| Category | Tool | Examples | Why This Tool |
|----------|------|----------|--------------|
| Server State | Context API + axios | API data, loading states | Direct control over HTTP requests, simple caching strategies |
| Real-time State | Apollo Client | GraphQL subscriptions, live updates | Built-in subscription support for AppSync |
| Client State | Context API | UI state, user preferences | React built-in, no additional dependencies |
| Form State | React Hook Form | Form inputs, validation | Optimized for form performance, built-in validation |
| URL State | Next.js Router | Query params, path params | Shareable URLs, browser history integration |

## Current Implementation {#current-implementation}

The MBC CQRS Serverless Web package uses the following state management architecture:

### AppProviders - Centralized Service Provider

The application uses a centralized provider pattern that combines multiple contexts:

```typescript
// provider.tsx
import React, { createContext, useContext, ReactNode, useMemo } from 'react'
import {
  ApolloClient,
  NormalizedCacheObject,
  ApolloProvider,
} from '@apollo/client'
import { AxiosInstance } from 'axios'
import { UserContext } from './types/UserContext'

// Define the shape of services provided to the app
export interface AppServices {
  httpClient: AxiosInstance
  apolloClient: ApolloClient<NormalizedCacheObject>
  user: UserContext
  urlProvider: IUrlProvider
}

// Create context with null default for error detection
const AppContext = createContext<AppServices | null>(null)

// Main provider that wraps the entire application
export function AppProviders({
  children,
  user,
  httpClient,
  apolloClient,
  urlProvider,
}: AppProvidersProps) {
  const services = useMemo(() => ({
    httpClient: httpClient ?? getClientInstance(),
    apolloClient: apolloClient ?? apolloClientInstance,
    urlProvider: urlProvider ?? new BaseUrlProvider(),
    user: user,
  }), [user, httpClient, apolloClient, urlProvider])

  return (
    <AppRootProvider services={services}>
      <LoadingProvider>{children}</LoadingProvider>
    </AppRootProvider>
  )
}
```

### Custom Hooks for Accessing Services

Create dedicated hooks to access specific services from the context:

```typescript
// Hook to access the HTTP client (axios)
export function useHttpClient(): AxiosInstance {
  const { httpClient } = useAppServices()
  return httpClient
}

// Hook to access the Apollo client for GraphQL
export function useApolloClient(): ApolloClient<NormalizedCacheObject> {
  const { apolloClient } = useAppServices()
  return apolloClient
}

// Hook to access user context
export function useUserContext(): UserContext {
  const { user } = useAppServices()
  return user
}
```

## Context API for Client State {#context-api}

### Use Case: Global Loading State

Scenario: Show a loading overlay during async operations across the application.

Problem: Each component managing its own loading state leads to inconsistent UX.

Solution: Use a centralized LoadingContext that all components can access.

```typescript
// stores/index.ts
export interface LoadingState {
  isLoading: boolean
  setLoading: () => void
  closeLoading: () => void
}

// stores/provider/index.tsx
'use client'

import React, { createContext, useState, useMemo, ReactNode } from 'react'
import { LoadingState } from '..'

export const LoadingContext = createContext<LoadingState | null>(null)

LoadingContext.displayName = 'LoadingContext'

export function LoadingProvider({ children }: { children: ReactNode }) {
  const [isLoading, setIsLoading] = useState(true)

  // Memoize context value to prevent unnecessary re-renders
  const value = useMemo(
    () => ({
      isLoading,
      setLoading: () => setIsLoading(true),
      closeLoading: () => setIsLoading(false),
    }),
    [isLoading]
  )

  return (
    <LoadingContext.Provider value={value}>{children}</LoadingContext.Provider>
  )
}
```

### Use Case: Custom Hook for Loading State

Create a custom hook with proper error handling:

```typescript
// stores/hooks/index.ts
import React, { useContext } from 'react'
import { LoadingContext } from '../provider'

export function useLoadingStore() {
  const context = useContext(LoadingContext)
  // Safeguard: throw error if hook used outside provider
  if (context === null) {
    throw new Error('useLoading must be used within a LoadingProvider')
  }
  return context
}
```

### Use Case: Wrapping Async Actions

Scenario: Execute async functions while automatically managing the loading overlay.

```typescript
// hook/useAsyncAction.ts
import { useLoadingStore } from '../stores/hooks'
import { useCallback } from 'react'

export const useAsyncAction = () => {
  const loadingStore = useLoadingStore()

  const performAction = useCallback(
    async <T>(asyncFunction: () => Promise<T>): Promise<T> => {
      loadingStore.setLoading()
      try {
        return await asyncFunction()
      } catch (error) {
        console.error('Async action failed:', error)
        throw error
      } finally {
        loadingStore.closeLoading()
      }
    },
    [loadingStore]
  )

  return { performAction, isLoading: loadingStore.isLoading }
}

// Usage in component
function ProductPage() {
  const { performAction, isLoading } = useAsyncAction()

  const handleSubmit = async (data: ProductData) => {
    await performAction(async () => {
      await productApi.create(data)
    })
  }

  return (
    <form onSubmit={handleSubmit}>
      {/* ... */}
    </form>
  )
}
```

## axios for HTTP Requests {#axios-http}

### Use Case: Centralized HTTP Client with Authentication

Scenario: All API requests need authentication tokens and consistent error handling.

Solution: Create a singleton axios instance with interceptors for token injection.

```typescript
// sdk/app-client.ts
import axios, { AxiosInstance } from 'axios'
import { Auth, withSSRContext } from 'aws-amplify'
import { GetServerSidePropsContext } from 'next'

export abstract class TokenHandlerBase {
  public constructor(protected serverSideContext?: GetServerSidePropsContext) {}

  public static init(
    serverSideContext?: GetServerSidePropsContext
  ): TokenHandlerBase {
    // Return test handler for Playwright tests
    if (process.env.NEXT_PUBLIC_ENV_PLAYWRIGHT === 'true') {
      return new TestTokenHandler(serverSideContext)
    }
    return new DefaultTokenHandler(serverSideContext)
  }

  public abstract getToken(): Promise<string>
}

export class DefaultTokenHandler extends TokenHandlerBase {
  public async getToken(): Promise<string> {
    // Handle SSR vs client-side token retrieval
    if (!!this.serverSideContext) {
      const { Auth: AuthSSR } = withSSRContext({
        req: this.serverSideContext.req,
      })
      return (await AuthSSR.currentSession()).getIdToken().getJwtToken()
    } else {
      return (await Auth.currentSession()).getIdToken().getJwtToken()
    }
  }
}

export class AppClient {
  private static instance: AxiosInstance

  public static getAppClientInstance(
    token?: string | (() => Promise<string>),
    headers?: Record<string, string>
  ): AxiosInstance {
    if (!AppClient.instance) {
      AppClient.instance = axios.create({
        baseURL: process.env.NEXT_PUBLIC_MASTER_API_BASE,
        timeout: 0,
        headers: { ...headers },
      })
      // Add interceptor to inject auth token
      AppClient.instance.interceptors.request.use(
        async (config) => {
          let tokenString = ''
          if (token) {
            tokenString = typeof token === 'string' ? token : await token()
          }
          config.headers.Authorization = `Bearer ${tokenString}`
          return config
        },
        (error) => Promise.reject(error)
      )
    }
    return AppClient.instance
  }
}

// Factory function for creating authenticated client
export const getClientInstance = (headers?: Record<string, string>) => {
  const tokenHandler = TokenHandlerBase.init()

  const token = () =>
    tokenHandler
      .getToken()
      .then((token) => token)
      .catch((err) => {
        const error = new UnauthorizedException(
          null,
          err,
          'Failed to get access token. Session expired.'
        )
        return Promise.reject(error)
      })
  return AppClient.getAppClientInstance(token, headers)
}
```

### Use Case: Making API Calls

Using the HTTP client through the context hook:

```typescript
import { useHttpClient } from '@mbc-cqrs-serverless/master-web/AppProviders'

function ProductList() {
  const httpClient = useHttpClient()
  const [products, setProducts] = useState<Product[]>([])
  const [loading, setLoading] = useState(false)

  useEffect(() => {
    const fetchProducts = async () => {
      setLoading(true)
      try {
        const response = await httpClient.get('/products')
        setProducts(response.data)
      } catch (error) {
        console.error('Failed to fetch products:', error)
      } finally {
        setLoading(false)
      }
    }
    fetchProducts()
  }, [httpClient])

  return (
    <div>
      {loading ? <Spinner /> : products.map(p => <ProductCard key={p.id} product={p} />)}
    </div>
  )
}
```

## Apollo Client for Real-time Subscriptions {#apollo-client}

### Use Case: GraphQL Subscriptions with AppSync

Scenario: Display real-time command status updates (e.g., data sync progress).

Solution: Use Apollo Client's subscription feature connected to AWS AppSync.

```typescript
// appsync/subscribe.ts
import { gql, ApolloClient, NormalizedCacheObject } from '@apollo/client'
import {
  OnMessageSubscription,
  OnMessageSubscriptionVariables,
} from './API'
import { onMessage } from './graphql/subscriptions'

export type CommandStatusContent = {
  status:
    | 'finish:FINISHED'
    | 'finish:STARTED'
    | 'sync_data:FINISHED'
    | 'sync_data:STARTED'
    | 'transform_data:FINISHED'
    | 'transform_data:STARTED'
}

export type DecodedMessage = Omit<Message, 'content'> & {
  content: MessageContent
}

export function subscribeMessage(
  client: ApolloClient<NormalizedCacheObject>,
  filters: OnMessageSubscriptionVariables,
  handler: (value: DecodedMessage) => void | Promise<void>
) {
  const observable = client.subscribe<
    OnMessageSubscription,
    OnMessageSubscriptionVariables
  >({
    query: gql`
      ${onMessage}
    `,
    variables: filters,
  })

  return observable.subscribe({
    next: ({ data }) => {
      if (!data.onMessage) {
        return
      }
      const message: DecodedMessage = {
        ...data.onMessage,
        content: parseContent(data.onMessage.content),
      }
      if (message) {
        handler(message)
      }
    },
    error: (error) => console.error('subscribeMessage error:', error),
  })
}

function parseContent(content: string): MessageContent {
  try {
    return JSON.parse(content)
  } catch (error) {
    return content
  }
}
```

### Use Case: Using Subscriptions in Components

```typescript
import { useApolloClient } from '@mbc-cqrs-serverless/master-web/AppProviders'
import { subscribeMessage, DecodedMessage } from '../appsync/subscribe'
import { useEffect, useState } from 'react'

function CommandStatusDisplay({ commandId }: { commandId: string }) {
  const apolloClient = useApolloClient()
  const [status, setStatus] = useState<string>('pending')

  useEffect(() => {
    const subscription = subscribeMessage(
      apolloClient,
      { pk: commandId },
      (message: DecodedMessage) => {
        if (typeof message.content === 'object') {
          setStatus(message.content.status)
        }
      }
    )

    // Cleanup subscription on unmount
    return () => {
      subscription.unsubscribe()
    }
  }, [apolloClient, commandId])

  return <StatusBadge status={status} />
}
```

## Best Practices {#best-practices}

### 1. Use Context Selectively

Problem: Putting too much state in a single context causes unnecessary re-renders.

Solution: Split contexts by domain and use memoization.

```typescript
// Good: Separate contexts for different concerns
<AuthProvider>
  <UIProvider>
    <LoadingProvider>
      {children}
    </LoadingProvider>
  </UIProvider>
</AuthProvider>

// Good: Memoize context values
const value = useMemo(
  () => ({ isLoading, setLoading, closeLoading }),
  [isLoading]
)
```

### 2. Always Handle Errors in Hooks

```typescript
export function useAppServices(): AppServices {
  const context = useContext(AppContext)
  // Throw helpful error if context is missing
  if (context === null) {
    throw new Error('useAppServices must be used within an AppRootProvider')
  }
  return context
}
```

### 3. Use Factory Pattern for HTTP Client

This allows for different configurations in different environments:

```typescript
// Production: Real auth tokens
const client = getClientInstance()

// Testing: Mock tokens
class TestTokenHandler extends TokenHandlerBase {
  public async getToken(): Promise<string> {
    return 'test'
  }
}
```

### 4. Clean Up Subscriptions

Always unsubscribe from Apollo subscriptions to prevent memory leaks:

```typescript
useEffect(() => {
  const subscription = subscribeMessage(client, filters, handler)

  return () => {
    subscription.unsubscribe()
  }
}, [client, filters])
```

## Alternative Options {#alternative-options}

While the current implementation uses Context API with axios and Apollo Client, there are alternative state management solutions you may consider for specific use cases:

### React Query (TanStack Query)

Best for applications with complex server state caching requirements:

- Automatic background refetching
- Cache invalidation and synchronization
- Optimistic updates
- Infinite scroll and pagination

```typescript
// Example: React Query usage
import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

export function useProducts() {
  return useQuery({
    queryKey: ['products'],
    queryFn: () => productApi.list(),
  })
}
```

### Zustand

Best for applications needing lightweight global state without Context boilerplate:

- Simple API with selectors
- Persist middleware for localStorage
- DevTools integration
- No provider required

```typescript
// Example: Zustand store
import { create } from 'zustand'

interface UIState {
  sidebarOpen: boolean
  toggleSidebar: () => void
}

export const useUIStore = create<UIState>((set) => ({
  sidebarOpen: true,
  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
}))
```

### SWR

Best for simple data fetching with automatic revalidation:

- Stale-while-revalidate strategy
- Focus revalidation
- Polling support

```typescript
// Example: SWR usage
import useSWR from 'swr'

function Profile() {
  const { data, error, isLoading } = useSWR('/api/user', fetcher)

  if (isLoading) return <Spinner />
  if (error) return <Error />
  return <div>Hello, {data.name}</div>
}
```

Choose the right tool based on your project's complexity and requirements. The current implementation with Context API + axios + Apollo Client provides a solid foundation that can be extended as needed.


## Related Documentation

- [API Integration Patterns](/docs/api-integration-patterns) - API client setup
- [API Integration Guide](/docs/api-integration-guide) - API integration guidance
- [Frontend Project Structure](/docs/frontend-project-structure) - Project structure
- [Authentication](/docs/authentication) - Auth state management


---

## Survey Web

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/survey-web

# Survey Web

Frontend component library for survey template management and form rendering in MBC CQRS Serverless applications.

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/survey-web
```

:::info Version Note
In [v0.0.42](/docs/web-changelog#v0042), React and React DOM were externalized as peer dependencies, resolving the Context isolation issue. If you are using v0.0.41 or earlier, upgrade to v0.0.42 or later for the fix.
:::

## Overview {#overview}

The Survey Web package (`@mbc-cqrs-serverless/survey-web`) provides React components for creating, editing, and rendering survey templates. It supports multiple question types, drag-and-drop section reordering, and real-time collaboration through AWS AppSync.

## Features {#features}

- **Template Management**: Create, edit, and delete survey templates
- **Multiple Question Types**: 9 built-in question types for various data collection needs
- **Drag and Drop**: Reorder sections and questions with @dnd-kit
- **Form Validation**: Zod-based validation with custom rules
- **Real-time Updates**: AWS AppSync integration for collaborative editing
- **Responsive Design**: Mobile-friendly survey forms
- **Section-based Structure**: Organize questions into logical sections

## Main Components {#main-components}

### SurveyTemplatePage

Displays a list of survey templates with search and management capabilities.

```tsx
import { SurveyTemplatePage } from "@mbc-cqrs-serverless/survey-web/SurveyTemplatePage";
import "@mbc-cqrs-serverless/survey-web/styles.css";

export default function SurveyTemplatesPage() {
  return <SurveyTemplatePage />;
}
```

### EditSurveyTemplatePage

Editor for creating and modifying survey templates with drag-and-drop functionality.

This component uses `useParams()` from `next/navigation` internally to get the survey ID from the URL. For new surveys (create mode), render on a route without an ID parameter. For editing existing surveys, render on a route with an ID parameter (e.g., `/surveys/[id]/edit`).

```tsx
import { EditSurveyTemplatePage } from "@mbc-cqrs-serverless/survey-web/EditSurveyTemplatePage";

// Route: /surveys/new (create mode)
// Route: /surveys/[id]/edit (edit mode - ID extracted from URL via useParams)
export default function EditSurveyPage() {
  return <EditSurveyTemplatePage />;
}
```

### SurveyForm

Renders a survey template as a fillable form for respondents.

```tsx
import { SurveyForm } from "@mbc-cqrs-serverless/survey-web/SurveyForm";

// Answer values can be string (single value) or string[] (multiple choice)
type SurveyAnswers = Record<string, string | string[] | undefined>;

// Define schema type based on the Survey Template Structure section below
interface SurveySchema {
  title: string;
  description?: string;
  items: SurveyItem[];
}

interface Props {
  schema: SurveySchema;
}

export default function SurveyResponsePage({ schema }: Props) {
  const handleSubmit = (answers: SurveyAnswers) => {
    console.log("Survey answers:", answers);
  };

  return (
    <SurveyForm
      schema={schema}
      onSubmit={handleSubmit}
      disabled={false}
    >
      {/* Optional: Custom content rendered inside the current section */}
    </SurveyForm>
  );
}
```

| Prop | Type | Required | Description |
|----------|----------|--------------|-----------------|
| `schema` | `SurveySchema` | Yes | The survey template schema to render |
| `onSubmit` | `(answers: SurveyAnswers) => void` | Yes | Callback when survey is submitted with all answers |
| `disabled` | `boolean` | No | Disable form interactions (default: false) |
| `children` | `React.ReactNode` | No | Optional content rendered inside the current section |

## Question Types {#question-types}

The Survey Web package supports 9 question types:

### 1. Short Text

Single-line text input for brief responses.

```json
{
  "id": "q1",
  "type": "short-text",
  "label": "What is your name?",
  "validation": {
    "required": true
  }
}
```

### 2. Long Text

Multi-line text area for detailed responses.

```json
{
  "id": "q2",
  "type": "long-text",
  "label": "Please describe your experience",
  "validation": {
    "required": false,
    "custom": {
      "type": "length",
      "rule": "max",
      "value": 1000,
      "customError": "Response must be 1000 characters or less"
    }
  }
}
```

### 3. Single Choice

Radio button selection for mutually exclusive options.

```json
{
  "id": "q3",
  "type": "single-choice",
  "label": "What is your preferred contact method?",
  "options": [
    { "value": "email", "label": "Email" },
    { "value": "phone", "label": "Phone" },
    { "value": "mail", "label": "Mail" }
  ],
  "validation": {
    "required": true
  }
}
```

### 4. Multiple Choice

Checkbox selection for multiple options.

```json
{
  "id": "q4",
  "type": "multiple-choice",
  "label": "Which products are you interested in?",
  "options": [
    { "value": "product_a", "label": "Product A" },
    { "value": "product_b", "label": "Product B" },
    { "value": "product_c", "label": "Product C" }
  ],
  "validation": {
    "required": true
  }
}
```

### 5. Dropdown

Select dropdown for choosing from a list.

```json
{
  "id": "q5",
  "type": "dropdown",
  "label": "Select your country",
  "options": [
    { "value": "jp", "label": "Japan" },
    { "value": "us", "label": "United States" },
    { "value": "uk", "label": "United Kingdom" }
  ],
  "validation": {
    "required": true
  }
}
```

### 6. Linear Scale

Numeric scale for rating responses.

```json
{
  "id": "q6",
  "type": "linear-scale",
  "label": "How likely are you to recommend us?",
  "min": 0,
  "max": 10,
  "minLabel": "Not likely",
  "maxLabel": "Very likely",
  "validation": {
    "required": true
  }
}
```

### 7. Rating

Configurable star/heart/thumb rating input with 2-10 levels.

```json
{
  "id": "q7",
  "type": "rating",
  "label": "Rate your overall satisfaction",
  "levels": 5,
  "symbol": "star",
  "validation": {
    "required": true
  }
}
```

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `levels` | `number` | `5` | Number of rating levels (2-10) |
| `symbol` | `'star' \| 'heart' \| 'thumb'` | `'star'` | Symbol used for rating display |

### 8. Date

Date picker for date selection with configurable options.

```json
{
  "id": "q8",
  "type": "date",
  "label": "When did you first use our service?",
  "includeTime": false,
  "includeYear": true,
  "validation": {
    "required": false
  }
}
```

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `includeTime` | `boolean` | `false` | Include time selection along with date |
| `includeYear` | `boolean` | `true` | Include year in date selection |

### 9. Time

Time picker for time or duration input.

```json
{
  "id": "q9",
  "type": "time",
  "label": "What time works best for a callback?",
  "answerType": "time",
  "validation": {
    "required": false
  }
}
```

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `answerType` | `'time' \| 'duration'` | `'time'` | Input mode: specific time or duration |

## Custom Hooks {#custom-hooks}

:::warning Internal Hooks
The hooks documented below (`useSurveyTemplates`, `useEditSurveyTemplate`, `useDeleteSurveyTemplate`) are internal hooks used by the page components. They are NOT exported from the main package index and cannot be imported directly. The import paths shown are for illustration purposes only. Use the page components (`SurveyTemplatePage`, `EditSurveyTemplatePage`) instead for standard use cases.
:::

### useSurveyTemplates

Fetch and manage survey templates with pagination and search support.

```tsx
// IMPORTANT: This hook is internal and cannot be imported directly.
// This code example is for reference only to show the hook's interface.
// Use SurveyTemplatePage component instead for standard use cases.

function TemplateList() {
  const {
    surveys,        // Array of survey templates (SurveyTemplateDataEntity[])
    totalItems,     // Total number of templates
    isLoading,
    error,          // Error | null
    refetch         // () => Promise<void> - Function to refresh the list
  } = useSurveyTemplates({
    page: 1,
    pageSize: 10,
    keyword: "",           // Optional: search keyword
    orderBy: "createdAt",  // Optional: sort field
    orderType: "desc"      // Optional: sort direction ('asc' | 'desc')
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;

  return (
    <div>
      <p>Total: {totalItems}</p>
      <ul>
        {surveys.map((survey) => (
          <li key={survey.id}>{survey.name}</li>
        ))}
      </ul>
    </div>
  );
}
```

### useEditSurveyTemplate

Hook for editing survey templates with schema management and submission handling.

```tsx
// IMPORTANT: This hook is internal and cannot be imported directly.
// This code example is for reference only to show the hook's interface.
// Use EditSurveyTemplatePage component instead for standard use cases.

function TemplateEditor({ id }: { id?: string }) {
  const {
    surveyData,           // Current survey data from server (SurveyTemplateDataEntity | null)
    currentSchema,        // Current editable schema (SurveySchemaType | null)
    originalSchema,       // Original schema for change detection (SurveySchemaType | null)
    isLoading,
    isSubmitting,
    error,
    setCurrentSchema,     // Function to update current schema
    handleCreateSurvey,   // (schema: SurveySchemaType) => Promise<void> - Create new survey
    handleUpdateSurvey,   // (schema: SurveySchemaType) => Promise<void> - Update existing survey
    retryFetchSurvey,     // () => Promise<void> - Retry fetching survey data
    isSchemaChanged,      // boolean - True if schema differs from original
    isButtonDisabled,     // boolean - True if submit should be disabled
    submitButtonRef       // React.RefObject<HTMLButtonElement> - Ref for submit button
  } = useEditSurveyTemplate({ id });

  const handleSave = async () => {
    if (!currentSchema) return;
    if (id) {
      await handleUpdateSurvey(currentSchema);
    } else {
      await handleCreateSurvey(currentSchema);
    }
  };

  return (
    <div>
      {/* Editor UI */}
      <button
        ref={submitButtonRef}
        onClick={handleSave}
        disabled={isButtonDisabled}
      >
        {isSubmitting ? "Saving..." : "Save"}
      </button>
    </div>
  );
}
```

### useDeleteSurveyTemplate

Hook for deleting survey templates with success callback.

```tsx
// IMPORTANT: This hook is internal and cannot be imported directly.
// This code example is for reference only to show the hook's interface.

function DeleteButton({ surveyId }: { surveyId: string }) {
  const {
    handleDeleteSurvey,  // (id: string) => Promise<void> - Delete survey by ID
    isDeleting           // boolean - True while deletion is in progress
  } = useDeleteSurveyTemplate({
    onSuccess: () => {
      console.log("Survey deleted successfully");
      // Navigate back to list or refresh
    }
  });

  return (
    <button
      onClick={() => handleDeleteSurvey(surveyId)}
      disabled={isDeleting}
    >
      Delete
    </button>
  );
}
```

## Survey Template Structure {#template-structure}

Survey templates use a flat list structure with section headers:

```typescript
interface SurveySchema {
  title: string;
  description?: string;
  items: SurveyItem[];  // Flat list of section headers and questions
}

// Section header item - acts as a bookmark or page break
interface SectionHeader {
  id: string;
  type: "section-header";
  title: string;
  description?: string;
  action?: {
    type: "submit";
  } | {
    type: "jump";
    targetSectionId: string;  // ID of another section-header for conditional branching
  };
}

// Available question types
type QuestionType =
  | "short-text"
  | "long-text"
  | "single-choice"
  | "multiple-choice"
  | "dropdown"
  | "linear-scale"
  | "rating"
  | "date"
  | "time";

// Question item
interface Question {
  id: string;
  type: QuestionType;  // short-text, long-text, single-choice, etc.
  label: string;
  description?: string;
  options?: QuestionOption[];  // For choice-based questions
  validation?: ValidationRules;
}

// Option for choice-based questions
interface QuestionOption {
  value: string;        // Unique value for the option
  label: string;        // Display label for the option
  nextSectionId?: string;  // ID of section to jump to when this option is selected (for conditional branching)
  isOther?: boolean;    // If true, shows a text input for custom "Other" response
}

// Union of all item types
type SurveyItem = SectionHeader | Question;
```

Example survey structure:

```json
{
  "title": "Customer Feedback Survey",
  "description": "Help us improve our service",
  "items": [
    {
      "id": "section-intro",
      "type": "section-header",
      "title": "Introduction",
      "description": "Please answer a few questions about yourself"
    },
    {
      "id": "q1",
      "type": "short-text",
      "label": "What is your name?",
      "validation": { "required": true }
    },
    {
      "id": "section-feedback",
      "type": "section-header",
      "title": "Feedback",
      "description": "Tell us about your experience"
    },
    {
      "id": "q2",
      "type": "linear-scale",
      "label": "How satisfied are you?",
      "min": 1,
      "max": 10,
      "minLabel": "Not satisfied",
      "maxLabel": "Very satisfied",
      "validation": { "required": true }
    }
  ]
}
```

## SurveyTemplateDataEntity Type {#survey-entity-type}

The `SurveyTemplateDataEntity` type represents the actual DynamoDB entity structure:

```typescript
type SurveyTemplateDataEntity = {
  // Primary keys
  pk: string;                    // Partition key
  sk: string;                    // Sort key

  // Entity identifiers
  id: string;                    // Unique identifier
  code: string;                  // Template code
  name: string;                  // Template name
  version: number;               // Version number
  tenantCode: string;            // Tenant code
  type: string;                  // Entity type

  // Audit fields (as strings)
  createdAt?: string;            // Creation timestamp
  updatedAt?: string;            // Last update timestamp
  createdBy?: string;            // Creator user ID
  updatedBy?: string;            // Last updater user ID

  // Optional fields
  cpk?: string;                  // Command partition key
  csk?: string;                  // Command sort key
  source?: string;               // Source identifier
  requestId?: string;            // Request ID
  createdIp?: string;            // Creator IP address
  updatedIp?: string;            // Updater IP address
  seq?: number;                  // Sequence number
  ttl?: number;                  // Time to live
  isDeleted?: boolean;           // Soft delete flag

  // Survey template data
  attributes: {
    description?: string;        // Template description
    surveyTemplate: {            // Survey template JSON structure
      [key: string]: unknown;
    };
  };
}
```

## Validation Rules {#validation-rules}

Validation rules are defined inside the `validation` object with a discriminated union structure:

```typescript
// Base validation rules - applies to all question types
interface BaseValidationRules {
  required?: boolean;
}

// For short-text questions
interface ShortTextValidationRules extends BaseValidationRules {
  custom?: CustomValidationRule;  // Supports all validation types
}

// For long-text questions
interface LongTextValidationRules extends BaseValidationRules {
  custom?: LongTextValidationRule;  // Supports only LengthValidation and RegexValidation
}

// For single-choice, dropdown, and multiple-choice questions
interface ChoiceValidationRules extends BaseValidationRules {
  shuffleOptions?: boolean;  // Randomize option order
}

// For multiple-choice questions
interface MultipleChoiceValidationRules extends ChoiceValidationRules {
  custom?: MultipleChoiceValidationRule;  // For min/max/exact selection count
}

// Discriminated union for custom validation rules
// Note: short-text supports all validation types
// Note: long-text only supports LengthValidation and RegexValidation
type CustomValidationRule =
  | NumberValidation   // short-text only
  | TextValidation     // short-text only
  | LengthValidation   // short-text and long-text
  | RegexValidation;   // short-text and long-text

// For long-text questions - subset of CustomValidationRule
type LongTextValidationRule =
  | LengthValidation
  | RegexValidation;

interface NumberValidation {
  type: "number";
  rule: "gt" | "gte" | "lt" | "lte" | "eq" | "neq" | "between" | "not_between" | "is_number" | "is_whole";
  value?: number;
  value2?: number;  // For 'between' and 'not_between' rules
  customError?: string;
}

interface TextValidation {
  type: "text";
  rule: "contains" | "not_contains" | "is_email" | "is_url";
  value?: string;
  customError?: string;
}

interface LengthValidation {
  type: "length";
  rule: "min" | "max";
  value: number;
  customError?: string;
}

interface RegexValidation {
  type: "regex";
  rule: "contains" | "not_contains" | "matches" | "not_matches";
  value: string;
  customError?: string;
}

// For multiple-choice questions
interface MultipleChoiceValidationRule {
  rule: "min" | "max" | "exact";
  value: number;
  customError?: string;
}

// Discriminated union for the validation property on Question
type ValidationRules =
  | BaseValidationRules
  | ShortTextValidationRules
  | LongTextValidationRules
  | ChoiceValidationRules
  | MultipleChoiceValidationRules;
```

Example with email validation:

```json
{
  "id": "email",
  "type": "short-text",
  "label": "Enter your email",
  "validation": {
    "required": true,
    "custom": {
      "type": "text",
      "rule": "is_email",
      "customError": "Please enter a valid email address"
    }
  }
}
```

Example with number range validation:

```json
{
  "id": "age",
  "type": "short-text",
  "label": "Enter your age",
  "validation": {
    "required": true,
    "custom": {
      "type": "number",
      "rule": "between",
      "value": 18,
      "value2": 120,
      "customError": "Age must be between 18 and 120"
    }
  }
}
```

Example with multiple choice validation (min/max selections):

```json
{
  "id": "interests",
  "type": "multiple-choice",
  "label": "Select your interests (2-5 choices)",
  "options": [
    { "value": "sports", "label": "Sports" },
    { "value": "music", "label": "Music" },
    { "value": "reading", "label": "Reading" },
    { "value": "travel", "label": "Travel" },
    { "value": "cooking", "label": "Cooking" }
  ],
  "validation": {
    "required": true,
    "custom": {
      "rule": "min",
      "value": 2,
      "customError": "Please select at least 2 options"
    }
  }
}
```

## Environment Variables {#environment-variables}

Configure the following environment variables:

| Variable | Description | Required |
|----------|-------------|----------|
| `API_URL` | Base URL for REST API endpoints (server-side only, takes precedence over NEXT_PUBLIC_API_URL) | No |
| `NEXT_PUBLIC_API_URL` | Base URL for REST API endpoints (client-side) | Yes |
| `NEXT_PUBLIC_TENANT_CODE` | Tenant code for x-tenant-code header (default: 'common') | No |
| `NEXT_PUBLIC_AWS_APPSYNC_GRAPHQLENDPOINT` | AWS AppSync GraphQL endpoint | Yes |
| `NEXT_PUBLIC_AWS_APPSYNC_APIKEY` | AWS AppSync API key for authentication | Yes |
| `NEXT_PUBLIC_AWS_APPSYNC_REGION` | AWS region for AppSync | Yes |

Example `.env.local` configuration:

```bash
# REST API Configuration
# API_URL is optional (server-side only), NEXT_PUBLIC_API_URL is required
NEXT_PUBLIC_API_URL=https://api.example.com

# Tenant Configuration
NEXT_PUBLIC_TENANT_CODE=my-tenant

# AWS AppSync Configuration
NEXT_PUBLIC_AWS_APPSYNC_GRAPHQLENDPOINT=https://xxxxx.appsync-api.us-east-1.amazonaws.com/graphql
NEXT_PUBLIC_AWS_APPSYNC_APIKEY=da2-xxxxxxxxxxxxxxxxxxxxxxxxxx
NEXT_PUBLIC_AWS_APPSYNC_REGION=us-east-1
```

## Styling {#styling}

Import the package styles in your application:

```tsx
// In your layout or entry file
import "@mbc-cqrs-serverless/survey-web/styles.css";
```

The components use Tailwind CSS. Ensure your project has Tailwind CSS configured with the following requirements:

- Tailwind CSS 3.x
- tailwindcss-animate plugin

## Dependencies {#dependencies}

Key dependencies used by this package:

- React 18.x
- Next.js 14.x
- @dnd-kit for drag and drop
- Apollo Client
- Radix UI components
- Tailwind CSS 3.x
- react-hook-form
- Zod for validation
- date-fns for date handling
- lucide-react for icons

## Changelog {#changelog}

:::info Version History
See [Web Packages Changelog](/docs/web-changelog) for all version history and release notes.
:::


## Related Documentation

- [Survey Template](/docs/survey-template) - Backend survey template service
- [Form Handling Patterns](/docs/form-handling-patterns) - React Hook Form and Zod validation patterns
- [Frontend Project Structure](/docs/frontend-project-structure) - Project structure
- [API Integration Patterns](/docs/api-integration-patterns) - API patterns
- [UI Setting](/docs/ui-setting) - Dynamic UI settings and configuration management


---

# Security

## Authentication

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/authentication

# Authentication

Understanding authentication is crucial for protecting your application's data. This page will guide you through what mbc-cqrs-serverless features to use to implement auth.

Before starting, it helps to break down the process into three concepts:

1. **Authentication**: Verifies if the user is who they say they are. It requires the user to prove their identity with something they have, such as a username and password.

2. **Session Management**: Tracks the user's auth state across requests.

3. **Authorization**: Decides what routes and data the user can access.

The examples on this page walk through an [Amazon Cognito](https://aws.amazon.com/cognito/) app client, you can invoke API operations for authentication and authorization of your users.

## Authentication {#authentication}

We recommend you use [AWS Amplify](https://docs.amplify.aws/nextjs/) to integrate Amazon Cognito with your web and mobile apps. <br/> Once authenticated, the server will issue a JWT that can be sent as a [bearer token](https://datatracker.ietf.org/doc/html/rfc6750) in an authorization header on subsequent requests to prove authentication.

## Authorization {#authorization}

Once a user is authenticated, you can implement authorization to control what the user can access and do within your application. Authorization is orthogonal and independent from authentication. However, authorization requires an authentication mechanism. <br/> We use optimistic types of authorization check: Checks if the user is authorized to access a route or perform an action using the session data stored in the cookie. Specifically, we implement Role-Based Access Control (RBAC).

First, let's create a Role enum representing roles in the system:

```ts
// role.enum.ts
import { ROLE_SYSTEM_ADMIN } from "@mbc-cqrs-serverless/core";

export enum Role {
  SYSTEM_ADMIN = ROLE_SYSTEM_ADMIN,
  USER = "user",
  ADMIN = "admin",
}
```

:::tip

In more sophisticated systems, you may store roles within a database, or pull them from the external authentication provider.

:::

### System Admin Bypass {#system-admin-bypass}

The framework includes a built-in system admin bypass mechanism. When a user has the `system_admin` role (defined as `ROLE_SYSTEM_ADMIN` constant), they automatically pass all role-based authorization checks, regardless of the specific roles required by the endpoint.

```ts
// Checks required roles from the @Auth() decorator
protected async verifyRole(context: ExecutionContext): Promise<boolean> {
  const requiredRoles = this.reflector.getAllAndOverride<string[]>(...)

  // If no roles required, allow all users
  if (!requiredRoles || !requiredRoles.length) {
    return true
  }

  const { tenantRoles, tenantGroupIds } = getUserContext(context)

  // System admin bypasses all role checks
  if (tenantRoles.includes(ROLE_SYSTEM_ADMIN)) {
    return true
  }

  // Check direct tenant roles, then group-derived roles
  if (this.hasAnyRole(requiredRoles, tenantRoles)) return true
  const groupRoles = await this.resolveGroupRoles(context, tenantGroupIds)
  return this.hasAnyRole(requiredRoles, groupRoles)
}
```

:::warning System Admin Usage
The `system_admin` role should be assigned sparingly and only to trusted administrators who need full access to all API endpoints. This role bypasses all role-based restrictions.
:::

Now that we have a custom Roles enum, we can use it to any route handler.

```ts
@Post()
@Auth(Role.SYSTEM_ADMIN)
async create(
  @INVOKE_CONTEXT() invokeContext: IInvoke,
  @Body() createCatDto: CreateCatDto,
) {
  return this.catsService.create(createCatDto, { invokeContext })
}
```

Then, we create a helper function that extracts information from the context.

```ts
// Event body example
// {
//     "claims": {
//       "cognito:username": "9999#admin",
//       "auth_time": 1717576015,
//       "email_verified": false,
//       "event_id": "b6642f6e-baf7-4a83-a912-ad559a87c327",
//       "iat": 1717576015,
//       "jti": "ee7bef16-0ea5-451a-a715-7e8baf1e6cdc",
//       "sub": "92ca4f68-9ac6-4080-9ae2-2f02a86206a4",
//       "token_use": "id",
//       "custom:tenant": "9999",
//       "custom:company_code": "999900000",
//       "custom:member_id": "MEMBER#9999#9999000000#99999",
//       "custom:roles": "[{\"tenant\":\"\",\"role\":\"user\"},{\"tenant\":\"9999\",\"role\":\"admin\"}]",
//       "exp": 1717662415,
//       "aud": "dnk8y7ii3wled35p3lw0l2cd7",
//       "iss": "http://localhost:9229/local_2G7noHgW"
//     }
//   }
import {
  extractInvokeContext,
  getAuthorizerClaims,
  getUserContext,
  HEADER_TENANT_CODE,
  IInvoke,
  UserContext,
} from "@mbc-cqrs-serverless/core";
import { ExecutionContext } from "@nestjs/common";
```

:::tip

The `getUserContext` function is provided by `@mbc-cqrs-serverless/core`. It automatically extracts `tenantCode` from `custom:tenant` claim and determines `tenantRole` by matching the tenant in the `custom:roles` JSON array.

:::

:::danger Tenant Code Normalization - Breaking Change
The `tenantCode` returned by `getUserContext()` is normalized to lowercase for case-insensitive matching. For example, `TenantA`, `TENANTA`, and `tenanta` are all returned as `tenanta`. This ensures consistent matching with `role.tenant` values in the `custom:roles` claim.

**Impact on partition keys:** Since tenant codes are typically included in partition keys (e.g., `PRODUCT#tenantCode`), this normalization affects data access. If your existing data uses uppercase tenant codes in keys, queries will fail to find that data.

**See also:** [Tenant Code Normalization Migration](/docs/data-migration-patterns#tenant-code-normalization-migration) for migration strategies.
:::

If you need custom logic, you can implement your own helper function:

```ts
import {
  extractInvokeContext,
  getAuthorizerClaims,
  HEADER_TENANT_CODE,
  IInvoke,
  CustomRole,
} from "@mbc-cqrs-serverless/core";
import { ExecutionContext } from "@nestjs/common";

interface UserContext {
  userId: string;
  tenantRole: string;
  tenantCode: string;
}

export const getCustomUserContext = (
  ctx: IInvoke | ExecutionContext
): UserContext => {
  if ("getHandler" in ctx) {
    ctx = extractInvokeContext(ctx);
  }
  const claims = getAuthorizerClaims(ctx);

  const userId = claims.sub;
  // Normalize tenant code to lowercase for case-insensitive matching
  const tenantCode = (
    claims["custom:tenant"] ||
    (ctx?.event?.headers || {})[HEADER_TENANT_CODE]
  )?.toLowerCase();

  // Parse roles from JSON array and find matching tenant role
  const roles = (
    JSON.parse(claims["custom:roles"] || "[]") as CustomRole[]
  ).map((role) => ({ ...role, tenant: (role.tenant || "").toLowerCase() }));

  let tenantRole = "";
  for (const { tenant, role } of roles) {
    if (tenant === "" || tenant === tenantCode) {
      tenantRole = role;
      if (tenant !== "") {
        break;
      }
    }
  }

  return {
    userId,
    tenantRole,
    tenantCode,
  };
};
```

Finally, we create a CustomRoleGuard class which will compare the roles assigned to the current user to the actual roles required by the current route being processed.

```ts
import { RolesGuard } from "@mbc-cqrs-serverless/core";
import { ExecutionContext, Injectable } from "@nestjs/common";

import { getCustomUserContext } from "./user.context";

@Injectable()
export class CustomRoleGuard extends RolesGuard {
  protected async verifyTenant(context: ExecutionContext): Promise<boolean> {
    const userContext = getCustomUserContext(context);

    return !!userContext.tenantCode;
  }
}
```

## Group-Based Roles {#group-based-roles}

:::info Version Note
Group-based role authorization (`@GroupRoleResolver`, the `custom:groups` claim, and `UserContext.tenantRoles` / `tenantGroupIds`) was added in [version 1.3.1](/docs/changelog#v131).
:::

`RolesGuard` resolves a user's effective roles in two steps:

1. **Direct roles** — read from the JWT `custom:roles` claim for the active tenant.
2. **Group-derived roles** — if the direct roles do not satisfy the required roles, the guard resolves roles from the user's groups listed in the `custom:groups` claim (tenant-scoped).

The mapping from a group to its roles is **not** stored in the JWT. Your application provides it by implementing a resolver.

### JWT Claims

```json
{
  "custom:roles": "[{\"tenant\":\"tenant-a\",\"role\":\"admin\"}]",
  "custom:groups": "[{\"tenant\":\"tenant-a\",\"groups\":[\"sales-team\"]}]"
}
```

`getUserContext()` exposes these as `tenantRoles` (the direct roles array) and `tenantGroupIds` (the group IDs for the active tenant). The singular `tenantRole` is kept for backward compatibility.

### Implementing a Resolver

Implement exactly **one** resolver per application and register it in your module `providers`. `AuthModule` is imported automatically via `AppModule.forRoot()`.

```typescript
import {
  GroupRoleResolver,
  IGroupRoleResolver,
  ResolveGroupRolesInput,
} from "@mbc-cqrs-serverless/core";

// Do not add @Injectable() — @GroupRoleResolver() already registers a singleton provider
@GroupRoleResolver()
export class AppGroupRoleResolver implements IGroupRoleResolver {
  async resolveRoles({
    tenantCode,
    groupIds,
    claims,
  }: ResolveGroupRolesInput): Promise<string[]> {
    // Map the user's group IDs to roles for this tenant (DynamoDB/RDS/config)
    return [];
  }
}
```

:::warning Resolver Guidelines
- **Singleton only** — the resolver is resolved once at bootstrap; do not use `REQUEST`/`TRANSIENT` scope. Adding `@Injectable()` on the same class can override the scope and break bootstrap.
- **Let failures propagate** — a resolver error surfaces as a 5xx, not a silent 403, so a backend outage is distinguishable from a genuine access denial. Do not catch-and-grant.
- **Case-sensitive roles** — keep the role casing in `custom:roles` consistent with your `@Roles(...)` values.
:::

## Tenant Verification {#tenant-verification}

The `RolesGuard` includes extensible methods for tenant verification, allowing you to customize cross-tenant access behavior.

:::info Version Note
Extensible tenant verification methods were added in [version 1.1.0](/docs/changelog#v110).
:::

### Built-in Methods

The following protected methods can be overridden to customize tenant verification:

| Method | Description | Default Behavior |
|------------|-----------------|----------------------|
| `isHeaderOverride()` | Detect if tenant code comes from header | Returns true when `custom:tenant` is absent from the JWT and a tenant code is present |
| `canOverrideTenant()` | Check if user can override tenant | Returns true for common tenant codes, or for users with a cross-tenant role (e.g., system_admin) |
| `getCommonTenantCodes()` | Get list of common tenant codes | Returns common or value from COMMON_TENANT_CODES env var |
| `getCrossTenantRoles()` | Get roles that can access cross-tenant | Returns system_admin or value from CROSS_TENANT_ROLES env var |

### Security: Tenant Code Header Override {#tenant-code-header-security}

By default, only users with the `system_admin` role can override the tenant code via the `x-tenant-code` header. This prevents unauthorized cross-tenant access.

```ts
// Default behavior in RolesGuard
protected canOverrideTenant(context: ExecutionContext, userContext: UserContext): boolean {
  // Allow access to common tenant codes (e.g., 'common')
  if (this.getCommonTenantCodes().includes(userContext.tenantCode)) {
    return true;
  }
  // Allow users with cross-tenant roles (e.g., system_admin)
  return this.getCrossTenantRoles().includes(userContext.tenantRole);
}
```

:::warning Security Note
In versions prior to v1.1.0, users without a `custom:tenant` Cognito attribute could specify any tenant via the `x-tenant-code` header, potentially accessing data from other tenants. This security issue has been fixed in v1.1.0.
:::

### Environment Variable Configuration

You can configure common tenant codes and cross-tenant roles via environment variables:

```bash
# Comma-separated list of common tenant codes
COMMON_TENANT_CODES=common,shared,global

# Comma-separated list of roles that can access cross-tenant data
CROSS_TENANT_ROLES=system_admin,general_manager
```

### Custom Implementation Example

To implement custom cross-tenant access logic, extend `RolesGuard` and override the relevant methods:

```ts
import { RolesGuard, getUserContext, UserContext } from "@mbc-cqrs-serverless/core";
import { ExecutionContext, Injectable } from "@nestjs/common";

@Injectable()
export class CustomRolesGuard extends RolesGuard {
  // Allow additional roles to access cross-tenant data
  protected getCrossTenantRoles(): string[] {
    return ['system_admin', 'regional_manager', 'auditor'];
  }

  // Add custom common tenant codes
  protected getCommonTenantCodes(): string[] {
    return ['common', 'shared', 'template'];
  }

  // Custom logic for tenant override permission
  protected canOverrideTenant(context: ExecutionContext, userContext: UserContext): boolean {
    // Allow specific users to override tenant
    if (userContext.tenantRole === 'regional_manager') {
      // Regional managers can only access tenants in their region
      return this.isRegionalManagerForTenant(userContext, context);
    }

    return super.canOverrideTenant(context, userContext);
  }

  private isRegionalManagerForTenant(userContext: UserContext, context: ExecutionContext): boolean {
    // Custom logic to verify regional access
    // ...
  }
}
```


## Related Documentation

- [Security Best Practices](/docs/security-best-practices) - Security implementation guidelines
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant-based access control
- [Controllers](/docs/controllers) - Authentication decorators for controllers
- [Environment Variables](/docs/environment-variables) - Cognito configuration variables
- [Common Issues — GroupRoleResolver DI conflict](/docs/common-issues#authentication-errors) - Troubleshooting AP027
- [Interfaces — IGroupRoleResolver](/docs/interfaces#authorization-interfaces) - TypeScript interface reference
- [Helpers](/docs/helpers) - getUserContext and context helper functions


---

## Security Best Practices

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/security-best-practices

# Security Best Practices

This guide covers security best practices for building secure applications with MBC CQRS Serverless, including input validation, authentication, authorization, and data protection.

## Input Validation {#input-validation}

### Validate All Input

Always validate input at the API boundary using class-validator decorators.

```typescript
import {
  IsNotEmpty,
  IsString,
  IsEmail,
  IsOptional,
  MaxLength,
  MinLength,
  Matches,
  IsNumber,
  Min,
  Max,
  ValidateNested,
  IsArray,
  ArrayMaxSize,
} from 'class-validator';
import { Type } from 'class-transformer';

export class OrderItemDto {
  @IsNotEmpty()
  @IsString()
  productId: string;

  @IsNumber()
  @Min(1)
  quantity: number;
}

export class CreateOrderDto {
  @IsNotEmpty()
  @IsString()
  @MaxLength(100)
  @Matches(/^[a-zA-Z0-9\s\-]+$/, {
    message: 'Name contains invalid characters',
  })
  name: string;

  @IsNotEmpty()
  @IsString()
  @Matches(/^[A-Z0-9\-]+$/, {
    message: 'Code must be uppercase alphanumeric with hyphens',
  })
  @MaxLength(50)
  code: string;

  @IsOptional()
  @IsEmail()
  customerEmail?: string;

  @IsNumber()
  @Min(0)
  @Max(1000000)
  amount: number;

  @IsOptional()
  @IsArray()
  @ArrayMaxSize(100)
  @ValidateNested({ each: true })
  @Type(() => OrderItemDto)
  items?: OrderItemDto[];
}
```

### Sanitize String Input

Prevent XSS and injection attacks by sanitizing string input.

```typescript
import { Transform } from 'class-transformer';
import * as sanitizeHtml from 'sanitize-html';

export class CommentDto {
  @IsString()
  @MaxLength(1000)
  @Transform(({ value }) => sanitizeHtml(value, {
    allowedTags: [],  // Strip all HTML
    allowedAttributes: {},
  }))
  content: string;

  @IsString()
  @MaxLength(500)
  @Transform(({ value }) => sanitizeHtml(value, {
    allowedTags: ['b', 'i', 'em', 'strong'],  // Allow basic formatting
    allowedAttributes: {},
  }))
  description: string;
}
```

### Code Injection Prevention {#code-injection}

Never use dynamic code execution constructs or build shell commands from user-controlled strings. These patterns are flagged as AP022 and AP023 by the MCP anti-pattern checker.

**Avoid `eval()` and `new Function()`**:

```typescript
// Forbidden — executes arbitrary code from user input
const result = eval(userInput);
const fn = new Function('return ' + userInput)();

// Safe — use a fixed dispatch table instead
const OPERATIONS: Record<string, (a: number, b: number) => number> = {
  add: (a, b) => a + b,
  subtract: (a, b) => a - b,
};
const op = OPERATIONS[userInput]; // Look up only — never eval
if (!op) throw new BadRequestException('Unknown operation');
const result = op(1, 2);
```

**Avoid shell commands built from string concatenation**:

```typescript
import { execSync } from 'child_process';

// Forbidden — shell injection risk when userInput contains special characters
const output = execSync(`ls ${userInput}`);

// Safe — use AWS SDK or fixed commands; never interpolate user input into shell strings
import { S3Client, ListObjectsV2Command } from '@aws-sdk/client-s3';
const client = new S3Client({});
await client.send(new ListObjectsV2Command({ Bucket: 'my-bucket', Prefix: sanitizedPrefix }));
```

### Validate File Uploads

Restrict file types, sizes, and scan for malware.

```typescript
import { BadRequestException } from '@nestjs/common';
import FileType from 'file-type'; // npm install file-type

// Validate file type and size
const ALLOWED_MIME_TYPES = [
  'image/jpeg',
  'image/png',
  'application/pdf',
  'text/csv',
];
const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB

async function validateUpload(file: Express.Multer.File): Promise<void> {
  // Check MIME type
  if (!ALLOWED_MIME_TYPES.includes(file.mimetype)) {
    throw new BadRequestException('File type not allowed');
  }

  // Check file size
  if (file.size > MAX_FILE_SIZE) {
    throw new BadRequestException('File too large');
  }

  // Verify file signature (magic bytes)
  const fileType = await FileType.fromBuffer(file.buffer);
  if (!fileType || !ALLOWED_MIME_TYPES.includes(fileType.mime)) {
    throw new BadRequestException('Invalid file content');
  }
}
```

## Authentication {#authentication}

### Configure Cognito Securely

Use strong password policies and MFA.

```typescript
// CDK configuration for Cognito User Pool
const userPool = new cognito.UserPool(this, 'UserPool', {
  selfSignUpEnabled: false,  // Disable self-registration if not needed
  signInAliases: {
    email: true,
    username: false,
  },
  passwordPolicy: {
    minLength: 12,
    requireLowercase: true,
    requireUppercase: true,
    requireDigits: true,
    requireSymbols: true,
    tempPasswordValidity: Duration.days(7),
  },
  mfa: cognito.Mfa.REQUIRED,
  mfaSecondFactor: {
    sms: true,
    otp: true,
  },
  accountRecovery: cognito.AccountRecovery.EMAIL_ONLY,
  advancedSecurityMode: cognito.AdvancedSecurityMode.ENFORCED,
});
```

:::info Default Implementation Note
The default implementation uses `minLength: 6` for development convenience. For production environments, we strongly recommend using at least 12 characters as shown above, along with MFA enabled.
:::

### Validate JWT Tokens

Always validate JWT tokens on the server side.

```typescript
import { Injectable, CanActivate, ExecutionContext, UnauthorizedException } from '@nestjs/common';
import { CognitoJwtVerifier } from 'aws-jwt-verify';

@Injectable()
export class JwtAuthGuard implements CanActivate {
  private verifier: CognitoJwtVerifier;

  constructor() {
    this.verifier = CognitoJwtVerifier.create({
      userPoolId: process.env.COGNITO_USER_POOL_ID,
      tokenUse: 'access',
      clientId: process.env.COGNITO_USER_POOL_CLIENT_ID,
    });
  }

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = this.extractToken(request);

    if (!token) {
      throw new UnauthorizedException('Missing token');
    }

    try {
      const payload = await this.verifier.verify(token);
      request.user = payload;
      return true;
    } catch (error) {
      throw new UnauthorizedException('Invalid token');
    }
  }

  private extractToken(request: any): string | null {
    const authHeader = request.headers.authorization;
    if (!authHeader?.startsWith('Bearer ')) {
      return null;
    }
    return authHeader.substring(7);
  }
}
```

### Token Refresh Strategy

Implement secure token refresh without storing refresh tokens on client.

```typescript
// Frontend token refresh
async function refreshTokenIfNeeded(): Promise<string> {
  try {
    const session = await Auth.currentSession();
    return session.getAccessToken().getJwtToken();
  } catch (error) {
    if (error.name === 'NotAuthorizedException') {
      // Redirect to login
      await Auth.signOut();
      throw new Error('Session expired');
    }
    throw error;
  }
}
```

## Authorization {#authorization}

### Implement Role-Based Access Control

Use the framework's `@Auth` decorator, which applies `RolesGuard` and checks the roles carried in the `custom:roles` JWT claim (and group-derived roles from `custom:groups`). See [Authentication](/docs/authentication) for the full role model.

```typescript
import { Controller, Get } from '@nestjs/common';
import { Auth, ROLE_SYSTEM_ADMIN } from '@mbc-cqrs-serverless/core';

// Usage in controller
@Controller('admin')
export class AdminController {
  @Get('users')
  @Auth(ROLE_SYSTEM_ADMIN)
  findAllUsers() {
    // Only users holding the required role can access
  }
}
```

:::warning AP027: GroupRoleResolver + @Injectable() Conflict
When implementing group-based role resolution (v1.3.1+), **do not annotate your resolver class with both `@GroupRoleResolver()` and `@Injectable()`**. `@GroupRoleResolver()` already registers the class as a singleton provider — adding `@Injectable()` creates a conflicting second registration that causes a NestJS DI error at startup.

```typescript
// ❌ Wrong — AP027 anti-pattern
@Injectable()
@GroupRoleResolver()
export class MyGroupRoleResolver implements IGroupRoleResolver { ... }

// ✅ Correct — only @GroupRoleResolver()
@GroupRoleResolver()
export class MyGroupRoleResolver implements IGroupRoleResolver { ... }
```

See [Group-Based Roles](/docs/authentication#group-based-roles) for implementation details and [Common Issues](/docs/common-issues#authentication-errors) for troubleshooting.
:::

### Enforce Tenant Isolation

Always derive the tenant code from the verified JWT via `getUserContext()` — never from request parameters or the request body. The framework's `RolesGuard` verifies tenant access (including the `x-tenant-code` header override for common tenants).

```typescript
import { Get } from '@nestjs/common';
import {
  getUserContext,
  IInvoke,
  INVOKE_CONTEXT,
} from '@mbc-cqrs-serverless/core';

@Get('orders')
async listOrders(@INVOKE_CONTEXT() invokeContext: IInvoke) {
  // The tenant code comes from the verified token, not from user input
  const { tenantCode } = getUserContext(invokeContext);
  return this.orderService.listOrders(tenantCode);
}

// Always include tenant in queries
async function getOrdersByTenant(invokeContext: IInvoke) {
  const { tenantCode } = getUserContext(invokeContext);

  // Tenant is always part of the partition key
  return this.dataService.listItemsByPk(`ORDER#${tenantCode}`);
}
```

### Resource-Level Authorization

Check ownership before allowing operations.

```typescript
import { NotFoundException, ForbiddenException } from '@nestjs/common';
import { getUserContext, IInvoke, ROLE_SYSTEM_ADMIN } from '@mbc-cqrs-serverless/core';

// In a service class with dataService and commandService injected
async updateOrder(
  pk: string,   // e.g., 'ORDER#tenant-a'
  sk: string,   // e.g., 'order-123'
  updates: UpdateOrderDto,
  invokeContext: IInvoke,
): Promise<CommandModel | null> {
  // Derive user identity from verified JWT — never from request parameters
  const { userId, tenantRoles } = getUserContext(invokeContext);
  const order = await this.dataService.getItem({ pk, sk });

  if (!order) {
    throw new NotFoundException('Order not found');
  }

  // Check ownership — allow system_admin to bypass
  const isAdmin = tenantRoles.includes(ROLE_SYSTEM_ADMIN);
  if (order.createdBy !== userId && !isAdmin) {
    throw new ForbiddenException('Not authorized to update this order');
  }

  return this.commandService.publishPartialUpdateSync({
    pk: order.pk,
    sk: order.sk,
    version: order.version,
    ...updates,
  }, { invokeContext });
}
```

## Data Protection {#data-protection}

### Encrypt Sensitive Data

Encrypt sensitive data before storing.

```typescript
import * as crypto from 'crypto';

const ENCRYPTION_KEY = process.env.ENCRYPTION_KEY; // 32 bytes for AES-256
const IV_LENGTH = 16;

function encrypt(text: string): string {
  const iv = crypto.randomBytes(IV_LENGTH);
  const cipher = crypto.createCipheriv(
    'aes-256-gcm',
    Buffer.from(ENCRYPTION_KEY, 'hex'),
    iv,
  );

  let encrypted = cipher.update(text, 'utf8', 'hex');
  encrypted += cipher.final('hex');

  const authTag = cipher.getAuthTag();

  return `${iv.toString('hex')}:${authTag.toString('hex')}:${encrypted}`;
}

function decrypt(encryptedText: string): string {
  const [ivHex, authTagHex, encrypted] = encryptedText.split(':');

  const decipher = crypto.createDecipheriv(
    'aes-256-gcm',
    Buffer.from(ENCRYPTION_KEY, 'hex'),
    Buffer.from(ivHex, 'hex'),
  );

  decipher.setAuthTag(Buffer.from(authTagHex, 'hex'));

  let decrypted = decipher.update(encrypted, 'hex', 'utf8');
  decrypted += decipher.final('utf8');

  return decrypted;
}

// Usage
const sensitiveData = {
  ssn: encrypt('123-45-6789'),
  creditCard: encrypt('4111111111111111'),
};
```

### Mask Sensitive Data in Logs

Never log sensitive information.

```typescript
// Create a logger that masks sensitive fields
const SENSITIVE_FIELDS = ['password', 'token', 'ssn', 'creditCard', 'secret'];

function maskSensitiveData(obj: any): any {
  if (!obj || typeof obj !== 'object') {
    return obj;
  }

  const masked = Array.isArray(obj) ? [...obj] : { ...obj };

  for (const key of Object.keys(masked)) {
    if (SENSITIVE_FIELDS.some(field =>
      key.toLowerCase().includes(field.toLowerCase())
    )) {
      masked[key] = '***MASKED***';
    } else if (typeof masked[key] === 'object') {
      masked[key] = maskSensitiveData(masked[key]);
    }
  }

  return masked;
}

// Usage
console.log('Request:', maskSensitiveData(requestBody));
```

:::warning
Never log `process.env` or a full HTTP request/event object. `process.env` exposes every environment variable (including secrets and API keys) to the log stream. A full request object exposes all headers including the `Authorization` token. This is detected as AP025 by the MCP anti-pattern checker.

```typescript
// Forbidden — leaks all secrets in process.env and request auth headers
this.logger.debug('Env:', process.env);
this.logger.debug('Request:', event);

// Safe — log only specific, non-sensitive fields
this.logger.debug('App:', { name: process.env.APP_NAME, env: process.env.NODE_ENV });
this.logger.debug('Request:', { path: event.rawPath, method: event.requestContext?.http?.method });
```
:::

### Secure Environment Variables

Use AWS Secrets Manager for sensitive configuration.

```typescript
import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from '@aws-sdk/client-secrets-manager';

const secretsClient = new SecretsManagerClient({});

async function getSecret(secretName: string): Promise<Record<string, string>> {
  const command = new GetSecretValueCommand({ SecretId: secretName });
  const response = await secretsClient.send(command);

  if (response.SecretString) {
    return JSON.parse(response.SecretString);
  }

  throw new Error('Secret not found');
}

// Cache secrets to avoid repeated API calls
let cachedSecrets: Record<string, string> | null = null;

async function getDatabasePassword(): Promise<string> {
  if (!cachedSecrets) {
    cachedSecrets = await getSecret('myapp/database');
  }
  return cachedSecrets.password;
}
```

## API Security {#api-security}

### Rate Limiting

Implement rate limiting to prevent abuse.

```typescript
// API Gateway throttling in serverless.yml
provider:
  apiGateway:
    throttling:
      burstLimit: 200
      rateLimit: 100

// Per-function throttling
functions:
  createOrder:
    handler: handler.createOrder
    events:
      - http:
          path: orders
          method: post
          throttling:
            burstLimit: 10
            rateLimit: 5
```

### CORS Configuration

Configure CORS strictly.

```typescript
// serverless.yml
provider:
  httpApi:
    cors:
      allowedOrigins:
        - https://myapp.example.com
        - https://admin.example.com
      allowedHeaders:
        - Content-Type
        - Authorization
        - X-Request-Id
      allowedMethods:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS
      maxAge: 3600
```

:::info Default Implementation Note
The default implementation uses `allowedOrigins: ['*']` for development convenience. For production environments, you should always restrict allowed origins to specific domains as shown above to prevent cross-site request forgery (CSRF) attacks.
:::

### Request Size Limits

Limit request payload size to prevent DoS.

```typescript
// API Gateway payload limit in serverless.yml
provider:
  apiGateway:
    binaryMediaTypes:
      - 'application/octet-stream'
    maximumPayloadSize: 10485760  # 10MB

// Application-level validation
@Post('upload')
@UseInterceptors(
  FileInterceptor('file', {
    limits: {
      fileSize: 10 * 1024 * 1024,  // 10MB
    },
  }),
)
async uploadFile(@UploadedFile() file: Express.Multer.File) {
  // Process file
}
```

## Infrastructure Security {#infrastructure-security}

### Least Privilege IAM Policies

Grant only necessary permissions to Lambda functions.

```yaml
# serverless.yml
provider:
  iam:
    role:
      statements:
        # DynamoDB access - specific tables only
        - Effect: Allow
          Action:
            - dynamodb:GetItem
            - dynamodb:PutItem
            - dynamodb:UpdateItem
            - dynamodb:Query
          Resource:
            - !GetAtt OrderTable.Arn
            - !Sub '${OrderTable.Arn}/index/*'

        # S3 access - specific bucket and prefix
        - Effect: Allow
          Action:
            - s3:GetObject
            - s3:PutObject
          Resource:
            - !Sub 'arn:aws:s3:::${UploadBucket}/uploads/*'

        # Secrets Manager - specific secrets only
        - Effect: Allow
          Action:
            - secretsmanager:GetSecretValue
          Resource:
            - !Sub 'arn:aws:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:myapp/*'
```

### VPC Configuration

Deploy Lambda functions in VPC for database access.

```yaml
# serverless.yml
provider:
  vpc:
    securityGroupIds:
      - !Ref LambdaSecurityGroup
    subnetIds:
      - !Ref PrivateSubnet1
      - !Ref PrivateSubnet2

resources:
  Resources:
    LambdaSecurityGroup:
      Type: AWS::EC2::SecurityGroup
      Properties:
        GroupDescription: Lambda security group
        VpcId: !Ref VPC
        SecurityGroupEgress:
          - IpProtocol: tcp
            FromPort: 443
            ToPort: 443
            CidrIp: 0.0.0.0/0  # HTTPS outbound only
          - IpProtocol: tcp
            FromPort: 5432
            ToPort: 5432
            DestinationSecurityGroupId: !Ref RDSSecurityGroup
```

### Enable AWS CloudTrail

Log all API calls for audit.

```typescript
// CDK configuration
const trail = new cloudtrail.Trail(this, 'AuditTrail', {
  bucket: auditBucket,
  sendToCloudWatchLogs: true,
  cloudWatchLogsRetention: logs.RetentionDays.ONE_YEAR,
  includeGlobalServiceEvents: true,
  isMultiRegionTrail: true,
});

// Log specific events
trail.addEventSelector(cloudtrail.DataResourceType.DYNAMODB_TABLE, [
  `arn:aws:dynamodb:${this.region}:${this.account}:table/*`,
]);
```

## Security Checklist {#security-checklist}

### Pre-Deployment

- [ ] All input is validated with class-validator
- [ ] Sensitive data is encrypted at rest
- [ ] JWT token validation is implemented
- [ ] Role-based access control is configured
- [ ] Tenant isolation is enforced
- [ ] Rate limiting is configured
- [ ] CORS is configured strictly
- [ ] IAM policies follow least privilege
- [ ] Secrets are stored in Secrets Manager
- [ ] VPC is configured for database access

### Post-Deployment

- [ ] CloudTrail is enabled
- [ ] CloudWatch alarms are configured
- [ ] Security groups are reviewed
- [ ] API Gateway throttling is verified
- [ ] Penetration testing is completed

## Related Documentation

- [Authentication](/docs/authentication) - Cognito authentication and JWT setup
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant isolation and access control
- [Error Catalog](/docs/error-catalog) - Security-related error codes
- [Monitoring and Logging](/docs/monitoring-logging) - Security event monitoring
- [Environment Variables](/docs/environment-variables) - Secret and credential configuration
- [Anti-Patterns](/docs/anti-patterns) - Common security mistakes to avoid


---

# Deployment & Operations

## CI/CD with CodePipeline

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/codepipeline-cicd

# CI/CD with CodePipeline

This guide explains how to set up a CI/CD pipeline using AWS CodePipeline for your MBC CQRS Serverless application.

## Overview {#overview}

AWS CodePipeline automates your build, test, and deployment workflow. A typical pipeline consists of:

1. **Source Stage**: Pulls code from your repository
2. **Build Stage**: Runs tests and builds the application
3. **Deploy Stage**: Deploys to AWS using CDK/CloudFormation

```mermaid
graph LR
    A[Source] --> B[Build]
    B --> C[Test]
    C --> D[Deploy Dev]
    D --> E[Approval]
    E --> F[Deploy Prod]
```

## Prerequisites {#prerequisites}

- AWS account with CodePipeline, CodeBuild permissions
- Source repository (GitHub, CodeCommit, or Bitbucket)
- AWS CDK project configured

## Pipeline Stack with CDK {#pipeline-stack}

### Create Pipeline Stack

Create a CDK stack for your pipeline in `infra/libs/pipeline-stack.ts`:

```typescript
import * as cdk from 'aws-cdk-lib';
import * as codepipeline from 'aws-cdk-lib/aws-codepipeline';
import * as codepipeline_actions from 'aws-cdk-lib/aws-codepipeline-actions';
import * as codebuild from 'aws-cdk-lib/aws-codebuild';
import { Construct } from 'constructs';

export interface PipelineStackProps extends cdk.StackProps {
  repositoryName: string;
  branchName: string;
  connectionArn: string;
}

export class PipelineStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: PipelineStackProps) {
    super(scope, id, props);

    // Source artifact
    const sourceOutput = new codepipeline.Artifact();

    // Build artifact
    const buildOutput = new codepipeline.Artifact();

    // CodeBuild project
    const buildProject = new codebuild.PipelineProject(this, 'BuildProject', {
      environment: {
        buildImage: codebuild.LinuxBuildImage.STANDARD_7_0,
        computeType: codebuild.ComputeType.MEDIUM,
      },
      buildSpec: codebuild.BuildSpec.fromSourceFilename('buildspec.yml'),
    });

    // Pipeline
    const pipeline = new codepipeline.Pipeline(this, 'Pipeline', {
      pipelineName: `${props.repositoryName}-pipeline`,
      stages: [
        {
          stageName: 'Source',
          actions: [
            new codepipeline_actions.CodeStarConnectionsSourceAction({
              actionName: 'GitHub_Source',
              owner: 'your-org',
              repo: props.repositoryName,
              branch: props.branchName,
              connectionArn: props.connectionArn,
              output: sourceOutput,
            }),
          ],
        },
        {
          stageName: 'Build',
          actions: [
            new codepipeline_actions.CodeBuildAction({
              actionName: 'Build',
              project: buildProject,
              input: sourceOutput,
              outputs: [buildOutput],
            }),
          ],
        },
        {
          stageName: 'Deploy',
          actions: [
            new codepipeline_actions.CloudFormationCreateUpdateStackAction({
              actionName: 'Deploy',
              stackName: `${props.repositoryName}-app`,
              templatePath: buildOutput.atPath('cdk.out/AppStack.template.json'),
              adminPermissions: true,
            }),
          ],
        },
      ],
    });
  }
}
```

## BuildSpec Configuration {#buildspec-configuration}

### Basic buildspec.yml

Create a `buildspec.yml` file in your project root:

```yaml
version: 0.2

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci

  pre_build:
    commands:
      - echo "Running tests..."
      - npm run test
      - npm run lint

  build:
    commands:
      - echo "Building application..."
      - npm run build
      - echo "Synthesizing CDK..."
      - cd infra && npm ci && npx cdk synth

  post_build:
    commands:
      - echo "Build completed on $(date)"

artifacts:
  files:
    - '**/*'
  base-directory: infra

cache:
  paths:
    - node_modules/**/*
    - infra/node_modules/**/*
```

### BuildSpec with Environment Variables

For builds that require environment-specific configuration:

```yaml
version: 0.2

env:
  variables:
    NODE_ENV: production
    ENVIRONMENT: production
  parameter-store:
    DATABASE_URL: /your-app/database-url
  secrets-manager:
    API_KEY: your-app-secrets:api-key

phases:
  install:
    runtime-versions:
      nodejs: 20
    commands:
      - npm ci

  build:
    commands:
      - npm run build
      - cd infra && npx cdk synth --context env=$ENVIRONMENT

artifacts:
  files:
    - 'infra/cdk.out/**/*'
```

## Multi-Environment Pipeline {#multi-environment}

### Development and Production Stages

Create a pipeline with separate stages for each environment:

```typescript
const pipeline = new codepipeline.Pipeline(this, 'Pipeline', {
  stages: [
    // Source stage
    { stageName: 'Source', actions: [sourceAction] },

    // Build stage
    { stageName: 'Build', actions: [buildAction] },

    // Deploy to Development
    {
      stageName: 'Deploy_Dev',
      actions: [
        new codepipeline_actions.CloudFormationCreateUpdateStackAction({
          actionName: 'Deploy_Dev',
          stackName: 'myapp-dev',
          templatePath: buildOutput.atPath('cdk.out/DevStack.template.json'),
          adminPermissions: true,
        }),
      ],
    },

    // Manual Approval for Production
    {
      stageName: 'Approval',
      actions: [
        new codepipeline_actions.ManualApprovalAction({
          actionName: 'Approve_Production',
          notifyEmails: ['team@your-company.com'],
        }),
      ],
    },

    // Deploy to Production
    {
      stageName: 'Deploy_Prod',
      actions: [
        new codepipeline_actions.CloudFormationCreateUpdateStackAction({
          actionName: 'Deploy_Prod',
          stackName: 'myapp-prod',
          templatePath: buildOutput.atPath('cdk.out/ProdStack.template.json'),
          adminPermissions: true,
        }),
      ],
    },
  ],
});
```

## GitHub Connection {#github-connection}

### Create CodeStar Connection

To connect GitHub to CodePipeline:

1. Go to AWS Console → Developer Tools → Settings → Connections
2. Click "Create connection"
3. Select "GitHub" as provider
4. Authorize AWS Connector for GitHub
5. Copy the Connection ARN

### Use Connection in CDK

```typescript
const connectionArn = 'arn:aws:codestar-connections:YOUR_REGION:YOUR_ACCOUNT_ID:connection/YOUR_CONNECTION_ID';

new codepipeline_actions.CodeStarConnectionsSourceAction({
  actionName: 'GitHub_Source',
  owner: 'your-org',
  repo: 'your-repo',
  branch: 'main',
  connectionArn: connectionArn,
  output: sourceOutput,
});
```

## Branch-Based Pipelines {#branch-based-pipelines}

### Feature Branch Strategy

Create separate pipelines for different branches:

| Branch | Environment | Auto Deploy |
|------------|-----------------|-----------------|
| `main` | Production | No (approval required) |
| `develop` | Staging | Yes |
| `feature/*` | Development | Yes |

### CDK Pipeline with Branches

```typescript
// Development pipeline
new PipelineStack(app, 'DevPipeline', {
  repositoryName: 'your-app',
  branchName: 'develop',
  connectionArn: connectionArn,
});

// Production pipeline
new PipelineStack(app, 'ProdPipeline', {
  repositoryName: 'your-app',
  branchName: 'main',
  connectionArn: connectionArn,
});
```

## Notifications {#notifications}

### SNS Notifications

Add pipeline notifications:

```typescript
import * as sns from 'aws-cdk-lib/aws-sns';
import * as notifications from 'aws-cdk-lib/aws-codestarnotifications';

const topic = new sns.Topic(this, 'PipelineNotifications');

new notifications.NotificationRule(this, 'PipelineNotificationRule', {
  source: pipeline,
  events: [
    'codepipeline-pipeline-pipeline-execution-failed',
    'codepipeline-pipeline-pipeline-execution-succeeded',
  ],
  targets: [topic],
});
```

## Best Practices {#best-practices}

### Security

- Use IAM roles with least privilege
- Store secrets in Secrets Manager or Parameter Store
- Enable encryption for artifacts
- Use VPC for CodeBuild if accessing private resources

### Performance

- Cache dependencies in CodeBuild
- Use appropriate compute types
- Parallelize independent actions

### Reliability

- Add health checks after deployment
- Implement rollback strategies
- Use blue-green or canary deployments for production

## Troubleshooting {#troubleshooting}

### Common Issues

| Issue | Solution |
|-----------|--------------|
| Source connection failed | Verify CodeStar connection is in "Available" status |
| Build timeout | Increase timeout in CodeBuild project settings |
| Permission denied | Check IAM roles have required permissions |
| Artifact not found | Verify buildspec artifacts configuration |

### Viewing Logs

CodeBuild logs are available in CloudWatch Logs:

```bash
aws logs tail /aws/codebuild/your-build-project --follow
```

## Related Documentation

- [Deployment Guide](/docs/deployment-guide) - Manual deployment options
- [Monitoring and Logging](/docs/monitoring-logging) - Set up observability
- [Environment Variables](/docs/environment-variables) - CI/CD environment configuration
- [Testing](/docs/testing) - Testing setup for CI pipeline


---

## Deployment Guide

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/deployment-guide

# Deployment Guide

This guide covers deploying your MBC CQRS Serverless application to AWS using AWS CDK.

## Prerequisites {#prerequisites}

Before deploying, ensure you have:

- AWS CLI installed and configured with appropriate credentials
- Node.js 20.x or later
- AWS CDK CLI installed (`npm install -g aws-cdk`)
- An AWS account with necessary permissions

## AWS Account Preparation {#aws-account-preparation}

### Required AWS Services

Your application will use the following AWS services:

- API Gateway - HTTP API endpoints
- Lambda - Serverless compute
- DynamoDB - NoSQL database
- RDS (MySQL) - Relational database (optional)
- Cognito - User authentication
- S3 - File storage
- SQS/SNS - Message queuing
- Step Functions - Workflow orchestration
- CloudWatch - Logging and monitoring

### IAM Permissions

The deploying user/role needs permissions for:

- CloudFormation (full access)
- Lambda, API Gateway, DynamoDB, S3, SQS, SNS, Step Functions
- IAM (for creating roles)
- CloudWatch Logs
- VPC (if using RDS)

## CDK Bootstrap {#cdk-bootstrap}

Before your first deployment, bootstrap CDK in your AWS account:

```bash
cdk bootstrap aws://YOUR_ACCOUNT_ID/YOUR_REGION
```

Example:

```bash
cdk bootstrap aws://123456789012/ap-northeast-1
```

## Environment Configuration {#environment-configuration}

### Create Environment Config

Create environment-specific configuration files in `infra/config/{env}/index.ts`:

```typescript
// infra/config/dev/index.ts
import { ApplicationLogLevel, SystemLogLevel } from 'aws-cdk-lib/aws-lambda';
import { Config } from '../type';

const config: Config = {
  env: 'dev',
  appName: 'your-app',

  // Domain configuration
  domain: {
    http: 'dev-api.your-domain.com',
    appsync: 'dev-appsync.your-domain.com',
  },

  // Existing Cognito User Pool (optional)
  userPoolId: 'ap-northeast-1_xxxxxxx',

  // VPC Configuration
  vpc: {
    id: 'vpc-xxxxxxxxx',
    subnetIds: ['subnet-xxx1', 'subnet-xxx2'],
    securityGroupIds: ['sg-xxxxxxxxx'],
  },

  // RDS Configuration
  rds: {
    accountSsmKey: '/your-app/dev/rds/account',
    endpoint: 'your-rds-endpoint.ap-northeast-1.rds.amazonaws.com',
    dbName: 'your_app_dev',
  },

  // Log Level Configuration
  logLevel: {
    lambdaSystem: SystemLogLevel.DEBUG,
    lambdaApplication: ApplicationLogLevel.TRACE,
    level: 'verbose',
  },

  frontBaseUrl: 'https://dev.your-domain.com',
  fromEmailAddress: 'noreply@your-domain.com',

  // WAF Configuration (optional)
  // wafArn: 'arn:aws:wafv2:ap-northeast-1:YOUR_ACCOUNT_ID:regional/webacl/xxx',
};

export default config;
```

### Environment Variables

Set up environment variables in `.env` or through your CI/CD pipeline:

```bash
# AWS Configuration
AWS_REGION=ap-northeast-1
AWS_ACCOUNT_ID=123456789012

# Application Configuration
APP_NAME=your-app
NODE_ENV=dev

# Database
DATABASE_URL=mysql://user:password@host:3306/dbname

# Cognito
COGNITO_USER_POOL_ID=ap-northeast-1_xxxxxxx
COGNITO_USER_POOL_CLIENT_ID=xxxxxxxxxxxxxxxxxx
```

## CDK Stack Structure {#cdk-stack-structure}

A typical MBC CQRS Serverless CDK project has the following structure:

```text
infra/
├── bin/
│   └── infra.ts              # CDK app entry point
├── cdk.json                  # CDK configuration
├── config/
│   ├── index.ts              # Config exports and getConfig function
│   ├── type.ts               # Config type definitions
│   ├── constant.ts           # Constants (e.g., PIPELINE_NAME)
│   ├── dev/
│   │   └── index.ts          # Development config
│   ├── stg/
│   │   └── index.ts          # Staging config
│   └── prod/
│       └── index.ts          # Production config
└── libs/
    ├── infra-stack.ts        # Main infrastructure stack
    ├── pipeline-stack.ts     # CI/CD pipeline stack
    └── pipeline-infra-stage.ts # Pipeline infrastructure stage
```

## Known Issues and Workarounds {#known-issues}

### npm install Errors with Legacy Dependencies

Some serverless-offline plugins have legacy dependencies that may cause build errors during `npm install`:

```text
npm error path node_modules/zlib
npm error command sh -c node-waf clean || true; node-waf configure build
npm error sh: node-waf: command not found
```

Workaround: Use the `--ignore-scripts` and `--legacy-peer-deps` flags:

```bash
npm install --legacy-peer-deps --ignore-scripts
npx prisma generate  # Run postinstall script manually
```

### CDK Environment Configuration

The default `infra/bin/infra.ts` template may have empty account/region values, causing errors like:

```text
Invalid S3 bucket name (value: cdk-hnb659fds-assets--)
```

The generated `infra/bin/infra.ts` leaves `account` and `region` empty by default — set them explicitly or use the standard CDK environment variables:

```typescript
import * as cdk from 'aws-cdk-lib';

const cdkEnv: cdk.Environment = {
  account: process.env.CDK_DEFAULT_ACCOUNT,
  region: process.env.CDK_DEFAULT_REGION || 'ap-northeast-1',
};
```

When running CDK commands, the AWS profile automatically provides these values:

```bash
AWS_PROFILE=your-profile cdk synth
```

## Deploying with CDK {#deploying-with-cdk}

### Configure Target Environments

The environments to deploy are configured in `infra/bin/infra.ts` by modifying the `envs` array:

```typescript
// infra/bin/infra.ts
const envs: Env[] = ['dev'];  // Add 'stg' or 'prod' as needed
```

To deploy multiple environments, add them to the array:

```typescript
const envs: Env[] = ['dev', 'stg', 'prod'];
```

### Synthesize CloudFormation Template

First, synthesize the CloudFormation template to verify your configuration:

```bash
cd infra
cdk synth
```

### Deploy Stacks

Deploy all configured environment stacks:

```bash
cdk deploy --all
```

Or deploy a specific environment stack (run `cdk ls` first to see all available stack names):

```bash
cdk ls
cdk deploy dev-your-app-pipeline-stack
```

### Deploy with Approval

For deployments that require approval:

```bash
cdk deploy --all --require-approval broadening
```

## Post-Deployment Verification {#post-deployment}

### Check Stack Status

```bash
aws cloudformation describe-stacks --stack-name YourStackName-dev
```

### Verify API Gateway

Get the API endpoint from the CloudFormation outputs:

```bash
aws cloudformation describe-stacks \
  --stack-name YourStackName-dev \
  --query 'Stacks[0].Outputs[?OutputKey==`ApiEndpoint`].OutputValue' \
  --output text
```

### Test the Health Endpoint

```bash
curl https://your-api-endpoint.execute-api.ap-northeast-1.amazonaws.com/health
```

## Multi-Environment Strategy {#multi-environment-strategy}

### Environment Isolation

Best practices for managing multiple environments:

| Aspect | Development | Staging | Production |
|------------|-----------------|-------------|----------------|
| AWS Account | Shared or dedicated | Dedicated | Dedicated |
| VPC | Shared | Dedicated | Dedicated |
| Database | Shared RDS | Dedicated RDS | Multi-AZ RDS |
| Log Level | verbose/debug | info | warn/error |

### Resource Naming Convention

Use consistent naming for resources:

```text
{environment}-{app-name}-{resource-type}
```

Example:
- `dev-myapp-api`
- `dev-myapp-dynamodb-command`
- `prod-myapp-lambda-handler`

## Rollback {#rollback}

### Automatic Rollback

CloudFormation automatically rolls back if deployment fails. To manually rollback:

```bash
aws cloudformation rollback-stack --stack-name YourStackName-dev
```

### Deploy Previous Version

To deploy a previous version, use Git to checkout the desired commit and redeploy:

```bash
git checkout <previous-commit>
cdk deploy --all
```

## Cleanup {#cleanup}

### Destroy Stack

To remove all resources:

```bash
cdk destroy --all
```

Or destroy a specific environment stack:

```bash
cdk destroy dev-your-app-pipeline-stack
```

Note: This will delete all resources including data. Use with caution.

### Selective Cleanup

Some resources may have deletion protection. Disable before destroying:

- DynamoDB tables with deletion protection
- RDS instances with deletion protection
- S3 buckets (must be emptied first)

## Related Documentation

- [CI/CD with CodePipeline](/docs/codepipeline-cicd) - Automate deployments with CodePipeline
- [CDK Infrastructure](/docs/architecture/cdk-infrastructure) - AWS infrastructure architecture details
- [Monitoring and Logging](/docs/monitoring-logging) - Set up observability after deployment
- [Environment Variables](/docs/environment-variables) - Configure environment for deployment
- [Troubleshooting](/docs/common-issues) - Common deployment issues


---

## Monitoring and Logging

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/monitoring-logging

# Monitoring and Logging

This guide covers setting up comprehensive monitoring and logging for MBC CQRS Serverless applications on AWS.

## Overview {#overview}

A complete observability strategy includes:

- **Logging**: Capturing application events and errors
- **Metrics**: Measuring performance and usage
- **Tracing**: Following requests across services
- **Alerting**: Notifying on issues

### Built-in Features

The MBC CQRS Serverless framework provides the following observability features out-of-the-box:

- **RequestLogger**: Extended NestJS logger with context (tenantCode, userId, requestId, sourceIp)
- **AWS X-Ray Tracing**: Enabled by default in the CDK template for Lambda and Step Functions
- **JSON Logging Format**: Lambda functions log in JSON format for easy querying
- **Configurable Log Levels**: Set via LOG_LEVEL environment variable

:::info AWS Services Guidance
The sections below provide guidance on setting up additional AWS CloudWatch features (metrics, dashboards, alarms). These are not built into the framework but are recommended patterns for production deployments.
:::

## CloudWatch Logs {#cloudwatch-logs}

### Lambda Logging

The framework includes a built-in RequestLogger that automatically adds context to your logs:

```typescript
// The framework's RequestLogger is used automatically
// Log output includes: context, requestId, ip, tenantCode, userId

import { Logger, Injectable } from '@nestjs/common';

@Injectable()
export class YourService {
  private readonly logger = new Logger(YourService.name);

  async doSomething() {
    // These logs automatically include user context in Lambda
    this.logger.log('Operation started');
    this.logger.debug('Debug information');
    this.logger.error('Error occurred');
  }
}
```

You can enhance with structured logging for more detailed tracking:

```typescript
import { Logger, Injectable } from '@nestjs/common';
import { getUserContext, IInvoke } from '@mbc-cqrs-serverless/core';

@Injectable()
export class TodoService {
  private readonly logger = new Logger(TodoService.name);

  async create(dto: CreateTodoDto, opts: { invokeContext: IInvoke }): Promise<Todo> {
    const { userId } = getUserContext(opts.invokeContext);
    const startTime = Date.now();
    this.logger.log({
      action: 'create_todo',
      input: dto,
      userId,
    });

    try {
      const result = await this.save(dto);
      this.logger.log({
        action: 'todo_created',
        todoId: result.id,
        duration: Date.now() - startTime,
      });
      return result;
    } catch (error) {
      this.logger.error({
        action: 'create_todo_failed',
        error: error.message,
        stack: error.stack,
      });
      throw error;
    }
  }
}
```

### Log Retention

Configure log retention in CDK:

```typescript
import * as cdk from 'aws-cdk-lib';
import * as logs from 'aws-cdk-lib/aws-logs';

const logGroup = new logs.LogGroup(this, 'AppLogGroup', {
  logGroupName: `/aws/lambda/${props.envName}-${props.appName}`,
  retention: logs.RetentionDays.ONE_MONTH,
  removalPolicy: cdk.RemovalPolicy.DESTROY,
});
```

### Log Format

Recommended log format for easy querying:

```typescript
interface LogEntry {
  timestamp: string;
  level: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR';
  message: string;
  context: string;
  correlationId?: string;
  userId?: string;
  duration?: number;
  error?: {
    name: string;
    message: string;
    stack: string;
  };
  metadata?: Record<string, any>;
}
```

## CloudWatch Metrics {#cloudwatch-metrics}

:::info Implementation Required
Custom metrics are not built into the framework. The following examples show how you can implement custom metrics in your application using the AWS SDK.
:::

### Custom Metrics

Publish custom metrics from your application:

```typescript
import { CloudWatchClient, PutMetricDataCommand } from '@aws-sdk/client-cloudwatch';

const cloudwatch = new CloudWatchClient({});

async function publishMetric(
  metricName: string,
  value: number,
  unit: string = 'Count',
): Promise<void> {
  await cloudwatch.send(new PutMetricDataCommand({
    Namespace: 'YourApp/Custom',
    MetricData: [
      {
        MetricName: metricName,
        Value: value,
        Unit: unit,
        Dimensions: [
          { Name: 'Environment', Value: process.env.ENVIRONMENT },
        ],
      },
    ],
  }));
}

// Usage
await publishMetric('TodosCreated', 1);
await publishMetric('ProcessingTime', 150, 'Milliseconds');
```

### Key Metrics to Monitor

| Category | Metric | Description |
|--------------|------------|-----------------|
| Lambda | `Invocations` | Number of function calls |
| Lambda | `Duration` | Execution time |
| Lambda | `Errors` | Failed invocations |
| Lambda | `ConcurrentExecutions` | Parallel executions |
| API Gateway | `Count` | Request count |
| API Gateway | `Latency` | Response time |
| API Gateway | `4XXError` | Client errors |
| API Gateway | `5XXError` | Server errors |
| DynamoDB | `ConsumedReadCapacity` | Read usage |
| DynamoDB | `ConsumedWriteCapacity` | Write usage |
| DynamoDB | `ThrottledRequests` | Throttled operations |

### CDK Dashboard

:::info CDK Customization
Dashboards are not included in the default CDK template. Add the following to your CDK stack to create a CloudWatch dashboard.
:::

Create a CloudWatch dashboard:

```typescript
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';

const dashboard = new cloudwatch.Dashboard(this, 'AppDashboard', {
  dashboardName: `${props.appName}-${props.envName}`,
});

dashboard.addWidgets(
  new cloudwatch.GraphWidget({
    title: 'Lambda Invocations',
    left: [handler.metricInvocations()],
  }),
  new cloudwatch.GraphWidget({
    title: 'Lambda Duration',
    left: [handler.metricDuration()],
  }),
  new cloudwatch.GraphWidget({
    title: 'Lambda Errors',
    left: [handler.metricErrors()],
  }),
  new cloudwatch.GraphWidget({
    title: 'API Gateway Requests',
    left: [
      api.metricCount(),
      api.metricClientError(),
      api.metricServerError(),
    ],
  }),
);
```

## CloudWatch Alarms {#cloudwatch-alarms}

:::info CDK Customization
Alarms are not included in the default CDK template. Add the following to your CDK stack for production monitoring.
:::

### Create Alarms

Set up alarms for critical metrics:

```typescript
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
import * as sns from 'aws-cdk-lib/aws-sns';
import * as actions from 'aws-cdk-lib/aws-cloudwatch-actions';

// SNS topic for notifications
const alertTopic = new sns.Topic(this, 'AlertTopic');

// Lambda error alarm
const errorAlarm = new cloudwatch.Alarm(this, 'LambdaErrorAlarm', {
  metric: handler.metricErrors(),
  threshold: 5,
  evaluationPeriods: 1,
  alarmDescription: 'Lambda function errors exceed threshold',
  treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
});
errorAlarm.addAlarmAction(new actions.SnsAction(alertTopic));

// High latency alarm
const latencyAlarm = new cloudwatch.Alarm(this, 'LatencyAlarm', {
  metric: handler.metricDuration({
    statistic: 'p99',
  }),
  threshold: 5000, // 5 seconds
  evaluationPeriods: 3,
  alarmDescription: 'P99 latency exceeds 5 seconds',
});
latencyAlarm.addAlarmAction(new actions.SnsAction(alertTopic));

// DynamoDB throttling alarm
const throttleAlarm = new cloudwatch.Alarm(this, 'ThrottleAlarm', {
  metric: table.metricThrottledRequests(),
  threshold: 1,
  evaluationPeriods: 1,
  alarmDescription: 'DynamoDB throttling detected',
});
throttleAlarm.addAlarmAction(new actions.SnsAction(alertTopic));
```

### Recommended Alarms

| Alarm | Metric | Threshold | Description |
|-----------|------------|---------------|-----------------|
| High Error Rate | `Lambda Errors` | > 5 per minute | Indicates application issues |
| High Latency | `Lambda Duration p99` | > 5 seconds | Slow response times |
| DynamoDB Throttling | `ThrottledRequests` | > 0 | Capacity issues |
| 5XX Errors | `API Gateway 5XXError` | > 1% | Server errors |
| Dead Letter Queue | `SQS ApproximateNumberOfMessages` | > 0 | Failed messages |

## AWS X-Ray Tracing {#xray-tracing}

:::tip Built-in Feature
X-Ray tracing is enabled by default in the MBC CQRS Serverless CDK template for Lambda functions and Step Functions.
:::

### Enable X-Ray

Lambda and Step Functions tracing is already enabled in the default CDK template. API Gateway stage tracing is not part of the default template — add it yourself if needed:

```typescript
const handler = new lambda.Function(this, 'Handler', {
  // ... other config
  tracing: lambda.Tracing.ACTIVE,
});

const api = new apigateway.HttpApi(this, 'Api', {
  // ... other config
});

// Enable X-Ray for API Gateway
const stage = api.defaultStage?.node.defaultChild as apigateway.CfnStage;
stage.addPropertyOverride('TracingEnabled', true);
```

### Instrument Application

:::info Optional Enhancement
For deeper tracing of AWS SDK calls and HTTP requests, you can optionally add the aws-xray-sdk package to your application.
:::

```typescript
import * as AWSXRay from 'aws-xray-sdk-core';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';

// Instrument AWS SDK v3 clients individually
const dynamoClient = AWSXRay.captureAWSv3Client(new DynamoDBClient({}));

// Instrument HTTP calls
AWSXRay.captureHTTPsGlobal(require('http'));
AWSXRay.captureHTTPsGlobal(require('https'));

// Add custom annotations
const segment = AWSXRay.getSegment();
const subsegment = segment?.addNewSubsegment('CustomOperation');
subsegment?.addAnnotation('userId', userId);
subsegment?.addMetadata('request', requestData);
// ... perform operation
subsegment?.close();
```

## Centralized Logging {#centralized-logging}

:::info CDK Customization
Centralized logging is not included in the default template. The following patterns show how to aggregate logs for complex applications.
:::

### Log Aggregation Pattern

For complex applications, aggregate logs:

```typescript
import * as logs from 'aws-cdk-lib/aws-logs';
import * as destinations from 'aws-cdk-lib/aws-logs-destinations';

// Create a centralized log group
const centralLogGroup = new logs.LogGroup(this, 'CentralLogs', {
  logGroupName: `/app/${props.appName}/central`,
  retention: logs.RetentionDays.THREE_MONTHS,
});

// Assume lambdaLogGroup and logProcessorFunction are already defined above
new logs.SubscriptionFilter(this, 'LambdaLogSubscription', {
  logGroup: lambdaLogGroup,
  destination: new destinations.LambdaDestination(logProcessorFunction),
  filterPattern: logs.FilterPattern.allEvents(),
});
```

### Log Insights Queries

Useful CloudWatch Logs Insights queries:

```text
# Error analysis
fields @timestamp, @message
| filter @message like /ERROR/
| stats count(*) by bin(1h)

# Slow requests
fields @timestamp, @duration, @requestId
| filter @duration > 3000
| sort @duration desc
| limit 20

# Request volume by endpoint
fields @timestamp
| filter @message like /HTTP/
| parse @message /(?<method>\w+) (?<path>\/\S+)/
| stats count(*) by path, method
| sort count desc

# Cold starts
fields @timestamp, @message
| filter @message like /Init Duration/
| parse @message /Init Duration: (?<initDuration>[\d.]+) ms/
| stats avg(initDuration), max(initDuration), count(*)
```

## Application Performance Monitoring {#apm}

:::info Implementation Required
The framework does not include built-in APM features. The following examples show patterns you can implement in your application.
:::

### Performance Metrics

Track key performance indicators:

```typescript
class PerformanceMonitor {
  private metrics: Map<string, number[]> = new Map();

  startTimer(operation: string): () => void {
    const start = Date.now();
    return () => {
      const duration = Date.now() - start;
      this.recordMetric(operation, duration);
    };
  }

  private recordMetric(name: string, value: number): void {
    if (!this.metrics.has(name)) {
      this.metrics.set(name, []);
    }
    this.metrics.get(name)!.push(value);
  }

  async flush(): Promise<void> {
    for (const [name, values] of this.metrics.entries()) {
      const avg = values.reduce((a, b) => a + b, 0) / values.length;
      await publishMetric(name, avg, 'Milliseconds');
    }
    this.metrics.clear();
  }
}
```

### Health Checks

The framework provides a basic health check endpoint at `GET /` that returns a simple response. For production applications, you may want to implement more comprehensive health checks:

:::tip Built-in Health Check
The default `GET /` endpoint returns "Hello World!" and can be used for basic liveness checks.
:::

For more detailed health checks, implement a custom controller:

```typescript
import { Controller, Get, Injectable } from '@nestjs/common';
import { PrismaClient } from '@prisma/client';
import { DynamoDBClient, ListTablesCommand } from '@aws-sdk/client-dynamodb';

interface HealthStatus {
  status: 'healthy' | 'degraded';
  timestamp: string;
  checks: Record<string, 'ok' | 'failed'>;
}

@Controller('health')
@Injectable()
export class HealthController {
  private readonly prisma = new PrismaClient();
  private readonly dynamodb = new DynamoDBClient({});

  @Get()
  async check(): Promise<HealthStatus> {
    const checks = await Promise.allSettled([
      this.checkDatabase(),
      this.checkDynamoDB(),
    ]);

    return {
      status: checks.every(c => c.status === 'fulfilled') ? 'healthy' : 'degraded',
      timestamp: new Date().toISOString(),
      checks: {
        database: checks[0].status === 'fulfilled' ? 'ok' : 'failed',
        dynamodb: checks[1].status === 'fulfilled' ? 'ok' : 'failed',
      },
    };
  }

  private async checkDatabase(): Promise<void> {
    await this.prisma.$queryRaw`SELECT 1`;
  }

  private async checkDynamoDB(): Promise<void> {
    await this.dynamodb.send(new ListTablesCommand({ Limit: 1 }));
  }
}
```

## Best Practices {#best-practices}

### Logging

- Use structured JSON logging
- Include correlation IDs
- Log at appropriate levels
- Avoid logging sensitive data
- Set appropriate retention periods

### Metrics

- Focus on actionable metrics
- Use percentiles (p50, p95, p99) for latency
- Set meaningful thresholds
- Create dashboards for different audiences

### Alerting

- Avoid alert fatigue
- Set appropriate thresholds
- Include runbooks in alert descriptions
- Use escalation policies

## Related Documentation

- [Deployment Guide](/docs/deployment-guide) - Deploy with monitoring enabled
- [Debugging Guide](/docs/debugging-guide) - Use logging for debugging
- [CI/CD with CodePipeline](/docs/codepipeline-cicd) - Pipeline monitoring
- [Troubleshooting](/docs/common-issues) - Common production issues


---

# Configuration

## Absolute Imports and Module Path Aliases

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/absolute_imports_and_module_path_aliases

# Absolute Imports and Module Path Aliases

MBC CQRS Serverless framework has in-built support for the `"paths"` and `"baseUrl"` options of `tsconfig.json` file.

These options allow you to alias project directories to absolute paths, making it easier to import modules. For example:

```ts
// before
import { Role } from "../../../auth/role.enum";

// after
import { Role } from "@/auth/role.enum";
```

## Absolute Imports {#absolute-imports}

The `baseUrl` configuration option allows you to import directly from the root of the project.

An example of this configuration:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "baseUrl": "."
  },
  "include": ["src/*", "src/**/*"]
}
```

## Module Aliases {#module-aliases}

In addition to configuring the `baseUrl` path, you can use the `"paths"` option to create module path aliases. The MBC CQRS Serverless convention maps `@/*` to `src/*`:

```json title="tsconfig.json"
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@shared/*": ["src/shared/*"]
    }
  },
  "include": ["src/**/*"]
}
```

This lets you write clean, refactoring-friendly imports:

```ts
// without alias
import { OrderService } from "../../../orders/order.service";

// with alias
import { OrderService } from "@/orders/order.service";
```

## Jest Configuration {#jest-configuration}

TypeScript path aliases must also be registered in Jest so tests resolve the same paths. Add a `moduleNameMapper` to your `jest.config.json`:

```json title="jest.config.json"
{
  "moduleNameMapper": {
    "^@/(.*)$": "<rootDir>/src/$1",
    "^@shared/(.*)$": "<rootDir>/src/shared/$1"
  }
}
```

:::info
Keep the `moduleNameMapper` patterns in sync with the `paths` entries in `tsconfig.json`. A missing mapper causes `Cannot find module` errors only in tests, which can be hard to diagnose.
:::

## Related Documentation

- [Project Structure](/docs/project-structure) - Project file organization
- [Installation](/docs/installation) - TypeScript configuration setup
- [Getting Started](/docs/getting-started) - Initial project setup


---

## Configuring

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/configuring

# Configuring

MBC CQRS Serverless framework allows you to customize your project to meet specific requirements. This guide covers all configuration options available in the framework.

## Project Configuration {#project-configuration}

### serverless.yml

The main configuration file for your serverless application.

:::info Table Prefix
The framework generates DynamoDB table names automatically using `NODE_ENV` and `APP_NAME` environment variables plus a type suffix. The format is `{NODE_ENV}-{APP_NAME}-{tableName}-command` for command tables and `{NODE_ENV}-{APP_NAME}-{tableName}-data` for data tables. For example, with `NODE_ENV=dev`, `APP_NAME=my-app`, and `tableName: 'order'`, the tables are `dev-my-app-order-command` and `dev-my-app-order-data`.
:::

```yaml
service: my-app

frameworkVersion: '3'

plugins:
  - serverless-offline
  - serverless-dynamodb

provider:
  name: aws
  runtime: nodejs20.x
  stage: ${opt:stage, 'dev'}
  region: ${opt:region, 'ap-northeast-1'}
  memorySize: 512
  timeout: 30

  environment:
    NODE_ENV: ${self:provider.stage}
    APP_NAME: ${self:service}
    COGNITO_USER_POOL_ID: ${env:COGNITO_USER_POOL_ID}
    COGNITO_USER_POOL_CLIENT_ID: ${env:COGNITO_USER_POOL_CLIENT_ID}

  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - dynamodb:Query
            - dynamodb:Scan
            - dynamodb:GetItem
            - dynamodb:PutItem
            - dynamodb:UpdateItem
            - dynamodb:DeleteItem
          Resource:
            - "arn:aws:dynamodb:${self:provider.region}:*:table/${self:provider.stage}-${self:service}-*"

custom:
  serverless-offline:
    httpPort: 3000
    lambdaPort: 3002

  serverless-dynamodb:
    stages:
      - dev
    start:
      port: 8000
      inMemory: true
      migrate: false
```

### NestJS Configuration

Configure NestJS modules in your application.

```typescript
// app.module.ts
import { Module } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import { CommandModule } from '@mbc-cqrs-serverless/core';

@Module({
  imports: [
    // Load environment variables
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: ['.env.local', '.env'],
    }),

    // Configure Command Module
    CommandModule.register({
      tableName: 'order', // Logical name; actual table: {NODE_ENV}-{APP_NAME}-order-command
      dataSyncHandlers: [],
    }),
  ],
})
export class AppModule {}
```

## TypeScript Configuration {#typescript-configuration}

### tsconfig.json

Recommended TypeScript configuration for MBC CQRS Serverless projects.

```json
{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2021",
    "lib": ["ES2021"],
    "declaration": true,
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noImplicitThis": true,
    "alwaysStrict": true,
    "noUnusedLocals": false,
    "noUnusedParameters": false,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": false,
    "inlineSourceMap": true,
    "inlineSources": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@shared/*": ["src/shared/*"]
    },
    "outDir": "./dist"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

The `paths` option enables module path aliases (e.g. `@/` for `src/`). See [Absolute Imports and Module Path Aliases](/docs/absolute_imports_and_module_path_aliases) for details.

## ESLint Configuration {#eslint-configuration}

### .eslintrc.js

Recommended ESLint configuration.

```javascript
module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    project: 'tsconfig.json',
    sourceType: 'module',
  },
  plugins: ['@typescript-eslint/eslint-plugin'],
  extends: [
    'plugin:@typescript-eslint/recommended',
    'plugin:prettier/recommended',
  ],
  root: true,
  env: {
    node: true,
    jest: true,
  },
  ignorePatterns: ['.eslintrc.js', 'dist', 'node_modules'],
  rules: {
    '@typescript-eslint/interface-name-prefix': 'off',
    '@typescript-eslint/explicit-function-return-type': 'off',
    '@typescript-eslint/explicit-module-boundary-types': 'off',
    '@typescript-eslint/no-explicit-any': 'warn',
    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
  },
};
```

## Module Configuration {#module-configuration}

### CommandModule Options

Configure the core CommandModule.

```typescript
import { Module } from '@nestjs/common';
import { CommandModule } from '@mbc-cqrs-serverless/core';
import { OrderRdsSyncHandler } from './order-rds-sync.handler'; // Your IDataSyncHandler implementation — see service-patterns

@Module({
  imports: [
    CommandModule.register({
      // Required: DynamoDB table name
      tableName: 'order',

      // Optional: Data sync handlers for RDS synchronization
      dataSyncHandlers: [OrderRdsSyncHandler],

      // Optional: Reserved for future use (not yet implemented)
      skipError: false,

      // Optional: Disable default DynamoDB data sync handler
      disableDefaultHandler: false,
    }),
  ],
})
export class OrderModule {}
```

### SequencesModule Options

Configure auto-incrementing sequences.

```typescript
import { Module } from '@nestjs/common';
import { SequencesModule } from '@mbc-cqrs-serverless/sequence';

@Module({
  imports: [
    SequencesModule.register({
      // Optional: Enable or disable default sequence controller
      enableController: true,
    }),
  ],
})
export class AppModule {}
```

Note: Rotation strategy (day, month, year, fiscal_yearly, none) is configured through master data settings, not module options. See the [Sequence documentation](/docs/sequence) for details.

### TenantModule Options

Configure multi-tenant support.

```typescript
import { Module } from '@nestjs/common';
import { TenantModule } from '@mbc-cqrs-serverless/tenant';
import { TenantRdsSyncHandler } from './tenant-rds-sync.handler'; // Your IDataSyncHandler implementation — see service-patterns

@Module({
  imports: [
    TenantModule.register({
      // Optional: Enable or disable default tenant controller
      enableController: true,

      // Optional: Data sync handlers for RDS synchronization
      dataSyncHandlers: [TenantRdsSyncHandler],
    }),
  ],
})
export class AppModule {}
```

### NotificationModule

Configure email and real-time notifications via environment variables.

```typescript
import { Module } from '@nestjs/common';
import { NotificationModule } from '@mbc-cqrs-serverless/core';

@Module({
  imports: [
    // NotificationModule is a global module - just import it
    NotificationModule,
  ],
})
export class AppModule {}
```

NotificationModule is configured through environment variables:

```bash
# Email (SES) configuration
# Required: Default sender email address
SES_FROM_EMAIL=noreply@example.com

# Optional: AWS SES endpoint (for local development)
SES_ENDPOINT=http://localhost:4566

# Optional: AWS SES region
SES_REGION=ap-northeast-1

# Real-time transport configuration
# Optional: Active transports — default is appsync-graphql (GraphQL Subscriptions)
# Set to appsync-event for AppSync Events API (v1.3.0+), or comma-separated for dual-publish
NOTIFICATION_TRANSPORTS=appsync-graphql

# Required when NOTIFICATION_TRANSPORTS includes appsync-graphql
APPSYNC_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/graphql
APPSYNC_API_KEY=da2-xxxx

# Required when NOTIFICATION_TRANSPORTS includes appsync-event (v1.3.0+)
# APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
```

See [Notification Module](/docs/notification-module) for full AppSync transport setup and real-time subscription patterns.

## Logging Configuration {#logging-configuration}

### Configure Logger

Set up structured logging for production.

```typescript
import { Injectable, Logger } from '@nestjs/common';

// Configure log level based on environment
const LOG_LEVELS = {
  production: ['error', 'warn', 'log'],
  development: ['error', 'warn', 'log', 'debug', 'verbose'],
  test: ['error', 'warn'],
};

// In main.ts or bootstrap
const app = await NestFactory.create(AppModule, {
  logger: LOG_LEVELS[process.env.NODE_ENV] || LOG_LEVELS.development,
});

// Structured logging in services
@Injectable()
export class OrderService {
  private readonly logger = new Logger(OrderService.name);

  async createOrder(dto: CreateOrderDto): Promise<Order> {
    this.logger.log({
      message: 'Creating order',
      code: dto.code,
      tenantCode: dto.tenantCode,
    });

    // ... implementation
  }
}
```

## Validation Configuration {#validation-configuration}

### Global Validation Pipe

Configure validation for all endpoints.

```typescript
import { BadRequestException, ValidationPipe } from '@nestjs/common';

// In main.ts or bootstrap
app.useGlobalPipes(
  new ValidationPipe({
    // Transform payloads to DTO instances
    transform: true,

    // Strip properties not in DTO
    whitelist: true,

    // Throw error for extra properties
    forbidNonWhitelisted: true,

    // Transform primitive types
    transformOptions: {
      enableImplicitConversion: true,
    },

    // Custom error messages
    exceptionFactory: (errors) => {
      const messages = errors.map(error => ({
        field: error.property,
        errors: Object.values(error.constraints || {}),
      }));
      return new BadRequestException({
        message: 'Validation failed',
        errors: messages,
      });
    },
  }),
);
```

## CORS Configuration {#cors-configuration}

### Configure CORS

Set up Cross-Origin Resource Sharing.

```typescript
// In main.ts
app.enableCors({
  origin: process.env.ALLOWED_ORIGINS?.split(',') || [
    'http://localhost:3000',
  ],
  methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-Id'],
  credentials: true,
  maxAge: 3600,
});
```

## Stage-Specific Configuration {#stage-specific-configuration}

### Environment-Based Settings

Configure different settings per environment.

```typescript
// config/configuration.ts
export default () => ({
  stage: process.env.STAGE || 'dev',

  database: {
    tablePrefix: `myapp-${process.env.STAGE}`,
    commandTable: `myapp-${process.env.STAGE}-command`,
    dataTable: `myapp-${process.env.STAGE}-data`,
  },

  aws: {
    region: process.env.AWS_REGION || 'ap-northeast-1',
    dynamodbEndpoint: process.env.DYNAMODB_ENDPOINT, // For local dev
  },

  auth: {
    userPoolId: process.env.COGNITO_USER_POOL_ID,
    clientId: process.env.COGNITO_USER_POOL_CLIENT_ID,
  },

  features: {
    enableDebugLogs: process.env.STAGE === 'dev',
    enableMetrics: process.env.STAGE === 'prod',
  },
});

// Usage
import { ConfigService } from '@nestjs/config';

@Injectable()
export class AppService {
  constructor(private configService: ConfigService) {}

  getTableName(): string {
    return this.configService.get<string>('database.commandTable');
  }
}
```

## Related Documentation

- [Environment Variables](/docs/environment-variables) - All available environment variables
- [Modules](/docs/modules) - Module configuration and registration
- [Command Service](/docs/command-service) - CommandModule behavior and options
- [Sequence](/docs/sequence) - SequencesModule for auto-incrementing IDs
- [Tenant Module](/docs/tenant) - TenantModule configuration
- [Notification Module](/docs/notification-module) - Email and real-time notification configuration
- [Email Service](/docs/email-service) - SES-based email with templates
- [Deployment Guide](/docs/deployment-guide) - Configure for production


---

## Environment Variables

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/environment-variables

# Environment Variables

MBC CQRS Serverless framework comes with built-in support for environment variables, which allows you to do the following:

- Use `.env` to load environment variables
- Validate environment variables

## Loading Environment Variables {#loading-env-vars}

MBC CQRS Serverless framework has built-in support for loading environment variables from `.env*` files into `process.env.`

:::info Core vs Application Variables
The environment variables listed below are categorized into two types:

- **Core Variables**: Variables validated by the framework's base `EnvironmentVariables` class. These are essential for the framework to function.
- **Application Variables**: Variables that your application may need based on which features you use. Add validation for these in your custom `EnvValidation` class.

The "Required" column indicates the general expectation for typical applications. You should add validation rules for all variables your specific application depends on.
:::

### Core Configuration

| Variable | Description | Required | Default | Example |
|-------------|-----------------|--------------|-------------|-------------|
| `NODE_ENV` | Running environment: local, dev, stg, prod | Yes | - | `local` |
| `APP_NAME` | Application name used for table prefixes | Yes | - | `demo` |
| `APP_PORT` | Application port for non-Lambda environments | No | `3000` | `3000` |
| `IS_OFFLINE` | Set to `true` automatically by serverless-offline when running locally. The framework uses this flag to detect local development and skip production-only behaviors. | No | `false` | `true` |
| `LOG_LEVEL` | Log level: debug, verbose, info, warn, error, fatal | Yes | - | `verbose` |
| `EVENT_SOURCE_DISABLED` | Disable event source route for API Gateway integration | Yes | - | `false` |
| `REQUEST_BODY_SIZE_LIMIT` | Request body size limit for JSON and URL-encoded data | No | `100kb` | `100kb` |

### Multi-Tenancy Configuration

| Variable | Description | Required | Default | Example |
|-------------|-----------------|--------------|-------------|-------------|
| `COMMON_TENANT_CODES` | Comma-separated list of tenant codes treated as common/shared across tenants | No | `common` | `common,shared,public` |
| `CROSS_TENANT_ROLES` | Comma-separated list of roles granted cross-tenant access | No | `system_admin` | `system_admin,general_manager` |

### Read-Your-Writes (RYW) Configuration {#ryw-session-configuration}

| Variable | Description | Required | Default | Example |
|-------------|-----------------|--------------|-------------|-------------|
| `RYW_SESSION_TTL_MINUTES` | Time-to-live in minutes for Read-Your-Writes session records. Leave unset or set to a non-positive value to disable RYW session writes | No | - | `15` |

### AWS Credentials

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `AWS_ACCESS_KEY_ID` | AWS access key ID for local development | No | `local` |
| `AWS_SECRET_ACCESS_KEY` | AWS secret access key for local development | No | `local` |
| `AWS_REGION` | Default AWS region | No | `ap-northeast-1` |

### DynamoDB Configuration {#dynamodb-configuration}

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `DYNAMODB_ENDPOINT` | DynamoDB endpoint URL for local development | No | `http://localhost:8000` |
| `DYNAMODB_REGION` | DynamoDB region | No | `ap-northeast-1` |
| `ATTRIBUTE_LIMIT_SIZE` | Maximum size in bytes for DynamoDB item `attributes` before the framework offloads them to S3 | Yes | `102400` |

The default of `102400` (100 KB) is sized for the AWS Step Functions payload limit, not DynamoDB's own 400 KB item limit. The command state machine passes the DynamoDB stream event twice per state (`input.$` and `context.$`), so the safe inline size is approximately `(256 KB Step Functions limit − ~20 KB context overhead) ÷ 2 ≈ 110 KB`. Attributes larger than `ATTRIBUTE_LIMIT_SIZE` are automatically stored in S3 instead of inline.

:::warning Known Issue (Fixed in v1.3.4)
In versions prior to v1.3.4, the framework's default `ATTRIBUTE_LIMIT_SIZE` in generated CDK templates and env examples was `389120` (380 KB) — sized for DynamoDB's item limit rather than the Step Functions payload limit. Because the command state machine duplicates the event payload (`input.$` + `context.$`), attributes above ~110 KB could still be inlined and cause the state machine to fail with `States.DataLimitExceeded`.

If your deployment still sets `ATTRIBUTE_LIMIT_SIZE=389120` (or another value above ~110 KB), lower it to `102400` or less.

See also: [Changelog v1.3.4](/docs/changelog#v134)
:::

### S3 Configuration

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `S3_ENDPOINT` | S3 endpoint URL for local development | No | `http://localhost:4566` |
| `S3_REGION` | S3 region | No | `ap-northeast-1` |
| `S3_BUCKET_NAME` | S3 bucket name for storing large DynamoDB attributes | Yes | `local-bucket` |

### Step Functions Configuration

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `SFN_ENDPOINT` | Step Functions endpoint URL for local development | No | `http://localhost:8083` |
| `SFN_REGION` | Step Functions region | No | `ap-northeast-1` |
| `SFN_COMMAND_ARN` | Step Functions state machine ARN for command processing | Yes | `arn:aws:states:ap-northeast-1:101010101010:stateMachine:command` |

### SNS Configuration

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `SNS_ENDPOINT` | SNS endpoint URL for local development | No | `http://localhost:4002` |
| `SNS_REGION` | SNS region | No | `ap-northeast-1` |
| `SNS_TOPIC_ARN` | Default SNS topic ARN for event notifications | No | `arn:aws:sns:ap-northeast-1:101010101010:CqrsSnsTopic` |
| `SNS_ALARM_TOPIC_ARN` | SNS topic ARN for alarm notifications (error alerts) | No | `arn:aws:sns:ap-northeast-1:101010101010:AlarmSnsTopic` |

### SQS Configuration

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `SQS_ENDPOINT` | SQS endpoint URL for local development | No | `http://localhost:9324` |
| `SQS_REGION` | SQS region | No | `ap-northeast-1` |

### Cognito Configuration

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `COGNITO_URL` | Cognito endpoint URL for local development | No | `http://localhost:9229` |
| `COGNITO_USER_POOL_ID` | Cognito User Pool ID | Yes | `local_2G7noHgW` |
| `COGNITO_USER_POOL_CLIENT_ID` | Cognito User Pool Client ID | Yes | `dnk8y7ii3wled35p3lw0l2cd7` |
| `COGNITO_REGION` | Cognito region | No | `ap-northeast-1` |

### AppSync Configuration

#### AppSync GraphQL Subscription (existing)

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `APPSYNC_ENDPOINT` | AppSync GraphQL endpoint URL | No | `http://localhost:4001/graphql` |
| `APPSYNC_API_KEY` | AppSync API key for local development | No | `da2-fakeApiId123456` |

#### AppSync Events API (opt-in) {#appsync-events-env}

Set `NOTIFICATION_TRANSPORTS=appsync-event` (or `appsync-graphql,appsync-event` for dual-publish) to activate the AppSync Events API transport. See [AppSyncEventsService](/docs/notification-module#appsync-events-service) for details.

| Variable | Description | Required | Default | Example |
|-------------|-----------------|--------------|-------------|-------------|
| `NOTIFICATION_TRANSPORTS` | Comma-separated list of active transports. Built-ins: `appsync-graphql`, `appsync-event` | No | `appsync-graphql` | `appsync-event` |
| `APPSYNC_EVENTS_ENDPOINT` | AppSync Events API HTTP endpoint URL | When `appsync-event` is active | - | `https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event` |
| `APPSYNC_EVENTS_NAMESPACE` | Channel namespace name — must match a pre-created namespace in your AppSync Event API | No | `default` | `notifications` |

### SES Email Configuration

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `SES_ENDPOINT` | SES endpoint URL for local development | No | `http://localhost:8005` |
| `SES_REGION` | SES region | No | `ap-northeast-1` |
| `SES_FROM_EMAIL` | Default sender email address | Yes | `email@example.com` |

### Database Configuration (Prisma)

| Variable | Description | Required | Example |
|-------------|-----------------|--------------|-------------|
| `DATABASE_URL` | Database connection URL for Prisma ORM | No | `mysql://root:RootCqrs@localhost:3306/cqrs` |

### Example .env file

```bash
# AWS Credentials
AWS_ACCESS_KEY_ID=local
AWS_SECRET_ACCESS_KEY=local
AWS_REGION=ap-northeast-1

# Core Configuration
NODE_ENV=local
APP_NAME=demo
APP_PORT=3000
LOG_LEVEL=verbose
EVENT_SOURCE_DISABLED=false
REQUEST_BODY_SIZE_LIMIT=100kb

# Multi-Tenancy Configuration
# COMMON_TENANT_CODES=common
# CROSS_TENANT_ROLES=system_admin

# Read-Your-Writes (RYW) Configuration
# RYW_SESSION_TTL_MINUTES=15

# DynamoDB Configuration
DYNAMODB_ENDPOINT=http://localhost:8000
DYNAMODB_REGION=ap-northeast-1
ATTRIBUTE_LIMIT_SIZE=102400

# S3 Configuration
S3_ENDPOINT=http://localhost:4566
S3_REGION=ap-northeast-1
S3_BUCKET_NAME=local-bucket

# Step Functions Configuration
SFN_ENDPOINT=http://localhost:8083
SFN_REGION=ap-northeast-1
SFN_COMMAND_ARN=arn:aws:states:ap-northeast-1:101010101010:stateMachine:command

# SNS Configuration
SNS_ENDPOINT=http://localhost:4002
SNS_REGION=ap-northeast-1
SNS_TOPIC_ARN=arn:aws:sns:ap-northeast-1:101010101010:CqrsSnsTopic
SNS_ALARM_TOPIC_ARN=arn:aws:sns:ap-northeast-1:101010101010:AlarmSnsTopic

# SQS Configuration
SQS_ENDPOINT=http://localhost:9324
SQS_REGION=ap-northeast-1

# Cognito Configuration
COGNITO_URL=http://localhost:9229
COGNITO_USER_POOL_ID=local_2G7noHgW
COGNITO_USER_POOL_CLIENT_ID=dnk8y7ii3wled35p3lw0l2cd7
COGNITO_REGION=ap-northeast-1

# AppSync Configuration
APPSYNC_ENDPOINT=http://localhost:4001/graphql
APPSYNC_API_KEY=da2-fakeApiId123456
# AppSync Events API (optional — set NOTIFICATION_TRANSPORTS=appsync-event to activate)
# NOTIFICATION_TRANSPORTS=appsync-event
# APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
# APPSYNC_EVENTS_NAMESPACE=default

# SES Configuration
SES_ENDPOINT=http://localhost:8005
SES_REGION=ap-northeast-1
SES_FROM_EMAIL=email@example.com

# Database Configuration
DATABASE_URL="mysql://root:RootCqrs@localhost:3306/cqrs"
```

## Validate Environment Variables {#validate-env-vars}

It is standard practice to throw an exception during application startup if required environment variables haven't been provided or if they don't meet certain validation rules. The `@mbc-cqrs-serverless/core` package makes this easy to do.

First, we have to define:

- a class with validation constraints,
- extend the EnvironmentVariables class.

```ts
// env.validation.ts
import { EnvironmentVariables } from "@mbc-cqrs-serverless/core";
import { IsUrl } from "class-validator";

export class EnvValidation extends EnvironmentVariables {
  @IsUrl({
    require_tld: false,
  })
  FRONT_BASE_URL: string;
}
```

With this in place, you pass the `EnvValidation` class as a configuration argument of the `createHandler` function, as follows:

```ts
import { createHandler } from "@mbc-cqrs-serverless/core";

import { EnvValidation } from "./env.validation";
import { MainModule } from "./main.module";

export const handler = createHandler({
  rootModule: MainModule,
  envCls: EnvValidation,
});
```


## Related Documentation

- [Configuring](/docs/configuring) - Module-level configuration options
- [Queue Module](/docs/queue) - SNS and SQS usage
- [Notification Module](/docs/notification-module) - SES and AppSync Events configuration
- [Directory](/docs/directory) - S3 file and folder management with presigned URLs
- [Deployment Guide](/docs/deployment-guide) - Deployment environment setup
- [Security Best Practices](/docs/security-best-practices) - Secure handling of credentials and secrets
- [Installation](/docs/installation) - Initial environment setup


---

# Testing

## End-to-end Tests

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/e2e-test

# End-to-end Tests

Unlike unit testing, which focuses on individual modules and classes, end-to-end (e2e) testing covers the interaction of classes and modules at a more aggregate level — closer to the kind of interaction that end-users will have with the production system. As an application grows, it becomes hard to manually test the end-to-end behavior of each API endpoint. Automated end-to-end tests help us ensure that the overall behavior of the system is correct and meets project requirements.

E2E tests run against the API in a real local environment so you do not need to mock any services. The main steps for writing an e2e test are:

- Create necessary data.
- Make API calls using the Supertest library to simulate HTTP requests.
- Verify the response data is correct.
- Clean up test data.

:::warning Test Execution Order
E2E tests that share database state should run sequentially to avoid race conditions. Use the `--runInBand` flag to disable parallel execution:

```bash
# Run E2E tests sequentially
jest --runInBand test/e2e

# Update the test:e2e script in package.json (the generated default does not include --runInBand)
"test:e2e": "jest --runInBand --config ./test/jest-e2e.json"
```

Without `--runInBand`, Jest runs tests in parallel across multiple workers, which can cause:
- Data conflicts when tests modify the same records
- Flaky tests due to timing issues
- Cleanup operations affecting other running tests
:::

Here is a basic structure for e2e tests:

```ts
import request from "supertest";
import { config } from "./config";
import {
  deleteItem,
  getItem,
  getTableName,
  putItem,
  TableType,
} from "./dynamo-client";
import { syncDataFinished } from "./utils";

const API_PATH = "/api/cat";

describe("Cat", () => {
  it("should create a new cat", async () => {
    // Arrange - define test data inline
    const payload = {
      pk: "CAT#tenant1",
      sk: "CAT#001",
      id: "CAT#tenant1#CAT#001",
      name: "Whiskers",
      version: 0,
      code: "001",
      type: "CAT",
    };

    // Action - make API call
    const res = await request(config.apiBaseUrl).post(API_PATH).send(payload);

    // Assert - verify response and data
    expect(res.statusCode).toEqual(201);

    // Wait for async processing to complete
    await syncDataFinished("cat_table", {
      pk: payload.pk,
      sk: `${payload.sk}@1`,
    });

    // Verify data in DynamoDB
    const data = await getItem(getTableName("cat_table", TableType.DATA), {
      pk: payload.pk,
      sk: payload.sk,
    });

    expect(data).toMatchObject({
      ...payload,
      version: 1,
    });
  }, 40000);

  // Clean up test data if needed
  afterAll(async () => {
    await deleteItem(getTableName("cat_table", TableType.DATA), {
      pk: "CAT#tenant1",
      sk: "CAT#001",
    });
  });
});
```

### Test Helper Utilities

The framework provides helper utilities for e2e testing:

#### config.ts - Environment Configuration

```ts
import dotenv from "dotenv";

dotenv.config();

const config = {
  nodeEnv: process.env.NODE_ENV,
  appName: process.env.APP_NAME,
  dynamoEndpoint: process.env.DYNAMODB_ENDPOINT,
  dynamoRegion: process.env.DYNAMODB_REGION,
  apiBaseUrl: process.env.API_BASE_URL || "http://0.0.0.0:3000",
};

export { config };
```

#### dynamo-client.ts - DynamoDB Operations

```ts
import {
  DynamoDBClient,
  GetItemCommand,
  PutItemCommand,
  DeleteItemCommand,
} from "@aws-sdk/client-dynamodb";
import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
import { config } from "./config";

const tablePrefix = `${config.nodeEnv}-${config.appName}-`;

enum TableType {
  COMMAND = "command",
  DATA = "data",
  HISTORY = "history",
}

const dynamoClient = new DynamoDBClient({
  endpoint: config.dynamoEndpoint,
  region: config.dynamoRegion,
});

const getTableName = (tableName: string, tableType: TableType) => {
  return `${tablePrefix}${tableName}-${tableType}`;
};

const getItem = async (tableName: string, key: { pk: string; sk: string }) => {
  const { Item } = await dynamoClient.send(
    new GetItemCommand({
      TableName: tableName,
      Key: marshall(key),
    })
  );
  return Item ? unmarshall(Item) : undefined;
};

const putItem = async (tableName: string, item: Record<string, unknown>) => {
  await dynamoClient.send(
    new PutItemCommand({
      TableName: tableName,
      Item: marshall(item),
    })
  );
};

const deleteItem = async (tableName: string, key: { pk: string; sk: string }) => {
  await dynamoClient.send(
    new DeleteItemCommand({
      TableName: tableName,
      Key: marshall(key),
    })
  );
};

export { getItem, putItem, deleteItem, getTableName, TableType, dynamoClient };
```

#### utils.ts - Test Utilities

```ts
import { getItem, getTableName, TableType } from "./dynamo-client";

const sleep = (ms = 0) => new Promise((resolve) => setTimeout(resolve, ms));

const retry = async <T>(
  fn: () => Promise<T> | T,
  { retries, retryIntervalMs }: { retries: number; retryIntervalMs: number }
): Promise<T> => {
  try {
    await sleep(retryIntervalMs);
    return await fn();
  } catch (error) {
    if (retries <= 0) throw error;
    await sleep(retryIntervalMs);
    return retry(fn, { retries: retries - 1, retryIntervalMs });
  }
};

// Wait for async command processing to finish
const syncDataFinished = async (
  tableName: string,
  key: { pk: string; sk: string }
) => {
  await retry(
    async () => {
      const res = await getItem(getTableName(tableName, TableType.COMMAND), key);
      if (res?.status === "finish:FINISHED") return;
      throw new Error("Not finished yet");
    },
    { retries: 10, retryIntervalMs: 3000 }
  );
};

export { retry, sleep, syncDataFinished };
```

## GitHub Actions Setup {#github-actions-setup}

To automate E2E testing in your CI/CD pipeline, you'll need to set up GitHub Actions. Here's a comprehensive guide on configuring GitHub Actions for E2E testing:

### Environment Setup

The workflow requires several services and configurations:

1. Docker Services:
   - DynamoDB Local
   - Cognito Local
   - LocalStack
   - ElasticMQ

2. Directory Permissions:
```yaml
- name: Set up permissions
  run: |
    sudo mkdir -p /var/lib/docker/volumes
    sudo chmod -R 777 /var/lib/docker/volumes
    
    # Create required directories
    sudo mkdir -p infra-local/docker-data/{.cognito,.dynamodb,.mysql,.localstack,.elasticmq}
    sudo chown -R $USER:$USER infra-local
    sudo chmod -R 777 infra-local/docker-data
```

3. Docker Container Health Checks:

Docker container health checks are important for monitoring container status. When configuring health checks, consider the following two contexts:

a) Health check from inside Docker container:
```yaml
services:
  dynamodb-local:
    healthcheck:
      test: ["CMD-SHELL", "curl -f -X POST -H 'Content-Type: application/x-amz-json-1.0' -H 'X-Amz-Target: DynamoDB_20120810.ListTables' -d '{}' http://dynamodb-local:8000 || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s
```

b) Health check from GitHub Actions workflow:
```yaml
steps:
  - name: Wait for DynamoDB
    run: |
      attempt=1
      max_attempts=20
      until curl -s -f -X POST \
        -H "Content-Type: application/x-amz-json-1.0" \
        -H "X-Amz-Target: DynamoDB_20120810.ListTables" \
        -d "{}" \
        http://localhost:8000 > /dev/null; do
        if [ $attempt -eq $max_attempts ]; then
          echo "DynamoDB failed to start after $max_attempts attempts"
          exit 1
        fi
        echo "Waiting for DynamoDB... (attempt $attempt/$max_attempts)"
        sleep 15
        attempt=$((attempt + 1))
      done
```

Notes:
- Inside Docker containers, use service names (e.g., dynamodb-local) to access services
- In GitHub Actions workflow steps, use localhost (via port forwarding)
- For more robust health checks, use actual API calls instead of simple connection checks (nc command)
- If network issues occur, check the following:
  - Docker Compose network settings
  - Port mapping configuration
  - Container name resolution
  - GitHub Actions runner environment variables

### Service Configuration

Each service should be configured with:

1. Proper user permissions in Dockerfile:
```dockerfile
RUN adduser -D -u 1001 serviceuser && \
    mkdir -p /app/data && \
    chown -R serviceuser:serviceuser /app
USER serviceuser
```

2. Volume management:
```yaml
volumes:
  service-data:
    driver: local
```

3. Health check mechanisms:
```yaml
healthcheck:
  test: ["CMD", "nc", "-z", "localhost", "PORT"]
  interval: 10s
  timeout: 5s
  retries: 5
  start_period: 15s
```

### Workflow Example

Here's a complete example of a GitHub Actions workflow for E2E testing:

```yaml
name: E2E Tests
on:
  push:
    paths:
      - 'src/**'
      - 'test/**'
      - 'infra/**'
      - '.github/workflows/**'
      - 'package.json'

jobs:
  e2e-tests:
    runs-on: ubuntu-latest # Adjust to self-hosted if your environment requires access to private VPC resources

    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20.x'
          
      - name: Set up environment
        run: |
          sudo mkdir -p /var/lib/docker/volumes
          sudo chmod -R 777 /var/lib/docker/volumes
          
          # Create required directories
          sudo mkdir -p infra-local/docker-data/{.cognito,.dynamodb,.mysql,.localstack,.elasticmq}
          sudo chown -R $USER:$USER infra-local
          sudo chmod -R 777 infra-local/docker-data
          
      - name: Start services
        run: |
          docker-compose down -v
          docker-compose build --no-cache
          docker-compose up -d
          
      - name: Run tests
        run: npm run test:e2e
```


## Related Documentation

- [Unit Testing](/docs/unit-test) - Unit testing with Jest
- [Testing](/docs/testing) - Testing overview
- [Deployment Guide](/docs/deployment-guide) - Deploy for integration testing


---

## Testing

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/testing

# Testing

Automated testing is considered an essential part of any serious software development effort. Automation makes it easy to repeat individual tests or test suites quickly and easily during development. This helps ensure that releases meet quality and performance goals. Automation helps increase coverage and provides a faster feedback loop to developers. Automation both increases the productivity of individual developers and ensures that tests are run at critical development lifecycle junctures, such as source code control check-in, feature integration, and version release.

Such tests often span a variety of types, including unit tests, end-to-end (e2e) tests, integration tests, and so on. While the benefits are unquestionable, it can be tedious to set them up. MBC CQRS Serverless strives to promote development best practices, including effective testing, so it includes features such as the following to help developers and teams build and automate tests. MBC CQRS Serverless:

- provides default tooling (such as a test runner that builds an isolated module/application loader)
- provides integration with [Jest](https://github.com/facebook/jest) and [Supertest](https://github.com/ladjs/supertest) out-of-the-box, while remaining agnostic to testing tools
- makes the Nest dependency injection system available in the testing environment for easily mocking components
- effortlessly mock AWS services

See the guides below to learn how to write tests:

```mdx-code-block
import DocCardList from '@theme/DocCardList';

<DocCardList />
```


## Related Documentation

- [Unit Testing](/docs/unit-test) - Unit testing with Jest
- [E2E Testing](/docs/e2e-test) - End-to-end testing setup
- [Debugging Guide](/docs/debugging-guide) - Debug test failures
- [Common Issues](/docs/common-issues) - Testing-related issues


---

## Unit Tests

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/unit-test

# Unit Tests

This guide explains how to write unit tests for services and handlers in the MBC CQRS Serverless framework.

## Mocking Dependencies {#mocking-dependencies}

The framework uses `@golevelup/ts-jest` for creating mocks. The `createMock()` function automatically generates mock implementations for any interface or class.

### Basic Usage of createMock()

```ts
import { createMock } from '@golevelup/ts-jest'
import { Test } from '@nestjs/testing'
import { ConfigService } from '@nestjs/config'

const moduleRef = await Test.createTestingModule({
  providers: [MyService],
})
  .useMocker(createMock) // Auto-mock all dependencies
  .compile()
```

### Custom Mock Implementation

```ts
import { createMock } from '@golevelup/ts-jest'
import { ConfigService } from '@nestjs/config'

const config = {
  NODE_ENV: 'test',
  APP_NAME: 'my-app',
}

const moduleRef = await Test.createTestingModule({
  providers: [
    MyService,
    {
      provide: ConfigService,
      useValue: createMock<ConfigService>({
        get: jest.fn((key) => config[key] ?? 'default'),
      }),
    },
  ],
}).compile()
```

## Mocking AWS SDK Clients {#mocking-aws-sdk}

Use `aws-sdk-client-mock` to mock AWS SDK v3 clients:

```ts
import { mockClient } from 'aws-sdk-client-mock'
import 'aws-sdk-client-mock-jest'
import { DynamoDBClient, PutItemCommand, GetItemCommand } from '@aws-sdk/client-dynamodb'

describe('MyService', () => {
  const dynamoDBMock = mockClient(DynamoDBClient)

  beforeEach(() => {
    dynamoDBMock.reset()
  })

  afterEach(() => {
    dynamoDBMock.reset()
  })

  it('should put item to DynamoDB', async () => {
    // Arrange: Set up mock response
    dynamoDBMock.on(PutItemCommand).resolves({})

    // Action: Execute the method
    await myService.saveItem({ pk: 'test', sk: 'item' })

    // Assert: Verify the mock was called
    expect(dynamoDBMock).toHaveReceivedCommandTimes(PutItemCommand, 1)
    expect(dynamoDBMock).toHaveReceivedCommandWith(PutItemCommand, {
      TableName: 'my-table',
      Item: expect.objectContaining({
        pk: { S: 'test' },
        sk: { S: 'item' },
      }),
    })
  })
})
```

## Complete Test Example {#complete-test-example}

Here is a complete example based on the framework's actual test patterns:

```ts
import { createMock } from '@golevelup/ts-jest'
import { Test } from '@nestjs/testing'
import { mockClient } from 'aws-sdk-client-mock'
import 'aws-sdk-client-mock-jest'
import { DynamoDBClient, GetItemCommand, PutItemCommand } from '@aws-sdk/client-dynamodb'
import { ConfigService } from '@nestjs/config'

const config = {
  NODE_ENV: 'test',
  APP_NAME: 'my-app',
}

describe('CommandService', () => {
  let commandService: CommandService
  const dynamoDBMock = mockClient(DynamoDBClient)

  beforeEach(async () => {
    const moduleRef = await Test.createTestingModule({
      providers: [
        CommandService,
        DynamoDbService,
        {
          provide: ConfigService,
          useValue: createMock<ConfigService>({
            get: jest.fn((key) => config[key]),
          }),
        },
      ],
    })
      .useMocker(createMock) // Auto-mock remaining dependencies
      .compile()

    commandService = moduleRef.get<CommandService>(CommandService)
  })

  afterEach(() => {
    jest.clearAllMocks()
    dynamoDBMock.reset()
  })

  describe('getLatestItem', () => {
    it('should return the latest item', async () => {
      // Arrange
      const key = { pk: 'master', sk: 'test' }

      // Action
      const item = await commandService.getLatestItem(key)

      // Assert
      expect(item).toBeDefined()
      expect(item?.pk).toBe('master')
    })

    it('should return null when item not found', async () => {
      // Arrange
      const key = { pk: 'master', sk: 'nonexistent' }

      // Action
      const item = await commandService.getLatestItem(key)

      // Assert
      expect(item).toBeNull()
    })
  })
})
```

## Key Testing Patterns {#testing-patterns}

### Test Structure

Each test follows the Arrange-Act-Assert pattern:

1. **Arrange**: Set up test data and mock responses
2. **Act**: Execute the method being tested
3. **Assert**: Verify the results and mock interactions

### Using `describe` and `it`

Use `describe` to group related tests and `it` for individual test cases:

```ts
describe('ServiceName', () => {
  describe('methodName', () => {
    it('should do something when condition is met', async () => {
      // test implementation
    })

    it('should throw error when input is invalid', async () => {
      // test implementation
    })
  })
})
```

### Testing Error Cases

```ts
import { BadRequestException } from '@nestjs/common';

it('should throw BadRequestException when item not found', async () => {
  const invalidKey = { pk: 'invalid', sk: 'key', version: 1 }

  await expect(
    commandService.publishPartialUpdateAsync(invalidKey, { invokeContext: {} })
  ).rejects.toThrow(BadRequestException)
})
```

## Advanced AWS SDK Mock Patterns {#advanced-mock-patterns}

### Mocking Multiple AWS Services

When testing services that interact with multiple AWS services, set up mocks for each client:

```ts
import { mockClient } from 'aws-sdk-client-mock'
import 'aws-sdk-client-mock-jest'
import { DynamoDBClient, PutItemCommand } from '@aws-sdk/client-dynamodb'
import { SNSClient, PublishCommand } from '@aws-sdk/client-sns'
import { SQSClient, SendMessageCommand } from '@aws-sdk/client-sqs'

describe('MultiServiceTest', () => {
  const dynamoMock = mockClient(DynamoDBClient)
  const snsMock = mockClient(SNSClient)
  const sqsMock = mockClient(SQSClient)

  beforeEach(() => {
    dynamoMock.reset()
    snsMock.reset()
    sqsMock.reset()
  })

  it('should publish to SNS after saving to DynamoDB', async () => {
    dynamoMock.on(PutItemCommand).resolves({})
    snsMock.on(PublishCommand).resolves({ MessageId: 'msg-123' })

    await myService.saveAndNotify(data)

    expect(dynamoMock).toHaveReceivedCommandTimes(PutItemCommand, 1)
    expect(snsMock).toHaveReceivedCommandTimes(PublishCommand, 1)
  })
})
```

### Mocking Conditional Responses

Use `callsFake` to return different responses based on input:

```ts
import { marshall } from '@aws-sdk/util-dynamodb'

dynamoMock.on(GetItemCommand).callsFake((input) => {
  if (input.Key.pk.S === 'existing-key') {
    return {
      Item: marshall({
        pk: 'existing-key',
        sk: 'item',
        name: 'Test Item',
      }),
    }
  }
  return { Item: undefined } // Item not found
})
```

### Mocking Errors

Test error handling by making mocks reject:

```ts
import { ConflictException } from '@nestjs/common'

it('should handle ConditionalCheckFailedException as 409 conflict', async () => {
  const error = new Error('The conditional request failed')
  error.name = 'ConditionalCheckFailedException'
  dynamoMock.on(PutItemCommand).rejects(error)

  await expect(myService.saveItem(data)).rejects.toThrow(ConflictException)
})
```

### Using jest.mock() for Module-Level Mocking

For services that instantiate AWS clients internally, use `jest.mock()`:

```ts
// Mock at the top of your test file
jest.mock('@aws-sdk/client-dynamodb', () => {
  const original = jest.requireActual('@aws-sdk/client-dynamodb')
  return {
    ...original,
    DynamoDBClient: jest.fn().mockImplementation(() => ({
      send: jest.fn(),
    })),
  }
})
```

:::tip Best Practice
Prefer `aws-sdk-client-mock` over `jest.mock()` when possible, as it provides better type safety and more detailed assertions like `toHaveReceivedCommandWith`.
:::


## Testing DataSyncHandlers {#testing-data-sync-handlers}

Test the `up()` and `down()` methods of an `IDataSyncHandler` by mocking database clients with `createMock()`.

```ts
import { createMock } from '@golevelup/ts-jest'
import { Test } from '@nestjs/testing'
import { CommandModel } from '@mbc-cqrs-serverless/core'

import { OrderDataSyncHandler } from './order.handler'
import { PrismaService } from 'src/prisma.service'

describe('OrderDataSyncHandler', () => {
  let handler: OrderDataSyncHandler
  let prisma: jest.Mocked<PrismaService>

  beforeEach(async () => {
    const moduleRef = await Test.createTestingModule({
      providers: [OrderDataSyncHandler],
    })
      .useMocker(createMock) // Auto-mock all dependencies
      .compile()

    handler = moduleRef.get(OrderDataSyncHandler)
    prisma = moduleRef.get(PrismaService)
  })

  describe('up', () => {
    it('should upsert record when command is processed', async () => {
      // Arrange: build a representative CommandModel
      const cmd = {
        pk: 'ORDER#mbc',
        sk: 'ORD-001',
        tenantCode: 'mbc',
        version: 1,
        type: 'ORDER',
        attributes: { customerId: 'C-001', total: 150 },
      } as unknown as CommandModel

      prisma.order.upsert.mockResolvedValue({ id: 'ORD-001' } as any)

      await handler.up(cmd)

      expect(prisma.order.upsert).toHaveBeenCalledWith(
        expect.objectContaining({ where: { sk: 'ORD-001' } }),
      )
    })
  })

  describe('down', () => {
    it('should delete record on rollback', async () => {
      const cmd = {
        pk: 'ORDER#mbc',
        sk: 'ORD-001',
        tenantCode: 'mbc',
      } as unknown as CommandModel

      prisma.order.delete.mockResolvedValue({ id: 'ORD-001' } as any)

      await handler.down(cmd)

      expect(prisma.order.delete).toHaveBeenCalledWith({
        where: { sk: 'ORD-001' },
      })
    })
  })
})
```

If your handler does not use Prisma (e.g., writes directly to DynamoDB), inject and mock `DynamoDbService` or `DataService` from `@mbc-cqrs-serverless/core` instead.

## Related Documentation

- [E2E Testing](/docs/e2e-test) - End-to-end testing guide
- [Testing](/docs/testing) - Testing overview
- [Command Service](/docs/command-service) - CommandService API (the subject of most unit tests)
- [Data Service](/docs/data-service) - DataService API (query operations to mock in tests)
- [Debugging Guide](/docs/debugging-guide) - Debug test failures


---

# Troubleshooting

## Common Issues

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/common-issues

# Common Issues

This page lists common issues and their solutions when working with MBC CQRS Serverless applications.

## Installation & Setup {#installation-setup}

### npm install fails with peer dependency errors

**Symptom**: npm install fails with peer dependency warnings or errors.

**Solution**:

```bash
# Use --legacy-peer-deps flag
npm install --legacy-peer-deps

# Or update npm to latest version
npm install -g npm@latest
```

### npm install fails with node-waf error

**Symptom**: npm install fails with `node-waf: command not found` error, typically from the zlib package.

```text
npm error path node_modules/zlib
npm error command sh -c node-waf clean || true; node-waf configure build
npm error sh: node-waf: command not found
```

**Cause**: Some legacy serverless-offline plugins depend on packages that use the deprecated node-waf build tool.

**Solution**:

```bash
# Skip build scripts during installation
npm install --legacy-peer-deps --ignore-scripts

# Then run postinstall scripts manually
npx prisma generate
```

### CLI command not found

**Symptom**: `mbc-cqrs` command is not recognized.

**Solution**:

```bash
# Install globally
npm install -g @mbc-cqrs-serverless/cli

# Or use npx
npx @mbc-cqrs-serverless/cli new my-app
```

### Docker services fail to start

**Symptom**: docker-compose up fails or services don't start.

**Solution**:

```bash
# Check Docker is running
docker info

# Clean up and restart
docker-compose -f infra-local/docker-compose.yml down -v
docker-compose -f infra-local/docker-compose.yml up -d

# Check logs for specific service
docker-compose -f infra-local/docker-compose.yml logs dynamodb-local
```

## Database Issues {#database-issues}

### DynamoDB connection refused

**Symptom**: Cannot connect to DynamoDB Local.

**Solution**:

1. Verify DynamoDB Local is running:
```bash
docker ps | grep dynamodb
```

2. Check the endpoint URL in your configuration:
```typescript
// Should be http://localhost:8000 for local development
dynamodbEndpoint: 'http://localhost:8000'
```

3. Verify tables exist:
```bash
aws dynamodb list-tables --endpoint-url http://localhost:8000
```

### Prisma migration errors

**Symptom**: Prisma migrate fails with connection errors.

**Solution**:

1. Verify the database container is running (the scaffolded project uses MySQL by default):
```bash
docker ps | grep mysql
```

2. Check DATABASE_URL in .env matches your database. The scaffolded project default uses MySQL:
```bash
DATABASE_URL="mysql://root:RootCqrs@localhost:3306/cqrs?schema=public&connection_limit=1"
```

3. Reset and re-run migrations:
```bash
npx prisma migrate reset
npx prisma migrate dev
```

### Master API returns 500 Internal Server Error

**Symptom**: Master API endpoints (`/api/master-setting/list`, `/api/master-data/list`) return 500 Internal Server Error.

**Cause**: The Master module requires both DynamoDB tables and an RDS table. If the `masters` table doesn't exist in RDS, the API will fail with a 500 error.

**Solution**:

1. Verify the `masters` table exists in RDS:
```bash
# For MySQL
docker exec mysql mysql -u root -proot mydb -e "SHOW TABLES LIKE 'masters';"

# For PostgreSQL
docker exec postgres psql -U postgres -d mydb -c "\dt masters"
```

2. If the table is missing, add it to your Prisma schema:
```prisma
model Master {
  pk         String   @db.VarChar(256)
  sk         String   @db.VarChar(512)
  id         String   @id @db.VarChar(256)
  name       String   @db.VarChar(256)
  code       String   @db.VarChar(256)
  version    Int      @default(0)
  tenantCode String   @map("tenant_code") @db.VarChar(64)
  type       String   @db.VarChar(256)
  attributes Json?
  isDeleted  Boolean  @default(false) @map("is_deleted")
  createdAt  DateTime @default(now()) @map("created_at")
  createdBy  String   @default("system") @map("created_by") @db.VarChar(256)
  updatedAt  DateTime @default(now()) @updatedAt @map("updated_at")
  updatedBy  String   @default("system") @map("updated_by") @db.VarChar(256)

  @@unique([pk, sk])
  @@index([tenantCode])
  @@map("masters")
}
```

3. Run Prisma migration:
```bash
npx prisma migrate dev --name add_master_table
```

4. Verify the DynamoDB tables also exist:
```bash
aws dynamodb list-tables --endpoint-url http://localhost:8000 | grep master
# Should show: master-command, master-data, master-history
```

### Serverless Offline fails with missing import_tmp stream {#missing-import-tmp-table}

**Symptom**: `npm run offline:sls` fails because the `LOCAL_DDB_IMPORT_TMP_STREAM` environment variable is not set.

**Cause**: The `import_tmp.json` table definition file is missing from `prisma/dynamodbs/`. Without it, `npm run migrate` cannot create the `import_tmp` DynamoDB table, so the stream ARN is never written to `.env`.

:::warning Known Issue (Fixed in v1.1.1)
In versions prior to v1.1.1, the `import_tmp.json` template was not included in CLI scaffolded projects. This was fixed in [version 1.1.1](/docs/changelog#v111).
:::

**Solution**:

Create `prisma/dynamodbs/import_tmp.json` with the following content:

```json
{
  "TableName": "import_tmp",
  "AttributeDefinitions": [
    { "AttributeName": "pk", "AttributeType": "S" },
    { "AttributeName": "sk", "AttributeType": "S" }
  ],
  "KeySchema": [
    { "AttributeName": "pk", "KeyType": "HASH" },
    { "AttributeName": "sk", "KeyType": "RANGE" }
  ],
  "BillingMode": "PAY_PER_REQUEST",
  "StreamSpecification": {
    "StreamEnabled": true,
    "StreamViewType": "NEW_IMAGE"
  },
  "TableClass": "STANDARD",
  "DeletionProtectionEnabled": true
}
```

Then re-run the migration:

```bash
npm run migrate
```

The migration script will automatically create the table and add the `LOCAL_DDB_IMPORT_TMP_STREAM` entry to your `.env` file.

### Version conflict (HTTP 409) {#version-conflict}

**Symptom**: API returns HTTP 409 Conflict when updating an item.

**Cause**: Two concurrent requests attempted to update the same item with the same version. The framework uses DynamoDB conditional writes (optimistic locking) — when two updates race, the second fails with `ConditionalCheckFailedException`, which the framework converts to HTTP 409.

**Solution**:

1. Retry the update after fetching the latest version:
```typescript
import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';
import { CommandService, DataService, IInvoke } from '@mbc-cqrs-serverless/core';

async function updateWithRetry(
  commandService: CommandService,
  dataService: DataService,
  pk: string,
  sk: string,
  updateData: object,
  invokeContext: IInvoke,
  maxRetries = 3,
) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const current = await dataService.getItem({ pk, sk });
      return await commandService.publishAsync(
        { pk, sk, ...updateData, version: current?.version },
        { invokeContext },
      );
    } catch (error) {
      if (
        error instanceof ConditionalCheckFailedException ||
        (error as Error).name === 'ConditionalCheckFailedException'
      ) {
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded due to version conflicts');
}
```

2. Or use `VERSION_LATEST = -1` to skip version checking (last writer wins):
```typescript
import { VERSION_LATEST } from '@mbc-cqrs-serverless/core';

await commandService.publishAsync(
  { pk, sk, ...updateData, version: VERSION_LATEST },
  { invokeContext },
);
```

See also: [Version Conflict Guide](/docs/version-conflict-guide)

### DynamoDB throughput exceeded

**Symptom**: ProvisionedThroughputExceededException error.

**Solution**:

- For development: Use on-demand billing mode
- For production: Increase provisioned capacity or enable auto-scaling

```typescript
// CDK configuration for on-demand
const table = new dynamodb.Table(this, 'Table', {
  billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
});
```

## Lambda Errors {#lambda-errors}

### Lambda timeout

**Symptom**: Task timed out after X seconds.

**Solution**:

1. Increase timeout in CDK:
```typescript
const handler = new lambda.Function(this, 'Handler', {
  timeout: cdk.Duration.seconds(30),
});
```

2. Optimize cold start:
- Reduce bundle size
- Use provisioned concurrency for critical functions
- Move initialization outside handler

### Lambda out of memory

**Symptom**: Runtime.ExitError or memory limit exceeded.

**Solution**:

```typescript
const handler = new lambda.Function(this, 'Handler', {
  memorySize: 1024, // Increase memory
});
```

### Module not found in Lambda

**Symptom**: Cannot find module 'xxx' error.

**Solution**:

1. Check bundling configuration:
```typescript
// Ensure dependencies are bundled
const handler = new lambda_nodejs.NodejsFunction(this, 'Handler', {
  bundling: {
    externalModules: [], // Don't exclude anything
  },
});
```

2. Verify package.json dependencies are correct

## Authentication Errors {#authentication-errors}

### Cognito token invalid

**Symptom**: 401 Unauthorized or token validation fails.

**Solution**:

1. Verify Cognito configuration:
```bash
# Check USER_POOL_ID and USER_POOL_CLIENT_ID match
COGNITO_USER_POOL_ID=ap-northeast-1_xxxxxx
COGNITO_USER_POOL_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx
```

2. Check token expiration:
- Access tokens expire after 1 hour by default
- Implement token refresh logic

3. Verify issuer URL:
```typescript
const issuer = `https://cognito-idp.${region}.amazonaws.com/${userPoolId}`;
```

### GroupRoleResolver causes DI scope conflict at startup (AP027)

**Symptom**: Application fails to start with a NestJS dependency injection error mentioning a scope conflict or duplicate provider for `GroupRoleResolver`.

**Cause**: The resolver class has both `@GroupRoleResolver()` and `@Injectable()` decorators. `@GroupRoleResolver()` already registers the class as a singleton provider — adding `@Injectable()` creates a conflicting second registration (AP027 anti-pattern).

**Solution**: Remove `@Injectable()` from the resolver class:

```typescript
// Incorrect — causes AP027: both decorators conflict
@Injectable()
@GroupRoleResolver()
export class AppGroupRoleResolver implements IGroupRoleResolver { ... }

// Correct — only @GroupRoleResolver()
@GroupRoleResolver()
export class AppGroupRoleResolver implements IGroupRoleResolver { ... }
```

The `mbc_check_anti_patterns` MCP tool flags this as AP027. See [Authentication — Group-Based Roles](/docs/authentication#group-based-roles) for complete usage.

### CORS errors

**Symptom**: Access-Control-Allow-Origin error in browser.

**Solution**:

1. Configure CORS in API Gateway:
```typescript
const api = new apigateway.HttpApi(this, 'Api', {
  corsPreflight: {
    allowOrigins: ['http://localhost:3000', 'https://your-domain.com'],
    allowMethods: [apigateway.CorsHttpMethod.ANY],
    allowHeaders: ['Authorization', 'Content-Type'],
  },
});
```

2. Ensure OPTIONS requests are handled

## Event Processing {#event-processing}

### Events not being processed

**Symptom**: DynamoDB streams or SQS messages not triggering handlers.

**Solution**:

1. Check event source mapping:
```bash
aws lambda list-event-source-mappings --function-name your-function
```

2. Verify handler is registered:
```typescript
@EventHandler(YourEvent)
export class YourEventHandler implements IEventHandler<YourEvent> {
  async execute(event: YourEvent): Promise<void> {
    // Handler implementation
  }
}
```

3. Check CloudWatch Logs for errors

### Duplicate event processing

**Symptom**: Same event processed multiple times.

**Solution**:

1. Implement idempotency:
```typescript
// Use a unique identifier to check if already processed
// For commands, use pk + sk + version as the idempotency key
const idempotencyKey = `${command.pk}#${command.sk}@${command.version}`;
if (await this.isProcessed(idempotencyKey)) {
  return; // Skip duplicate
}
```

2. Configure SQS visibility timeout appropriately

## Step Functions {#step-functions}

### Step Function execution failed

**Symptom**: State machine execution fails with error.

**Solution**:

1. Check execution history in AWS Console:
   - Go to Step Functions → State machines → Your machine
   - Click on failed execution
   - Review error details in each step

2. Add error handling:
```typescript
// Add retry and catch in state machine definition
{
  "Retry": [
    {
      "ErrorEquals": ["States.TaskFailed"],
      "IntervalSeconds": 2,
      "MaxAttempts": 3,
      "BackoffRate": 2
    }
  ],
  "Catch": [
    {
      "ErrorEquals": ["States.ALL"],
      "Next": "HandleError"
    }
  ]
}
```

### Step Function timeout

**Symptom**: Execution times out.

**Solution**:

- Increase timeout in state machine definition
- Break long-running tasks into smaller steps
- Use wait states with callbacks for async operations

## Deployment Issues {#deployment-issues}

### CDK deployment fails

**Symptom**: cdk deploy fails with CloudFormation error.

**Solution**:

1. Check CloudFormation events:
```bash
aws cloudformation describe-stack-events --stack-name YourStack
```

2. Common causes:
   - IAM permission issues
   - Resource limit exceeded
   - Invalid resource configuration

3. Roll back and fix:
```bash
aws cloudformation delete-stack --stack-name YourStack
# Fix the issue and redeploy
cdk deploy
```

### Resource already exists

**Symptom**: Resource with name X already exists.

**Solution**:

1. Use unique naming:
```typescript
const bucket = new s3.Bucket(this, 'Bucket', {
  bucketName: `${props.appName}-${props.envName}-${cdk.Aws.ACCOUNT_ID}`,
});
```

2. Or let CDK generate names by not specifying bucketName

## Performance Issues {#performance-issues}

### Slow API response times

**Symptom**: API responses take too long.

**Solution**:

1. Enable Lambda provisioned concurrency
2. Implement caching with API Gateway or DAX
3. Optimize database queries
4. Use connection pooling for RDS

### High Lambda costs

**Symptom**: Unexpectedly high Lambda billing.

**Solution**:

1. Review invocation counts and duration
2. Optimize memory allocation (more memory = faster execution)
3. Implement request batching
4. Use reserved concurrency to limit scaling

## Notifications & Real-time Events {#notifications-realtime}

### AppSync Events API not publishing notifications {#appsync-events-not-publishing}

**Symptom**: Clients subscribed via the AppSync Events API do not receive notifications after commands are processed (v1.3.0+).

**Checklist**:

1. Verify the environment variable is set:
```bash
NOTIFICATION_TRANSPORTS=appsync-event
# Or, to dual-publish to both GraphQL and Events API:
NOTIFICATION_TRANSPORTS=appsync-graphql,appsync-event
```

2. Confirm `APPSYNC_EVENTS_ENDPOINT` points to the Events API URL — it ends in `/event`, not `/graphql`:
```bash
# Correct
APPSYNC_EVENTS_ENDPOINT=https://xxxx.appsync-api.ap-northeast-1.amazonaws.com/event
```

3. Check IAM permissions — Lambda/ECS execution role must have `appsync:EventPublish` on the Event API ARN. The CDK template adds this automatically via `grantPublish()`.

4. Verify the channel namespace — `APPSYNC_EVENTS_NAMESPACE` must match a pre-created namespace in your AppSync Event API (default: `default`).

5. Check CloudWatch Logs for publish errors:
```bash
aws logs filter-log-events \
  --log-group-name /aws/lambda/your-function \
  --filter-pattern "appsync"
```

See [AppSync Events API](/docs/notification-module#appsync-events-service) for full setup instructions.

## Getting Help {#getting-help}

If you can't find a solution here:

1. Check the [Debugging Guide](/docs/debugging-guide) for investigation techniques
2. Search existing issues on GitHub
3. Create a new issue with:
   - Clear description of the problem
   - Steps to reproduce
   - Error messages and logs
   - Environment details (Node version, OS, etc.)


## Related Documentation

- [Debugging Guide](/docs/debugging-guide) - Detailed debugging procedures
- [Error Catalog](/docs/error-catalog) - Error codes and solutions
- [Version Conflict Guide](/docs/version-conflict-guide) - Handling HTTP 409 version conflicts
- [Monitoring and Logging](/docs/monitoring-logging) - Production monitoring setup


---

## Debugging Guide

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/debugging-guide

# Debugging Guide

This guide covers debugging techniques for MBC CQRS Serverless applications in both local and AWS environments.

## Local Development Debugging {#local-debugging}

### Using NestJS REPL

The REPL (Read-Eval-Print Loop) allows interactive debugging:

```bash
npm run start:repl
```

In the REPL, you can:

```typescript
// Get a service instance
> get(TodoService)
TodoService { ... }

// Call methods directly
> await get(TodoService).findAll()
[{ id: '1', title: 'Test' }, ...]

// Show available methods on a service
> methods(TodoService)
Methods:
 ◻ findAll
 ◻ findOne
 ◻ create
 ◻ update
 ◻ delete
```

For more details on NestJS REPL, see the [NestJS REPL documentation](https://docs.nestjs.com/recipes/repl).

### VS Code Debugging

Create a `.vscode/launch.json` configuration:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Serverless Offline",
      "program": "${workspaceFolder}/node_modules/.bin/serverless",
      "args": ["offline", "start"],
      "cwd": "${workspaceFolder}/infra-local",
      "env": {
        "NODE_ENV": "development"
      },
      "console": "integratedTerminal"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Tests",
      "program": "${workspaceFolder}/node_modules/.bin/jest",
      "args": ["--runInBand", "--watchAll=false"],
      "console": "integratedTerminal"
    }
  ]
}
```

### Serverless Offline Debugging

Enable detailed logging with Serverless Offline:

```bash
SLS_DEBUG=* npm run offline:sls
```

Or add to serverless.yml:

```yaml
custom:
  serverless-offline:
    httpPort: 3000
    lambdaPort: 3002
    printOutput: true
```

### Console Logging

Use structured logging for easier debugging:

```typescript
import { Logger } from '@nestjs/common';

@Injectable()
export class TodoService {
  private readonly logger = new Logger(TodoService.name);

  async create(dto: CreateTodoDto, invokeContext: IInvoke): Promise<Todo> {
    this.logger.debug(`Creating todo: ${JSON.stringify(dto)}`);

    try {
      const command = { pk: dto.pk, sk: dto.sk, version: 0, name: dto.name, attributes: dto };
      const result = await this.commandService.publishAsync(command, { invokeContext });
      if (!result) throw new Error('Command publish returned null (no-op)');
      this.logger.log(`Todo created: ${result.id}`);
      return result;
    } catch (error) {
      this.logger.error(`Failed to create todo: ${error.message}`, error.stack);
      throw error;
    }
  }
}
```

## DynamoDB Debugging {#dynamodb-debugging}

### View Table Contents

Using AWS CLI with DynamoDB Local:

```bash
# List tables
aws dynamodb list-tables --endpoint-url http://localhost:8000

# Scan table
aws dynamodb scan \
  --table-name your-table-name \
  --endpoint-url http://localhost:8000

# Query by partition key
aws dynamodb query \
  --table-name your-table-name \
  --key-condition-expression "pk = :pk" \
  --expression-attribute-values '{":pk":{"S":"TODO#123"}}' \
  --endpoint-url http://localhost:8000
```

### DynamoDB Streams

Debug stream records:

```typescript
import { DataSyncNewCommandEvent, IEventHandler } from '@mbc-cqrs-serverless/core';

@EventHandler(DataSyncNewCommandEvent)
export class DebugHandler implements IEventHandler<DataSyncNewCommandEvent> {
  async execute(event: DataSyncNewCommandEvent): Promise<void> {
    console.log('DynamoDB stream record:', JSON.stringify(event.dynamodb, null, 2));
    console.log('Event name:', event.eventName);
    console.log('New image:', event.dynamodb?.NewImage);
    console.log('Old image:', event.dynamodb?.OldImage);
  }
}
```

## CloudWatch Logs {#cloudwatch-logs}

### Viewing Logs

Use AWS CLI to tail logs:

```bash
# Find log group
aws logs describe-log-groups --log-group-name-prefix /aws/lambda/your-app

# Tail logs
aws logs tail /aws/lambda/your-app-dev-handler --follow

# Filter logs
aws logs filter-log-events \
  --log-group-name /aws/lambda/your-app-dev-handler \
  --filter-pattern "ERROR"
```

### Log Insights Queries

Use CloudWatch Logs Insights for advanced queries:

```text
# Find errors
fields @timestamp, @message
| filter @message like /ERROR/
| sort @timestamp desc
| limit 100

# Analyze cold starts
fields @timestamp, @message, @duration
| filter @type = "REPORT"
| stats avg(@duration), max(@duration), count(*) by bin(1h)

# Find slow requests
fields @timestamp, @message, @duration
| filter @duration > 3000
| sort @duration desc
| limit 20
```

### Structured Log Analysis

If using structured logging:

```text
fields @timestamp, level, message, context
| filter level = "error"
| sort @timestamp desc
```

## Step Functions Debugging {#step-functions-debugging}

### Execution History

View execution in AWS Console:

1. Go to Step Functions → State machines
2. Select your state machine
3. Click on an execution
4. View the visual workflow with step status

### Event History

Using AWS CLI:

```bash
# List executions
aws stepfunctions list-executions \
  --state-machine-arn arn:aws:states:REGION:ACCOUNT:stateMachine:YourMachine

# Get execution details
aws stepfunctions describe-execution \
  --execution-arn arn:aws:states:REGION:ACCOUNT:execution:YourMachine:execution-id

# Get execution history
aws stepfunctions get-execution-history \
  --execution-arn arn:aws:states:REGION:ACCOUNT:execution:YourMachine:execution-id
```

### Debug with CloudWatch

Enable logging in Step Functions:

```typescript
import * as sfn from 'aws-cdk-lib/aws-stepfunctions';
import * as logs from 'aws-cdk-lib/aws-logs';

const stateMachine = new sfn.StateMachine(this, 'StateMachine', {
  definition: definition,
  logs: {
    destination: new logs.LogGroup(this, 'StateMachineLogGroup'),
    level: sfn.LogLevel.ALL,
  },
  tracingEnabled: true, // Enable X-Ray
});
```

## API Gateway Debugging {#api-gateway-debugging}

### Enable Access Logs

```typescript
import * as apigateway from 'aws-cdk-lib/aws-apigatewayv2';
import * as logs from 'aws-cdk-lib/aws-logs';

const logGroup = new logs.LogGroup(this, 'ApiAccessLogs');
const api = new apigateway.HttpApi(this, 'Api');

const stage = api.defaultStage?.node.defaultChild as apigateway.CfnStage;
stage.accessLogSettings = {
  destinationArn: logGroup.logGroupArn,
  format: JSON.stringify({
    requestId: '$context.requestId',
    ip: '$context.identity.sourceIp',
    method: '$context.httpMethod',
    path: '$context.path',
    status: '$context.status',
    latency: '$context.responseLatency',
    error: '$context.error.message',
  }),
};
```

### Test Endpoints

Use curl with verbose output:

```bash
curl -v -X POST https://your-api.execute-api.region.amazonaws.com/todos \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Todo"}'
```

## X-Ray Tracing {#xray-tracing}

X-Ray tracing is automatically enabled at the CDK level for Lambda functions and API Gateway. SDK-level instrumentation with `aws-xray-sdk` is optional for additional tracing capabilities.

### CDK-Level Configuration

X-Ray is enabled by default in the CDK infrastructure:

```typescript
// Lambda functions have X-Ray tracing enabled by default
const handler = new NodejsFunction(this, 'Handler', {
  // ...
  tracing: lambda.Tracing.ACTIVE, // Enabled by default
});

// Step Functions can also enable X-Ray
const stateMachine = new sfn.StateMachine(this, 'StateMachine', {
  definition: definition,
  tracingEnabled: true, // Enable X-Ray
});
```

### Optional: SDK-Level Instrumentation

For more detailed tracing, you can optionally install and configure the X-Ray SDK:

```bash
npm install aws-xray-sdk
```

```typescript
// Optional: Instrument AWS SDK for detailed tracing
import * as AWSXRay from 'aws-xray-sdk';
import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
const dynamoClient = AWSXRay.captureAWSv3Client(new DynamoDBClient({}));
```

### Add Custom Segments

If you need custom subsegments for detailed tracing:

```typescript
import * as AWSXRay from 'aws-xray-sdk';

async function processOrder(orderId: string): Promise<void> {
  const segment = AWSXRay.getSegment();
  const subsegment = segment?.addNewSubsegment('ProcessOrder');

  try {
    subsegment?.addAnnotation('orderId', orderId);
    // Process order
    subsegment?.addMetadata('result', { status: 'success' });
  } catch (error) {
    subsegment?.addError(error);
    throw error;
  } finally {
    subsegment?.close();
  }
}
```

## Common Debugging Patterns {#common-debugging-patterns}

### Request Correlation

Add correlation IDs to trace requests:

```typescript
import { Injectable, NestMiddleware } from '@nestjs/common';
import { Request, Response, NextFunction } from 'express';
import { v4 as uuidv4 } from 'uuid';

@Injectable()
export class CorrelationMiddleware implements NestMiddleware {
  use(req: Request, res: Response, next: NextFunction) {
    const correlationId = req.headers['x-correlation-id'] || uuidv4();
    req['correlationId'] = correlationId;
    res.setHeader('x-correlation-id', correlationId);
    next();
  }
}
```

### Debug Environment Variables

```typescript
// Log environment on startup (development only)
if (process.env.NODE_ENV === 'development') {
  console.log('Environment:', {
    NODE_ENV: process.env.NODE_ENV,
    AWS_REGION: process.env.AWS_REGION,
    DATABASE_URL: process.env.DATABASE_URL ? '[SET]' : '[NOT SET]',
  });
}
```

### Conditional Debugging

```typescript
const DEBUG = process.env.DEBUG === 'true';

function debugLog(message: string, data?: any): void {
  if (DEBUG) {
    console.log(`[DEBUG] ${message}`, data ? JSON.stringify(data, null, 2) : '');
  }
}
```

## Troubleshooting Checklist {#troubleshooting-checklist}

When debugging an issue:

1. **Reproduce locally**: Can you reproduce in local environment?
2. **Check logs**: Review CloudWatch Logs for errors
3. **Verify configuration**: Check environment variables and settings
4. **Test isolation**: Test components individually
5. **Check permissions**: Verify IAM roles and policies
6. **Review recent changes**: What changed since it last worked?
7. **Check dependencies**: Are all services healthy?

## Local Step Functions Debugging {#local-step-functions-debugging}

The framework includes support for AWS Step Functions Local, allowing you to test and debug Step Functions workflows in your local development environment.

### Starting Step Functions Local

Step Functions Local runs as a Docker container alongside other local services:

```bash
# Start all local services including Step Functions
cd infra-local
docker-compose up -d
```

The Step Functions Local service runs on port 8083 and connects to your local Lambda functions.

### Creating State Machines Locally

Use the AWS CLI to create state machines in Step Functions Local:

```bash
# Create state machine from definition
aws stepfunctions create-state-machine \
  --endpoint-url http://localhost:8083 \
  --name command \
  --definition file://state-machine-definition.json \
  --role-arn "arn:aws:iam::101010101010:role/DummyRole"
```

### Starting and Monitoring Executions

Start and monitor Step Functions executions locally:

```bash
# Start an execution
aws stepfunctions start-execution \
  --endpoint-url http://localhost:8083 \
  --state-machine-arn arn:aws:states:ap-northeast-1:101010101010:stateMachine:command \
  --input '{"pk":"TODO#tenant","sk":"item#001@1"}'

# List executions
aws stepfunctions list-executions \
  --endpoint-url http://localhost:8083 \
  --state-machine-arn arn:aws:states:ap-northeast-1:101010101010:stateMachine:command

# Get execution history
aws stepfunctions get-execution-history \
  --endpoint-url http://localhost:8083 \
  --execution-arn arn:aws:states:ap-northeast-1:101010101010:execution:command:execution-id
```

### Debugging waitForTaskToken

When debugging Step Functions that use waitForTaskToken (like the command processing workflow), you can manually send task success or failure:

```bash
# Send task success
aws stepfunctions send-task-success \
  --endpoint-url http://localhost:8083 \
  --task-token "YOUR_TASK_TOKEN" \
  --task-output '{"Payload":[[{"result":0}]]}'

# Send task failure
aws stepfunctions send-task-failure \
  --endpoint-url http://localhost:8083 \
  --task-token "YOUR_TASK_TOKEN" \
  --cause "Debug failure" \
  --error "TestError"
```

## Production Debugging with CloudWatch {#production-debugging}

### Lambda Log Analysis

Each Lambda function writes logs to CloudWatch. Use these patterns to analyze production issues:

```bash
# Find log groups for your application
aws logs describe-log-groups \
  --log-group-name-prefix /aws/lambda/prod-myapp

# Get recent log events
aws logs get-log-events \
  --log-group-name /aws/lambda/prod-myapp-handler \
  --log-stream-name '2024/01/15/[$LATEST]abc123' \
  --limit 100

# Filter for errors in the last hour
aws logs filter-log-events \
  --log-group-name /aws/lambda/prod-myapp-handler \
  --start-time $(( $(date +%s) - 3600 ))000 \
  --filter-pattern "ERROR"
```

### Step Functions Execution Analysis

For production Step Functions debugging:

```bash
# List failed executions
aws stepfunctions list-executions \
  --state-machine-arn arn:aws:states:REGION:ACCOUNT:stateMachine:command \
  --status-filter FAILED

# Get detailed execution history
aws stepfunctions get-execution-history \
  --execution-arn arn:aws:states:REGION:ACCOUNT:execution:command:exec-id \
  --include-execution-data

# Describe execution for input/output
aws stepfunctions describe-execution \
  --execution-arn arn:aws:states:REGION:ACCOUNT:execution:command:exec-id
```

### CloudWatch Logs Insights for CQRS

Use these CloudWatch Logs Insights queries tailored for MBC CQRS applications:

```text
# Find version conflicts
fields @timestamp, @message
| filter @message like /version mismatch|version not match|ConditionalCheckFailed/
| sort @timestamp desc
| limit 50

# Track command processing
fields @timestamp, @message
| filter @message like /publish|publishSync|publishAsync/
| parse @message "pk=* sk=*" as pk, sk
| sort @timestamp desc
| limit 100

# Analyze data sync operations
fields @timestamp, @message
| filter @message like /DataSyncHandler|sync_data/
| sort @timestamp desc
| limit 100

# Find Step Functions timeouts
fields @timestamp, @message
| filter @message like /waitForTaskToken|taskToken/
| sort @timestamp desc
| limit 50
```

## Version Conflict Debugging {#version-conflict-debugging}

Version conflicts occur when multiple processes attempt to update the same item simultaneously. The framework uses optimistic locking to ensure data consistency.

### Understanding Version Numbers

In MBC CQRS Serverless, version management works as follows:

- Command table sort key format: `TYPE#code@version` (e.g., `TODO#001@3`); data table sort key omits the `@version` suffix
- Version separator: `@`
- VERSION_FIRST: `0` (initial version)
- VERSION_LATEST: `-1` (auto-fetch latest version)

### Identifying Version Conflicts

Check the command table for version history:

```bash
# Query all versions of an item
aws dynamodb query \
  --table-name prod-myapp-command \
  --endpoint-url http://localhost:8000 \
  --key-condition-expression "pk = :pk AND begins_with(sk, :sk)" \
  --expression-attribute-values '{
    ":pk": {"S": "TODO#tenant"},
    ":sk": {"S": "TODO#001@"}
  }' \
  --scan-index-forward false
```

### Resolving Version Conflicts

```typescript
// Option 1: Use VERSION_LATEST (-1) for auto-versioning
await commandService.publishPartialUpdateAsync({
  pk: 'TODO#tenant',
  sk: 'TODO#001',
  version: -1,  // Auto-fetches latest version
  name: 'Updated Name',
}, options);

// Option 2: Fetch and retry pattern
async function updateWithRetry(pk: string, sk: string, updates: any, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const latest = await dataService.getItem({ pk, sk });
      return await commandService.publishPartialUpdateSync({
        pk,
        sk,
        version: latest.version,
        ...updates,
      }, options);
    } catch (error) {
      if (error.message.includes('version mismatch') && i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, 100 * Math.pow(2, i)));
        continue;
      }
      throw error;
    }
  }
}
```

## Inspecting DynamoDB Command History {#inspecting-command-history}

The command table stores a complete history of all commands, enabling full audit trails and debugging.

### Table Structure

The framework uses two DynamoDB tables per module:

- `{env}-{app}-{module}-command`: Stores command history with versions
- `{env}-{app}-{module}-data`: Stores current state (latest version)

### Querying Command History

```bash
# Get the latest version from data table
aws dynamodb get-item \
  --table-name dev-myapp-sample-data \
  --endpoint-url http://localhost:8000 \
  --key '{"pk":{"S":"TODO#tenant"},"sk":{"S":"TODO#001"}}'

# Get all command versions
aws dynamodb query \
  --table-name dev-myapp-sample-command \
  --endpoint-url http://localhost:8000 \
  --key-condition-expression "pk = :pk AND begins_with(sk, :sk)" \
  --expression-attribute-values '{
    ":pk": {"S": "TODO#tenant"},
    ":sk": {"S": "TODO#001@"}
  }' \
  --projection-expression "pk, sk, version, createdAt, createdBy, #s, requestId" \
  --expression-attribute-names '{"#s": "source"}' \
  --scan-index-forward false

# Get a specific version
aws dynamodb get-item \
  --table-name dev-myapp-sample-command \
  --endpoint-url http://localhost:8000 \
  --key '{"pk":{"S":"TODO#tenant"},"sk":{"S":"TODO#001@3"}}'
```

### Using DynamoDB Admin UI

DynamoDB Admin provides a web interface for browsing local DynamoDB tables:

1. Access http://localhost:8001 when running local services
2. Select your table (e.g., `dev-myapp-sample-command`)
3. Use filters to find specific items by pk or sk

### Programmatic History Access

```typescript
import { DynamoDbService } from '@mbc-cqrs-serverless/core';

// Get all versions of an item
async function getCommandHistory(pk: string, baseSk: string) {
  const result = await dynamoDbService.listItemsByPk(
    commandTableName,
    pk,
    {
      skExpression: 'begins_with(sk, :sk)',
      skAttributeValues: { ':sk': `${baseSk}@` },
    },
    undefined,
    100,
    'desc', // Latest first
  );
  return result.items;
}
```

## Common Debugging Scenarios {#debugging-scenarios}

### Scenario 1: Command Not Appearing in Data Table

Symptoms: Command was published but data table shows old version.

Debugging steps:

1. Check command table for the new version:
   ```bash
   aws dynamodb query --table-name dev-myapp-sample-command \
     --endpoint-url http://localhost:8000 \
     --key-condition-expression "pk = :pk" \
     --expression-attribute-values '{":pk":{"S":"TODO#tenant"}}' \
     --scan-index-forward false --limit 5
   ```

2. Check DynamoDB Streams is enabled and processing:
   - Verify LOCAL_DDB_SAMPLE_STREAM is set in .env
   - Check Lambda logs for stream processing errors

3. Check Step Functions execution:
   ```bash
   aws stepfunctions list-executions \
     --endpoint-url http://localhost:8083 \
     --state-machine-arn arn:aws:states:ap-northeast-1:101010101010:stateMachine:command \
     --status-filter RUNNING
   ```

4. Verify data sync handlers are registered:
   ```typescript
   // Check in your module
   @Module({
     imports: [
       CommandModule.register({
         tableName: 'sample',
         dataSyncHandlers: [YourSyncHandler], // Ensure registered
       }),
     ],
   })
   ```

### Scenario 2: Step Function Stuck in RUNNING State

Symptoms: Step Functions execution never completes.

Debugging steps:

1. Get execution details:
   ```bash
   aws stepfunctions describe-execution \
     --endpoint-url http://localhost:8083 \
     --execution-arn YOUR_EXECUTION_ARN
   ```

2. Check if waiting for taskToken:
   - If stuck at `wait_prev_command`, a previous version is still processing
   - Check if the previous command's taskToken callback was sent

3. Check command table for taskToken:
   ```bash
   aws dynamodb get-item \
     --table-name dev-myapp-sample-command \
     --endpoint-url http://localhost:8000 \
     --key '{"pk":{"S":"TODO#tenant"},"sk":{"S":"TODO#001@2"}}' \
     --projection-expression "taskToken, version, #s" \
     --expression-attribute-names '{"#s": "status"}'
   ```

4. Manually resume if needed (for debugging only):
   ```bash
   aws stepfunctions send-task-success \
     --endpoint-url http://localhost:8083 \
     --task-token "TASK_TOKEN_FROM_COMMAND" \
     --task-output '{"Payload":[[{"result":0}]]}'
   ```

### Scenario 3: Duplicate Commands Being Processed

Symptoms: Same command processed multiple times.

Debugging steps:

1. Check for multiple versions with same data:
   ```bash
   aws dynamodb query --table-name dev-myapp-sample-command \
     --endpoint-url http://localhost:8000 \
     --key-condition-expression "pk = :pk AND begins_with(sk, :sk)" \
     --expression-attribute-values '{":pk":{"S":"TODO#tenant"},":sk":{"S":"TODO#001@"}}' \
     --projection-expression "sk, version, requestId, createdAt"
   ```

2. Compare requestId values to identify duplicate submissions

3. Check if client is retrying on timeout:
   - Review client-side error handling
   - Implement idempotency keys

### Scenario 4: Data Sync Handler Not Executing

Symptoms: Command saved but external systems not updated.

Debugging steps:

1. Verify handler is decorated correctly:
   ```typescript
   @DataSyncHandler('sample')
   export class CustomSyncHandler implements IDataSyncHandler {
     // ...
   }
   ```

2. Check if handler is discovered:
   - Enable debug logging: `DEBUG=* npm run offline`
   - Look for "find data sync handlers from decorator" message

3. Add debugging to handler:
   ```typescript
   async up(command: CommandModel): Promise<void> {
     this.logger.debug(`CustomSyncHandler.up called: ${command.pk}#${command.sk}`);
     // Your sync logic
   }
   ```

### Scenario 5: X-Ray Traces Not Appearing

Symptoms: X-Ray service map or traces not visible.

Debugging steps:

1. Verify X-Ray is enabled in CDK:
   ```typescript
   // Check Lambda function configuration
   const handler = new NodejsFunction(this, 'Handler', {
     tracing: lambda.Tracing.ACTIVE, // Should be ACTIVE
   });
   ```

2. Check IAM permissions include X-Ray:
   ```json
   {
     "Effect": "Allow",
     "Action": [
       "xray:PutTraceSegments",
       "xray:PutTelemetryRecords"
     ],
     "Resource": "*"
   }
   ```

3. For SDK instrumentation, verify setup:
   ```typescript
   import * as AWSXRay from 'aws-xray-sdk';
   import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
   // Wrap each AWS SDK v3 client with X-Ray for instrumentation
   const dynamoClient = AWSXRay.captureAWSv3Client(new DynamoDBClient({}));
   ```

## Related Documentation

- [Common Issues](/docs/common-issues) - Frequently encountered problems and solutions
- [Monitoring and Logging](/docs/monitoring-logging) - Set up comprehensive monitoring
- [Error Catalog](/docs/error-catalog) - Error codes and resolution steps
- [Version Conflict Guide](/docs/version-conflict-guide) - Resolving optimistic locking conflicts
- [E2E Testing](/docs/e2e-test) - End-to-end testing for debugging
- [Unit Testing](/docs/unit-test) - Unit testing with Jest


---

# Examples

## E-commerce Example

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/ecommerce-example

# E-commerce Example

This example demonstrates a complete e-commerce implementation with order management, inventory tracking, and multi-tenant support using MBC CQRS Serverless.

## Overview {#overview}

The e-commerce example covers:

- Order lifecycle management (create, update, cancel)
- Inventory tracking with optimistic locking
- Multi-tenant storefront isolation
- Event-driven order processing

## Data Model {#data-model}

### Key Structure

```text
Partition Key (pk)           Sort Key (sk)
──────────────────────────────────────────────────
TENANT#shop-a                    ORDER#ORD-000001
TENANT#shop-a                    ORDER#ORD-000002
TENANT#shop-a                    PRODUCT#PRD-001
TENANT#shop-a                    INVENTORY#PRD-001
TENANT#shop-b                    ORDER#ORD-000001
```

### Entity Definitions

```typescript
export interface OrderItem {
  productCode: string;
  quantity: number;
  unitPrice: number;
}

export interface Address {
  street: string;
  city: string;
  state: string;
  postalCode: string;
  country: string;
}

// Order Entity
export interface OrderAttributes {
  customerId: string;
  items: OrderItem[];
  shippingAddress: Address;
  paymentMethod: string;
  subtotal: number;
  tax: number;
  total: number;
  status: OrderStatus;
  placedAt: string;
  shippedAt?: string;
  deliveredAt?: string;
}

export type OrderStatus =
  | 'pending'
  | 'confirmed'
  | 'processing'
  | 'shipped'
  | 'delivered'
  | 'cancelled';

// Product Entity
export interface ProductAttributes {
  categoryCode: string;
  sku: string;
  price: number;
  currency: string;
  description: string;
  images: string[];
  isActive: boolean;
}

// Inventory Entity
export interface InventoryAttributes {
  productCode: string;
  quantity: number;
  reservedQuantity: number;
  warehouseCode: string;
  lastRestockedAt: string;
}
```

## Module Implementation {#module-implementation}

### Order Module

```typescript
// order.module.ts
import { Module } from '@nestjs/common';
import { CommandModule } from '@mbc-cqrs-serverless/core';
import { SequencesModule } from '@mbc-cqrs-serverless/sequence';
import { OrderController } from './order.controller';
import { OrderService } from './order.service';
import { OrderDataSyncHandler } from './order-data-sync.handler';

@Module({
  imports: [
    CommandModule.register({
      tableName: 'order',
      dataSyncHandlers: [OrderDataSyncHandler],
    }),
    SequencesModule,
  ],
  controllers: [OrderController],
  providers: [OrderService],
  exports: [OrderService],
})
export class OrderModule {}
```

### Order Service

```typescript
// order.service.ts
import { Injectable, NotFoundException, BadRequestException } from '@nestjs/common';
import {
  CommandService,
  DataService,
  IInvoke,
  KEY_SEPARATOR,
  VERSION_FIRST,
  getUserContext,
} from '@mbc-cqrs-serverless/core';
import { SequencesService } from '@mbc-cqrs-serverless/sequence';

// Example helper: per-tenant partition key
const generatePk = (tenantCode: string): string =>
  `TENANT${KEY_SEPARATOR}${tenantCode}`;


@Injectable()
export class OrderService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly sequencesService: SequencesService,
  ) {}

  // Create a new order
  async createOrder(dto: CreateOrderDto, context: IInvoke) {
    const { tenantCode } = getUserContext(context);

    // Generate unique order number
    const sequence = await this.sequencesService.generateSequenceItem(
      { tenantCode, typeCode: 'ORDER' },
      { invokeContext: context },
    );
    const orderCode = sequence.formattedNo;

    // Calculate totals
    const subtotal = dto.items.reduce(
      (sum, item) => sum + item.price * item.quantity,
      0
    );
    const tax = subtotal * 0.1; // 10% tax
    const total = subtotal + tax;

    const command = {
      pk: generatePk(tenantCode),
      sk: `ORDER#${orderCode}`,
      version: VERSION_FIRST,
      code: orderCode,
      name: `Order ${orderCode}`,
      tenantCode,
      attributes: {
        customerId: dto.customerId,
        items: dto.items,
        shippingAddress: dto.shippingAddress,
        paymentMethod: dto.paymentMethod,
        subtotal,
        tax,
        total,
        status: 'pending' as OrderStatus,
        placedAt: new Date().toISOString(),
      },
    };

    return this.commandService.publishAsync(command, { invokeContext: context });
  }

  // Update order status
  async updateOrderStatus(
    orderCode: string,
    newStatus: OrderStatus,
    context: IInvoke,
  ) {
    const { tenantCode } = getUserContext(context);
    const pk = generatePk(tenantCode);
    const sk = `ORDER#${orderCode}`;

    // Fetch current order
    const current = await this.dataService.getItem({ pk, sk });
    if (!current) {
      throw new NotFoundException(`Order ${orderCode} not found`);
    }

    // Validate status transition
    this.validateStatusTransition(current.attributes.status, newStatus);

    // Build update command with version for optimistic locking
    const command = {
      ...current,
      version: current.version, // Required for optimistic locking
      attributes: {
        ...current.attributes,
        status: newStatus,
        ...(newStatus === 'shipped' && { shippedAt: new Date().toISOString() }),
        ...(newStatus === 'delivered' && { deliveredAt: new Date().toISOString() }),
      },
    };

    return this.commandService.publishAsync(command, { invokeContext: context });
  }

  // List orders with pagination
  async listOrders(options: ListOrdersDto, context: IInvoke) {
    const { tenantCode } = getUserContext(context);

    return this.dataService.listItemsByPk(generatePk(tenantCode), {
      sk: {
        skExpression: 'begins_with(sk, :prefix)',
        skAttributeValues: { ':prefix': 'ORDER#' },
      },
      limit: options.limit || 20,
      startFromSk: options.cursor,
    });
  }

  // Validate order status transitions
  private validateStatusTransition(current: OrderStatus, next: OrderStatus) {
    const validTransitions: Record<OrderStatus, OrderStatus[]> = {
      pending: ['confirmed', 'cancelled'],
      confirmed: ['processing', 'cancelled'],
      processing: ['shipped', 'cancelled'],
      shipped: ['delivered'],
      delivered: [],
      cancelled: [],
    };

    if (!validTransitions[current].includes(next)) {
      throw new BadRequestException(
        `Cannot transition from ${current} to ${next}`
      );
    }
  }
}
```

### Order Controller

```typescript
// order.controller.ts
import { Controller, Get, Post, Patch, Body, Param, Query } from '@nestjs/common';
import { ApiTags, ApiOperation } from '@nestjs/swagger';
import { INVOKE_CONTEXT, IInvoke } from '@mbc-cqrs-serverless/core';
import { OrderService } from './order.service';

@ApiTags('orders')
@Controller('orders')
export class OrderController {
  constructor(private readonly orderService: OrderService) {}

  @Post()
  @ApiOperation({ summary: 'Create a new order' })
  async create(
    @Body() dto: CreateOrderDto,
    @INVOKE_CONTEXT() invokeContext: IInvoke,
  ) {
    return this.orderService.createOrder(dto, invokeContext);
  }

  @Get()
  @ApiOperation({ summary: 'List orders' })
  async list(
    @Query() options: ListOrdersDto,
    @INVOKE_CONTEXT() invokeContext: IInvoke,
  ) {
    return this.orderService.listOrders(options, invokeContext);
  }

  @Patch(':code/status')
  @ApiOperation({ summary: 'Update order status' })
  async updateStatus(
    @Param('code') code: string,
    @Body() dto: UpdateStatusDto,
    @INVOKE_CONTEXT() invokeContext: IInvoke,
  ) {
    return this.orderService.updateOrderStatus(code, dto.status, invokeContext);
  }
}
```

## Inventory Management {#inventory-management}

### Inventory Service

```typescript
// inventory.service.ts
import { Injectable, ConflictException, NotFoundException } from '@nestjs/common';
import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';
import { CommandService, DataService, KEY_SEPARATOR } from '@mbc-cqrs-serverless/core';
import { OrderItem } from './order.service';

const generatePk = (tenantCode: string): string =>
  `TENANT${KEY_SEPARATOR}${tenantCode}`;

@Injectable()
export class InventoryService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
  ) {}

  // Reserve inventory for order
  // tenantCode is passed directly so this method can be called from both
  // controllers (use getUserContext) and DataSyncHandlers (use cmd.tenantCode)
  async reserveInventory(
    items: OrderItem[],
    tenantCode: string,
  ): Promise<void> {
    const pk = generatePk(tenantCode);

    for (const item of items) {
      const sk = `INVENTORY#${item.productCode}`;
      const inventory = await this.dataService.getItem({ pk, sk });

      if (!inventory) {
        throw new NotFoundException(`Product ${item.productCode} not found`);
      }

      const available =
        inventory.attributes.quantity - inventory.attributes.reservedQuantity;

      if (available < item.quantity) {
        throw new ConflictException(
          `Insufficient inventory for ${item.productCode}: ` +
          `requested ${item.quantity}, available ${available}`
        );
      }

      // Update with optimistic locking
      const command = {
        ...inventory,
        version: inventory.version,
        attributes: {
          ...inventory.attributes,
          reservedQuantity:
            inventory.attributes.reservedQuantity + item.quantity,
        },
      };

      try {
        await this.commandService.publishAsync(command, {});
      } catch (error) {
        if (error instanceof ConditionalCheckFailedException) {
          // Retry on concurrent modification
          throw new ConflictException(
            'Inventory was modified, please retry'
          );
        }
        throw error;
      }
    }
  }

  // Release reserved inventory
  async releaseInventory(
    items: OrderItem[],
    tenantCode: string,
  ): Promise<void> {
    const pk = generatePk(tenantCode);

    for (const item of items) {
      const sk = `INVENTORY#${item.productCode}`;
      const inventory = await this.dataService.getItem({ pk, sk });

      if (!inventory) continue;

      const command = {
        ...inventory,
        version: inventory.version,
        attributes: {
          ...inventory.attributes,
          reservedQuantity: Math.max(
            0,
            inventory.attributes.reservedQuantity - item.quantity
          ),
        },
      };

      await this.commandService.publishAsync(command, {});
    }
  }

  // Deduct inventory after shipment
  async deductInventory(
    items: OrderItem[],
    tenantCode: string,
  ): Promise<void> {
    const pk = generatePk(tenantCode);

    for (const item of items) {
      const sk = `INVENTORY#${item.productCode}`;
      const inventory = await this.dataService.getItem({ pk, sk });

      if (!inventory) continue;

      const command = {
        ...inventory,
        version: inventory.version,
        attributes: {
          ...inventory.attributes,
          quantity: inventory.attributes.quantity - item.quantity,
          reservedQuantity:
            inventory.attributes.reservedQuantity - item.quantity,
        },
      };

      await this.commandService.publishAsync(command, {});
    }
  }
}
```

## Event-Driven Processing {#event-driven-processing}

### Order Data Sync Handler

```typescript
// order-data-sync.handler.ts
import { Injectable, Logger } from '@nestjs/common';
import {
  CommandModel,
  DataSyncHandler,
  IDataSyncHandler,
  VERSION_FIRST,
} from '@mbc-cqrs-serverless/core';
import { InventoryService } from '../inventory/inventory.service';
import { NotificationService } from '../notification/notification.service';

@DataSyncHandler('order')
@Injectable()
export class OrderDataSyncHandler implements IDataSyncHandler {
  private readonly logger = new Logger(OrderDataSyncHandler.name);

  constructor(
    private readonly inventoryService: InventoryService,
    private readonly notificationService: NotificationService,
  ) {}

  async up(cmd: CommandModel): Promise<any> {
    // Filter for order events only
    if (!cmd.sk.startsWith('ORDER#')) {
      return;
    }

    // First write: stored version is VERSION_FIRST + 1
    if (cmd.version === VERSION_FIRST + 1) {
      this.logger.log(`New order created: ${cmd.code}`);
      await this.handleNewOrder(cmd);
      return;
    }

    // Later versions are updates such as status changes
    await this.handleStatusChange(cmd);
  }

  async down(cmd: CommandModel): Promise<any> {
    // Optional rollback logic when a sync step fails
  }

  private async handleNewOrder(order: CommandModel) {
    // Reserve inventory
    try {
      await this.inventoryService.reserveInventory(order.attributes.items, order.tenantCode);
    } catch (error) {
      this.logger.error(`Failed to reserve inventory: ${error.message}`);
      // Send notification to operations team
      await this.notificationService.sendAlert({
        type: 'inventory_reservation_failed',
        orderId: order.code,
        error: error.message,
      });
    }

    // Send order confirmation email
    await this.notificationService.sendOrderConfirmation(order);
  }

  private async handleStatusChange(order: CommandModel) {
    const status = order.attributes.status;
    this.logger.log(`Order ${order.code} status changed to: ${status}`);

    switch (status) {
      case 'cancelled':
        // Release reserved inventory
        await this.inventoryService.releaseInventory(order.attributes.items, order.tenantCode);
        await this.notificationService.sendCancellationNotice(order);
        break;

      case 'shipped':
        // Deduct from inventory
        await this.inventoryService.deductInventory(order.attributes.items, order.tenantCode);
        await this.notificationService.sendShippingNotification(order);
        break;

      case 'delivered':
        await this.notificationService.sendDeliveryConfirmation(order);
        break;
    }
  }
}
```

## API Endpoints {#api-endpoints}

| Method | Endpoint | Description |
|------------|--------------|-----------------|
| POST | `/orders` | Create new order |
| GET | `/orders` | List orders with pagination |
| GET | `/orders/:code` | Get order details |
| PATCH | `/orders/:code/status` | Update order status |
| POST | `/products` | Create product |
| GET | `/products` | List products |
| PATCH | `/inventory/:productCode` | Update inventory |

## Request/Response Examples {#request-response-examples}

### Create Order

```json
// POST /orders
// Request
{
  "customerId": "CUST-001",
  "items": [
    {
      "productCode": "PRD-001",
      "name": "Wireless Mouse",
      "quantity": 2,
      "price": 29.99
    }
  ],
  "shippingAddress": {
    "street": "123 Main St",
    "city": "Tokyo",
    "postalCode": "100-0001",
    "country": "JP"
  },
  "paymentMethod": "credit_card"
}

// Response
{
  "pk": "TENANT#shop-a",
  "sk": "ORDER#ORD-000001@1",
  "code": "ORD-000001",
  "name": "Order ORD-000001",
  "version": 1,
  "attributes": {
    "customerId": "CUST-001",
    "items": [...],
    "subtotal": 59.98,
    "tax": 6.00,
    "total": 65.98,
    "status": "pending",
    "placedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

## Best Practices {#best-practices}

### 1. Inventory Consistency

Always use optimistic locking when modifying inventory to prevent overselling:

```typescript
const command = {
  ...inventory,
  version: inventory.version, // Include current version
  attributes: { ... }
};
```

### 2. Status Validation

Define allowed transitions and validate before updating:

```typescript
const validTransitions = {
  pending: ['confirmed', 'cancelled'],
  confirmed: ['processing', 'cancelled'],
  // ...
};
```

### 3. Idempotency

Use sequence numbers or UUIDs to ensure operations are idempotent:

```typescript
const orderCode = `ORD-${String(sequence.value).padStart(6, '0')}`;
```

## Related Documentation

- [SaaS Example](/docs/saas-example) - SaaS application example
- [Backend Development](/docs/backend-development) - Core backend implementation patterns
- [Service Patterns](/docs/service-patterns) - CRUD patterns used
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Multi-tenant design
- [Sequence](/docs/sequence) - Auto-incrementing order number generation
- [Event Handling Patterns](/docs/event-handling-patterns) - Event-driven order processing


---

## Examples

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/recipes

# Examples

This section provides practical examples and implementation guides for common use cases. Each example demonstrates real-world scenarios with complete, production-ready code.

## Available Examples {#available-examples}

| Example | Description | Key Concepts |
|-------------|-----------------|------------------|
| [Todo App Tutorial](/docs/build-todo-app) | Step-by-step CQRS app with full CRUD | Commands, queries, RDS sync, sequences |
| [E-commerce](/docs/ecommerce-example) | Order management with inventory tracking | Optimistic locking, event-driven sync, status transitions |
| [SaaS Application](/docs/saas-example) | Multi-tenant subscription and usage metering | Tenant isolation, quota enforcement, billing integration |
| [Survey Template](/docs/survey-template) | Dynamic form builder with validation | Schema design, versioning, complex attributes |

## Implementation Patterns {#implementation-patterns}

Each example follows consistent patterns:

### 1. Entity Design

```typescript
// Define your entity with proper key structure
export class OrderEntity extends DataEntity {
  pk: string;           // ORDER#tenantCode
  sk: string;           // ORDER#orderId
  id: string;
  tenantCode: string;
  code: string;
  name: string;
  attributes: OrderAttributes;
}
```

### 2. Command Pattern

```typescript
// Create commands for state changes
import { VERSION_FIRST, generateId } from '@mbc-cqrs-serverless/core';

async createOrder(dto: CreateOrderDto, context: IInvoke) {
  const orderId = await this.sequencesService.generateSequenceItem(
    {
      tenantCode: dto.tenantCode,
      typeCode: 'ORDER',
    },
    { invokeContext: context },
  );
  const pk = `ORDER#${dto.tenantCode}`;
  const sk = `ORDER#${orderId.formattedNo}`;
  return this.commandService.publishAsync(
    {
      pk,
      sk,
      id: generateId(pk, sk),           // Required: unique identifier (pk#sk)
      code: orderId.formattedNo,
      name: dto.name,
      version: VERSION_FIRST,            // Required: VERSION_FIRST (0) for new entities
      tenantCode: dto.tenantCode,
      type: 'ORDER',                     // Required: entity type
      attributes: dto.attributes,
    },
    { invokeContext: context },
  );
}
```

### 3. Query Pattern

```typescript
// Query data with proper filtering
async listOrders(tenantCode: string, options: ListOptions) {
  return this.dataService.listItemsByPk(
    `ORDER#${tenantCode}`,
    {
      limit: options.limit,
      startFromSk: options.lastSk,
    },
  );
}
```

### 4. Event Handler

```typescript
// Handle data sync events
import { EventHandler, IEventHandler } from '@mbc-cqrs-serverless/core';
import { Injectable } from '@nestjs/common';
import { PrismaService } from 'src/prisma';

@EventHandler(OrderDataSyncEvent)
@Injectable()
export class OrderDataSyncHandler implements IEventHandler<OrderDataSyncEvent> {
  constructor(private readonly prisma: PrismaService) {}

  async execute(event: OrderDataSyncEvent): Promise<void> {
    // Sync to read model (RDS, OpenSearch, etc.)
    await this.prisma.order.upsert({
      where: { sk: event.data.sk },
      create: { sk: event.data.sk, ...event.data.attributes },
      update: event.data.attributes,
    });
  }
}
```

## Best Practices {#best-practices}

### Key Design

- Use consistent prefix patterns: `TENANT#code`, `ORDER#id`
- Keep partition keys broad enough for even distribution
- Use sort keys for hierarchical data

### Error Handling

```typescript
import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';
import { ConflictException } from '@nestjs/common';

try {
  await this.commandService.publishAsync(command, options);
} catch (error) {
  if (error instanceof ConditionalCheckFailedException) {
    // Handle optimistic locking conflict (version mismatch)
    throw new ConflictException('Item was modified by another process');
  }
  throw error;
}
```

### Testing

```typescript
describe('OrderService', () => {
  it('should create order with sequence', async () => {
    const result = await service.createOrder(mockDto, mockContext);
    expect(result.code).toMatch(/^ORD-\d{6}$/);
  });
});
```

## Explore Examples {#explore-examples}

```mdx-code-block
import DocCardList from '@theme/DocCardList';

<DocCardList />
```


## Related Documentation

- [Service Patterns](/docs/service-patterns) - CRUD service patterns
- [Backend Development](/docs/backend-development) - Core backend guide
- [Key Patterns](/docs/key-patterns) - Key design for recipes


---

## SaaS Application Example

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/saas-example

# SaaS Application Example

This example demonstrates a multi-tenant SaaS application with subscription management, usage tracking, and billing integration using MBC CQRS Serverless.

## Overview {#overview}

The SaaS example covers:

- Multi-tenant isolation with tenant hierarchy
- Subscription and plan management
- Usage metering and quota enforcement
- Billing event generation

## Data Model {#data-model}

### Key Structure

```text
Partition Key (pk)           Sort Key (sk)
──────────────────────────────────────────────────
TENANT#acme-corp                 SUBSCRIPTION#SUB-001
TENANT#acme-corp                 USAGE#2024-01
TENANT#acme-corp                 USER#usr-001
TENANT#acme-corp                 APIKEY#key-001
MASTER#common                    PLAN#starter
MASTER#common                    PLAN#professional
MASTER#common                    PLAN#enterprise
```

### Entity Definitions

```typescript
// Plan Entity (Master Data)
export interface PlanAttributes {
  displayName: string;
  monthlyPrice: number;
  yearlyPrice: number;
  currency: string;
  features: PlanFeature[];
  limits: PlanLimits;
  isActive: boolean;
}

export interface PlanLimits {
  maxUsers: number;
  maxApiCalls: number;
  maxStorageGb: number;
  maxProjects: number;
}

// Subscription Entity
export interface SubscriptionAttributes {
  planCode: string;
  billingCycle: 'monthly' | 'yearly';
  status: SubscriptionStatus;
  startDate: string;
  endDate: string;
  autoRenew: boolean;
  paymentMethodId?: string;
}

export type SubscriptionStatus =
  | 'active'
  | 'trial'
  | 'past_due'
  | 'cancelled'
  | 'expired';

// Usage Entity
export interface UsageAttributes {
  period: string; // YYYY-MM
  apiCalls: number;
  storageUsedGb: number;
  activeUsers: number;
  projectCount: number;
  lastUpdatedAt: string;
}
```

## Tenant Management {#tenant-management}

### Tenant Service Extension

```typescript
// tenant-setup.service.ts
import { Injectable } from '@nestjs/common';
import { CommandService, IInvoke, KEY_SEPARATOR } from '@mbc-cqrs-serverless/core';
import { TenantService } from '@mbc-cqrs-serverless/tenant';
import { SubscriptionService } from './subscription.service';

// Example helper: per-tenant partition key
const generatePk = (tenantCode: string): string =>
  `TENANT${KEY_SEPARATOR}${tenantCode}`;


@Injectable()
export class TenantSetupService {
  constructor(
    private readonly tenantService: TenantService,
    private readonly subscriptionService: SubscriptionService,
    private readonly commandService: CommandService,
  ) {}

  // Create tenant with initial subscription
  async provisionTenant(dto: ProvisionTenantDto, context: IInvoke) {
    // Step 1: Create tenant
    const tenant = await this.tenantService.createTenant(
      {
        code: dto.companySlug,
        name: dto.companyName,
        attributes: {
          industry: dto.industry,
          country: dto.country,
          timezone: dto.timezone,
        },
      },
      { invokeContext: context },
    );

    // Step 2: Create trial subscription
    await this.subscriptionService.createTrialSubscription(
      dto.companySlug,
      dto.planCode,
      context,
    );

    // Step 3: Initialize usage tracking
    await this.initializeUsageTracking(dto.companySlug, context);

    return tenant;
  }

  private async initializeUsageTracking(
    tenantCode: string,
    context: IInvoke,
  ) {
    const currentPeriod = this.getCurrentPeriod();

    await this.commandService.publishAsync(
      {
        pk: generatePk(tenantCode),
        sk: `USAGE#${currentPeriod}`,
        code: currentPeriod,
        name: `Usage for ${currentPeriod}`,
        tenantCode,
        attributes: {
          period: currentPeriod,
          apiCalls: 0,
          storageUsedGb: 0,
          activeUsers: 0,
          projectCount: 0,
          lastUpdatedAt: new Date().toISOString(),
        },
      },
      { invokeContext: context },
    );
  }

  private getCurrentPeriod(): string {
    const now = new Date();
    return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
  }
}
```

## Subscription Management {#subscription-management}

### Subscription Service

```typescript
// subscription.service.ts
import { Injectable, BadRequestException, NotFoundException } from '@nestjs/common';
import {
  CommandService,
  DataService,
  IInvoke,
  KEY_SEPARATOR,
  getUserContext,
} from '@mbc-cqrs-serverless/core';
import { MasterDataService } from '@mbc-cqrs-serverless/master';

// Example helper: per-tenant partition key
const generatePk = (tenantCode: string): string =>
  `TENANT${KEY_SEPARATOR}${tenantCode}`;

@Injectable()
export class SubscriptionService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly masterDataService: MasterDataService,
  ) {}

  // Create trial subscription
  async createTrialSubscription(
    tenantCode: string,
    planCode: string,
    context: IInvoke,
  ) {
    const plan = await this.masterDataService.get({
      pk: `MASTER${KEY_SEPARATOR}common`,
      sk: `PLAN${KEY_SEPARATOR}${planCode}`,
    });
    if (!plan) {
      throw new BadRequestException(`Plan ${planCode} not found`);
    }

    const trialDays = 14;
    const startDate = new Date();
    const endDate = new Date(startDate);
    endDate.setDate(endDate.getDate() + trialDays);

    const command = {
      pk: generatePk(tenantCode),
      sk: `SUBSCRIPTION#SUB-${Date.now()}`,
      code: `SUB-${Date.now()}`,
      name: `${plan.name} Subscription`,
      tenantCode,
      attributes: {
        planCode,
        billingCycle: 'monthly',
        status: 'trial' as SubscriptionStatus,
        startDate: startDate.toISOString(),
        endDate: endDate.toISOString(),
        autoRenew: true,
      },
    };

    return this.commandService.publishAsync(command, { invokeContext: context });
  }

  // Upgrade/Downgrade subscription
  async changePlan(
    subscriptionCode: string,
    newPlanCode: string,
    context: IInvoke,
  ) {
    const { tenantCode } = getUserContext(context);
    const pk = generatePk(tenantCode);
    const sk = `SUBSCRIPTION#${subscriptionCode}`;

    const current = await this.dataService.getItem({ pk, sk });
    if (!current) {
      throw new NotFoundException(`Subscription ${subscriptionCode} not found`);
    }

    // Validate plan exists
    const newPlan = await this.masterDataService.get({
      pk: `MASTER${KEY_SEPARATOR}common`,
      sk: `PLAN${KEY_SEPARATOR}${newPlanCode}`,
    });
    if (!newPlan) {
      throw new BadRequestException(`Plan ${newPlanCode} not found`);
    }

    // Validate upgrade/downgrade is allowed
    await this.validatePlanChange(tenantCode, current.attributes, newPlan);

    const command = {
      ...current,
      version: current.version,
      attributes: {
        ...current.attributes,
        planCode: newPlanCode,
        planChangedAt: new Date().toISOString(),
      },
    };

    return this.commandService.publishAsync(command, { invokeContext: context });
  }

  // Cancel subscription
  async cancelSubscription(
    subscriptionCode: string,
    reason: string,
    context: IInvoke,
  ) {
    const { tenantCode } = getUserContext(context);
    const pk = generatePk(tenantCode);
    const sk = `SUBSCRIPTION#${subscriptionCode}`;

    const current = await this.dataService.getItem({ pk, sk });
    if (!current) {
      throw new NotFoundException(`Subscription ${subscriptionCode} not found`);
    }

    const command = {
      ...current,
      version: current.version,
      attributes: {
        ...current.attributes,
        status: 'cancelled' as SubscriptionStatus,
        autoRenew: false,
        cancellationReason: reason,
        cancelledAt: new Date().toISOString(),
      },
    };

    return this.commandService.publishAsync(command, { invokeContext: context });
  }

  private async validatePlanChange(
    tenantCode: string,
    currentSub: SubscriptionAttributes,
    newPlan: any,
  ) {
    // Check current usage against new plan limits
    const usage = await this.getCurrentUsage(tenantCode);

    if (usage.activeUsers > newPlan.attributes.limits.maxUsers) {
      throw new BadRequestException(
        `Cannot downgrade: current users (${usage.activeUsers}) ` +
        `exceeds new plan limit (${newPlan.attributes.limits.maxUsers})`
      );
    }

    if (usage.storageUsedGb > newPlan.attributes.limits.maxStorageGb) {
      throw new BadRequestException(
        `Cannot downgrade: current storage (${usage.storageUsedGb}GB) ` +
        `exceeds new plan limit (${newPlan.attributes.limits.maxStorageGb}GB)`
      );
    }
  }

  private async getCurrentUsage(tenantCode: string): Promise<UsageAttributes> {
    const now = new Date();
    const period = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
    const record = await this.dataService.getItem({
      pk: generatePk(tenantCode),
      sk: `USAGE#${period}`,
    });
    return (record?.attributes ?? {
      apiCalls: 0,
      storageUsedGb: 0,
      activeUsers: 0,
      projectCount: 0,
    }) as UsageAttributes;
  }
}
```

## Usage Metering {#usage-metering}

### Usage Service

```typescript
// usage.service.ts
import { Injectable, Logger, NotFoundException } from '@nestjs/common';
import {
  CommandService,
  DataService,
  IInvoke,
  KEY_SEPARATOR,
  getUserContext,
} from '@mbc-cqrs-serverless/core';
import { MasterDataService } from '@mbc-cqrs-serverless/master';

// Example helper: per-tenant partition key
const generatePk = (tenantCode: string): string =>
  `TENANT${KEY_SEPARATOR}${tenantCode}`;

@Injectable()
export class UsageService {
  private readonly logger = new Logger(UsageService.name);

  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
    private readonly masterDataService: MasterDataService,
  ) {}

  // Track API call
  async trackApiCall(context: IInvoke): Promise<void> {
    await this.incrementUsage(context, 'apiCalls', 1);
  }

  // Track storage usage
  async trackStorageChange(
    deltaGb: number,
    context: IInvoke,
  ): Promise<void> {
    await this.incrementUsage(context, 'storageUsedGb', deltaGb);
  }

  // Check if quota is exceeded
  async checkQuota(
    metric: keyof UsageAttributes,
    context: IInvoke,
  ): Promise<QuotaCheckResult> {
    const { tenantCode } = getUserContext(context);

    const [usage, subscription] = await Promise.all([
      this.getCurrentUsage(tenantCode),
      this.getActiveSubscription(tenantCode),
    ]);

    const plan = await this.masterDataService.get({
      pk: `MASTER${KEY_SEPARATOR}common`,
      sk: `PLAN${KEY_SEPARATOR}${subscription.attributes.planCode}`,
    });

    const limit = this.getLimit(plan, metric);
    const current = usage.attributes[metric] as number;
    const percentage = (current / limit) * 100;

    return {
      metric,
      current,
      limit,
      percentage,
      isExceeded: current >= limit,
      isNearLimit: percentage >= 80,
    };
  }

  // Get usage summary for billing
  async getUsageSummary(
    tenantCode: string,
    period: string,
  ): Promise<UsageSummary> {
    const pk = generatePk(tenantCode);
    const sk = `USAGE#${period}`;

    const usage = await this.dataService.getItem({ pk, sk });
    if (!usage) {
      return {
        period,
        apiCalls: 0,
        storageUsedGb: 0,
        activeUsers: 0,
        projectCount: 0,
      };
    }

    return usage.attributes;
  }

  private async incrementUsage(
    context: IInvoke,
    metric: string,
    delta: number,
  ): Promise<void> {
    const { tenantCode } = getUserContext(context);
    const period = this.getCurrentPeriod();
    const pk = generatePk(tenantCode);
    const sk = `USAGE#${period}`;

    const current = await this.dataService.getItem({ pk, sk });

    if (!current) {
      // Create new usage record
      const command = {
        pk,
        sk,
        code: period,
        name: `Usage for ${period}`,
        tenantCode,
        attributes: {
          period,
          apiCalls: 0,
          storageUsedGb: 0,
          activeUsers: 0,
          projectCount: 0,
          [metric]: delta,
          lastUpdatedAt: new Date().toISOString(),
        },
      };
      await this.commandService.publishAsync(command, { invokeContext: context });
      return;
    }

    // Update existing record
    const command = {
      ...current,
      version: current.version,
      attributes: {
        ...current.attributes,
        [metric]: (current.attributes[metric] || 0) + delta,
        lastUpdatedAt: new Date().toISOString(),
      },
    };

    await this.commandService.publishAsync(command, { invokeContext: context });
  }

  private getLimit(plan: any, metric: string): number {
    const limitMapping: Record<string, string> = {
      apiCalls: 'maxApiCalls',
      storageUsedGb: 'maxStorageGb',
      activeUsers: 'maxUsers',
      projectCount: 'maxProjects',
    };

    return plan.attributes.limits[limitMapping[metric]] || Infinity;
  }

  private getCurrentPeriod(): string {
    const now = new Date();
    return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
  }

  private async getCurrentUsage(tenantCode: string): Promise<any> {
    const pk = generatePk(tenantCode);
    const sk = `USAGE#${this.getCurrentPeriod()}`;
    return (
      (await this.dataService.getItem({ pk, sk })) ?? {
        attributes: { apiCalls: 0, storageUsedGb: 0, activeUsers: 0, projectCount: 0 },
      }
    );
  }

  private async getActiveSubscription(tenantCode: string): Promise<any> {
    const pk = generatePk(tenantCode);
    const items = await this.dataService.listItemsByPk(pk, {
      skExpression: 'begins_with(sk, :prefix)',
      skAttributeValues: { ':prefix': 'SUBSCRIPTION#' },
    });
    const active = items.items.find(
      (item) =>
        item.attributes.status === 'active' ||
        item.attributes.status === 'trial',
    );
    if (!active) {
      throw new NotFoundException(
        `No active subscription found for tenant ${tenantCode}`,
      );
    }
    return active;
  }
}
```

### Quota Guard

```typescript
// quota.guard.ts
import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { UsageService } from './usage.service';
import { extractInvokeContext } from '@mbc-cqrs-serverless/core';

@Injectable()
export class QuotaGuard implements CanActivate {
  constructor(
    private readonly reflector: Reflector,
    private readonly usageService: UsageService,
  ) {}

  async canActivate(context: ExecutionContext): Promise<boolean> {
    const metric = this.reflector.get<string>('quota_metric', context.getHandler());
    if (!metric) {
      return true;
    }

    const ctx = extractInvokeContext(context);
    const quota = await this.usageService.checkQuota(metric, ctx);

    if (quota.isExceeded) {
      throw new ForbiddenException(
        `Quota exceeded for ${metric}: ${quota.current}/${quota.limit}. ` +
        'Please upgrade your plan.'
      );
    }

    return true;
  }
}

// Usage in controller
@Controller('projects')
export class ProjectController {
  @Post()
  @UseGuards(QuotaGuard)
  @SetMetadata('quota_metric', 'projectCount')
  async create(
    @Body() dto: CreateProjectDto,
    @INVOKE_CONTEXT() invokeContext: IInvoke,
  ) {
    // ...
  }
}
```

## Billing Integration {#billing-integration}

### Billing Event Handler

```typescript
// billing-event.handler.ts
import { Injectable, Logger, NotFoundException } from '@nestjs/common';
import {
  CommandModel,
  DataService,
  DataSyncHandler,
  IDataSyncHandler,
  KEY_SEPARATOR,
  VERSION_FIRST,
} from '@mbc-cqrs-serverless/core';
import { MasterDataService } from '@mbc-cqrs-serverless/master';
import { BillingService } from './billing.service';

@DataSyncHandler('subscription')
@Injectable()
export class BillingEventHandler implements IDataSyncHandler {
  private readonly logger = new Logger(BillingEventHandler.name);

  constructor(
    private readonly billingService: BillingService,
    private readonly dataService: DataService,
    private readonly masterDataService: MasterDataService,
  ) {}

  async up(cmd: CommandModel): Promise<any> {
    // Handle subscription changes
    if (cmd.sk.startsWith('SUBSCRIPTION#')) {
      await this.handleSubscriptionChange(cmd);
      return;
    }

    // Handle usage updates
    if (cmd.sk.startsWith('USAGE#')) {
      await this.handleUsageChange(cmd);
      return;
    }
  }

  async down(cmd: CommandModel): Promise<any> {
    // Optional rollback logic when a sync step fails
  }

  private async handleSubscriptionChange(cmd: CommandModel) {
    const attrs = cmd.attributes;

    // New subscription: stored version is VERSION_FIRST + 1
    if (cmd.version === VERSION_FIRST + 1) {
      this.logger.log(`New subscription: ${cmd.code}`);

      if (attrs.status === 'active') {
        await this.billingService.createBillingCycle({
          tenantCode: cmd.tenantCode,
          subscriptionCode: cmd.code,
          planCode: attrs.planCode,
          billingCycle: attrs.billingCycle,
          startDate: attrs.startDate,
        });
      }
      return;
    }

    // Subscription cancelled
    if (attrs.status === 'cancelled') {
      this.logger.log(`Subscription cancelled: ${cmd.code}`);
      await this.billingService.cancelBillingCycle(cmd.code);
      return;
    }

    // Plan changed
    if (attrs.planChangedAt) {
      this.logger.log(`Plan changed for ${cmd.code}: now ${attrs.planCode}`);
      await this.billingService.prorate({
        subscriptionCode: cmd.code,
        newPlanCode: attrs.planCode,
        changeDate: attrs.planChangedAt,
      });
    }
  }

  private async handleUsageChange(usage: CommandModel) {
    // Check for overage
    const subscription = await this.getActiveSubscription(usage.tenantCode);
    const plan = await this.masterDataService.get({
      pk: `MASTER${KEY_SEPARATOR}common`,
      sk: `PLAN${KEY_SEPARATOR}${subscription.attributes.planCode}`,
    });

    const overages = this.calculateOverages(usage.attributes, plan.attributes.limits);

    if (overages.length > 0) {
      this.logger.log(`Overage detected for ${usage.tenantCode}`, overages);
      await this.billingService.recordOverage({
        tenantCode: usage.tenantCode,
        period: usage.attributes.period,
        overages,
      });
    }
  }

  private calculateOverages(
    usage: UsageAttributes,
    limits: PlanLimits,
  ): Overage[] {
    const overages: Overage[] = [];

    if (usage.apiCalls > limits.maxApiCalls) {
      overages.push({
        metric: 'apiCalls',
        limit: limits.maxApiCalls,
        actual: usage.apiCalls,
        overage: usage.apiCalls - limits.maxApiCalls,
      });
    }

    if (usage.storageUsedGb > limits.maxStorageGb) {
      overages.push({
        metric: 'storageUsedGb',
        limit: limits.maxStorageGb,
        actual: usage.storageUsedGb,
        overage: usage.storageUsedGb - limits.maxStorageGb,
      });
    }

    return overages;
  }

  private async getActiveSubscription(tenantCode: string): Promise<any> {
    const pk = `TENANT${KEY_SEPARATOR}${tenantCode}`;
    const items = await this.dataService.listItemsByPk(pk, {
      skExpression: 'begins_with(sk, :prefix)',
      skAttributeValues: { ':prefix': 'SUBSCRIPTION#' },
    });
    const active = items.items.find(
      (item) =>
        item.attributes.status === 'active' ||
        item.attributes.status === 'trial',
    );
    if (!active) {
      throw new NotFoundException(
        `No active subscription found for tenant ${tenantCode}`,
      );
    }
    return active;
  }
}
```

## API Key Management {#api-key-management}

### API Key Service

```typescript
// api-key.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { randomBytes, createHash } from 'crypto';
import {
  CommandService,
  DataService,
  IInvoke,
  KEY_SEPARATOR,
  getUserContext,
} from '@mbc-cqrs-serverless/core';

// Example helper: per-tenant partition key
const generatePk = (tenantCode: string): string =>
  `TENANT${KEY_SEPARATOR}${tenantCode}`;

@Injectable()
export class ApiKeyService {
  constructor(
    private readonly commandService: CommandService,
    private readonly dataService: DataService,
  ) {}

  // Generate new API key
  async createApiKey(dto: CreateApiKeyDto, context: IInvoke) {
    const { tenantCode, userId } = getUserContext(context);

    // Generate secure API key
    const rawKey = `mbc_${randomBytes(32).toString('hex')}`;
    const keyHash = this.hashKey(rawKey);
    const keyPrefix = rawKey.substring(0, 11); // Show first 11 chars

    const command = {
      pk: generatePk(tenantCode),
      sk: `APIKEY#${keyHash}`,
      code: keyHash,
      name: dto.name,
      tenantCode,
      attributes: {
        keyPrefix,
        keyHash,
        createdBy: userId,
        scopes: dto.scopes || ['read'],
        expiresAt: dto.expiresAt,
        lastUsedAt: null,
        isActive: true,
      },
    };

    await this.commandService.publishAsync(command, { invokeContext: context });

    // Return raw key only once
    return {
      key: rawKey,
      keyPrefix,
      name: dto.name,
      scopes: dto.scopes,
    };
  }

  // Validate API key
  async validateApiKey(rawKey: string): Promise<ApiKeyValidation> {
    const keyHash = this.hashKey(rawKey);

    // Search across all tenants via GSI using DynamoDB client directly
    // DataService.listItemsByPk() queries by pk; for GSI queries inject DynamoDbService.client
    const result = await this.dataService.listItemsByPk(keyHash);

    if (!result.items.length) {
      return { valid: false, reason: 'Key not found' };
    }

    const apiKey = result.items[0];

    if (!apiKey.attributes.isActive) {
      return { valid: false, reason: 'Key is inactive' };
    }

    if (
      apiKey.attributes.expiresAt &&
      new Date(apiKey.attributes.expiresAt) < new Date()
    ) {
      return { valid: false, reason: 'Key expired' };
    }

    // Update last used timestamp asynchronously
    this.updateLastUsed(apiKey).catch(() => {});

    return {
      valid: true,
      tenantCode: apiKey.tenantCode,
      scopes: apiKey.attributes.scopes,
    };
  }

  // Revoke API key
  async revokeApiKey(keyPrefix: string, context: IInvoke) {
    const { tenantCode } = getUserContext(context);
    const pk = generatePk(tenantCode);

    // Find key by prefix
    const keys = await this.dataService.listItemsByPk(pk, {
      sk: {
        skExpression: 'begins_with(sk, :prefix)',
        skAttributeValues: { ':prefix': 'APIKEY#' },
      },
    });

    const apiKey = keys.items.find(
      (k) => k.attributes.keyPrefix === keyPrefix
    );

    if (!apiKey) {
      throw new NotFoundException('API key not found');
    }

    const command = {
      ...apiKey,
      version: apiKey.version,
      attributes: {
        ...apiKey.attributes,
        isActive: false,
        revokedAt: new Date().toISOString(),
      },
    };

    return this.commandService.publishAsync(command, { invokeContext: context });
  }

  private hashKey(rawKey: string): string {
    return createHash('sha256').update(rawKey).digest('hex');
  }
}
```

## API Endpoints {#api-endpoints}

| Method | Endpoint | Description |
|------------|--------------|-----------------|
| POST | `/tenants/provision` | Provision new tenant |
| GET | `/subscription` | Get current subscription |
| PATCH | `/subscription/plan` | Change plan |
| POST | `/subscription/cancel` | Cancel subscription |
| GET | `/usage` | Get current usage |
| GET | `/usage/:period` | Get usage for period |
| POST | `/api-keys` | Create API key |
| DELETE | `/api-keys/:prefix` | Revoke API key |

## Best Practices {#best-practices}

### 1. Tenant Isolation

Always scope data access by tenant:

```typescript
const { tenantCode } = getUserContext(context);
const pk = generatePk(tenantCode);
```

### 2. Usage Tracking

Track usage incrementally, not on every request:

```typescript
// Batch updates using a buffer
private usageBuffer = new Map<string, number>();

async trackApiCall(tenantCode: string) {
  const current = this.usageBuffer.get(tenantCode) || 0;
  this.usageBuffer.set(tenantCode, current + 1);

  // Flush every 100 calls or 60 seconds
  if (current + 1 >= 100) {
    await this.flushUsage(tenantCode);
  }
}
```

### 3. Billing Events

Use event handlers for billing, not synchronous calls:

```typescript
// Good: Event-driven billing
@DataSyncHandler('subscription')
export class BillingEventHandler {
  // Async, decoupled, reliable
}

// Avoid: Synchronous billing calls
async createSubscription() {
  await this.createInStripe(); // Can fail, blocks user
}
```

## Related Documentation

- [E-commerce Example](/docs/ecommerce-example) - Commerce application example
- [Backend Development](/docs/backend-development) - Core backend implementation patterns
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant isolation
- [Authentication](/docs/authentication) - Subscription authentication
- [Service Patterns](/docs/service-patterns) - CRUD service patterns


---

## Survey Template

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/survey-template

# Survey Template

Survey template management functionality for the MBC CQRS Serverless framework.

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/survey-template
```

## Overview {#overview}

The Survey Template package provides comprehensive survey template management in a multi-tenant CQRS architecture. It enables the creation, management, and storage of survey templates with flexible JSON-based definitions supporting various question types.

## Features {#features}

- **Survey Template CRUD Operations**: Create, read, update, and delete survey templates
- **Multi-tenant Support**: Tenant-isolated survey template management
- **Flexible Survey Structure**: JSON-based survey template definitions
- **Various Question Types**: Support for text, multiple choice, rating, and more
- **Search and Filtering**: Advanced search capabilities with keyword matching
- **Event-Driven Architecture**: Built on CQRS pattern with command/event handling
- **RESTful API**: Complete REST API for survey template operations

## Basic Setup {#basic-setup}

### Module Configuration

```typescript
import { SurveyTemplateModule } from '@mbc-cqrs-serverless/survey-template';
import { Module } from '@nestjs/common';

@Module({
  imports: [
    SurveyTemplateModule.register({
      enableController: true,  // Enable REST API endpoints
      prismaService: PrismaService,  // Required when enableController is true
    }),
  ],
})
export class AppModule {}
```

## API Endpoints {#api-endpoints}

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/survey-template/` | Search and list survey templates |
| POST | `/api/survey-template/` | Create a new survey template |
| GET | `/api/survey-template/:id` | Get a specific survey template |
| PUT | `/api/survey-template/:id` | Update a survey template |
| DELETE | `/api/survey-template/:id` | Delete a survey template |

## Creating a Survey Template {#creating-survey-template}

```typescript
import { Injectable } from '@nestjs/common';
import { IInvoke } from '@mbc-cqrs-serverless/core';
import {
  SurveyTemplateCreateDto,
  SurveyTemplateDataEntity,
  SurveyTemplateService,
} from '@mbc-cqrs-serverless/survey-template';

@Injectable()
export class SurveyService {
  constructor(
    private readonly surveyTemplateService: SurveyTemplateService,
  ) {}

  async createTemplate(
    dto: SurveyTemplateCreateDto,
    invokeContext: IInvoke,
  ): Promise<SurveyTemplateDataEntity> {
    return this.surveyTemplateService.create(dto, { invokeContext });
  }
}
```

## Question Types {#question-types}

### Text Question

```json
{
  "type": "text",
  "text": "Please describe your experience",
  "required": true,
  "maxLength": 1000,
  "placeholder": "Enter your response..."
}
```

### Multiple Choice

```json
{
  "type": "multiple_choice",
  "text": "Which products do you use?",
  "required": true,
  "allowMultiple": true,
  "options": [
    { "value": "product_a", "label": "Product A" },
    { "value": "product_b", "label": "Product B" },
    { "value": "product_c", "label": "Product C" }
  ]
}
```

### Rating Scale

```json
{
  "type": "rating",
  "text": "Rate your experience",
  "required": true,
  "min": 1,
  "max": 10,
  "labels": {
    "1": "Poor",
    "5": "Average",
    "10": "Excellent"
  }
}
```

### Yes/No Question

```json
{
  "type": "boolean",
  "text": "Would you recommend us to a friend?",
  "required": true
}
```

### Date Question

```json
{
  "type": "date",
  "text": "When did you first use our service?",
  "required": false,
  "minDate": "2020-01-01",
  "maxDate": "today"
}
```

## Survey Template Structure {#template-structure}

```typescript
interface SurveyTemplate {
  id: string;
  name: string;
  description?: string;
  sections: Section[];
  settings?: TemplateSettings;
  createdAt: Date;
  updatedAt: Date;
}

interface Section {
  title: string;
  description?: string;
  questions: Question[];
}

interface TemplateSettings {
  allowAnonymous: boolean;
  showProgressBar: boolean;
  randomizeQuestions: boolean;
}

type QuestionType = 'text' | 'multiple_choice' | 'rating' | 'boolean' | 'date';

interface Question {
  type: QuestionType;
  text: string;
  required: boolean;
  // text question options
  maxLength?: number;
  placeholder?: string;
  // multiple_choice options
  allowMultiple?: boolean;
  options?: Array<{ value: string; label: string }>;
  // rating options
  min?: number;
  max?: number;
  labels?: Record<string, string>;
  // date options
  minDate?: string;
  maxDate?: string;
}
```

## Searching Templates {#searching-templates}

```typescript
async searchTemplates(
  tenantCode: string,
  searchDto: SearchDto,
): Promise<SurveyTemplateDataListEntity> {
  return this.surveyTemplateService.searchData(tenantCode, searchDto);
}

async getTemplate(key: DetailKey): Promise<SurveyTemplateDataEntity> {
  return this.surveyTemplateService.findOne(key);
}
```

## Updating Templates {#updating-templates}

```typescript
async updateTemplate(
  key: DetailKey,
  dto: SurveyTemplateUpdateDto,
  invokeContext: IInvoke,
): Promise<SurveyTemplateDataEntity> {
  return this.surveyTemplateService.update(key, dto, { invokeContext });
}
```

## Deleting Templates {#deleting-templates}

```typescript
async deleteTemplate(
  key: DetailKey,
  invokeContext: IInvoke,
): Promise<SurveyTemplateDataEntity> {
  return this.surveyTemplateService.remove(key, { invokeContext });
}
```

## Multi-tenant Usage {#multi-tenant-usage}

Templates are automatically isolated by tenant through the invoke context:

```typescript
import { Controller, Get, Query } from '@nestjs/common';
import { getUserContext, IInvoke, INVOKE_CONTEXT, SearchDto } from '@mbc-cqrs-serverless/core';
import {
  SurveyTemplateDataListEntity,
  SurveyTemplateService,
} from '@mbc-cqrs-serverless/survey-template';

@Controller('api/survey-template')
export class SurveyTemplateController {
  constructor(
    private readonly surveyTemplateService: SurveyTemplateService,
  ) {}

  @Get()
  async searchData(
    @Query() searchDto: SearchDto,
    @INVOKE_CONTEXT() invokeContext: IInvoke,
  ): Promise<SurveyTemplateDataListEntity> {
    const { tenantCode } = getUserContext(invokeContext);
    return this.surveyTemplateService.searchData(tenantCode, searchDto);
  }
}
```

## Event Handling {#event-handling}

Handle survey template data synchronization using data sync handlers:

```typescript
import { CommandModel, IDataSyncHandler } from '@mbc-cqrs-serverless/core';

export class SurveyTemplateDataSyncHandler implements IDataSyncHandler {
  async up(cmd: CommandModel): Promise<any> {
    // Called automatically on every command event — sync to RDS, notify users, etc.
    console.log('Survey template upserted:', cmd.name);
  }

  async down(cmd: CommandModel): Promise<any> {
    // Reserved for manual rollback — not called automatically by the framework
    console.log('Survey template rollback:', cmd.name);
  }
}
```

## Best Practices {#best-practices}

1. **Use Sections**: Organize questions into logical sections for better user experience
2. **Validate Questions**: Ensure required fields are properly marked
3. **Limit Options**: For multiple choice, keep options to a reasonable number
4. **Version Templates**: Create new versions instead of modifying existing templates in use
5. **Test Templates**: Preview templates before deployment


## Related Documentation

- [Survey Web](/docs/survey-web) - Frontend survey components
- [Backend Development](/docs/backend-development) - Core backend patterns
- [Service Patterns](/docs/service-patterns) - Service implementation
- [Multi-Tenant Patterns](/docs/multi-tenant-patterns) - Tenant isolation in survey templates


---

# AI Integration

## AI Integration

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/ai-integration

# AI Integration

The MBC CQRS Serverless framework is designed with AI tool integration in mind.

## Overview {#overview}

Modern development workflows increasingly include AI assistance for code generation, debugging, and documentation lookup. This framework supports AI development tools through llms.txt files and MCP server.

## llms.txt Convention {#llms-txt}

### What is llms.txt?

The llms.txt convention provides a standardized way for websites and projects to expose information for LLMs.

### File Structure

The framework provides two versions:

- **`llms.txt`** - Concise overview and quick reference
- **`llms-full.txt`** - Comprehensive documentation and context

### Using llms.txt

AI tools can directly fetch these files to build context about the framework:

```bash
# Short version for quick context
curl https://mbc-cqrs-serverless.mbc-net.com/llms.txt

# Full version for comprehensive context
curl https://mbc-cqrs-serverless.mbc-net.com/llms-full.txt
```

## MCP Server Integration {#mcp-server-integration}

The Model Context Protocol (MCP) server provides a more dynamic way for AI tools to interact with the framework.

### Context7 Integration

Context7 is an MCP server that provides real-time, version-specific documentation to AI assistants.

MBC CQRS Serverless documentation is available through Context7. You can access it at:

- Context7 URL: [https://context7.com/mbc-net/mbc-cqrs-serverless-doc](https://context7.com/mbc-net/mbc-cqrs-serverless-doc)

To use Context7, add it to Claude Code:

```bash
claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
```

### Custom MCP Server

The framework also provides a custom MCP server for deeper integration:

| Feature | Description |
|---------|-------------|
| Resources | Access to framework documentation |
| Tools | Code generation and validation tools |
| Prompts | Guided workflows for common tasks |

### Setup

Add to Claude Code or other MCP-compatible tools:

```json
{
  "mcpServers": {
    "mbc-cqrs-serverless": {
      "command": "npx",
      "args": ["@mbc-cqrs-serverless/mcp-server"],
      "env": {
        "MBC_PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}
```

Learn more: [MCP Server Documentation](/docs/mcp-server)

## Best Practices {#best-practices}

### Documentation First

Before tackling complex tasks, let AI read the framework documentation:

1. Use MCP resources to fetch architecture documentation
2. Review CQRS patterns and Event Sourcing concepts
3. Examine existing modules as reference patterns

### Code Generation

When asking AI to generate modules, be specific:

```text
"Generate an Order module with async command handling and validation"
```

### Debugging Assistance

When encountering errors, AI can use the error catalog to find solutions:

```text
"I'm getting error 'version mismatch'. What should I do?"
```

## Supported Tools {#supported-tools}

The following AI tools can integrate with MBC CQRS Serverless:

| Tool | Support | Notes |
|------|---------|-------|
| Claude Code | Full Support | Native MCP support |
| Cursor | Full Support | MCP support available |
| GitHub Copilot | Partial Support | Via llms.txt |

## Related Documentation {#related-documentation}

- [AI Prompts Library](/docs/ai-prompts) - Optimized prompts for common tasks
- [MCP Server](/docs/mcp-server) - Detailed MCP server documentation
- [CLI Tool](/docs/cli) - CLI commands for code generation
- [Error Catalog](/docs/error-catalog) - Error reference with solutions
- [Architecture](/docs/architecture) - System architecture overview


---

## AI Prompts Library

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/ai-prompts

# AI Prompts Library

This page provides optimized prompts for common development tasks when using AI assistants with the MBC CQRS Serverless framework.

## Module Generation {#module-generation}

### Create a New CQRS Module

```text
Create a new CQRS module for [FEATURE_NAME] in MBC CQRS Serverless with:
- CommandModule registration with table name "[TABLE_NAME]"
- Command handlers: Create, Update, Delete (async processing)
- DataService for queries: list with pagination, getById
- Entity extending DataEntity with attributes
- DTOs for create, update, and response
- Follow existing patterns in the codebase
```

### Create a Module with RDS Sync

```text
Create a CQRS module for [FEATURE_NAME] that syncs data to RDS:
- CommandModule with DataSyncHandler for RDS
- Prisma model in prisma/schema.prisma for the RDS table
- Handle create, update, and delete sync operations
- Include error handling for sync failures
```

## Command Operations {#command-operations}

### Implement Async Command

```text
Implement an async command handler for [OPERATION] in MBC CQRS Serverless:
- Use publishAsync for immediate response
- Include input validation in DTO
- Set appropriate command source
- Handle optimistic locking with version
- Follow the existing command pattern in this codebase
```

### Implement Sync Command

```text
Implement a synchronous command for [OPERATION] that waits for completion:
- Use publishSync method
- Return the fully processed result
- Include proper error handling
- Consider timeout implications
```

## Query Operations {#query-operations}

### List Query with Filters

```text
Implement a list query for [ENTITY] with:
- Pagination support (limit, cursor)
- Filter by [FIELD_NAMES]
- Sort options
- Use DataService.listItemsByPk with skExpression
- Return paginated response with items and cursor
```

### Detail Query

```text
Implement a detail query to get [ENTITY] by ID:
- Use DataService.getItem
- Handle VERSION_LATEST for latest version
- Include proper error handling for not found
- Serialize response for API output
```

## Event Handling {#event-handling}

### Create Custom Event Handler

```text
Create a custom event handler for [EVENT_TYPE] in MBC CQRS Serverless:
- Extend appropriate event class (DynamoDbEvent, SqsEvent, etc.)
- Implement IEventHandler interface
- Register handler in EventHandlerModule
- Include error handling and logging
- Follow the event handling patterns in the codebase
```

### DynamoDB Stream Handler

```text
Create a DynamoDB stream handler to [PURPOSE]:
- Process INSERT, MODIFY, REMOVE events
- Filter by table name if needed
- Extract old and new images
- Implement idempotent processing
- Handle errors appropriately
```

## Data Sync {#data-sync}

### Create Data Sync Handler

```text
Create a DataSyncHandler to sync [ENTITY] to [TARGET]:
- Implement IDataSyncHandler interface
- Handle up() for create/update operations
- Handle down() for delete operations
- Use transactions where appropriate
- Include error handling and rollback logic
```

## Multi-Tenancy {#multi-tenancy}

### Implement Tenant-Aware Feature

```text
Implement [FEATURE] with multi-tenancy support:
- Extract tenantCode from invocation context
- Use tenant-prefixed partition keys
- Apply tenant isolation in queries
- Include tenant validation
- Follow existing tenant patterns in the codebase
```

## Authentication & Authorization {#auth-prompts}

### Implement Group-Based Role Resolver (v1.3.1+)

```text
Implement a GroupRoleResolver for [APP_NAME]:
- Group-to-role mapping stored in [DynamoDB / RDS / hardcoded config]
- Map groups: [LIST_GROUPS] to roles: [LIST_ROLES]
- Use @GroupRoleResolver() decorator (NOT @Injectable() — AP027 anti-pattern)
- Implement IGroupRoleResolver interface with resolveRoles()
- Register as provider in AppModule
- See: https://mbc-cqrs-serverless.mbc-net.com/docs/authentication#group-based-roles
```

### Add AppSync Events API Notifications (v1.3.0+)

```text
Set up AppSync Events API real-time notifications for [FEATURE]:
- Add NOTIFICATION_TRANSPORTS=appsync-event to environment
- Configure APPSYNC_EVENTS_ENDPOINT and APPSYNC_EVENTS_NAMESPACE
- Add appsyncEvents CDK config to provision EventApi + ChannelNamespace
- Subscribe frontend client using AppSync Events API channel path format
- See: https://mbc-cqrs-serverless.mbc-net.com/docs/notification-module#appsync-events-service
```

## Testing {#testing}

### Unit Test for Command Handler

```text
Write unit tests for [COMMAND_HANDLER]:
- Mock CommandService and dependencies
- Test successful command execution
- Test validation errors
- Test version conflict handling
- Use Jest with AWS SDK mocks
```

### Integration Test

```text
Write integration tests for [FEATURE]:
- Set up test DynamoDB tables
- Test full command-query flow
- Verify data sync if applicable
- Clean up test data after each test
- Use LocalStack for local testing
```

## Debugging {#debugging}

### Diagnose Version Conflict

```text
I'm getting an "Invalid input: item not found or version mismatch" error when updating [ENTITY].
Please help me:
1. Understand why this error occurs in CQRS/Event Sourcing
2. Check if I'm using the correct version in my update
3. Suggest how to handle concurrent updates properly
4. Show me how to implement retry logic if needed
```

### Diagnose Data Sync Issues

```text
Data is not syncing to RDS for [ENTITY]. Please help me:
1. Check if DataSyncHandler is properly registered
2. Verify the sync handler implementation
3. Check for errors in the sync process
4. Suggest debugging steps and logging
```

### Diagnose Event Processing

```text
Events are not being processed for [EVENT_TYPE]. Please check:
1. Event handler registration in the module
2. Event class implementation
3. SQS/SNS configuration
4. Error handling and dead letter queue setup
```

## Architecture Review {#architecture-review}

### Review Module Implementation

```text
Review this [MODULE_NAME] module implementation for:
- Proper CQRS pattern adherence (command/query separation)
- Event sourcing best practices
- Multi-tenancy implementation
- Error handling completeness
- Performance considerations
- Security best practices
```

### Review for Production Readiness

```text
Review [FEATURE] for production readiness:
- Error handling and recovery
- Logging and monitoring
- Performance under load
- Security vulnerabilities
- Data consistency guarantees
- Rollback procedures
```

## Migration {#migration}

### Create Migration for Schema Change

```text
Create a migration for [SCHEMA_CHANGE]:
- Prisma migration (run npm run migrate:dev to create the migration file)
- Handle existing data transformation
- Include rollback procedure
- Test with sample data
- Document breaking changes if any
```

## Best Practices {#best-practices}

When using these prompts:

1. **Be Specific**: Replace placeholders with actual names and requirements
2. **Provide Context**: Include relevant code snippets or file paths
3. **Reference Existing Code**: Point to similar implementations in your codebase
4. **Specify Constraints**: Mention any performance, security, or compatibility requirements
5. **Request Explanations**: Ask AI to explain its implementation choices

## Related Documentation

- [AI Integration](/docs/ai-integration) - Overview of AI tool support
- [MCP Server](/docs/mcp-server) - MCP server for AI tools
- [Error Catalog](/docs/error-catalog) - Error reference with solutions


---

## MCP Server

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/mcp-server

# MCP Server

MCP (Model Context Protocol) Server for the MBC CQRS Serverless framework. This package enables interaction with the framework through tools like Claude Code and Cursor.

## What is MCP? {#what-is-mcp}

Model Context Protocol (MCP) is a protocol for AI tools to interact with applications and frameworks in a standardized way. It provides three main concepts: Resources, Tools, and Prompts.

## Features {#features}

### Resources

Access framework documentation and project information.

| Resource URI | Description |
|--------------|-------------|
| `mbc://docs/overview` | Complete framework documentation |
| `mbc://docs/llms-short` | Concise framework overview |
| `mbc://docs/architecture` | CQRS architecture guide |
| `mbc://docs/errors` | Error catalog with solutions |
| `mbc://docs/faq` | Frequently asked questions |
| `mbc://docs/troubleshooting` | Troubleshooting guide |
| `mbc://docs/security` | Security best practices |
| `mbc://project/entities` | List of project entities |
| `mbc://project/modules` | List of project modules |
| `mbc://project/structure` | Project directory structure |

### Tools

Provides code generation and project analysis tools.

| Tool | Description |
|------|-------------|
| `mbc_generate_module` | Generate a complete CQRS module |
| `mbc_generate_controller` | Generate a controller |
| `mbc_generate_service` | Generate a service |
| `mbc_generate_entity` | Generate an entity |
| `mbc_generate_dto` | Generate a DTO |
| `mbc_validate_cqrs` | Validate CQRS pattern implementation |
| `mbc_analyze_project` | Analyze project structure |
| `mbc_lookup_error` | Look up error solutions |
| `mbc_check_anti_patterns` | Check code for common anti-patterns |
| `mbc_health_check` | Perform project health check |
| `mbc_explain_code` | Explain code in MBC context |

### Prompts

Provides guided assistance.

| Prompt | Description |
|--------|-------------|
| `cqrs_implementation_guide` | Step-by-step CQRS implementation |
| `debug_command_error` | Debug command-related errors |
| `migration_guide` | Version migration guidance |

## Installation {#installation}

```bash
npm install @mbc-cqrs-serverless/mcp-server
```

Or use directly with npx:

```bash
npx @mbc-cqrs-serverless/mcp-server
```

## Configuration {#configuration}

### Claude Code

Add the following configuration to `.mcp.json` in your project root:

```json
{
  "mcpServers": {
    "mbc-cqrs-serverless": {
      "command": "npx",
      "args": ["@mbc-cqrs-serverless/mcp-server"],
      "env": {
        "MBC_PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}
```

### Cursor

Add to Cursor MCP configuration:

```json
{
  "mbc-cqrs-serverless": {
    "command": "npx",
    "args": ["@mbc-cqrs-serverless/mcp-server"],
    "env": {
      "MBC_PROJECT_PATH": "/path/to/your/project"
    }
  }
}
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `MBC_PROJECT_PATH` | Path to project directory | Current working directory |

## Usage Examples {#usage-examples}

### Module Generation

You can ask Claude Code:

```text
"Generate a new Order module with async command handling"
```

### Project Analysis

Analyze project structure.

```text
"Analyze my project structure"
```

### Debug Assistance

Get help debugging errors.

```text
"I'm getting a version mismatch error, help me debug"
```

## Code Analysis Tools {#code-analysis-tools}

:::info Version Note
Code analysis tools (`mbc_check_anti_patterns`, `mbc_health_check`, `mbc_explain_code`) were added in [version 1.0.22](/docs/changelog#v1022).
:::

### Anti-Pattern Detection {#anti-pattern-detection}

:::info Version Note
AP011–AP015 were added in [v1.2.x](/docs/changelog#v120) (publishSync null check, deprecated APIs, TaskModule duplication). AP016–AP020 were added in [v1.2.5](/docs/changelog#v125). AP021 (event emit after publishAsync) was added in [v1.2.6](/docs/changelog#v126). AP022–AP025 (eval, shell injection, HTTP timeout, sensitive logging) and AP026 (@NotificationTransport + @Injectable conflict) were added in [v1.3.0](/docs/changelog#v130). AP027 (GroupRoleResolver + @Injectable) was added in [v1.3.1](/docs/changelog#v131). AP028 (duplicate DataSyncHandler), AP029 (reserved `'dynamodb'` type in `@DataSyncHandler`), and AP030 (fully-qualified table name in `@DataSyncHandler`) were added in [v1.3.2](/docs/changelog#v132).
:::

The `mbc_check_anti_patterns` tool detects common code issues. The detector emits **detector AP codes** (this table), which use a separate numbering system from the **skill-doc AP codes** in `/mbc-review` skill. The detector output annotates each hit with the corresponding skill-doc code, e.g. `AP005: Hardcoded Tenant (skill-doc: AP002)`. Only AP016–AP019 and AP021 share the same code in both systems.

| Detector Code | Name | Severity | Skill-doc Code |
|------|------|----------|--------------------|
| AP001 | Direct DynamoDB Write | Critical | AP012 |
| AP002 | Ignored Version Mismatch | High | AP005 |
| AP003 | N+1 Query Pattern | High | — |
| AP004 | Full Table Scan | High | — |
| AP005 | Hardcoded Tenant | Critical | AP002 |
| AP006 | Missing Tenant Validation | Critical | AP002 |
| AP007 | Throwing in Sync Handler | High | — |
| AP008 | Hardcoded Secret | Critical | — |
| AP009 | Manual JWT Parsing | Critical | — |
| AP010 | Heavy Module Import | Medium | — |
| AP011 | Deprecated Method Usage (`publish()`) | High | AP010 |
| AP012 | Uppercase COMMON Tenant Key (pre-v1.1.0) | Critical | — |
| AP013 | `publishSync` Null Return Unchecked (v1.2.0+) | High | AP001 |
| AP014 | Removed `genNewSequence()` call (removed in v1.1.0) | High | AP010 |
| AP015 | Duplicate `TaskModule.register()` (v1.2.4) | High | — |
| AP016 | Missing Error Logging Before Rethrow | High | AP016 |
| AP017 | Incorrect Attribute Merging on Partial Update | High | AP017 |
| AP018 | Missing Swagger Documentation | Low | AP018 |
| AP019 | Missing Pagination in List Queries | High | AP019 |
| AP020 | Missing `getCommandSource` for Tracing | Low | AP011 |
| AP021 | Event Emit Directly After publishAsync in CommandService | High | AP021 |
| AP022 | Use of `eval()` or `Function()` Constructor | Critical | — |
| AP023 | Shell Command Built from String Concatenation | Critical | — |
| AP024 | HTTP Request Without Timeout | Medium | — |
| AP025 | Logging `process.env` or full request object | High | — |
| AP026 | `@NotificationTransport` class also annotated with `@Injectable` | High | — |
| AP027 | `@GroupRoleResolver` class also annotated with `@Injectable` | High | — |
| AP028 | Duplicate `DataSyncHandler` Registration | High | — |
| AP029 | Reserved `'dynamodb'` Type in `@DataSyncHandler` | High | — |
| AP030 | Fully-Qualified Table Name in `@DataSyncHandler` | High | — |

### Health Check

The `mbc_health_check` tool verifies project configuration:

- MBC framework packages installation
- NestJS dependencies
- TypeScript configuration
- Environment file setup
- Source directory structure
- Serverless configuration

### Code Explanation

The `mbc_explain_code` tool analyzes code and explains:

- NestJS module structure and imports
- REST controller endpoints
- Service patterns and dependencies
- Entity definitions and DynamoDB keys
- CQRS command publishing patterns
- Data sync handler behavior

## Claude Code Skills {#claude-code-skills}

:::info Version Note
Claude Code Skills were added in [version 1.0.24](/docs/changelog#v1024).
:::

Claude Code Skills provide guided assistance for MBC CQRS Serverless development. Skills are specialized prompts that help developers with common tasks.

### Available Skills

| Skill | Description |
|-------|-------------|
| `/mbc-generate` | Generate boilerplate code (modules, services, controllers, DTOs, handlers) |
| `/mbc-review` | Review code for best practices and anti-patterns (22 patterns) |
| `/mbc-migrate` | Guide version migrations and breaking changes |
| `/mbc-debug` | Debug and troubleshoot common issues |

### Installing Skills

#### Using CLI (Recommended)

The easiest way to install skills is using the MBC CLI:

```bash
# Install to personal skills directory (available in all projects)
mbc install-skills

# Install to project directory (shared with team via git)
mbc install-skills --project

# List available skills
mbc install-skills --list

# Force overwrite existing skills
mbc install-skills --force
```

#### Manual Installation

Alternatively, copy them manually to your Claude Code skills directory:

```bash
# Copy to personal skills (available in all projects)
cp -r node_modules/@mbc-cqrs-serverless/mcp-server/skills/* ~/.claude/skills/

# Or copy to project skills (shared with team)
cp -r node_modules/@mbc-cqrs-serverless/mcp-server/skills/* .claude/skills/
```

### /mbc-generate Skill

Generates boilerplate code following MBC CQRS Serverless best practices.

**Core Templates:**
- Module, Controller, Service, DTOs, DataSyncHandler

**Additional Templates:**
- Event Handler for custom event processing
- Query Handler for complex searches
- Elasticsearch Sync Handler
- GraphQL Resolver

**Example Usage:**
```text
/mbc-generate
Create an Order module with RDS synchronization
```

### /mbc-review Skill

Reviews code for MBC CQRS Serverless best practices and identifies anti-patterns.

**Anti-Patterns Detected (22 patterns):**

These are the **skill-doc AP codes** used in `/mbc-review` reviews and human-facing documentation. They use a separate numbering system from the **detector AP codes** emitted by the `mbc_check_anti_patterns` tool. See the [Anti-Pattern Detection table](#code-analysis-tools) above for the detector→skill-doc mapping. AP021 was added in [v1.2.6](/docs/changelog#v126). AP022 was added in [v1.3.1](/docs/changelog#v131).

| Code | Description | Severity |
|------|-------------|----------|
| AP001 | Using publishSync instead of publishAsync | Warning |
| AP002 | Missing tenantCode in multi-tenant operations | Error |
| AP003 | Hardcoded version numbers | Error |
| AP004 | Missing DataSyncHandler registration | Error |
| AP005 | Not handling ConditionalCheckFailedException | Warning |
| AP006 | Using wrong PK/SK format | Error |
| AP007 | Missing invokeContext in service methods | Error |
| AP008 | Not using generateId for entity IDs | Warning |
| AP009 | Missing DTO validation decorators | Warning |
| AP010 | Deprecated method usage | Warning |
| AP011 | Missing getCommandSource for tracing | Warning |
| AP012 | Direct DynamoDB access instead of DataService | Warning |
| AP013 | Missing type declaration in DataSyncHandler | Error |
| AP014 | Not using DetailKey type | Info |
| AP015 | Hardcoded table names | Warning |
| AP016 | Missing error logging | Warning |
| AP017 | Incorrect attribute merging | Error |
| AP018 | Missing Swagger documentation | Info |
| AP019 | Not handling pagination correctly | Warning |
| AP020 | Circular module dependencies | Error |
| AP021 | Emitting events directly in CommandService after publishAsync | Error |
| AP022 | Incorrect group-based role resolver implementation (v1.3.1+) | Error |

**Example Usage:**
```text
/mbc-review
Review the code in src/order/order.service.ts
```

### /mbc-migrate Skill

Guides version migrations for MBC CQRS Serverless framework.

**Features:**
- Version migration matrix (v1.0.16 to v1.3.1)
- Detailed migration guides for each version
- Deprecated API migration instructions
- Migration checklist (before, during, after)
- Version compatibility matrix

**Example Usage:**
```text
/mbc-migrate
I need to upgrade from v1.2.x to v1.3.0
```

### /mbc-debug Skill

Helps debug and troubleshoot issues in MBC CQRS Serverless applications.

**Features:**
- Error code quick lookup
- 6 debugging workflows (Command, ConditionalCheckFailedException, DataSyncHandler, Tenant, Import, Performance)
- CloudWatch log queries
- Local development debugging (LocalStack, Serverless Offline)
- Troubleshooting decision tree

**Example Usage:**
```text
/mbc-debug
I'm getting ConditionalCheckFailedException errors
```

## Related Packages {#related-packages}

- [CLI Tool](/docs/cli) - CLI tool for code generation
- [API Reference](/docs/api-reference) - Detailed API documentation


## Related Documentation

- [AI Integration](/docs/ai-integration) - Overview of AI tool support
- [AI Prompts Library](/docs/ai-prompts) - Optimized prompts for common tasks
- [CLI](/docs/cli) - MBC CLI code generation tool


---

# Reference

## Anti-Patterns Guide

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/anti-patterns

# Anti-Patterns Guide

This guide documents common mistakes and anti-patterns to avoid when developing with the MBC CQRS Serverless framework. Understanding what NOT to do is as important as knowing the best practices.

## Command Handling Anti-Patterns {#command-handling}

### AP001: Direct Database Writes Bypassing Command Service

:::danger Anti-Pattern
Never write directly to DynamoDB tables bypassing the CommandService.
:::

```typescript
// ❌ Anti-Pattern: Direct DynamoDB write
const dynamodb = new DynamoDBClient({});
await dynamodb.send(new PutItemCommand({
  TableName: 'my-table',
  Item: { pk: { S: 'TENANT#mbc' }, sk: { S: 'ITEM#001' }, ... }
}));
```

```typescript
// ✅ Correct: Use CommandService
await this.commandService.publishAsync({
  pk: 'TENANT#mbc',
  sk: 'ITEM#001',
  version: 0,
  // ...
}, { invokeContext });
```

**Why this is problematic:**
- Bypasses version control and optimistic locking
- Skips event publishing for downstream sync
- No audit trail in command table
- Breaks CQRS pattern consistency

---

### AP002: Ignoring Version Mismatch Errors

:::danger Anti-Pattern
Never catch and ignore ConditionalCheckFailedException without proper handling.
:::

```typescript
// ❌ Anti-Pattern: Silently ignoring version mismatch
import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';

try {
  await this.commandService.publishAsync(command, context);
} catch (error) {
  if (error instanceof ConditionalCheckFailedException) {
    console.log('Version mismatch, skipping...'); // Silent failure!
  }
}
```

```typescript
// ✅ Correct: Implement retry with fresh data
import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';

const MAX_RETRIES = 3;
for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
  try {
    const latest = await this.dataService.getItem({ pk, sk });
    const command = this.buildCommand(latest);
    await this.commandService.publishAsync(command, context);
    break;
  } catch (error) {
    if (error instanceof ConditionalCheckFailedException && attempt < MAX_RETRIES - 1) {
      continue; // Retry with fresh data
    }
    throw error;
  }
}
```

**Why this is problematic:**
- Data loss - changes are silently discarded
- Inconsistent state between what user sees and database
- Hard to debug issues in production

---

### AP003: Using publishSync for Heavy Operations

:::danger Anti-Pattern
Avoid publishSync for operations that trigger heavy downstream processing.
:::

```typescript
// ❌ Anti-Pattern: Sync publish for batch import
for (const item of thousandItems) {
  await this.commandService.publishSync(item, context); // Blocks until complete!
}
```

```typescript
// ✅ Correct: Use publishAsync for batch operations
const promises = thousandItems.map(item =>
  this.commandService.publishAsync(item, context)
);
await Promise.all(promises);
```

**Why this is problematic:**
- Lambda timeout risk - Step Functions execution adds latency
- Poor user experience - long wait times
- Higher costs - Lambda billed by duration

---

## Data Access Anti-Patterns {#data-access}

### AP004: N+1 Query Pattern

:::danger Anti-Pattern
Avoid fetching related data inside loops.
:::

```typescript
// ❌ Anti-Pattern: N+1 queries
const orders = await this.dataService.listItemsByPk(tenantPk);
for (const order of orders.items) {
  // Each iteration makes a DB call!
  const customer = await this.dataService.getItem({
    pk: order.customerPk,
    sk: order.customerSk
  });
  order.customer = customer;
}
```

```typescript
// ✅ Correct: Batch fetch or denormalize
// Option 1: Denormalize — store customer snapshot inside the order item (recommended for CQRS)
// Option 2: Parallel fetch — use Promise.all to avoid sequential blocking
const orders = await this.dataService.listItemsByPk(tenantPk);
const customers = await Promise.all(
  orders.items.map(o => this.dataService.getItem({ pk: o.customerPk, sk: o.customerSk }))
);
const customerMap = new Map(customers.filter(Boolean).map(c => [c.sk, c]));
orders.items.forEach(order => {
  order.customer = customerMap.get(order.customerSk);
});
```

**Why this is problematic:**
- Performance degradation - 100 orders = 101 DB calls
- Higher DynamoDB costs
- Potential throttling under load

---

### AP005: Scanning Without Filters

:::danger Anti-Pattern
Never scan entire tables without proper filtering.
:::

```typescript
// ❌ Anti-Pattern: Full table scan
// Avoid Scan via DynamoDB SDK directly — reads all items regardless of tenant/key
const result = await this.dynamoDbService.client.send(
  new ScanCommand({ TableName: 'data-table' })
);
const filteredItems = result.Items?.filter(item => item.status?.S === 'active');
```

```typescript
// ✅ Correct: Query with proper key conditions
const result = await this.dataService.listItemsByPk(tenantPk, {
  sk: {
    skExpression: 'begins_with(sk, :skPrefix)',
    skAttributeValues: { ':skPrefix': 'ITEM#' },
  },
});
// Filter by non-key attributes in application code after fetching
const activeItems = result.items.filter(item => item.attributes?.status === 'active');
```

**Why this is problematic:**
- Reads entire table consuming massive RCUs
- Extremely slow for large tables
- Can cause DynamoDB throttling affecting other operations

---

### AP006: Storing Large Objects in DynamoDB

:::danger Anti-Pattern
Don't store large files or binary data directly in DynamoDB items.
:::

```typescript
// ❌ Anti-Pattern: Large base64 file in DynamoDB
const command = new DocumentCommand({
  pk,
  sk,
  attributes: {
    pdfContent: largeBase64String, // Could be megabytes!
  }
});
```

```typescript
// ✅ Correct: Store in S3, reference in DynamoDB
import { toS3AttributeKey } from '@mbc-cqrs-serverless/core';

const s3Key = `documents/${tenantCode}/${documentId}.pdf`;
await this.s3Service.upload(s3Key, fileBuffer);

const command = new DocumentCommand({
  pk,
  sk,
  attributes: {
    pdfLocation: toS3AttributeKey(bucket, s3Key), // s3://bucket/path
  }
});
```

**Why this is problematic:**
- DynamoDB item size limit is 400KB
- High read/write costs for large items
- Slower query performance

---

## Multi-Tenant Anti-Patterns {#multi-tenant}

### AP007: Hardcoding Tenant Code

:::danger Anti-Pattern
Never hardcode tenant codes in application logic.
:::

```typescript
// ❌ Anti-Pattern: Hardcoded tenant
const pk = 'TENANT#default';
const items = await this.dataService.listItemsByPk(pk);
```

```typescript
// ✅ Correct: Use context-provided tenant
const { tenantCode } = getUserContext(context);
const pk = generatePk(tenantCode);
const items = await this.dataService.listItemsByPk(pk);
```

**Why this is problematic:**
- Cross-tenant data leakage risk
- Breaks multi-tenant isolation
- Difficult to debug tenant-specific issues

---

### AP008: Missing Tenant Validation

:::danger Anti-Pattern
Never trust client-provided tenant codes without validation.
:::

```typescript
// ❌ Anti-Pattern: Trusting client input
@Post()
async create(@Body() dto: CreateDto) {
  const pk = `TENANT#${dto.tenantCode}`; // Client controls tenant!
  // ...
}
```

```typescript
// ✅ Correct: Validate against JWT claims
import { INVOKE_CONTEXT, IInvoke, getUserContext } from '@mbc-cqrs-serverless/core';

@Post()
async create(
  @Body() dto: CreateDto,
  @INVOKE_CONTEXT() invokeContext: IInvoke
) {
  const { tenantCode } = getUserContext(invokeContext);
  const pk = generatePk(tenantCode); // From authenticated context
  // ...
}
```

**Why this is problematic:**
- Critical security vulnerability
- Attackers can access other tenants' data
- Compliance violations (GDPR, SOC2, etc.)

---

## Event Handling Anti-Patterns {#event-handling}

### AP009: Throwing Errors in Data Sync Handlers

:::danger Anti-Pattern
Don't let unhandled exceptions escape from DataSyncHandler.
:::

```typescript
// ❌ Anti-Pattern: Unhandled exception
@DataSyncHandler('sample')
export class MyDataSyncHandler implements IDataSyncHandler {
  async up(cmd: CommandModel): Promise<any> {
    const result = await this.externalApi.call(cmd.attributes);
    // If API fails, entire batch fails and retries!
  }
}
```

```typescript
// ✅ Correct: Handle errors gracefully
@DataSyncHandler('sample')
export class MyDataSyncHandler implements IDataSyncHandler {
  async up(cmd: CommandModel): Promise<any> {
    try {
      const result = await this.externalApi.call(cmd.attributes);
    } catch (error) {
      this.logger.error('Sync failed', { cmd, error });
      await this.deadLetterQueue.send(cmd); // DLQ for later processing
      // Don't rethrow - mark as processed
    }
  }
}
```

**Why this is problematic:**
- DynamoDB Streams retries the entire batch
- Can cause infinite retry loops
- Blocks processing of subsequent events

---

### AP010: Long-Running Sync Handlers

:::danger Anti-Pattern
Avoid long-running operations in sync handlers.
:::

```typescript
// ❌ Anti-Pattern: Heavy processing in handler
@DataSyncHandler('sample')
export class MyDataSyncHandler implements IDataSyncHandler {
  async up(cmd: CommandModel): Promise<any> {
    await this.generatePdfReport(cmd.attributes); // Takes 30+ seconds
    await this.sendEmailWithAttachment(report);
  }
}
```

```typescript
// ✅ Correct: Delegate to async processing
@DataSyncHandler('sample')
export class MyDataSyncHandler implements IDataSyncHandler {
  async up(cmd: CommandModel): Promise<any> {
    // Quick enqueue, process asynchronously
    await this.taskService.publish('GenerateReport', {
      itemId: cmd.id,
      type: 'pdf'
    });
  }
}
```

**Why this is problematic:**
- Lambda timeout (15 min max)
- Blocks DynamoDB Stream processing
- Higher costs and poor scalability

---

## Quick Reference Card {#quick-reference}

AP001–AP010 correspond to the sections above (guide codes). AP011–AP027 are detector codes emitted by the `mbc_check_anti_patterns` tool — the tool uses a separate numbering system, so AP003–AP010 detector codes differ from guide codes. See [Anti-Pattern Detection](/docs/mcp-server#anti-pattern-detection) for the full detector→guide mapping.

| Code | Anti-Pattern | Severity |
|----------|------------------|--------------|
| AP001 | Direct database writes | Critical |
| AP002 | Ignoring version mismatch | High |
| AP003 | publishSync for heavy ops | Medium |
| AP004 | N+1 query pattern | High |
| AP005 | Unfiltered table scans | High |
| AP006 | Large objects in DynamoDB | Medium |
| AP007 | Hardcoded tenant codes | Critical |
| AP008 | Missing tenant validation | Critical |
| AP009 | Throwing in sync handlers | High |
| AP010 | Long-running sync handlers | Medium |
| AP011 | Deprecated `publish()` method | High |
| AP012 | Uppercase COMMON tenant key (pre-v1.1.0) | Critical |
| AP013 | `publishSync` null return unchecked (v1.2.0+) | High |
| AP014 | Removed `genNewSequence()` call (removed in v1.1.0) | High |
| AP015 | Duplicate `TaskModule.register()` | High |
| AP016 | Missing error logging before rethrow | High |
| AP017 | Incorrect attribute merging on partial update | High |
| AP018 | Missing Swagger documentation | Low |
| AP019 | Missing pagination in list queries | High |
| AP020 | Missing `getCommandSource` for tracing | Low |
| AP021 | Event emit directly after publishAsync | High |
| AP022 | Use of `eval()` or `Function()` constructor | Critical |
| AP023 | Shell command built from string concatenation | Critical |
| AP024 | HTTP request without timeout | Medium |
| AP025 | Logging `process.env` or full request object | High |
| AP026 | `@NotificationTransport` class also annotated with `@Injectable` | High |
| AP027 | `@GroupRoleResolver` class also annotated with `@Injectable` | High |

## Related Documentation

- [Service Patterns](/docs/service-patterns) - Recommended patterns
- [Command Service](/docs/command-service) - Correct command handling (AP001–AP003)
- [Event Handling Patterns](/docs/event-handling-patterns) - Correct sync handler patterns (AP009–AP010)
- [Backend Development](/docs/backend-development) - Core backend implementation guide
- [Security Best Practices](/docs/security-best-practices) - Security guidelines
- [Common Issues](/docs/common-issues) - Troubleshooting guide
- [MCP Server](/docs/mcp-server) - Anti-pattern detection tools


---

## Error Catalog

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/error-catalog

# Error Catalog

This catalog provides comprehensive documentation of errors encountered in MBC CQRS Serverless, including their causes, solutions, and recovery strategies.

## Quick Reference {#quick-reference}

Use this table to quickly identify errors and jump to solutions.

### Command & Data Errors

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-CMD-001 | Invalid input: item not found or version mismatch | High | Fetch latest version or use `version: -1` |
| MBC-CMD-002 | Invalid input key: item not found | Medium | Check if item exists before update |
| MBC-CMD-003 | Invalid input version | Medium | Use latest version from getItem() |

### Tenant Errors {#tenant-errors}

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-TNT-001 | Tenant not found | High | Verify tenant exists with getTenant() |
| MBC-TNT-002 | Tenant already exists | Low | Check existence before creating |

### Sequence & Task Errors

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-SEQ-001 | Sequence not found | Medium | Sequence auto-initializes on first use |
| MBC-TSK-001 | Task not found | Medium | Verify task exists with NotFoundException |

### Validation Errors {#validation-errors}

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-VAL-001 | Validation failed | Medium | Check DTO constraints and input data |

### DynamoDB Errors {#dynamodb-errors}

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-DDB-001 | ProvisionedThroughputExceededException | High | Implement exponential backoff retry |
| MBC-DDB-002 | ConditionalCheckFailedException | High | Refresh item and retry with new version |
| MBC-DDB-003 | ResourceNotFoundException | Critical | Verify table exists and check env vars |
| MBC-DDB-004 | ValidationException | Medium | Avoid empty strings, escape reserved words |

### Authentication Errors

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-COG-001 | NotAuthorizedException | High | Refresh token or re-authenticate |
| MBC-COG-002 | UserNotFoundException | Medium | Check user exists in pool |
| MBC-COG-003 | UserNotConfirmedException | Medium | Resend confirmation code |

### Import Module Errors

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-IMP-001 | Step Functions Timeout | Critical | Upgrade to v1.0.18+ for proper failure handling |
| MBC-IMP-002 | No import strategy found | High | Register ImportStrategy in module config |
| MBC-IMP-003 | Import stuck in PROCESSING | High | Check DynamoDB streams and SNS topics |

### Step Functions Errors {#step-functions-errors}

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-SFN-001 | TaskTimedOut | High | Increase Lambda timeout or chunk processing |
| MBC-SFN-002 | TaskFailed | High | Add proper error handling with sendTaskFailure |

### AWS Service Errors

| Code | Error Message | Severity | Quick Fix |
|----------|-------------------|--------------|---------------|
| MBC-S3-001 | NoSuchKey | Medium | Check object exists with headObject |
| MBC-S3-002 | AccessDenied | High | Add required IAM permissions |
| MBC-SQS-001 | MessageNotInflight | Medium | Process within visibility timeout |

---

## Command Service Errors {#command-service-errors}

### BadRequestException: "Invalid input: item not found or version mismatch"

**Location**: `packages/core/src/commands/command.service.ts`

**Cause**: Optimistic locking failure. The version number in the request does not match the current version in the database.

:::info Version Note
In versions prior to v1.0.25, this exception used the message "The input is not a valid, item not found or version not match". The wording was corrected in v1.0.25; the cause and solution are the same.
:::

**Solution**:
```typescript
// Option 1: Fetch latest version before update
const latest = await dataService.getItem({ pk, sk });
if (!latest) throw new NotFoundException('Item not found');
await commandService.publishPartialUpdateSync({
  pk,
  sk,
  version: latest.version,
  name: 'Updated Name',
}, options);

// Option 2: Use version: -1 for auto-fetch (async mode only)
await commandService.publishPartialUpdateAsync({
  pk,
  sk,
  version: -1,
  name: 'Updated Name',
}, options);

// Option 3: Implement retry logic
async function updateWithRetry(data, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const latest = await dataService.getItem({ pk: data.pk, sk: data.sk });
      if (!latest) throw new NotFoundException('Item not found');
      return await commandService.publishPartialUpdateSync({
        ...data,
        version: latest.version,
      }, options);
    } catch (error) {
      if (error.message.includes('version mismatch') && i < maxRetries - 1) {
        await new Promise(r => setTimeout(r, 100 * (i + 1)));
        continue;
      }
      throw error;
    }
  }
}
```

---

### BadRequestException: "Invalid input key: item not found"

**Location**: `packages/core/src/commands/command.service.ts`

**Cause**: Attempting to update an item that does not exist in the database.

**Solution**:
```typescript
// Check if item exists first
const existing = await dataService.getItem({ pk, sk });
if (!existing) {
  // Create new item
  await commandService.publishAsync(newItem, options);
} else {
  // Update existing item
  await commandService.publishPartialUpdateAsync({
    pk,
    sk,
    version: existing.version,
    ...updates,
  }, options);
}
```

---

### BadRequestException: "Invalid input version. The input version must be equal to the latest version"

**Location**: `packages/core/src/commands/command.service.ts`

**Cause**: Using a version in publishSync that does not match the latest saved version.

**Solution**: Fetch the latest item and use its version, or use version: -1 with async methods.

---

## Tenant Errors {#tenant-errors}

### BadRequestException: "Tenant not found"

**Location**: `packages/tenant/src/services/tenant.service.ts`

**Cause**: The tenant code passed to `addTenantGroup()` or a similar mutation method does not exist. `getTenant()` does not throw this error — it returns `undefined` for missing tenants.

**Solution**:
```typescript
// Verify tenant exists before mutating
const pk = `${TENANT_SYSTEM_PREFIX}${KEY_SEPARATOR}${SettingTypeEnum.TENANT}`;
const sk = `${TENANT_SK}${KEY_SEPARATOR}${tenantCode}`;
const tenant = await tenantService.getTenant({ pk, sk });
if (!tenant) {
  console.log('Tenant does not exist:', tenantCode);
}
```

---

### BadRequestException: "Tenant already exists"

**Location**: `packages/tenant/src/services/tenant.service.ts`

**Cause**: Attempting to create a tenant with an existing code.

**Solution**:
```typescript
// Check if tenant exists before creating
const pk = `${TENANT_SYSTEM_PREFIX}${KEY_SEPARATOR}${SettingTypeEnum.TENANT}`;
const sk = `${TENANT_SK}${KEY_SEPARATOR}${tenantCode}`;
const existing = await tenantService.getTenant({ pk, sk });
if (existing && !existing.isDeleted) {
  console.log('Tenant already exists, using existing tenant');
} else {
  await tenantService.createTenant({ code: tenantCode, name: tenantName }, { invokeContext });
}
```

---

## Sequence Errors {#sequence-errors}

### BadRequestException: "Sequence not found"

**Location**: `packages/sequence/src/sequences.service.ts`

**Cause**: The requested sequence key does not exist.

**Solution**:
```typescript
// Generate sequence - auto-initializes on first use
try {
  const result = await sequencesService.generateSequenceItem(
    {
      tenantCode,
      typeCode: 'ORDER',
    },
    { invokeContext },
  );
} catch (error) {
  // If error persists, check DynamoDB table permissions
}
```

---

## Task Errors {#task-errors}

### NotFoundException: "Task not found"

**Location**: `packages/task/src/task.controller.ts`

**Cause**: The specified task does not exist or has been completed/deleted.

**Solution**:
```typescript
// Verify task status before operations
const task = await taskService.getTask({ pk, sk });
if (!task) {
  throw new NotFoundException('Task not found');
}
if (task.status === 'completed') {
  throw new BadRequestException('Task already completed');
}
```

---

## Validation Errors {#validation-errors}

### BadRequestException: "Validation failed"

**Location**: `packages/core/src/pipe/class.validation.pipe.ts`

**Cause**: The request DTO failed class-validator validation.

**Common Validation Errors**:
```typescript
// Example DTO with validation
export class CreateOrderDto {
  @IsNotEmpty({ message: 'Name is required' })
  @IsString()
  @MaxLength(100)
  name: string;

  @IsNotEmpty({ message: 'Code is required' })
  @Matches(/^[A-Z0-9-]+$/, { message: 'Code must be uppercase alphanumeric' })
  code: string;

  @IsOptional()
  @IsNumber()
  @Min(0)
  amount?: number;
}

// Common validation errors and fixes:
// - "name must be a string" -> Ensure name is string type
// - "code should not be empty" -> Provide code value
// - "amount must not be less than 0" -> Use positive number
```

**Solution**:
```typescript
// Validate before sending
import { validate } from 'class-validator';
import { plainToInstance } from 'class-transformer';

const dto = plainToInstance(CreateOrderDto, requestBody);
const errors = await validate(dto);
if (errors.length > 0) {
  console.log('Validation errors:', errors.map(e => e.constraints));
}
```

---

## DynamoDB Errors {#dynamodb-errors}

### ProvisionedThroughputExceededException

**Location**: AWS DynamoDB

**Cause**: Read or write capacity has been exceeded on on-demand or provisioned tables.

**Solution**:
```typescript
// Implement exponential backoff retry
async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 5,
  baseDelay = 100
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.name === 'ProvisionedThroughputExceededException') {
        const delay = baseDelay * Math.pow(2, i) + Math.random() * 100;
        console.log(`Throughput exceeded, retrying in ${delay}ms...`);
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}
```

**Prevention**:
- Use on-demand capacity mode for unpredictable workloads
- Implement request batching to reduce write operations
- Use DAX for read-heavy workloads

---

### ConditionalCheckFailedException

**Location**: AWS DynamoDB

**Cause**: Optimistic locking condition failed (version mismatch) or unique constraint violation.

**Solution**:
```typescript
// Handle conditional check failure
try {
  await commandService.publishSync(item, options);
} catch (error) {
  if (error.name === 'ConditionalCheckFailedException') {
    // Refresh and retry
    const latest = await dataService.getItem({ pk, sk });
    if (!latest) throw new NotFoundException('Item not found');
    await commandService.publishSync({
      ...item,
      version: latest.version,
    }, options);
  }
}
```

---

### ResourceNotFoundException

**Location**: AWS DynamoDB

**Cause**: The specified table or index does not exist.

**Solution**:
```bash
# Verify table exists
aws dynamodb describe-table --table-name your-table-name

# Check environment variable
echo $DYNAMODB_TABLE_NAME
```

---

### ValidationException: "One or more parameter values were invalid"

**Location**: AWS DynamoDB

**Cause**: Invalid key structure, empty string for non-key attribute, or reserved word conflict.

**Solution**:
```typescript
// Avoid empty strings
const item = {
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001',
  name: value || null,  // Use null instead of empty string
};

// Use expression attribute names for reserved words
const params = {
  ExpressionAttributeNames: {
    '#name': 'name',
    '#status': 'status',
  },
};
```

---

## Cognito Authentication Errors {#cognito-errors}

### NotAuthorizedException

**Location**: AWS Cognito

**Cause**: Invalid credentials or token expired.

**Solution**:
```typescript
// Frontend: Refresh token
try {
  await Auth.currentSession();  // Auto-refreshes if needed
} catch (error) {
  if (error.name === 'NotAuthorizedException') {
    // Redirect to login
    await Auth.signOut();
    window.location.href = '/login';
  }
}
```

---

### UserNotFoundException

**Location**: AWS Cognito

**Cause**: User does not exist in the user pool.

**Solution**:
```typescript
// Check user exists before operations
try {
  const user = await adminGetUser({ Username: email });
} catch (error) {
  if (error.name === 'UserNotFoundException') {
    // Create new user or show registration form
  }
}
```

---

### UserNotConfirmedException

**Location**: AWS Cognito

**Cause**: User has not confirmed their email/phone.

**Solution**:
```typescript
try {
  await Auth.signIn(email, password);
} catch (error) {
  if (error.name === 'UserNotConfirmedException') {
    // Resend confirmation code
    await Auth.resendSignUp(email);
    // Redirect to confirmation page
  }
}
```

---

## Import Module Errors {#import-module-errors}

:::tip Related Documentation
For API details and usage patterns, see [ImportStatusHandler API](/docs/import-export-patterns#importstatushandler-api). For version history, see [Changelog v1.0.18](/docs/changelog#v1018).
:::

### Step Functions Timeout (Import Job)

**Location**: `packages/import/src/event/import-status.queue.event.handler.ts`

**Symptom**: Step Functions execution stays in `RUNNING` state indefinitely for import jobs.

**Cause**: Prior to version 1.0.18, the `ImportStatusHandler` only sent `SendTaskSuccessCommand` for completed jobs. When an import job failed, no callback was sent to Step Functions, causing it to wait indefinitely for the `waitForTaskToken` callback.

**Solution** (Fixed in 1.0.18+):
The handler now always calls `SendTaskSuccessCommand` so the ZIP orchestrator can continue. For FAILED jobs, the failure status is embedded in the output payload (via `buildZipOrchestratorFailureOutput`) so the orchestrator can mark the ZIP job as FAILED after aggregating all files:

```typescript
// Internal behavior (automatic, no user action needed):
// - COMPLETED status → SendTaskSuccessCommand (with result payload)
// - FAILED status → SendTaskSuccessCommand (with failure info embedded in output)
```

If you're on an older version:
1. Upgrade to `@mbc-cqrs-serverless/import@^1.0.18`
2. For stuck executions, manually stop them via AWS Console or CLI:
   ```bash
   aws stepfunctions stop-execution --execution-arn <execution-arn>
   ```

---

### BadRequestException: "No import strategy found for table: `{tableName}`"

**Location**: `packages/import/src/import.service.ts`

**Cause**: No import strategy is registered for the specified table name.

**Solution**:
Register an import strategy when configuring the ImportModule:

```typescript
ImportModule.register({
  profiles: [
    {
      tableName: 'your-table-name',  // Must match the tableName in your import request
      importStrategy: YourImportStrategy,
      processStrategy: YourProcessStrategy,
    },
  ],
})
```

---

### Import Job Stuck in PROCESSING Status

**Location**: `packages/import/src/event/import.queue.event.handler.ts`

**Cause**: An error occurred during import processing but the job status wasn't properly updated, or DynamoDB streams failed to trigger the next step.

**Solution**:
1. Check CloudWatch logs for Lambda errors
2. Verify DynamoDB streams are enabled on the import_tmp table
3. Check if the SNS topic for import status notifications exists
4. Clean up stuck records:
   ```typescript
   await importService.updateStatus(
     { pk: 'CSV_IMPORT#tenant', sk: 'table#taskCode' },
     ImportStatusEnum.FAILED,
     { error: 'Manual cleanup' }
   );
   ```

---

## Step Functions Errors {#step-functions-errors}

### TaskTimedOut

**Location**: AWS Step Functions

**Cause**: Lambda function did not respond within the configured timeout.

**Solution**:
```typescript
// Increase Lambda timeout in serverless.yml
functions:
  processTask:
    handler: handler.process
    timeout: 900  # 15 minutes max

// Or break into smaller chunks
async function processInChunks(items, chunkSize = 100) {
  for (let i = 0; i < items.length; i += chunkSize) {
    const chunk = items.slice(i, i + chunkSize);
    await processChunk(chunk);
  }
}
```

---

### TaskFailed

**Location**: AWS Step Functions

**Cause**: Lambda function threw an unhandled error.

**Solution**:
```typescript
import { SFNClient, SendTaskSuccessCommand, SendTaskFailureCommand } from '@aws-sdk/client-sfn';

const sfnClient = new SFNClient({});

// Proper error handling with Step Functions
export async function handler(event: StepFunctionEvent) {
  try {
    const result = await processTask(event.input);

    // Send success callback
    await sfnClient.send(new SendTaskSuccessCommand({
      taskToken: event.taskToken,
      output: JSON.stringify(result),
    }));
  } catch (error) {
    // Send failure callback
    await sfnClient.send(new SendTaskFailureCommand({
      taskToken: event.taskToken,
      error: error.name,
      cause: error.message,
    }));
  }
}
```

---

## S3 Errors {#s3-errors}

### NoSuchKey

**Location**: AWS S3

**Cause**: The specified object does not exist in the bucket.

**Solution**:
```typescript
import { S3Client, HeadObjectCommand, GetObjectCommand } from '@aws-sdk/client-s3';

const s3Client = new S3Client({});

// Check if object exists before downloading
try {
  await s3Client.send(new HeadObjectCommand({ Bucket: bucket, Key: key }));
  const data = await s3Client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
} catch (error) {
  if (error.name === 'NoSuchKey' || error.name === 'NotFound') {
    console.log('File does not exist:', key);
    return null;
  }
  throw error;
}
```

---

### AccessDenied

**Location**: AWS S3

**Cause**: IAM policy does not allow the requested operation.

**Solution**:
```yaml
# Add required permissions in serverless.yml
provider:
  iam:
    role:
      statements:
        - Effect: Allow
          Action:
            - s3:GetObject
            - s3:PutObject
            - s3:DeleteObject
          Resource:
            - arn:aws:s3:::${self:custom.bucketName}/*
```

---

## SQS Errors {#sqs-errors}

### MessageNotInflight

**Location**: AWS SQS

**Cause**: Attempting to delete or change visibility of a message that is no longer in flight.

**Solution**:
```typescript
// Process messages within visibility timeout
export async function handler(event: SQSEvent) {
  for (const record of event.Records) {
    try {
      await processMessage(record);
      // Message auto-deleted on successful return
    } catch (error) {
      // Throw to keep message in queue for retry
      throw error;
    }
  }
}
```

---

## HTTP Status Code Reference {#http-status-codes}

| Status | Exception | Meaning | Recovery Strategy |
|--------|-----------|---------|-------------------|
| 400 | BadRequestException | Invalid input or business rule violation | Fix request data |
| 401 | UnauthorizedException | Authentication missing or invalid | Refresh token or re-login |
| 403 | ForbiddenException | Authenticated but not authorized | Check user permissions |
| 404 | NotFoundException | Resource not found | Verify resource exists |
| 409 | ConflictException | Version conflict (optimistic locking) | Refresh and retry |
| 422 | UnprocessableEntityException | Validation failed | Fix validation errors |
| 429 | TooManyRequestsException | Rate limit exceeded | Implement backoff retry |
| 500 | InternalServerErrorException | Unexpected server error | Check logs, report bug |
| 502 | BadGatewayException | Upstream service error | Retry with backoff |
| 503 | ServiceUnavailableException | Service temporarily unavailable | Retry later |
| 504 | GatewayTimeoutException | Upstream service timeout | Increase timeout or optimize |

---

## Error Handling Best Practices {#error-handling-best-practices}

### 1. Centralized Error Handler

```typescript
import { Catch, ExceptionFilter, ArgumentsHost, HttpException } from '@nestjs/common';

// Create a global exception filter
@Catch()
export class GlobalExceptionFilter implements ExceptionFilter {
  catch(exception: unknown, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const request = ctx.getRequest();

    const status = exception instanceof HttpException
      ? exception.getStatus()
      : 500;

    const message = exception instanceof HttpException
      ? exception.message
      : 'Internal server error';

    // Log error with context
    console.error({
      timestamp: new Date().toISOString(),
      path: request.url,
      method: request.method,
      status,
      message,
      stack: exception instanceof Error ? exception.stack : undefined,
    });

    response.status(status).json({
      statusCode: status,
      message,
      timestamp: new Date().toISOString(),
      path: request.url,
    });
  }
}
```

### 2. Retry with Exponential Backoff

```typescript
async function retryWithBackoff<T>(
  operation: () => Promise<T>,
  options: {
    maxRetries?: number;
    baseDelay?: number;
    maxDelay?: number;
    retryableErrors?: string[];
  } = {}
): Promise<T> {
  const {
    maxRetries = 3,
    baseDelay = 100,
    maxDelay = 10000,
    retryableErrors = [
      'ProvisionedThroughputExceededException',
      'ThrottlingException',
      'ServiceUnavailable',
    ],
  } = options;

  let lastError: Error;

  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await operation();
    } catch (error) {
      lastError = error;

      if (!retryableErrors.includes(error.name) || attempt === maxRetries) {
        throw error;
      }

      const delay = Math.min(
        baseDelay * Math.pow(2, attempt) + Math.random() * 100,
        maxDelay
      );

      console.log(`Retry attempt ${attempt + 1} after ${delay}ms`);
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }

  throw lastError;
}
```

### 3. Circuit Breaker Pattern

```typescript
class CircuitBreaker {
  private failures = 0;
  private lastFailure: number = 0;
  private state: 'closed' | 'open' | 'half-open' = 'closed';

  constructor(
    private threshold: number = 5,
    private timeout: number = 60000
  ) {}

  async execute<T>(operation: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      if (Date.now() - this.lastFailure > this.timeout) {
        this.state = 'half-open';
      } else {
        throw new Error('Circuit breaker is open');
      }
    }

    try {
      const result = await operation();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess() {
    this.failures = 0;
    this.state = 'closed';
  }

  private onFailure() {
    this.failures++;
    this.lastFailure = Date.now();
    if (this.failures >= this.threshold) {
      this.state = 'open';
    }
  }
}
```

---

## Debugging Tips {#debugging-tips}

1. **Enable debug logging**:
   ```bash
   DEBUG=* npm run offline
   ```

2. **Check CloudWatch logs for Lambda errors**:
   ```bash
   aws logs tail /aws/lambda/your-function-name --follow
   ```

3. **Use request IDs for tracing**:
   ```typescript
   console.log('RequestId:', context.awsRequestId);
   ```

4. **Verify environment variables**:
   ```typescript
   console.log('Config:', {
     table: process.env.DYNAMODB_TABLE_NAME,
     region: process.env.AWS_REGION,
   });
   ```

5. **Test locally with serverless-offline**:
   ```bash
   npm run offline -- --stage dev
   ```

## Related Documentation

- [Debugging Guide](/docs/debugging-guide) - Detailed debugging procedures
- [Common Issues](/docs/common-issues) - Frequently encountered problems
- [Monitoring and Logging](/docs/monitoring-logging) - Production monitoring setup
- [Version Conflict Guide](/docs/version-conflict-guide) - Optimistic locking patterns and retry strategies


---

## Glossary

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/glossary

# Glossary

This glossary provides definitions for key terms and concepts used throughout the MBC CQRS Serverless framework documentation.

## Design Patterns {#design-patterns}

### CQRS (Command Query Responsibility Segregation)

The command query responsibility segregation (CQRS) pattern separates the data mutation, or the command part of a system, from the query part. You can use the CQRS pattern to separate updates and queries if they have different requirements for throughput, latency, or consistency. The CQRS pattern splits the application into two parts—the command side and the query side. The command side handles create, update, and delete requests. The query side runs the query part by using the read replicas.

![CQRS flow](./images/CQRS.png)

> See: [CQRS pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/modernization-data-persistence/cqrs-pattern.html)

### Event Sourcing

The Event Sourcing pattern is typically used with the CQRS pattern to decouple read from write workloads, and optimize for performance, scalability, and security. Data is stored as a series of events, instead of direct updates to data stores. Microservices replay events from an event store to compute the appropriate state of their own data stores. The pattern provides visibility for the current state of the application and additional context for how the application arrived at that state. The Event Sourcing pattern works effectively with the CQRS pattern because data can be reproduced for a specific event, even if the command and query data stores have different schemas.

> See: [Event Sourcing pattern](https://docs.aws.amazon.com/prescriptive-guidance/latest/modernization-data-persistence/service-per-team.html)

### Optimistic Locking

A concurrency control mechanism that allows multiple transactions to proceed without locking resources. Before committing, the system checks if another transaction has modified the data. In MBC CQRS Serverless, this is implemented using version numbers - each update must include the current version, and the update fails if the version doesn't match.

### Domain-Driven Design (DDD)

A software design approach that focuses on modeling software based on the business domain. Key concepts include entities, value objects, aggregates, and bounded contexts. MBC CQRS Serverless uses DDD principles to structure modules and entities.

### Aggregate

A cluster of domain objects that can be treated as a single unit. An aggregate has a root entity (the aggregate root) and boundary that defines what's inside the aggregate. In MBC CQRS Serverless, each command table typically represents an aggregate.

## Framework Concepts {#framework-concepts}

### Command

A request to change the state of the system. Commands are processed by the command side of the CQRS pattern. In MBC CQRS Serverless, commands are published using CommandService and stored in DynamoDB command tables.

### Command Table

A DynamoDB table that stores the command (write) model. Contains the full history of changes with version tracking. Data flows from command tables to data tables via DynamoDB Streams.

### Data Table

A DynamoDB table that stores the data (read) model. Contains the current state of entities, optimized for queries. Updated automatically when commands are processed.

### Data Sync Handler

A handler that processes DynamoDB Stream events to synchronize data between tables or to external systems like RDS. Implements the IDataSyncHandler interface.

### Invoke Context

The context object passed to service methods containing user information, tenant context, and request metadata. Created from the Lambda event and used for authorization and auditing.

### UserContext

A structured object extracted from the Invoke Context via `getUserContext(invokeContext)`. Contains the authenticated user's information: `userId`, `email`, `tenantCode`, `roles` (from `custom:roles` JWT claim), `tenantRole` (first role, for backward compatibility), and — since v1.3.1 — `tenantRoles` (all direct roles) and `tenantGroupIds` (Cognito group IDs for the active tenant). See [Helpers — getUserContext](/docs/helpers#context-helpers).

### Partition Key (PK)

The primary key component in DynamoDB that determines data distribution across partitions. In MBC CQRS Serverless, typically formatted as `TYPE#tenantCode` (e.g., `ORDER#tenant001`).

### Sort Key (SK)

The secondary key component in DynamoDB that enables range queries within a partition. In MBC CQRS Serverless, typically formatted as `TYPE#code` for data tables or `TYPE#code@vN` for command tables.

### Tenant

An isolated organizational unit in a multi-tenant application. Each tenant has its own data partition identified by a tenant code. Tenants share the application infrastructure but have completely isolated data.

### Version

A number that tracks the revision history of an entity. Incremented on each update. Used for optimistic locking to prevent concurrent update conflicts.

### CommandModel

The TypeScript type returned by `publishAsync`, `publishSync`, and related methods. Encapsulates the result of a command operation including metadata such as `pk`, `sk`, `version`, `tenantCode`, and `attributes`. Methods may return `null` when the command produces no change (no-op).

### DataEntity

The base class for entities stored in data (read-side) tables. Extends the raw DynamoDB item with typed accessors and helper methods. Used in the `items` array returned by `DataService.listItemsByPk()`. Note: `DataService.getItem()` returns the raw `DataModel` interface, not `DataEntity`.

### CommandEntity

The base class for entities stored in command tables. Tracks full command history including version, tenant, and attribute changes. Typically used in data sync handlers to read command-side state.

### DetailKey

A key object containing `pk` (partition key) and `sk` (sort key) used to identify a specific item in DynamoDB. Passed to methods like `getItem({ pk, sk })` and `getLatestItem({ pk, sk })`.

### VERSION_FIRST

A constant with value `0` used as the version when creating a new entity that does not yet exist. The framework sets version `1` on the first successful write. Import from `@mbc-cqrs-serverless/core`.

### VERSION_LATEST

A constant with value `-1` used to instruct the framework to auto-resolve to the latest version of an entity, bypassing optimistic locking. Use only when "last writer wins" semantics are intentional. Import from `@mbc-cqrs-serverless/core`.

### NotificationTransport

A pluggable notification delivery mechanism registered with `@NotificationTransport()`. Built-in transports are `appsync-graphql` (default) and `appsync-event` (opt-in, v1.3.0+). Custom transports can be added by implementing `INotificationTransport` and registering with `@NotificationTransport('transport-name')`.

### AppSync Events API

An HTTP pub/sub API provided by AWS AppSync that does not require a GraphQL schema. Available as an opt-in notification transport since v1.3.0 via `NOTIFICATION_TRANSPORTS=appsync-event`. Channel paths follow the pattern `/{namespace}/{tenantCode}/{action}/{itemId}`. Clients subscribe using the Amplify v6 `events` API; servers publish via `AppSyncEventsService`.

### GroupRoleResolver

A user-supplied class (annotated with `@GroupRoleResolver()`) that maps Cognito group IDs to application roles. Introduced in v1.3.1. Exactly one resolver must be registered per application to use group-based role authorization. Do not also annotate the class with `@Injectable()` — `@GroupRoleResolver()` already registers the singleton provider.

### IGroupRoleResolver

The TypeScript interface that a `GroupRoleResolver` class must implement. Defines a single method `resolveRoles(groupIds: string[]): Promise<string[]> | string[]` that receives the Cognito group IDs for the current tenant and returns the corresponding application roles. Introduced in v1.3.1.

### custom:groups

A Cognito user pool attribute (JWT claim) added in v1.3.1 that stores tenant-scoped group memberships as a JSON-encoded array of `{"tenant": "...", "groups": [...]}` objects. The framework parses this claim to determine which Cognito groups a user belongs to for the active tenant, then passes the group IDs to the `GroupRoleResolver` for role derivation. Malformed or absent values are treated as an empty group list (fault-tolerant parsing).

### Read-Your-Writes (RYW)

A consistency guarantee where a user sees their own most-recent write immediately after it is published, even before the async DynamoDB Stream pipeline has propagated the change to the read model. Implemented via the `Repository` class and enabled by setting `RYW_SESSION_TTL_MINUTES`. See [Command Service — Read-Your-Writes](/docs/command-service#read-your-writes) for details.

### Repository

A drop-in replacement for `DataService` that adds Read-Your-Writes (RYW) session caching. When a user publishes a command via `publishAsync`, the pending data is stored in a DynamoDB session table. Subsequent `getItem` and `listItemsByPk` calls merge pending data with the persisted read model, so the user sees their own writes before the DynamoDB Stream propagates the change. Enabled by setting `RYW_SESSION_TTL_MINUTES` in the environment.

### History Table

A DynamoDB table that stores every past version of a command as an immutable record. Written by `publishSync` (since v1.1.4) and by the Stream-based async pipeline. Used by `HistoryService.getItem()` to retrieve a specific historical version for audit trails or rollback. The sort key includes the version suffix: `sk@N`.

### ULID (Universally Unique Lexicographically Sortable Identifier)

A time-ordered unique identifier format used as sort keys for DynamoDB items. ULIDs are 26 characters, URL-safe, monotonically sortable by creation time within a millisecond, and globally unique. Generated with `ulid()` from the `ulidx` package. Using ULID as the sort key enables time-based range queries and predictable ordering of items.

## AWS Services {#aws-services}

### Amazon DynamoDB

A fully managed NoSQL database service that provides fast and predictable performance with seamless scalability. MBC CQRS Serverless uses DynamoDB as the primary data store for both command and data tables.

### DynamoDB Streams

A feature that captures data modification events in DynamoDB tables. Used by MBC CQRS Serverless to trigger data synchronization between command and data tables, and to external systems.

### AWS Lambda

A serverless compute service that runs code in response to events. MBC CQRS Serverless uses Lambda functions for API handlers, event processors, and background tasks.

### Amazon Cognito

A service that provides user authentication, authorization, and user management. MBC CQRS Serverless uses Cognito for user authentication and JWT token validation.

### AWS Step Functions

A serverless orchestration service that lets you combine Lambda functions and other AWS services. Used in MBC CQRS Serverless for long-running workflows like data imports and batch processing.

### Amazon SES (Simple Email Service)

An email platform that provides an easy, cost-effective way to send and receive email. Used by MBC CQRS Serverless for notification emails.

### Amazon S3 (Simple Storage Service)

Object storage service for storing and retrieving any amount of data. Used for file uploads, exports, and static asset storage.

### Amazon SQS (Simple Queue Service)

A fully managed message queuing service. Used for asynchronous processing and decoupling components.

### Amazon RDS (Relational Database Service)

A managed relational database service. Used in MBC CQRS Serverless for complex queries that require SQL joins and aggregations.

### AWS AppSync

A managed GraphQL and Pub/Sub API service. MBC CQRS Serverless uses AppSync for real-time notifications — either via GraphQL Subscriptions (default) or the schema-free AppSync Events API (opt-in since v1.3.0).

### AWS CDK (Cloud Development Kit)

An open-source software development framework to define cloud infrastructure in code. MBC CQRS Serverless uses CDK for infrastructure provisioning.

### API Gateway

A fully managed service for creating, publishing, and managing APIs. Provides the HTTP endpoints for MBC CQRS Serverless applications.

### CloudWatch

A monitoring and observability service. Used for logging, metrics, and alarms in MBC CQRS Serverless applications.

## Tooling & Libraries {#tooling-libraries}

### NestJS

Nest (NestJS) is a framework for building efficient, scalable Node.js server-side applications. It uses progressive JavaScript, is built with and fully supports TypeScript (yet still enables developers to code in pure JavaScript) and combines elements of OOP (Object Oriented Programming), FP (Functional Programming), and FRP (Functional Reactive Programming).

> See: [NestJS Documentation](https://docs.nestjs.com/)

### Serverless Framework

The Serverless Framework consists of a Command Line Interface and an optional Dashboard, and helps you deploy code and infrastructure together on Amazon Web Services, while increasingly supporting other cloud providers. The Framework is a YAML-based experience that uses simplified syntax to help you deploy complex infrastructure patterns easily, without needing to be a cloud expert.

> See: [Serverless Framework Documentation](https://www.serverless.com/framework/docs)

### Prisma

Prisma is an ORM for Node.js and TypeScript that serves as an alternative to writing plain SQL or using other database access tools, such as Knex or Sequelize. It simplifies database access and management by providing developers with a type-safe query builder and auto-generator.

> See: [Prisma Documentation](https://www.prisma.io/docs/orm/overview/introduction/what-is-prisma)

### class-validator

A validation library that uses decorators for defining validation rules on class properties. Used in MBC CQRS Serverless for request DTO validation.

### class-transformer

A library for transforming plain objects into class instances and vice versa. Works with class-validator for type-safe request handling.

## API Concepts {#api-concepts}

### DTO (Data Transfer Object)

An object that carries data between processes. In MBC CQRS Serverless, DTOs define the structure of API request and response bodies, typically with validation decorators.

### Entity

A domain object with a distinct identity that persists over time. In MBC CQRS Serverless, entities are TypeScript classes that define the structure of data stored in DynamoDB.

### Controller

A class that handles incoming HTTP requests. In NestJS/MBC CQRS Serverless, controllers define API routes and delegate business logic to services.

### Service

A class that contains business logic. In MBC CQRS Serverless, services orchestrate data operations using CommandService and DataService.

### Module

A class annotated with @Module() decorator that organizes the application structure. Each feature area has its own module containing controllers, services, and providers.

### Guard

A class that determines whether a request should be handled by the route handler. Used for authentication and authorization.

### Pipe

A class that transforms or validates input data before it reaches the route handler. Used for validation and data transformation.

### Middleware

A function called before the route handler. Can perform operations like logging, authentication, and request modification.

## Data Operations {#data-operations}

### Publish (publishAsync/publishSync)

Create or update an entity. `publishAsync` writes to the command table and returns immediately (async data propagation via DynamoDB Streams is a side effect). `publishSync` runs the full write + data sync pipeline synchronously before returning.

### Partial Update (publishPartialUpdateAsync/publishPartialUpdateSync)

Update specific fields of an existing entity without providing all fields. Requires version for optimistic locking.

### Soft Delete

Mark an entity as deleted (isDeleted: true) without physically removing it from the database. Allows for data recovery and audit trails.

### Hard Delete

Physically remove an entity from the database. Typically done with TTL (Time-to-Live) or explicit delete operations.

### Sequence

An auto-incrementing number generator. Used to generate unique codes like order numbers. Rotation modes: `DAILY`, `MONTHLY`, `YEARLY`, `FISCAL_YEARLY`, or `NONE` (no rotation).

## Architecture Terms {#architecture-terms}

### Cold Start

The initial startup time of a Lambda function when it's invoked after being idle. Can affect latency for the first request.

### Warm Start

Subsequent invocations of a Lambda function that reuse an existing execution environment. Faster than cold starts.

### Idempotency

The property where an operation produces the same result regardless of how many times it's executed. Critical for retry logic and event handling.

### Eventually Consistent

A consistency model where reads may not immediately reflect the latest write, but will eventually become consistent. Default for DynamoDB reads.

### Strongly Consistent

A consistency model where reads always return the most recent write. Available for DynamoDB reads with higher latency.

### TTL (Time-to-Live)

A DynamoDB feature that automatically deletes items after a specified timestamp. Used for temporary data and automatic cleanup.

### GSI (Global Secondary Index)

An index with a partition key and optional sort key different from the table's primary key. Enables efficient queries on alternative access patterns.

### LSI (Local Secondary Index)

An index with the same partition key as the table but a different sort key. Must be created at table creation time.

## Security Terms {#security-terms}

### JWT (JSON Web Token)

A compact, URL-safe token format for securely transmitting claims. Used by Cognito for authentication tokens.

### IAM (Identity and Access Management)

AWS service for managing access to AWS resources. Defines permissions for Lambda functions and other services.

### RBAC (Role-Based Access Control)

An access control method where permissions are assigned to roles, and users are assigned to roles. Implemented via Cognito groups.

## Related Documentation

- [Architecture](/docs/architecture) - System architecture overview
- [CQRS Flow](/docs/architecture/cqrs-flow) - Detailed CQRS implementation
- [Getting Started](/docs/getting-started) - Introduction to key concepts


---

## Helper Functions

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/helpers

# Helper Functions

The framework provides various helper functions for common operations.

## Key Helpers {#key-helpers}

Functions for working with DynamoDB keys.

### `addSortKeyVersion(sk: string, version: number): string`

Adds a version suffix to a sort key.

```ts
import { addSortKeyVersion } from '@mbc-cqrs-serverless/core';

const versionedSk = addSortKeyVersion('CAT#001', 1);
// Result: 'CAT#001@1'
```

### `getSortKeyVersion(sk: string): number`

Extracts the version number from a sort key. Returns VERSION_LATEST if no version suffix exists.

```ts
import { getSortKeyVersion } from '@mbc-cqrs-serverless/core';

const version = getSortKeyVersion('CAT#001@3');
// Result: 3

const latestVersion = getSortKeyVersion('CAT#001');
// Result: VERSION_LATEST (-1)
```

### `removeSortKeyVersion(sk: string): string`

Removes the version suffix from a sort key.

```ts
import { removeSortKeyVersion } from '@mbc-cqrs-serverless/core';

const sk = removeSortKeyVersion('CAT#001@3');
// Result: 'CAT#001'
```

### `generateId(pk: string, sk: string): string`

Generates a unique ID by combining partition key and sort key (without version).

```ts
import { generateId } from '@mbc-cqrs-serverless/core';

const id = generateId('TENANT#mbc', 'CAT#001@3');
// Result: 'TENANT#mbc#CAT#001'
```

### `sortKeyBaseFromId(pk: string, itemId: string): string | undefined`

The inverse of `generateId`: extracts the base sort key from a composite ID. Returns `undefined` if the ID does not start with the given partition key.

```ts
import { sortKeyBaseFromId } from '@mbc-cqrs-serverless/core';

const skBase = sortKeyBaseFromId('TENANT#mbc', 'TENANT#mbc#CAT#001');
// Result: 'CAT#001'
```

### `parseTwoSegmentPkSkFromId(itemId: string): { pk: string; skBase: string } | undefined`

Splits a composite ID back into its partition key and base sort key, assuming the partition key has two segments (type and tenant code). Returns `undefined` if the ID has fewer than three segments.

```ts
import { parseTwoSegmentPkSkFromId } from '@mbc-cqrs-serverless/core';

const result = parseTwoSegmentPkSkFromId('TENANT#mbc#CAT#001');
// result.pk is 'TENANT#mbc' and result.skBase is 'CAT#001'
```

### `getTenantCode(pk: string): string | undefined`

Extracts the tenant code from a partition key.

```ts
import { getTenantCode } from '@mbc-cqrs-serverless/core';

const tenantCode = getTenantCode('TENANT#mbc');
// Result: 'mbc'
```

### `masterPk(tenantCode?: string): string`

Generates a partition key for master data.

```ts
import { masterPk } from '@mbc-cqrs-serverless/core';

const pk = masterPk('mbc');
// Result: 'MASTER#mbc'

const commonPk = masterPk();
// Result: 'MASTER#single' (DEFAULT_TENANT_CODE)
```

### `seqPk(tenantCode?: string): string`

Generates a partition key for sequences.

```ts
import { seqPk } from '@mbc-cqrs-serverless/core';

const pk = seqPk('mbc');
// Result: 'SEQ#mbc'
```

### `ttlSk(tableName: string): string`

Generates a TTL sort key for a table. Used to identify TTL-related records.

```ts
import { ttlSk } from '@mbc-cqrs-serverless/core';

const sk = ttlSk('my-table');
// Result: 'TTL#my-table'
```

## S3 Attribute Helpers {#s3-attribute-helpers}

Functions for working with S3 URI attributes.

### `isS3AttributeKey(attributes: any): boolean`

Checks if an attribute value is an S3 URI.

```ts
import { isS3AttributeKey } from '@mbc-cqrs-serverless/core';

const isS3 = isS3AttributeKey('s3://my-bucket/path/to/file.pdf');
// Result: true

const isNotS3 = isS3AttributeKey('regular string');
// Result: false
```

### `toS3AttributeKey(bucket: string, key: string): string`

Creates an S3 URI from bucket and key.

```ts
import { toS3AttributeKey } from '@mbc-cqrs-serverless/core';

const s3Uri = toS3AttributeKey('my-bucket', 'path/to/file.pdf');
// Result: 's3://my-bucket/path/to/file.pdf'
```

### `parseS3AttributeKey(s3Uri: string): { bucket: string; key: string }`

Parses an S3 URI into bucket and key components.

```ts
import { parseS3AttributeKey } from '@mbc-cqrs-serverless/core';

const { bucket, key } = parseS3AttributeKey('s3://my-bucket/path/to/file.pdf');
// bucket: 'my-bucket', key: 'path/to/file.pdf'
```

## Context Helpers {#context-helpers}

Functions for working with invocation context and user information.

### `getUserContext(ctx: IInvoke | ExecutionContext): UserContext`

Extracts user context from the invocation context. Returns userId, tenantCode, tenantRole, tenantRoles, and tenantGroupIds.

```ts
import { getUserContext } from '@mbc-cqrs-serverless/core';

const userContext = getUserContext(invokeContext);
// Returns: { userId: '...', tenantCode: 'mbc', tenantRole: 'admin', tenantRoles: ['admin'], tenantGroupIds: [] }
```

### `extractInvokeContext(ctx?: ExecutionContext): IInvoke`

Extracts the invocation context from a NestJS execution context. Supports both Lambda and local development environments.

```ts
import { extractInvokeContext } from '@mbc-cqrs-serverless/core';
import { Injectable, CanActivate, ExecutionContext } from '@nestjs/common';

@Injectable()
export class MyGuard implements CanActivate {
  canActivate(ctx: ExecutionContext) {
    const invokeContext = extractInvokeContext(ctx);
    // Use ctx for further operations
    return true;
  }
}
```

### `getAuthorizerClaims(ctx: IInvoke): JwtClaims`

Extracts JWT claims from the authorizer in the invocation context.

```ts
import { getAuthorizerClaims } from '@mbc-cqrs-serverless/core';

const claims = getAuthorizerClaims(invokeContext);
// Returns JWT claims including sub, email, custom:tenant, etc.
```

## UserContext Class {#usercontext-class}

```ts
class UserContext {
  userId: string;            // User's unique identifier (sub claim)
  tenantCode: string;        // Current tenant code
  tenantRole: string;        // User's role in the current tenant
  tenantRoles: string[];     // Direct roles for the active tenant (excludes group-derived roles)
  tenantGroupIds: string[];  // Group IDs from custom:groups for the active tenant

  constructor(partial: Partial<UserContext>);
}
```

:::info Version Note
`tenantRoles` and `tenantGroupIds` were added to `UserContext` in [version 1.3.1](/docs/changelog#v131) as part of group-based role authorization. `tenantRole` (singular) is kept for backward compatibility. See [Authentication — Group-Based Roles](/docs/authentication#group-based-roles) for usage.
:::

## JwtClaims Interface {#jwt-claims}

```ts
interface JwtClaims {
  sub: string;                     // User's unique identifier
  iss: string;                     // Token issuer URL
  username?: string;               // Username
  'cognito:groups'?: string[];     // Cognito user groups
  'cognito:username': string;      // Cognito username
  origin_jti?: string;             // Original JWT ID
  client_id?: string;              // OAuth client ID
  scope?: string;                  // OAuth scopes
  aud: string;                     // Token audience
  event_id: string;                // Cognito event ID
  token_use: string;               // Token type (access/id)
  auth_time: number;               // Authentication timestamp
  name: string;                    // User's name
  'custom:tenant'?: string;        // User's default tenant code
  'custom:roles'?: string;         // JSON array of tenant roles
  'custom:groups'?: string;        // JSON array of TenantGroupMembership
  exp: number;                     // Expiration timestamp
  email: string;                   // User's email address
  email_verified?: boolean;        // Email verification status
  iat: number;                     // Issued at timestamp
  jti: string;                     // JWT ID
}
```

## DateTime Helpers {#datetime-helpers}

Functions for working with dates and ISO strings.

### `toISOString(date: Date): string | undefined`

Converts a Date to ISO string format. Returns undefined if date is null/undefined.

```ts
import { toISOString } from '@mbc-cqrs-serverless/core';

const isoString = toISOString(new Date('2024-01-15T10:30:00Z'));
// Result: '2024-01-15T10:30:00.000Z'
```

### `toISOStringWithTimezone(date: Date): string | undefined`

Converts a Date to ISO string format with timezone offset. Returns undefined if date is null/undefined.

```ts
import { toISOStringWithTimezone } from '@mbc-cqrs-serverless/core';

const isoString = toISOStringWithTimezone(new Date('2024-01-15T10:30:00'));
// Result: '2024-01-15T10:30:00+09:00' (in JST timezone)
```

### `isISOString(val: string): boolean`

Checks if a string is a valid ISO date string.

```ts
import { isISOString } from '@mbc-cqrs-serverless/core';

isISOString('2024-01-15T10:30:00.000Z'); // true
isISOString('2024-01-15');               // false
isISOString('invalid');                  // false
```

### `isISOStringWithTimezone(val: string): boolean`

Checks if a string is a valid ISO date string with timezone.

```ts
import { isISOStringWithTimezone } from '@mbc-cqrs-serverless/core';

isISOStringWithTimezone('2024-01-15T10:30:00+09:00'); // true
isISOStringWithTimezone('2024-01-15T10:30:00.000Z'); // false
```

## Event-Type Helpers {#event-type-helpers}

Functions for working with AWS event source ARNs.

### `getEventTypeFromArn(source: string): string | null`

Extracts the event type from an AWS ARN. Returns 'sqs', 'sns', 'dynamodb', 'event-bridge', or null.

```ts
import { getEventTypeFromArn } from '@mbc-cqrs-serverless/core';

const eventType = getEventTypeFromArn('arn:aws:dynamodb:ap-northeast-1:123456789:table/my-table/stream/...');
// Result: 'dynamodb'

const sqsType = getEventTypeFromArn('arn:aws:sqs:ap-northeast-1:123456789:my-queue');
// Result: 'sqs'
```

### `getResourceNameFromArn(source: string): string`

Extracts the resource name from an AWS ARN.

```ts
import { getResourceNameFromArn } from '@mbc-cqrs-serverless/core';

const tableName = getResourceNameFromArn('arn:aws:dynamodb:ap-northeast-1:123456789:table/my-table/stream/...');
// Result: 'my-table'

const queueName = getResourceNameFromArn('arn:aws:sqs:ap-northeast-1:123456789:my-queue');
// Result: 'my-queue'
```

## Object Helpers {#object-helpers}

Functions for working with objects.

### `isObject(item: any): boolean`

Checks if the value is a plain object (not array, not null).

```ts
import { isObject } from '@mbc-cqrs-serverless/core';

isObject({ key: 'value' }); // true
isObject([1, 2, 3]);        // false
isObject(null);             // false
isObject('string');         // false
```

### `mergeDeep(target: any, ...sources: any[]): any`

Deep merges objects without mutating the original objects.

```ts
import { mergeDeep } from '@mbc-cqrs-serverless/core';

const result = mergeDeep(
  { a: 1, b: { c: 2 } },
  { b: { d: 3 }, e: 4 }
);
// Result: { a: 1, b: { c: 2, d: 3 }, e: 4 }
```

### `objectBytes(obj: any): number`

Calculates the byte size of a JSON-serialized object.

```ts
import { objectBytes } from '@mbc-cqrs-serverless/core';

const size = objectBytes({ name: 'test', value: 123 });
// Result: byte size of JSON string
```

### `pickKeys(obj: any, keys: string[]): object`

Creates a new object with only the specified keys.

```ts
import { pickKeys } from '@mbc-cqrs-serverless/core';

const result = pickKeys({ a: 1, b: 2, c: 3 }, ['a', 'c']);
// Result: { a: 1, c: 3 }
```

### `omitKeys(obj: any, keys: string[]): object`

Creates a new object without the specified keys.

```ts
import { omitKeys } from '@mbc-cqrs-serverless/core';

const result = omitKeys({ a: 1, b: 2, c: 3 }, ['b']);
// Result: { a: 1, c: 3 }
```

## Serializer Helpers {#serializer-helpers}

Functions for converting between internal DynamoDB structure and external flat structure.

### SerializerOptions Interface

```ts
interface SerializerOptions {
  keepAttributes?: boolean;  // Reserved for future use
  flattenDepth?: number;     // Reserved for future use
}
```

:::note
The `SerializerOptions` interface is defined for future extensibility but is not currently used by the function. The function always flattens attributes to the top level.
:::

### `serializeToExternal<T extends CommandEntity | DataEntity>(item: T | null | undefined, options?: SerializerOptions): Record<string, any> | null`

Converts internal DynamoDB entity to external flat structure. Flattens the attributes object into the root level. Returns null if input is null or undefined.

```ts
import { serializeToExternal } from '@mbc-cqrs-serverless/core';

const entity = {
  pk: 'TENANT#mbc',
  sk: 'CAT#001',
  id: 'TENANT#mbc#CAT#001',
  code: '001',
  name: 'Category 1',
  version: 1,
  tenantCode: 'mbc',
  type: 'CAT',
  isDeleted: false,
  attributes: { color: 'red', size: 'large' }
};

const external = serializeToExternal(entity);
// Result:
// {
//   id: 'TENANT#mbc#CAT#001',
//   pk: 'TENANT#mbc',
//   sk: 'CAT#001',
//   code: '001',
//   name: 'Category 1',
//   version: 1,
//   tenantCode: 'mbc',
//   type: 'CAT',
//   isDeleted: false,
//   color: 'red',        // Flattened from attributes
//   size: 'large'        // Flattened from attributes
// }
```

### `deserializeToInternal<T extends CommandEntity | DataEntity>(data: Record<string, any> | null | undefined, EntityClass: new () => T): T | null`

Converts external flat structure back to internal DynamoDB entity structure. Returns null if input is null or undefined.

```ts
import { deserializeToInternal, DataEntity } from '@mbc-cqrs-serverless/core';

const external = {
  id: 'TENANT#mbc#CAT#001',
  name: 'Category 1',
  color: 'red',
  size: 'large'
};

const entity = deserializeToInternal(external, DataEntity);
// Result: DataEntity with pk, sk, name, and attributes: { color, size }
```

## Source Helper {#source-helper}

Function for generating command source identifiers.

### `getCommandSource(moduleName: string, controllerName: string, method: string): string`

Generates a standardized source string for commands.

```ts
import { getCommandSource } from '@mbc-cqrs-serverless/core';

const source = getCommandSource('CatalogModule', 'CatalogController', 'create');
// Result: '[CatalogModule]:CatalogController.create'
```

## Constants {#constants}

### `VERSION_FIRST: number`

A constant equal to `0`. Use as the `version` field when creating a new entity for the first time.

```ts
import { VERSION_FIRST } from '@mbc-cqrs-serverless/core';

const command = {
  pk,
  sk,
  name: dto.name,
  version: VERSION_FIRST, // New entity: version starts at 0
};
```

### `VERSION_LATEST: number`

A constant equal to `-1`. Use as the `version` field to bypass optimistic locking (always overwrites). Returned by `getSortKeyVersion()` when no version suffix is present.

```ts
import { VERSION_LATEST } from '@mbc-cqrs-serverless/core';

const command = {
  pk,
  sk,
  name: dto.name,
  version: VERSION_LATEST, // Bypass optimistic locking
};
```

:::caution
Using `VERSION_LATEST` bypasses optimistic locking, so concurrent writes from multiple clients will silently overwrite each other. Only use it when concurrent writes to the same entity are impossible (e.g., system-only background jobs, TTL-managed records, or initial seeding).
:::

### `IS_LAMBDA_RUNNING: boolean`

A constant that indicates whether the code is running in an AWS Lambda environment.

```ts
import { IS_LAMBDA_RUNNING } from '@mbc-cqrs-serverless/core';

if (IS_LAMBDA_RUNNING) {
  // Lambda-specific logic
} else {
  // Local development logic
}
```

## Related Documentation

- [Key Patterns](/docs/key-patterns) - DynamoDB key design
- [Command Service](/docs/command-service) - Using key helpers
- [Interfaces](/docs/interfaces) - UserContext and IInvoke interfaces
- [Authentication](/docs/authentication) - JWT claims and role-based access in UserContext


---

## Interfaces

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/interfaces

# Interfaces

This document provides a comprehensive reference of all TypeScript interfaces used in the MBC CQRS Serverless framework.

## Core Interfaces {#core-interfaces}

### Command Interfaces

#### CommandInputModel

The primary interface for creating new commands. Used when publishing new entities.

```ts
export interface CommandInputModel {
  pk: string              // Partition key (e.g., "ORDER#tenant001")
  sk: string              // Sort key (e.g., "ORDER#ORD001") — no version suffix needed
  id: string              // Unique identifier (e.g., UUID)
  code: string            // Business code (e.g., "ORD001")
  name: string            // Display name
  version: number         // Version number for optimistic locking
  tenantCode: string      // Tenant identifier
  type: string            // Entity type (e.g., "ORDER")
  isDeleted?: boolean     // Soft delete flag
  seq?: number            // Sequence number (auto-generated)
  ttl?: number            // Time-to-live in seconds
  attributes?: Record<string, any>  // Custom domain attributes
}
```

**Usage Example**:
```typescript
const orderInput: CommandInputModel = {
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001',         // No @version suffix — version is the separate field
  id: crypto.randomUUID(),
  code: 'ORD001',
  name: 'Customer Order',
  version: 0,                   // VERSION_FIRST for new entities
  tenantCode: 'tenant001',
  type: 'ORDER',
  attributes: {
    customerId: 'CUST001',
    totalAmount: 1500,
    status: 'pending',
  },
};
```

#### CommandPartialInputModel

Used for partial updates. Only pk, sk, and version are required.

```ts
export interface CommandPartialInputModel extends Partial<CommandInputModel> {
  pk: string       // Required: Partition key
  sk: string       // Required: Sort key
  version: number  // Required: Current version for optimistic locking
}
```

**Usage Example**:
```typescript
const partialUpdate: CommandPartialInputModel = {
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001',
  version: 2,  // Must match current version
  name: 'Updated Order Name',
  attributes: {
    status: 'confirmed',
  },
};
```

#### ICommandOptions

Options passed to command publishing methods.

```ts
export interface ICommandOptions {
  source?: string        // Source identifier for tracking
  requestId?: string     // Request ID for tracing
  invokeContext: IInvoke // Required: Invocation context
}
```

**Usage Example**:
```typescript
const options: ICommandOptions = {
  source: 'order-service',
  requestId: invokeContext.context.awsRequestId,
  invokeContext, // Injected via @INVOKE_CONTEXT() decorator
};
```

### Key Interfaces

#### DetailKey

Represents the primary key for DynamoDB items.

```ts
export interface DetailKey {
  pk: string  // Partition key
  sk: string  // Sort key
}
```

### Context Interfaces

#### IInvoke

Invocation context containing Lambda/Express event and context.

```ts
export interface IInvoke {
  event?: IInvokeEvent      // Request event (headers, requestContext, etc.)
  context?: IInvokeContext  // Lambda context (requestId, functionName, etc.)
}
```

#### IInvokeEvent

HTTP request event structure from API Gateway or Express.

```ts
export interface IInvokeEvent {
  version?: string
  routeKey?: string                    // e.g., "POST /api/resource"
  rawPath?: string
  rawQueryString?: string
  headers?: Record<string, string>
  requestContext?: {
    accountId?: string
    apiId?: string
    domainName?: string
    domainPrefix?: string
    http?: {
      method?: string
      path?: string
      protocol?: string
      sourceIp?: string                // Client IP address
      userAgent?: string
    }
    requestId?: string
    stage?: string
    time?: string
    timeEpoch?: number
    authorizer?: {
      jwt?: {
        claims?: JwtClaims             // Decoded JWT claims
        scopes?: string[]
      }
    }
  }
  isBase64Encoded?: boolean
}
```

#### IInvokeContext

Lambda execution context information.

```ts
export interface IInvokeContext {
  functionName?: string               // Lambda function name
  functionVersion?: string            // Lambda function version
  invokedFunctionArn?: string         // Lambda ARN
  memoryLimitInMB?: string           // Memory limit
  awsRequestId?: string              // AWS request ID for tracing
  logGroupName?: string              // CloudWatch log group
  logStreamName?: string             // CloudWatch log stream
  identity?: {
    cognitoIdentityId?: string
    cognitoIdentityPoolId?: string
  }
}
```

#### JwtClaims

JWT token claims structure from Cognito.

```ts
export interface JwtClaims {
  sub: string                        // Cognito user ID (UUID)
  iss: string                        // Token issuer URL
  username?: string
  'cognito:groups'?: string[]        // Cognito groups the user belongs to
  'cognito:username': string         // Cognito username
  origin_jti?: string                // Original JWT ID
  client_id?: string                 // OAuth client ID
  scope?: string                     // OAuth scopes
  aud: string                        // Audience (client ID)
  event_id: string
  token_use: string                  // Token type (id or access)
  auth_time: number                  // Authentication timestamp
  name: string                       // User's display name
  'custom:tenant'?: string           // Custom claim for tenant code
  'custom:roles'?: string            // Custom claim for roles JSON array
  'custom:groups'?: string           // Custom claim for tenant group memberships JSON array
  exp: number                        // Token expiration timestamp
  email: string
  email_verified?: boolean
  iat: number                        // Token issued at timestamp
  jti: string                        // JWT ID
}
```

**Custom Claims Example**:
```typescript
// The custom:roles claim contains a JSON array of role assignments
// [{"tenant":"","role":"user"},{"tenant":"9999","role":"admin"}]
// - Empty tenant ("") means the role applies globally
// - Specific tenant means the role applies only to that tenant
```

:::info Version Note
The `custom:groups` claim was added to `JwtClaims` in [version 1.3.1](/docs/changelog#v131) as part of group-based role authorization.
:::

#### UserContext

User context class extracted from authentication token.

```ts
export class UserContext {
  userId: string             // Cognito user ID (from JWT sub claim)
  tenantRole: string         // User's role within the tenant
  tenantCode: string         // Current tenant code
  tenantRoles: string[]      // Direct roles for the active tenant (excludes group-derived roles)
  tenantGroupIds: string[]   // Group IDs from custom:groups for the active tenant

  constructor(partial: Partial<UserContext>)  // Initialize with partial properties
}
```

:::info Version Note
`tenantRoles` and `tenantGroupIds` were added to `UserContext` in [version 1.3.1](/docs/changelog#v131) as part of group-based role authorization. `tenantRole` (singular) is kept for backward compatibility.
:::

**Usage Example**:
```typescript
import { getUserContext, IInvoke } from '@mbc-cqrs-serverless/core';

// Extract user context from IInvoke or ExecutionContext
const userContext = getUserContext(invokeContext);
console.log(userContext.userId);      // '92ca4f68-9ac6-4080-9ae2-2f02a86206a4'
console.log(userContext.tenantCode);  // 'tenant001'
console.log(userContext.tenantRole);  // 'admin'
```

## Data Interfaces {#data-interfaces}

### Entity Interfaces

#### CommandModel

Interface for command entities (write model).

```ts
export interface CommandModel extends CommandInputModel {
  status?: string       // Processing status (e.g., 'PENDING', 'COMPLETED', 'FAILED')
  source?: string       // Event source identifier (e.g., 'POST /api/master', 'SQS')
  requestId?: string    // Unique request ID for tracing and idempotency
  createdAt?: Date      // Timestamp when the command was created
  updatedAt?: Date      // Timestamp when the command was last updated
  createdBy?: string    // User ID who created the command
  updatedBy?: string    // User ID who last updated the command
  createdIp?: string    // IP address of the creator
  updatedIp?: string    // IP address of the last updater
  taskToken?: string    // Step Functions task token for async workflows
  syncMode?: CommandSyncMode  // 'SYNC' when the command was applied via synchronous publish
}
```

:::tip Step Functions Integration
The `taskToken` field is used when integrating with AWS Step Functions callback patterns. When a Step Functions state machine invokes your application with a task token, store it using [`CommandService.updateTaskToken()`](/docs/command-service#updatetasktoken). Later, use the token with AWS SDK's `SendTaskSuccessCommand` or `SendTaskFailureCommand` to signal task completion.
:::

#### DataModel

Base interface for data entities (read model).

```ts
export interface DataModel extends Omit<CommandModel, 'status'> {
  cpk?: string  // Command partition key - references source command record
  csk?: string  // Command sort key with version - references exact command version
}
```

### Entity Classes

#### CommandEntity

Class implementing CommandModel for API responses. Includes Swagger decorators.

```ts
export class CommandEntity implements CommandModel {
  // All properties from CommandModel
  pk: string
  sk: string
  // ...

  get key(): DetailKey  // Returns { pk, sk } for DynamoDB operations
}
```

**Usage Example**:
```typescript
const command: CommandEntity = await commandService.getItem({
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001',
});

// Access the DynamoDB key pair
const key = command.key;  // { pk: 'ORDER#tenant001', sk: 'ORDER#ORD001' }
```

#### DataEntity

Class implementing DataModel for API responses. Includes Swagger decorators.

```ts
export class DataEntity implements DataModel {
  // All properties from DataModel
  pk: string
  sk: string
  // ...

  constructor(data: Partial<DataEntity>)  // Initialize with partial properties

  get key(): DetailKey  // Returns { pk, sk } for DynamoDB operations
}
```

**Usage Example**:
```typescript
const data: DataEntity = await dataService.getItem({
  pk: 'ORDER#tenant001',
  sk: 'ORDER#ORD001',
});

// Access the DynamoDB key pair
const key = data.key;  // { pk: 'ORDER#tenant001', sk: 'ORDER#ORD001' }
```

### List Response Interfaces

#### DataListEntity

Paginated list response for data queries.

```ts
export class DataListEntity {
  items: DataEntity[]   // Array of entities
  total?: number        // Total count (if available)
  lastSk?: string       // Pagination cursor (last sort key)

  constructor(data: Partial<DataListEntity>)  // Initialize with partial properties
}
```

**Usage Example**:
```typescript
const result = await dataService.listItemsByPk('ORDER#tenant001', {
  limit: 20,
  startFromSk: previousLastSk,
});

// Pagination
if (result.lastSk) {
  // More items available - use result.lastSk for next page
}
```

## Service Interfaces {#service-interfaces}

### Sync Handler Interfaces

#### IDataSyncHandler

Interface for implementing data synchronization handlers. Handles both forward (up) and rollback (down) operations.

```ts
export interface IDataSyncHandler<TExecuteResult = any, TRollbackResult = any> {
  readonly type?: string  // Optional type identifier

  /**
   * Sync data when a command is executed.
   * Called automatically by the framework during command processing.
   */
  up(cmd: CommandModel): Promise<TExecuteResult>

  /**
   * Reserved for rollback operations.
   * Note: This method is NOT automatically called by the framework.
   * Implement this for manual rollback scenarios in your application.
   */
  down(cmd: CommandModel): Promise<TRollbackResult>
}
```

**Implementation Example**:
```typescript
import { Injectable } from '@nestjs/common';
import { CommandModel, IDataSyncHandler } from '@mbc-cqrs-serverless/core';
import { PrismaService } from 'src/prisma';

@Injectable()
export class OrderRdsSyncHandler implements IDataSyncHandler {
  readonly type = 'ORDER';

  constructor(private readonly prisma: PrismaService) {}

  async up(cmd: CommandModel): Promise<void> {
    if (cmd.isDeleted) {
      await this.prisma.order.delete({
        where: { id: cmd.id },
      });
    } else {
      await this.prisma.order.upsert({
        where: { id: cmd.id },
        create: this.toRdsModel(cmd),
        update: this.toRdsModel(cmd),
      });
    }
  }

  async down(cmd: CommandModel): Promise<void> {
    // Rollback logic - restore previous state
    await this.prisma.order.delete({
      where: { id: cmd.id },
    });
  }

  private toRdsModel(cmd: CommandModel) {
    return {
      id: cmd.id,
      code: cmd.code,
      name: cmd.name,
      ...cmd.attributes,
    };
  }
}
```

### Authorization Interfaces {#authorization-interfaces}

#### IGroupRoleResolver

:::info Version Note
`IGroupRoleResolver` was added in [version 1.3.1](/docs/changelog#v131) for group-based role authorization.
:::

Interface for resolving group-to-role mappings. Implement exactly one resolver per application and register it with `@GroupRoleResolver()`.

```ts
export interface IGroupRoleResolver {
  resolveRoles(input: ResolveGroupRolesInput): Promise<string[]>
}
```

#### ResolveGroupRolesInput

```ts
export interface ResolveGroupRolesInput {
  tenantCode: string   // Active tenant for which roles are being resolved
  groupIds: string[]   // Group IDs from the `custom:groups` JWT claim for this tenant
  claims: JwtClaims    // Full JWT claims for additional context
}
```

**Implementation Example**:
```typescript
import {
  GroupRoleResolver,
  IGroupRoleResolver,
  ResolveGroupRolesInput,
} from '@mbc-cqrs-serverless/core';

// Do not add @Injectable() — @GroupRoleResolver() registers a singleton provider
@GroupRoleResolver()
export class AppGroupRoleResolver implements IGroupRoleResolver {
  async resolveRoles({ tenantCode, groupIds }: ResolveGroupRolesInput): Promise<string[]> {
    // Map group IDs to roles — fetch from DB, config, etc.
    return groupIds.includes('admin-group') ? ['admin'] : ['user'];
  }
}
```

See [Group-Based Roles](/docs/authentication#group-based-roles) for complete usage documentation.

## Notification Interfaces {#notification-interfaces}

### EmailNotification

Configuration for sending email notifications.

```ts
export interface EmailNotification {
  fromAddr?: string       // Sender address (uses default if not specified)
  toAddrs: string[]       // Required: Recipient addresses
  ccAddrs?: string[]      // CC addresses
  bccAddrs?: string[]     // BCC addresses
  subject: string         // Required: Email subject
  body: string            // Required: HTML body content
  replyToAddrs?: string[] // Reply-to addresses
  attachments?: Attachment[]  // File attachments
}

export interface Attachment {
  filename: string      // Attachment filename
  content: Buffer       // File content as Buffer
  contentType?: string  // MIME type (e.g., 'application/pdf')
}
```

**Usage Example**:
```typescript
await emailService.sendEmail({
  toAddrs: ['user@example.com'],
  subject: 'Order Confirmation',
  body: `<h1>Order Confirmed</h1><p>Your order ${orderCode} has been confirmed.</p>`,
});
```

## Module Configuration Interfaces {#module-config-interfaces}

### CommandModuleOptions

Configuration options for CommandModule.

```ts
export interface CommandModuleOptions {
  tableName: string                           // DynamoDB table name
  dataSyncHandlers?: Type<IDataSyncHandler>[] // Custom sync handlers
  skipError?: boolean                         // Reserved for future use (not yet implemented)
  disableDefaultHandler?: boolean             // Disable the default DynamoDB data sync handler
}
```

**Usage Example**:
```typescript
import { Module } from '@nestjs/common';
import { CommandModule } from '@mbc-cqrs-serverless/core';
import { OrderRdsSyncHandler } from './order-rds-sync.handler';

@Module({
  imports: [
    CommandModule.register({
      tableName: 'order',
      dataSyncHandlers: [OrderRdsSyncHandler],
      disableDefaultHandler: false,
    }),
  ],
})
export class OrderModule {}
```

### SequencesModuleOptions

Configuration options for SequencesModule.

```ts
export interface SequencesModuleOptions {
  enableController?: boolean  // Enable or disable default sequence controller
}
```

## Event Interfaces {#event-interfaces}

### SnsEvent

Base interface for all SNS messages published via `SnsService`. Every message must include an `action` field. Extend this interface to add domain-specific payload fields.

```ts
export interface SnsEvent {
  action: string  // Message action identifier (e.g. 'order-created', 'user-updated')
}
```

See [Queue — SnsEvent](/docs/queue#type-definitions) for usage examples and extension patterns.

### StepFunctionsEvent

Event structure from AWS Step Functions.

```ts
export interface StepFunctionsContextExecution {
  Id: string                    // Execution ID
  Input: { [id: string]: any }  // Input data
  Name: string                  // Execution name
  RoleArn: string               // IAM role ARN
  StartTime: string             // Execution start time
}

export interface StepFunctionsContextState {
  EnteredTime: string   // State entered time
  Name: string          // State name
  RetryCount: number    // Retry count
}

export interface StepFunctionsContextStateMachine {
  Id: string    // State machine ID
  Name: string  // State machine name
}

export interface StepFunctionsContext {
  Execution: StepFunctionsContextExecution
  State: StepFunctionsContextState
  StateMachine: StepFunctionsContextStateMachine
}

export interface StepFunctionsEvent<TInput> {
  input: TInput                    // Input data passed to the state
  context: StepFunctionsContext    // Step Functions context information
}
```

## Type Utilities {#type-utilities}

### Common Type Helpers

```ts
// Partial type that requires specific keys
type RequiredPick<T, K extends keyof T> = Partial<T> & Pick<T, K>;

// Deep partial type
type DeepPartial<T> = {
  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
};

// Entity without audit fields
type EntityInput<T> = Omit<T, 'createdAt' | 'createdBy' | 'updatedAt' | 'updatedBy'>;
```

## Related Documentation

- [Command Service](/docs/command-service) - Using commands with these interfaces
- [Data Service](/docs/data-service) - Querying data with these interfaces
- [Entity Patterns](/docs/entity-patterns) - Designing entities
- [Error Catalog](/docs/error-catalog) - Error handling
- [Authentication](/docs/authentication#group-based-roles) - Group-based role authorization (`IGroupRoleResolver` usage)


---

# Changelog

## Changelog

URL: https://mbc-cqrs-serverless.mbc-net.com/docs/changelog

# Changelog

All notable changes to MBC CQRS Serverless are documented here. This project follows [Semantic Versioning](https://semver.org/) and [Conventional Commits](https://conventionalcommits.org/).

## Version Scheme {#version-scheme}

- `x.y.z` - Production releases
- `x.y.z-beta.n` - Beta releases for testing
- `x.y.z-alpha.n` - Alpha releases for early access

---

## Stable Releases (1.x) {#stable-releases}

## [1.4.0](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.4.0) (2026-08-02) {#v140}

### Features

- **core, master, directory, survey-template, ui-setting:** Make the DynamoDB table names of the domain modules configurable via a backward-compatible `tableName?` option, and add `registerAsync` support to all four modules. Defaults are unchanged (`master` / `directory` / `survey` / `master`), so existing apps upgrade with no code changes ([See Details](/docs/directory#configurable-table-name)) ([PR #493](https://github.com/mbc-net/mbc-cqrs-serverless/pull/493))
  - `DirectoryStorageModule` additionally accepts `pkPrefix?` (default `DIRECTORY`) and `prismaModelName?` (default `directory`)
  - The `directory` → `document` rename ([PR #469](https://github.com/mbc-net/mbc-cqrs-serverless/pull/469)) is now expressed as opt-in configuration (`tableName: 'document'`, `pkPrefix: 'DOCUMENT'`, `prismaModelName: 'document'`) rather than a forced default

### Changes

- **master, directory, survey-template:** `prismaService` is now always required at registration (previously validated only when `enableController: true`). A missing value now fails fast at startup with a clear message instead of a cryptic dependency-resolution error. Pass `prismaService` explicitly if you registered with `enableController: false` and relied on a globally-provided token
- **master, ui-setting:** When `MasterModule` and `SettingModule` share the default `master` table, the framework logs a startup warning if both own the `master_CommandEventHandler` alias (data-sync ownership becomes import-order dependent). Set `registerEventHandlerAlias: false` on `SettingModule` so `MasterModule` owns the alias
- **master:** `MasterModule` logs a warning if its `tableName` is overridden — the `master` table is a framework-wide config store read at a fixed `master-data` name by `TtlService` and the sequence package, so renaming it is not fully supported

## [1.3.5](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.5) (2026-08-01) {#v135}

### Bug Fixes

- **core:** Harden command-handler resume against read-after-write races — `waitConfirmToken` now self-resumes when the predecessor command has already finished, closes the residual TOCTOU window via `STARTED|FINISHED` status checks, retries the predecessor `getItem` with exponential backoff, and classifies `checkNextToken` resume failures so a stuck resume raises an alarm instead of failing silently ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **core:** Add `ConsistentRead` support to `DynamoDbService.getItem` and thread it through `CommandService.getItem` / `getNextCommand`, so resume decisions read the latest committed state instead of a possibly stale replica ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **cli:** Fix the scaffolded infra template failing `cdk synth`/`deploy` — the import-CSV Step Functions definition referenced an undefined `aws_stepfunctions` identifier (corrected to `cdk.aws_stepfunctions`), which broke every project scaffolded with `mbc new` on v1.3.4. Upgrade to v1.3.5 to restore deployability ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))

### Features

- **infra:** Add CloudWatch alarms on the command-handler Step Functions state machine (`ExecutionsFailed` and degraded self-resume paths), add a 24h timeout and catch on `wait_prev_command`, and scope the `SendTaskSuccess` IAM permission to the command state machine ARN ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **cli:** Local development tooling for `mbc new` projects — make the local infra ports configurable via `LOCAL_*_PORT` env vars (defaults unchanged), keep cognito-local's JWT issuer in sync with `LOCAL_COGNITO_PORT`, and harden Step Functions Local pre-registration (readiness wait, fail-fast on real errors, tolerate already-registered state machines); no runtime impact on deployed apps ([PR #337](https://github.com/mbc-net/mbc-cqrs-serverless/pull/337))

### Security

- Restore the blocking `npm audit --omit=dev --audit-level=high` CI gate that was temporarily disabled, and patch `brace-expansion` (top-level `brace-expansion@2` → `5.0.8`); root production audit: 0 critical/high ([PR #482](https://github.com/mbc-net/mbc-cqrs-serverless/pull/482))
  - Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (`packages/cli/templates/infra`) is not an npm workspace member and ships `@aws/pdk` (build-time cdk-graph tooling) whose transitive tree still carries high advisories; it is now audited in CI (non-blocking) and tracked separately in [issue #486](https://github.com/mbc-net/mbc-cqrs-serverless/issues/486)

---

## [1.3.4](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.4) (2026-07-17) {#v134}

### Bug Fixes

- **core, cli:** Lower the default `ATTRIBUTE_LIMIT_SIZE` from `389120` (380 KB) to `102400` (100 KB) in CDK infra templates and env examples — the previous default was sized for DynamoDB's 400 KB item limit, but Step Functions enforces a 256 KB payload limit per state, and the command state machine passes the DynamoDB stream event twice (`input.---
sidebar_position: 100
sidebar_label: "Backend (Framework)"
description: Track all notable changes, new features, and bug fixes in MBC CQRS Serverless releases.
---

# Changelog

All notable changes to MBC CQRS Serverless are documented here. This project follows [Semantic Versioning](https://semver.org/) and [Conventional Commits](https://conventionalcommits.org/).

## Version Scheme {#version-scheme}

- `x.y.z` - Production releases
- `x.y.z-beta.n` - Beta releases for testing
- `x.y.z-alpha.n` - Alpha releases for early access

---

## Stable Releases (1.x) {#stable-releases}

## [1.4.0](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.4.0) (2026-08-02) {#v140}

### Features

- **core, master, directory, survey-template, ui-setting:** Make the DynamoDB table names of the domain modules configurable via a backward-compatible `tableName?` option, and add `registerAsync` support to all four modules. Defaults are unchanged (`master` / `directory` / `survey` / `master`), so existing apps upgrade with no code changes ([See Details](/docs/directory#configurable-table-name)) ([PR #493](https://github.com/mbc-net/mbc-cqrs-serverless/pull/493))
  - `DirectoryStorageModule` additionally accepts `pkPrefix?` (default `DIRECTORY`) and `prismaModelName?` (default `directory`)
  - The `directory` → `document` rename ([PR #469](https://github.com/mbc-net/mbc-cqrs-serverless/pull/469)) is now expressed as opt-in configuration (`tableName: 'document'`, `pkPrefix: 'DOCUMENT'`, `prismaModelName: 'document'`) rather than a forced default

### Changes

- **master, directory, survey-template:** `prismaService` is now always required at registration (previously validated only when `enableController: true`). A missing value now fails fast at startup with a clear message instead of a cryptic dependency-resolution error. Pass `prismaService` explicitly if you registered with `enableController: false` and relied on a globally-provided token
- **master, ui-setting:** When `MasterModule` and `SettingModule` share the default `master` table, the framework logs a startup warning if both own the `master_CommandEventHandler` alias (data-sync ownership becomes import-order dependent). Set `registerEventHandlerAlias: false` on `SettingModule` so `MasterModule` owns the alias
- **master:** `MasterModule` logs a warning if its `tableName` is overridden — the `master` table is a framework-wide config store read at a fixed `master-data` name by `TtlService` and the sequence package, so renaming it is not fully supported

## [1.3.5](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.5) (2026-08-01) {#v135}

### Bug Fixes

- **core:** Harden command-handler resume against read-after-write races — `waitConfirmToken` now self-resumes when the predecessor command has already finished, closes the residual TOCTOU window via `STARTED|FINISHED` status checks, retries the predecessor `getItem` with exponential backoff, and classifies `checkNextToken` resume failures so a stuck resume raises an alarm instead of failing silently ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **core:** Add `ConsistentRead` support to `DynamoDbService.getItem` and thread it through `CommandService.getItem` / `getNextCommand`, so resume decisions read the latest committed state instead of a possibly stale replica ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **cli:** Fix the scaffolded infra template failing `cdk synth`/`deploy` — the import-CSV Step Functions definition referenced an undefined `aws_stepfunctions` identifier (corrected to `cdk.aws_stepfunctions`), which broke every project scaffolded with `mbc new` on v1.3.4. Upgrade to v1.3.5 to restore deployability ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))

### Features

- **infra:** Add CloudWatch alarms on the command-handler Step Functions state machine (`ExecutionsFailed` and degraded self-resume paths), add a 24h timeout and catch on `wait_prev_command`, and scope the `SendTaskSuccess` IAM permission to the command state machine ARN ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **cli:** Local development tooling for `mbc new` projects — make the local infra ports configurable via `LOCAL_*_PORT` env vars (defaults unchanged), keep cognito-local's JWT issuer in sync with `LOCAL_COGNITO_PORT`, and harden Step Functions Local pre-registration (readiness wait, fail-fast on real errors, tolerate already-registered state machines); no runtime impact on deployed apps ([PR #337](https://github.com/mbc-net/mbc-cqrs-serverless/pull/337))

### Security

- Restore the blocking `npm audit --omit=dev --audit-level=high` CI gate that was temporarily disabled, and patch `brace-expansion` (top-level `brace-expansion@2` → `5.0.8`); root production audit: 0 critical/high ([PR #482](https://github.com/mbc-net/mbc-cqrs-serverless/pull/482))
  - Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (`packages/cli/templates/infra`) is not an npm workspace member and ships `@aws/pdk` (build-time cdk-graph tooling) whose transitive tree still carries high advisories; it is now audited in CI (non-blocking) and tracked separately in [issue #486](https://github.com/mbc-net/mbc-cqrs-serverless/issues/486)

---

## [1.3.4](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.4) (2026-07-17) {#v134}

### Bug Fixes

- **core, cli:**  + `context.---
sidebar_position: 100
sidebar_label: "Backend (Framework)"
description: Track all notable changes, new features, and bug fixes in MBC CQRS Serverless releases.
---

# Changelog

All notable changes to MBC CQRS Serverless are documented here. This project follows [Semantic Versioning](https://semver.org/) and [Conventional Commits](https://conventionalcommits.org/).

## Version Scheme {#version-scheme}

- `x.y.z` - Production releases
- `x.y.z-beta.n` - Beta releases for testing
- `x.y.z-alpha.n` - Alpha releases for early access

---

## Stable Releases (1.x) {#stable-releases}

## [1.4.0](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.4.0) (2026-08-02) {#v140}

### Features

- **core, master, directory, survey-template, ui-setting:** Make the DynamoDB table names of the domain modules configurable via a backward-compatible `tableName?` option, and add `registerAsync` support to all four modules. Defaults are unchanged (`master` / `directory` / `survey` / `master`), so existing apps upgrade with no code changes ([See Details](/docs/directory#configurable-table-name)) ([PR #493](https://github.com/mbc-net/mbc-cqrs-serverless/pull/493))
  - `DirectoryStorageModule` additionally accepts `pkPrefix?` (default `DIRECTORY`) and `prismaModelName?` (default `directory`)
  - The `directory` → `document` rename ([PR #469](https://github.com/mbc-net/mbc-cqrs-serverless/pull/469)) is now expressed as opt-in configuration (`tableName: 'document'`, `pkPrefix: 'DOCUMENT'`, `prismaModelName: 'document'`) rather than a forced default

### Changes

- **master, directory, survey-template:** `prismaService` is now always required at registration (previously validated only when `enableController: true`). A missing value now fails fast at startup with a clear message instead of a cryptic dependency-resolution error. Pass `prismaService` explicitly if you registered with `enableController: false` and relied on a globally-provided token
- **master, ui-setting:** When `MasterModule` and `SettingModule` share the default `master` table, the framework logs a startup warning if both own the `master_CommandEventHandler` alias (data-sync ownership becomes import-order dependent). Set `registerEventHandlerAlias: false` on `SettingModule` so `MasterModule` owns the alias
- **master:** `MasterModule` logs a warning if its `tableName` is overridden — the `master` table is a framework-wide config store read at a fixed `master-data` name by `TtlService` and the sequence package, so renaming it is not fully supported

## [1.3.5](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.5) (2026-08-01) {#v135}

### Bug Fixes

- **core:** Harden command-handler resume against read-after-write races — `waitConfirmToken` now self-resumes when the predecessor command has already finished, closes the residual TOCTOU window via `STARTED|FINISHED` status checks, retries the predecessor `getItem` with exponential backoff, and classifies `checkNextToken` resume failures so a stuck resume raises an alarm instead of failing silently ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **core:** Add `ConsistentRead` support to `DynamoDbService.getItem` and thread it through `CommandService.getItem` / `getNextCommand`, so resume decisions read the latest committed state instead of a possibly stale replica ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **cli:** Fix the scaffolded infra template failing `cdk synth`/`deploy` — the import-CSV Step Functions definition referenced an undefined `aws_stepfunctions` identifier (corrected to `cdk.aws_stepfunctions`), which broke every project scaffolded with `mbc new` on v1.3.4. Upgrade to v1.3.5 to restore deployability ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))

### Features

- **infra:** Add CloudWatch alarms on the command-handler Step Functions state machine (`ExecutionsFailed` and degraded self-resume paths), add a 24h timeout and catch on `wait_prev_command`, and scope the `SendTaskSuccess` IAM permission to the command state machine ARN ([PR #465](https://github.com/mbc-net/mbc-cqrs-serverless/pull/465))
- **cli:** Local development tooling for `mbc new` projects — make the local infra ports configurable via `LOCAL_*_PORT` env vars (defaults unchanged), keep cognito-local's JWT issuer in sync with `LOCAL_COGNITO_PORT`, and harden Step Functions Local pre-registration (readiness wait, fail-fast on real errors, tolerate already-registered state machines); no runtime impact on deployed apps ([PR #337](https://github.com/mbc-net/mbc-cqrs-serverless/pull/337))

### Security

- Restore the blocking `npm audit --omit=dev --audit-level=high` CI gate that was temporarily disabled, and patch `brace-expansion` (top-level `brace-expansion@2` → `5.0.8`); root production audit: 0 critical/high ([PR #482](https://github.com/mbc-net/mbc-cqrs-serverless/pull/482))
  - Scope note: the "0 critical/high" figure applies to the root workspace only. The scaffolded infra template (`packages/cli/templates/infra`) is not an npm workspace member and ships `@aws/pdk` (build-time cdk-graph tooling) whose transitive tree still carries high advisories; it is now audited in CI (non-blocking) and tracked separately in [issue #486](https://github.com/mbc-net/mbc-cqrs-serverless/issues/486)

---

## [1.3.4](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.4) (2026-07-17) {#v134}

### Bug Fixes

- **core, cli:** ), so inline attributes above ~110 KB could trigger `States.DataLimitExceeded` ([See Details](/docs/environment-variables#dynamodb-configuration)) ([PR #466](https://github.com/mbc-net/mbc-cqrs-serverless/pull/466))
- **mcp-server:** Update skills with guidance on the new `ATTRIBUTE_LIMIT_SIZE` default ([PR #470](https://github.com/mbc-net/mbc-cqrs-serverless/pull/470))

---

## [1.3.2](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.2) (2026-06-27) {#v132}

### Features

- **mcp-server:** Add AP028, AP029, AP030 anti-pattern detectors ([See Details](/docs/mcp-server#anti-pattern-detection)) ([PR #460](https://github.com/mbc-net/mbc-cqrs-serverless/pull/460), [PR #461](https://github.com/mbc-net/mbc-cqrs-serverless/pull/461))
  - AP028: Duplicate `DataSyncHandler` registration across NestJS modules — detected and deduplicated with a warning log
  - AP029: Reserved `'dynamodb'` type on `@DataSyncHandler` causes the handler to be silently excluded from dispatch
  - AP030: Fully-qualified table name (ending in `'-command'`) in `@DataSyncHandler` causes silent handler skip

### Bug Fixes

- **core:** Fix `DataSyncHandler` duplicate registration — `ExplorerService` now deduplicates handlers via `Set`; `CommandService` deduplicates via `Map<constructor.name, instance>` and emits a `warn` log for each removed duplicate ([PR #459](https://github.com/mbc-net/mbc-cqrs-serverless/pull/459))
- **core:** Fix `publishSync` — versioned `sk` is now assigned to `command.sk` before handler dispatch so `IDataSyncHandler.up()` receives the correct key; `updateStatus` errors are no longer silently masked; `pk`/`sk` are now included in `checkNextToken` warn logs ([See Details](/docs/command-service#publishsync-audit-trail)) ([PR #460](https://github.com/mbc-net/mbc-cqrs-serverless/pull/460))

### Security

- Harden npm dependencies — resolve high/moderate vulnerabilities via `overrides` (`lodash`, `tmp`, `multer`, `ajv`, `picomatch`, `fast-xml-parser`) and targeted upgrades (`@nestjs/config` ^4.0.4, `@typescript-eslint` v8); root production audit: 0 critical/high ([PR #445](https://github.com/mbc-net/mbc-cqrs-serverless/pull/445)–[#453](https://github.com/mbc-net/mbc-cqrs-serverless/pull/453))
- **cli:** Upgrade `multer` to v2.2.0 in scaffolded templates to fix CVE-2026-5079 (DoS via deeply nested multipart field names) ([PR #463](https://github.com/mbc-net/mbc-cqrs-serverless/pull/463))
- Add blocking CI gates: `npm audit --omit=dev --audit-level=high` and ESLint startup check run on every PR, failing the build on any production vulnerability ([PR #448](https://github.com/mbc-net/mbc-cqrs-serverless/pull/448))

---

## [1.3.1](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.1) (2026-06-02) {#v131}

### Features

- **core:** Add group-based role authorization — `RolesGuard` checks direct roles from `custom:roles` first, then roles derived from the user's groups in the new `custom:groups` claim ([See Details](/docs/authentication#group-based-roles)) ([PR #440](https://github.com/mbc-net/mbc-cqrs-serverless/pull/440))
  - New `@GroupRoleResolver()` decorator and `IGroupRoleResolver` interface — implement exactly one resolver per app to map group IDs to roles (loaded from DynamoDB/RDS/config); the mapping is not stored in the JWT
  - `UserContext` gains `tenantRoles` (direct roles array) and `tenantGroupIds` (group IDs for the active tenant); `tenantRole` (singular) is kept for backward compatibility
  - Opt-in: existing `@Roles()` checks keep working with no code changes
  - A resolver failure propagates as a 5xx (not a silent 403), so a backend outage is distinguishable from a genuine access denial
- **mcp-server:** Update skills and analyzer for v1.3.1
  - AP027 anti-pattern detector added: a `@GroupRoleResolver()` class must not also be annotated with `@Injectable()`
  - `mbc-migrate` skill: v1.3.1 migration guide added
  - `mbc-generate` skill: group role resolver code generation template added
  - `mbc-review` skill: AP022 (group role resolver) added to checklist

### Bug Fixes

- **core:** Tolerate a malformed `custom:groups` claim (fail-closed to no group roles) instead of throwing, so a bad token degrades to direct-role-only checks rather than crashing the request
- See [Migration Guide v1.3.1](/docs/migration/v1.3.1) for upgrade instructions.

---

## [1.3.0](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.3.0) (2026-05-21) {#v130}

### Features

- **core:** Add `AppSyncEventsService` — opt-in HTTP pub/sub transport for real-time notifications via AWS AppSync Events API ([See Details](/docs/notification-module#appsync-events-service)) ([PR #433](https://github.com/mbc-net/mbc-cqrs-serverless/pull/433))
  - Transport selection via `NOTIFICATION_TRANSPORTS` env var (comma-separated); default `appsync-graphql` — existing GraphQL Subscription behavior is unchanged
  - Channel structure: `/{namespace}/{tenantCode}/{action}/{sanitizedId}` — clients subscribe at any granularity using AppSync wildcard (`/*`)
  - Authentication: IAM SigV4 for Lambda/ECS publish; API key for client subscriptions
  - Dual-publish mode: `NOTIFICATION_TRANSPORTS=appsync-graphql,appsync-event` to publish to both transports simultaneously during migration
  - New environment variables: `NOTIFICATION_TRANSPORTS`, `APPSYNC_EVENTS_ENDPOINT`, `APPSYNC_EVENTS_NAMESPACE` ([See Details](/docs/environment-variables#appsync-events-env))
  - `@NotificationTransport` decorator: pluggable transport registration — custom transports can be added without modifying framework code
- **cli:** CDK infra template: add `appsyncEvents` and `notificationTransports` to `Config` type — provisions `EventApi` + `ChannelNamespace`, injects `NOTIFICATION_TRANSPORTS`, `APPSYNC_EVENTS_ENDPOINT`, and `APPSYNC_EVENTS_NAMESPACE` into Lambda and ECS, and grants `appsync:EventPublish` IAM permission via `grantPublish()` automatically
- **mcp-server:** Update skills and analyzer for v1.3.0 ([PR #436](https://github.com/mbc-net/mbc-cqrs-serverless/pull/436))
  - AP026 anti-pattern detector added: `@NotificationTransport` implementors must not also be annotated with `@Injectable`
  - `mbc-migrate` skill: v1.3.0 migration guide and version compatibility table updated
  - `mbc-generate` skill: custom notification transport code generation template added
  - `mbc-review` skill: AP026 added to checklist
- See [Migration Guide v1.3.0](/docs/migration/v1.3.0) for upgrade instructions.

---

## [1.2.6](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.2.6) (2026-05-06) {#v126}

### Features

- **core:** Repository Read-Your-Writes (RYW) improvements — proactively purge stale RYW sessions when the data table catches up to or surpasses the session version, eliminating "stale override" reads ([See Details](/docs/command-service#ryw-session-cleanup)) ([PR #410](https://github.com/mbc-net/mbc-cqrs-serverless/pull/410))
  - `getItem`: when `existing.version >= session.version`, the session is purged in the background and persisted data is returned directly (skipping the unnecessary command-table read)
  - `listItemsByPk`: synchronized sessions are cleaned up in-place during the merge loop
  - `listItems` (RDS path): per-session checks are now parallelized via `Promise.all`, eliminating sequential N+1 latency
  - New optional `mergeOptions.getVersion` lets callers skip the extra DynamoDB GetItem when the existing RDS row already proves caught-up
  - `SessionService.delete()` and `DynamoDbService.deleteItem()` added; both safe for fire-and-forget use
  - Backward-compatible: `getVersion` is optional; projects with `RYW_SESSION_TTL_MINUTES` unset are unaffected
- **mcp-server:** Add AP021 anti-pattern detector — `Event Emit Directly After publishAsync in CommandService` (Severity: High) ([See Details](/docs/mcp-server#code-analysis-tools)) ([PR #408](https://github.com/mbc-net/mbc-cqrs-serverless/pull/408))
  - Detects `eventEmitter.emit()` calls within 200 chars after `commandService.publishAsync/publishSync`
  - Recommendation: emit events from `IDataSyncHandler.up()`/`down()` instead, since the data table is populated asynchronously via DynamoDB Streams after `publishAsync`
- **mcp-server:** Add cross-reference table mapping detector AP codes (`analyze.ts`) to skill-doc AP codes (`skills/mbc-review/SKILL.md`) — the two systems use independent numbering and only AP016–AP019 and AP021 share codes ([PR #411](https://github.com/mbc-net/mbc-cqrs-serverless/pull/411))
  - Detector output now annotates each hit with its corresponding skill-doc AP code, e.g. `AP005: Hardcoded Tenant (skill-doc: AP002)`
  - `mbc-migrate` skill: added v1.2.5 and v1.2.6 sections with migration matrix entries
  - `mbc-debug` skill: added troubleshooting entry for the (intentional) early RYW session purge in v1.2.6

### Bug Fixes

- **mcp-server:** `server.ts` was hardcoding the package version, which silently drifted on every `lerna version` bump. Now read at runtime from `package.json` ([PR #411](https://github.com/mbc-net/mbc-cqrs-serverless/pull/411))

---

## [1.2.5](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.2.5) (2026-04-10) {#v125}

### Features

- **import:** Refactor ZIP import processing — move ZIP job handling directly into `ImportService`, removing the separate `ZipImportQueueEventHandler` ([See Details](/docs/import#zip-import-architecture)) ([PR #404](https://github.com/mbc-net/mbc-cqrs-serverless/pull/404))
  - `ZipImportQueueEventHandler` has been removed; ZIP import jobs are now processed directly within `ImportService`
  - `ImportEventHandler` now skips SQS publishing for `ZIP_MASTER_JOB` events
  - Enhanced ZIP import validation in `CreateZipImportDto`
  - Improved error handling and logging for ZIP processing
- **mcp-server:** Add AP016–AP020 anti-pattern detectors to `mbc_check_anti_patterns` tool (total: 20 patterns) ([PR #403](https://github.com/mbc-net/mbc-cqrs-serverless/pull/403))
  - AP016: Missing Error Logging Before Rethrow (High)
  - AP017: Incorrect Attribute Merging on Partial Update (High)
  - AP018: Missing Swagger Documentation / `@ApiTags` (Low)
  - AP019: Missing Pagination in List Queries (High)
  - AP020: Missing `getCommandSource` for Tracing (Low)
- **mcp-server:** Update `mbc-migrate` and `mbc-debug` skills with v1.1.x and v1.2.x breaking change guidance ([PR #403](https://github.com/mbc-net/mbc-cqrs-serverless/pull/403))

### Dependencies

- **mcp-server:** Update `@modelcontextprotocol/sdk` from 1.26.0 to 1.29.0 ([PR #403](https://github.com/mbc-net/mbc-cqrs-serverless/pull/403))

---

## [1.2.4](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.2.4) (2026-04-09) {#v124}

### Features

- **task:** `TaskModule.register()` now returns a global module, eliminating the need to register it in multiple feature modules ([PR #398](https://github.com/mbc-net/mbc-cqrs-serverless/pull/398))
  - Previously, `TaskModule.register()` had to be called in each module that needed task functionality; now register it once in `AppModule`
- **mcp-server:** Add AP015 anti-pattern detector — detects duplicate `TaskModule.register()` calls (now redundant in v1.2.4+) ([PR #399](https://github.com/mbc-net/mbc-cqrs-serverless/pull/399))

---

## [1.2.3](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.2.3) (2026-04-08) {#v123}

### Bug Fixes

- **import:** Fix Head-of-Line Blocking (Poison Pill) in `CsvBatchProcessor` by implementing Smart Retry pattern ([See Details](/docs/import#csv-batch-error-handling)) ([PR #394](https://github.com/mbc-net/mbc-cqrs-serverless/pull/394))
  - Previously, a persistent validation error on the first row caused the entire batch to crash immediately
  - Now, each row is processed independently; errors are collected and a single aggregated error is thrown after the full batch is processed
  - Valid rows are saved successfully; failed rows trigger SQS retry; already-succeeded rows are skipped on retry via EQUAL comparison (idempotency maintained)
- **import:** Fix `ImportQueueEventHandler` passing raw SQS payload instead of parsed `importEvent` to `SingleImportProcessor` ([PR #394](https://github.com/mbc-net/mbc-cqrs-serverless/pull/394))
  - `singleImportProcessor.process()` now receives `event.importEvent` (parsed, rich object) instead of `event.payload` (raw SQS payload)

---

## [1.2.2](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.2.2) (2026-04-08) {#v122}

### Features

- **import:** Enhance import processing with SQS integration and parent job counter tracking ([PR #387](https://github.com/mbc-net/mbc-cqrs-serverless/pull/387))
  - `ImportQueueEventHandler` now publishes sub-job events to SQS for distributed processing
  - Parent job counter increments correctly when child jobs are enqueued
- **import:** Fix `CsvImportSfnEventHandler` to process both SUCCEEDED and FAILED Step Functions results ([PR #387](https://github.com/mbc-net/mbc-cqrs-serverless/pull/387))

### Bug Fixes

- **core:** Handle malformed JWT tokens gracefully in `extractInvokeContext` ([PR #388](https://github.com/mbc-net/mbc-cqrs-serverless/pull/388))
  - Prevents authentication failures caused by corrupted or unexpected JWT payloads

---

## [1.2.1](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.2.1) (2026-04-06) {#v121}

### Features

- **core:** Add `SqsService` and `SqsClientFactory` for SQS message operations ([See Details](/docs/queue#sqs-service)) ([PR #383](https://github.com/mbc-net/mbc-cqrs-serverless/pull/383))
  - `sendMessage()` — send a single message to an SQS queue
  - `sendMessageBatch()` — send up to 10 messages in a single API call
  - `receiveMessages()` — receive messages with configurable `MaxNumberOfMessages` (default: 10) and `WaitTimeSeconds` (default: 0)
  - `deleteMessage()` — acknowledge and delete a single processed message
  - `deleteMessageBatch()` — delete up to 10 messages in a single API call
  - `SqsService` is registered in `QueueModule` (global) and injectable across the application
  - Supports `MessageSystemAttributeNames` for receiving system attributes (deprecated `AttributeNames` not exposed)
- **core:** Refactor `SnsClientFactory` to use a singleton `SNSClient` instance ([PR #383](https://github.com/mbc-net/mbc-cqrs-serverless/pull/383))
  - Previously cached a separate client per topic ARN; now a single instance is shared across all publish calls
  - `getClient()` signature changed from `getClient(topicArn: string)` to `getClient()`

---

## [1.2.0](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.2.0) (2026-04-02) {#v120}

### Breaking Changes

- **core:** `publishSync()` and `publishPartialUpdateSync()` now return `null` when the command is not dirty (no-op) ([See Details](/docs/command-service#publishsync-audit-trail)) ([PR #375](https://github.com/mbc-net/mbc-cqrs-serverless/pull/375))
  - Return type changes from `Promise<CommandModel>` to `Promise<CommandModel | null>`
  - Matches the existing behavior of `publishAsync()` and `publishPartialUpdateAsync()`
  - Migration: add a null check before accessing any property on the result

### Features

- **core:** Add Read-Your-Writes (RYW) consistency via `SessionService` and `Repository` ([See Details](/docs/command-service#read-your-writes)) ([PR #375](https://github.com/mbc-net/mbc-cqrs-serverless/pull/375))
  - After `publishAsync`, subsequent reads by the same user now return pending command data before the DynamoDB Stream sync completes
  - Opt-in: set `RYW_SESSION_TTL_MINUTES` environment variable to enable (e.g. `5`)
  - New `Repository` class exported from `CommandModule` / `@mbc-cqrs-serverless/core` — wraps `DataService` with RYW merge for `getItem`, `listItemsByPk`, `listItems`
  - Session table `{NODE_ENV}-{APP_NAME}-session` must be created (see `dynamodbs/session.json`)
  - No effect when `RYW_SESSION_TTL_MINUTES` is unset — zero impact on existing projects
- **mcp-server:** Add AP013 and AP014 anti-pattern detectors for v1.2.0 breaking changes ([PR #377](https://github.com/mbc-net/mbc-cqrs-serverless/pull/377))
  - AP013: detects `publishSync`/`publishPartialUpdateSync` result used without null check
  - AP014: detects deprecated `genNewSequence()` usage
  - `migration_guide` prompt updated with v1.2.0 sections
- See [Migration Guide v1.2.0](/docs/migration/v1.2.0) for detailed upgrade instructions for both breaking changes.

### Bug Fixes

- **import:** Fix import status handling for ZIP orchestrator ([PR #370](https://github.com/mbc-net/mbc-cqrs-serverless/pull/370))
  - `ImportStatusHandler` now sends task success with `importJobStatus` when the job fails
  - `ZipImportSfnEventHandler` aggregates CSV task failure counts and adjusts final job status

---

## [1.1.6](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.1.6) (2026-03-30) {#v116}

### Bug Fixes

- **import:** Fix import status handling for ZIP orchestrator ([PR #371](https://github.com/mbc-net/mbc-cqrs-serverless/pull/371)) (backport from v1.2.0)
  - `ImportStatusHandler` now sends task success with `importJobStatus` when the job fails
  - `ZipImportSfnEventHandler` aggregates CSV task failure counts and adjusts final job status

---

## [1.1.5](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.1.5) (2026-03-28) {#v115}

### Features

- **import:** Implement v2 batch processing architecture for high-throughput CSV imports ([See Details](/docs/import-export-patterns#v2-batch-processing)) ([PR #366](https://github.com/mbc-net/mbc-cqrs-serverless/pull/366))
  - Replace per-row `import_tmp` writes with direct in-Lambda command publishing, eliminating Hot Partition bottlenecks
  - Distributed Map now configured with `MaxItemsPerBatch: 100` and `MaxConcurrency: 50` for significantly higher throughput
  - New `finalize_parent_job` state aggregates batch summaries and writes final job status in a single DynamoDB `UpdateItem` call
  - Remove per-row atomic counter updates from `CommandFinishedHandler`, eliminating DynamoDB throttling at scale
  - Add `ImportPublishMode` enum (`SYNC` / `ASYNC`) to `ImportEntityProfile` for per-entity publish mode configuration
  - Add empty `processingResults` guard: job is marked `FAILED` if no batch results are received

### Breaking Changes

- **import:** CSV import no longer provides real-time row-level progress tracking ([See Details](/docs/import-export-patterns#v2-batch-processing-breaking-changes))
  - `processedRows`, `succeededRows`, `failedRows` counters are now aggregated once when Step Functions execution completes
  - Individual CSV rows are no longer written to the `import_tmp` DynamoDB table
  - The `import-csv` state machine requires a new `finalize_parent_job` state and `resultPath: '$.processingResults'` — CDK and `serverless.yml` must be updated together with this package

### Tests

- Add SYNC/ASYNC routing tests for `ImportQueueEventHandler` (6 test cases covering EQUAL/NOT_EXIST/CHANGED × SYNC/ASYNC + fallback)
- Add empty `processingResults` guard test for `CsvImportSfnEventHandler`
- Add batch aggregation tests (1,000 + 500 rows, COMPLETED and FAILED scenarios)

---

## [1.1.4](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.1.4) (2026-03-27) {#v114}

### Features

- **core:** Restore audit trail and history parity for `publishSync` ([See Details](/docs/command-service#publishsync-audit-trail)) ([PR #363](https://github.com/mbc-net/mbc-cqrs-serverless/pull/363))
  - `publishSync` now writes an immutable event to the Command table with `status: 'publish_sync:STARTED'` and `syncMode: 'SYNC'`
  - History table is now populated by `publishSync`, matching the async Step Functions pipeline
  - Command lifecycle follows `publish_sync:STARTED` → `finish:FINISHED` (or `publish_sync:FAILED` on error)
  - Ported `isNotCommandDirty` early-return optimization from `publishAsync` — returns `null` when no changes detected
  - DynamoDB Stream filter updated to exclude `syncMode=SYNC` records, preventing Step Functions double-execution
  - `DefaultEventFactory` also filters `syncMode=SYNC` records for local development environments

### Tests

- Add comprehensive tests for `publishSync` audit trail and history parity

---

## [1.1.3](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.1.3) (2026-03-24) {#v113}

### Bug Fixes

- **import:** Fix CSV import Distributed Map state result exceeding 256KB limit ([See Details](/docs/import-export-patterns#csv-total-row-counting)) ([PR #348](https://github.com/mbc-net/mbc-cqrs-serverless/pull/348))
  - Set `resultPath: DISCARD` on Distributed Map to prevent child execution results from being aggregated into state data
  - Remove `MapResult` dependency from `CsvImportSfnEventHandler`, use `countCsvRows()` from S3 instead
  - Add error handling for cases where the S3 stream is not readable

### CI/CD

- Switch to npm OIDC trusted publishing, removing dependency on `NPM_TOKEN` secret ([PR #357](https://github.com/mbc-net/mbc-cqrs-serverless/pull/357))
  - Upgrade lerna from v8 to v9 for built-in OIDC support
  - Add `id-token: write` permission to publish job
  - Add lockfile sync step for Node 22+ compatibility

### Tests

- Add comprehensive tests for `CsvImportSfnEventHandler` finalize_parent_job logic
  - Test FAILED status when failedRows > 0
  - Test COMPLETED status when all rows succeed
  - Test no status update when processing is incomplete
  - Test error handling when S3 stream is not readable

---

## [1.1.2](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.1.2) (2026-02-25) {#v112}

### Features

- **master:** Add built-in upsert methods for master settings and data ([See Details](/docs/master#upsert-pattern))
  - `upsertTenantSetting()`, `upsertSetting()`, `upsertBulk()` for MasterSettingService
  - `upsert()`, `upsertSetting()`, `upsertBulk()` for MasterDataService
  - Automatically creates new records, updates changed records, and skips unchanged records
  - Supports recreating soft-deleted records
- **master:** Add unified bulk upsert API (`/api/master-bulk/`) ([See Details](/docs/master#unified-bulk-upsert))
  - Single endpoint that handles both settings and data items
  - Items routed by presence of `settingCode` field
  - Preserves original input order in response
  - Tenant code validation enforced
- **master:** Add `@ArrayMaxSize(100)` validation to all bulk DTOs
- **master:** Add tenant code validation to individual bulk endpoints (`/api/master-setting/bulk`, `/api/master-data/bulk`)

### Bug Fixes

- **core:** Fix `checkVersion` error message using hardcoded value instead of actual `commandVersion` ([PR #331](https://github.com/mbc-net/mbc-cqrs-serverless/pull/331))
- **master:** Fix `seq === 0` being treated as falsy in `createSetting` by changing to null check (`seq == null`)
- **master:** Fix DTO mutation in `createSetting` by cloning attributes before modifying seq

### Tests

- Add comprehensive unit tests for MasterBulkController (8 test cases)
- Add unit tests for MasterDataService upsert and upsertBulk methods
- Add unit tests for MasterSettingService upsertTenantSetting and upsertBulk methods
- Add integration tests for master data and setting upsert scenarios

---

## [1.1.1](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.1.1) (2026-02-07) {#v111}

### Bug Fixes

- **cli:** Add missing `import_tmp.json` DynamoDB table template ([See Details](/docs/dynamodb#system-table-definitions)) ([PR #323](https://github.com/mbc-net/mbc-cqrs-serverless/pull/323))
  - The `import_tmp` table definition was missing from CLI templates, causing `npm run offline:sls` to fail
  - The `serverless.yml` references `LOCAL_DDB_IMPORT_TMP_STREAM` environment variable, which requires the table to be created during migration
  - See [Common Issues](/docs/common-issues#missing-import-tmp-table) for workaround if using older versions

---

## [1.1.0](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.1.0) (2026-02-03) {#v110}

### Breaking Changes

- **tenant:** Change `TENANT_COMMON` enum value from `'COMMON'` to `'common'` (lowercase)
  - This change affects partition key format: `TENANT#COMMON` → `TENANT#common`
  - **Migration required:** Existing data with `TENANT#COMMON` partition keys needs to be migrated
  - See [Migration Guide](/docs/migration/v1.1.0) for detailed instructions
- **core:** Remove deprecated `CommandService.publish()` method ([See Details](/docs/migration/v1.1.0#breaking-change-3-deprecated-methods-removed))
  - Use `CommandService.publishAsync()` instead
- **core:** Remove deprecated `CommandService.publishPartialUpdate()` method
  - Use `CommandService.publishPartialUpdateAsync()` instead
- **sequence:** Remove deprecated `SequencesService.genNewSequence()` method
  - Use `SequencesService.generateSequenceItem()` instead

### Features

- **core:** Add tenant code normalization for case-insensitive matching ([See Details](/docs/data-migration-patterns#tenant-code-normalization-migration))
  - Tenant codes are now automatically normalized to lowercase
  - `getUserContext()` returns normalized tenant code
  - All DynamoDB operations use normalized tenant codes for consistency
- **core:** Add `normalizeTenantCode()` utility function for explicit normalization
- **core:** Add `isCommonTenant()` utility function for common tenant detection
- **core:** Add EmailTags support for AWS SES email categorization and filtering ([See Details](/docs/notification-module#email-tags))
  - New `emailTags` option in `EmailNotification` interface
  - Tags are passed to SES for email categorization and tracking
- **core:** Add extensible tenant verification in RolesGuard ([See Details](/docs/authentication#tenant-verification))
  - `isHeaderOverride()`: Detect header-based tenant override
  - `canOverrideTenant()`: Check permission for cross-tenant access
  - `getCommonTenantCodes()`: Configurable common tenant list
  - `getCrossTenantRoles()`: Configurable cross-tenant roles (default: 'system_admin')
- **cli:** Add npm registry version check for skill updates
  - Fetch latest version from npm registry instead of local package.json
  - 24-hour cache to reduce network requests
  - Offline fallback to cached version

### Security

- **core:** Restrict tenant code header override to system admin only
  - Previously, users without `custom:tenant` Cognito attribute could specify any tenant via header
  - Now only users with global `system_admin` role can override tenant code via `x-tenant-code` header
  - Regular users must have `custom:tenant` set in Cognito

### Bug Fixes

- **master:** Fix `TENANT_COMMON` constant usage in MasterSettingService and MasterDataService
  - Previously hardcoded `'COMMON'` strings are now using `SettingTypeEnum.TENANT_COMMON`
  - Ensures consistent partition key generation across the framework

### Tests

- **tenant:** Add comprehensive tests for TenantService methods
  - `getTenant()`: Retrieval tests
  - `updateTenant()`: Update and attribute merge tests
  - `deleteTenant()`: Soft delete tests
  - `addTenantGroup()`: Group management tests
  - `customizeSettingGroups()`: Setting customization tests
  - `createTenantGroup()`: Tenant group creation tests
- **tenant:** Add SettingTypeEnum validation tests
  - Verify `TENANT_COMMON = 'common'` (lowercase)
  - Ensure enum completeness and consistency
- **core:** Add tenant code normalization tests (70+ test cases)
- **core:** Add tenant normalization command tests (30+ test cases)
- **core:** Add comprehensive dependency integration tests (3400+ tests)
  - AWS SDK integration tests (DynamoDB, S3, SNS, SQS, Step Functions, SES)
  - NestJS behavior tests (decorators, config, DI, Swagger)
  - Third-party library tests (class-transformer, class-validator, RxJS)

### Documentation

- Add migration guide for v1.1.0 tenant code changes

---

## [1.0.26](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.26) (2026-01-26) {#v1026}

### Features

- **cli:** Add configurable local service ports via environment variables ([See Details](/docs/installation#configuring-local-ports)) ([PR #300](https://github.com/mbc-net/mbc-cqrs-serverless/pull/300))
  - Support for `LOCAL_HTTP_PORT`, `LOCAL_DYNAMODB_PORT`, `LOCAL_RDS_PORT`, and other port variables
  - Allows users to resolve port conflicts with other services
  - Configuration is automatically applied to Docker Compose, Serverless Offline, and trigger scripts

### Security

- Update `diff` package from 4.0.2 to 4.0.4 for security fix ([PR #297](https://github.com/mbc-net/mbc-cqrs-serverless/pull/297), [PR #299](https://github.com/mbc-net/mbc-cqrs-serverless/pull/299))
- Update `lodash` package from 4.17.21 to 4.17.23 for prototype pollution fix ([PR #298](https://github.com/mbc-net/mbc-cqrs-serverless/pull/298))

---

## [1.0.25](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.25) (2026-01-19) {#v1025}

### Features

- **core:** Enhanced inline template email with advanced variable substitution ([See Details](/docs/notification-module#advanced-template-features))
  - Support for nested property access in template variables (e.g., user.profile.name in double-brace placeholders)
  - Support for Unicode/Japanese keys in template variables
  - Whitespace trimming inside placeholders so spaces around the variable name are ignored
  - Improved local development fallback for template compilation

---

## [1.0.24](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.24) (2026-01-17) {#v1024}

### Features

- **mcp-server:** Add Claude Code Skills for guided development assistance ([See Details](/docs/mcp-server#claude-code-skills))
  - `/mbc-generate`: Generate boilerplate code (modules, services, controllers, DTOs, handlers)
  - `/mbc-review`: Review code for best practices and anti-patterns (20 patterns)
  - `/mbc-migrate`: Guide version migrations and breaking changes
  - `/mbc-debug`: Debug and troubleshoot common issues
  - Skills are distributed via npm package and can be installed to `~/.claude/skills/` or `.claude/skills/`
- **cli:** Add `mbc install-skills` command for easy skills installation ([See Details](/docs/cli#install-skills))
  - Install skills to personal directory (`~/.claude/skills/`) or project directory (`.claude/skills/`)
  - Options: `--project`, `--force`, `--list`

### Bug Fixes

- **core:** Fix typo in parameter name `skExpession` to `skExpression`
  - Affected packages: core, directory, master, task, ui-setting
  - This was a breaking change for TypeScript users who referenced the old parameter name

---

## [1.0.23](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.23) (2026-01-16) {#v1023}

### Features

- **core:** Add inline template email support with `sendInlineTemplateEmail()` method ([See Details](/docs/notification-module#inline-template-emails))
  - New `sendInlineTemplateEmail(msg: TemplatedEmailNotification)` method in EmailService
  - Support for inline HTML/text templates with dynamic data substitution
  - Local development fallback with manual template compilation when SES is unavailable
  - New interfaces: `InlineTemplateContent`, `TemplatedEmailNotification`

---

## [1.0.22](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.22) (2026-01-16) {#v1022}

### Features

- **mcp-server:** Add code analysis tools for AI-assisted development ([See Details](/docs/mcp-server#code-analysis-tools))
  - `mbc_check_anti_patterns`: Detect common anti-patterns in code with severity levels
  - `mbc_health_check`: Project health check (dependencies, structure, configuration)
  - `mbc_explain_code`: Analyze and explain code in MBC CQRS context

### Bug Fixes

- **mcp-server:** Improve code analysis tools robustness
  - Renumber anti-patterns sequentially (AP001-AP010)
  - Limit regex match range to prevent false positives
  - Add error handling for file reading and JSON parsing
  - Add 18 unit tests for analyze tools

### Security

- Fix security vulnerabilities in dependencies: qs, express, body-parser

### Dependencies

- Bump qs from 6.13.0 to 6.14.1
- Bump @nestjs/platform-express from 10.4.20 to 10.4.22
- Bump express from 4.21.2 to 4.22.1
- Bump body-parser from 1.20.3 to 1.20.4

---

## [1.0.21](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.21) (2026-01-15) {#v1021}

### Features

- **import:** Add ZIP finalization hooks support to ImportModule
  - New `IZipFinalizationHook` interface for custom post-import processing
  - Register hooks via `zipFinalizationHooks` option in `ImportModule.register()`
  - Hooks receive `ZipFinalizationContext` with results, status, and execution input

---

## [1.0.20](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.20) (2026-01-11) {#v1020}

### Bug Fixes

- **import:** Fix Step Functions CSV handler always setting COMPLETED status regardless of child job failures
  - Fixed `CsvImportSfnEventHandler.finalizeParentJob()` to correctly set status to FAILED when any child job fails
  - Fixed `CsvImportSfnEventHandler` in `csv_loader` state to correctly set status when early finalization occurs with failures
  - Previously, the ternary operator was incorrectly returning COMPLETED for both cases: `failedRows > 0 ? COMPLETED : COMPLETED`
  - Now correctly returns FAILED when failedRows > 0: `failedRows > 0 ? FAILED : COMPLETED`
  - This bug caused Step Functions to report SUCCESS even when child import jobs failed
  - See [CsvImportSfnEventHandler](/docs/import-export-patterns#csvimportsfneventhandler) for details

---

## [1.0.19](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.19) (2026-01-11) {#v1019}

### Bug Fixes

- **import:** Fix master job status not updating to FAILED when child import jobs fail
  - Previously, when a child import job failed with errors like `ConditionalCheckFailedException`, the master job status remained `PROCESSING` indefinitely
  - Fixed `incrementParentJobCounters` to correctly set master job status to `FAILED` when any child job fails (was always setting to `COMPLETED`)
  - Fixed `ImportQueueEventHandler.handleImport` to call `incrementParentJobCounters` on error, ensuring parent counters are updated
  - Removed `throw error` in error handler to prevent Lambda crashes and allow proper status propagation
  - This fix completes the Step Functions error handling started in v1.0.18, ensuring `SendTaskFailure` is properly triggered
  - See [ImportQueueEventHandler Error Handling](/docs/import-export-patterns#import-error-handling) for details

---

## [1.0.18](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.18) (2026-01-10) {#v1018}

### Bug Fixes

- **import:** Add `SendTaskFailure` support to `ImportStatusHandler` for proper Step Functions error handling
  - Previously, when an import job failed, the Step Function would wait indefinitely because only `SendTaskSuccess` was implemented
  - Now the handler properly sends `SendTaskFailure` when a job fails, allowing Step Functions to handle errors correctly
  - Added `sendTaskFailure()` method to send `SendTaskFailureCommand`
  - Handler now processes both `COMPLETED` and `FAILED` statuses for CSV import jobs
  - See [ImportStatusHandler API](/docs/import-export-patterns#importstatushandler-api) for details

---

## [1.0.17](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.17) (2026-01-08) {#v1017}

### Bug Fixes

- **master:** Fix `masterTypeCode` comparison in `MasterDataService.search()` - Changed from partial match (`contains`) to exact match for `settingCode` search parameter ([See Details](/docs/master#search-parameters))
- **cli:** Stabilize AbstractRunner tests by removing setTimeout to fix flaky CI failures

### Security

- Fix security vulnerabilities in dependencies: jws (HMAC signature verification issue), nodemailer (DoS vulnerability)

### Dependencies

- Bump validator from 13.15.20 to 13.15.26
- Bump @modelcontextprotocol/sdk from 1.25.1 to 1.25.2

### Documentation

- Update README files for all packages with comprehensive API references and usage examples
- Fix `createTenantGroup` parameter name in tenant package README
- Update Japanese guide links to official documentation

---

## [1.0.16](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.16) (2025-12-31) {#v1016}

### Bug Fixes

- **cli:** Add cleanup for test-generated files and update .gitignore
- **master, directory, task, cli:** Improve error messages for better clarity

### Features

- Include __s3Key in attributes for import creation
- Zip mode provide table name
- Add optional s3Key to CreateImportDto

---

## [1.0.15](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.15) (2025-12-31) {#v1015}

### Bug Fixes

- **ui-setting:** Improve error messages for better clarity
- **mcp-server:** Use MBC_PROJECT_PATH for ERROR_CATALOG.md lookup

---

## [1.0.14](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.14) (2025-12-29) {#v1014}

### Features

- **mcp-server:** Add MCP server package for AI tool integration

### Documentation

- Add comprehensive error message catalog
- Add JSDoc comments to core interfaces
- Add operational documentation (FAQ, troubleshooting, security)
- Add AI-friendly documentation files

---

## [1.0.13](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.13) (2025-12-26) {#v1013}

### Features

- Enhance CreateZipImportDto and ZipImportQueueEventHandler

---

## [1.0.12](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.12) (2025-12-23) {#v1012}

### Bug Fixes

- Merge tenant attributes in TenantService

---

## [1.0.11](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.11) (2025-12-22) {#v1011}

### Bug Fixes

- Handle unknown source IP in SequencesService

---

## [1.0.10](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.10) (2025-11-28) {#v1010}

### Bug Fixes

- Fix createTenantGroup method in TenantService

---

## [1.0.9](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.9) (2025-11-26) {#v109}

### Bug Fixes

- Remove callback parameter from Lambda handler for Node.js 24 compatibility

---

## [1.0.8](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.8) (2025-11-17) {#v108}

### Security

- Bump jws dependency for security fix

---

## [1.0.7](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.7) (2025-11-07) {#v107}

### Security

- Bump validator dependency in examples
- Bump js-yaml dependency for security fix

---

## [1.0.6](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.6) (2025-11-05) {#v106}

### Features

- **master:** Add tenantCode support to MasterDataCreateDto and update service logic

---

## [1.0.5](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.5) (2025-11-04) {#v105}

### Features

- **master:** Enhance master settings with tenantCode support in DTOs and service logic

---

## [1.0.4](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.4) (2025-10-29) {#v104}

### Features

- **core:** Add configurable request body size limit to bootstrap and environment validation
- **master:** Add bulk creation endpoints for master data and settings

### Dependencies

- Bump validator from 13.11.0/13.12.0 to 13.15.20
- Bump multer from 1.4.4-lts.1 to 2.0.2 and @nestjs/platform-express from 10.4.4 to 10.4.20
- Bump axios from 1.7.7 to 1.13.1 in CLI templates

---

## [1.0.3](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.3) (2025-10-23) {#v103}

### Features

- **master:** Add bulk creation endpoints for master data and settings, enabling batch operations for improved efficiency

---

## [1.0.2](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.2) (2025-10-16) {#v102}

### Features

- **survey:** Add survey template API for managing survey templates

### Dependencies

- Bump @nestjs/common from 10.3.0 to 10.4.16 in /examples/master
- Bump multer from 1.4.4-lts.1 to 2.0.2 and @nestjs/platform-express from 10.4.15 to 10.4.20 in /examples/seq
- Bump @nestjs/cli from 10.4.5 to 11.0.10 and inquirer from 8.2.6 to 8.2.7

---

## [1.0.1](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.1) (2025-09-19) {#v101}

### Features

- **import:** Add zip mode support for import module, enabling compressed file imports

---

## [1.0.0](https://github.com/mbc-net/mbc-cqrs-serverless/releases/tag/v1.0.0) (2025-09-18) {#v100}

### Highlights

- First stable production release
- Based on beta version 0.1.74

---

## Beta Releases (0.1.x) {#beta-releases}

## [0.1.75-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.74-beta.0...v0.1.75-beta.0)

### Bug Fixes

- **import:** Add `SendTaskFailure` support to `ImportStatusHandler` for proper Step Functions error handling
  - Previously, when an import job failed, the Step Function would wait indefinitely because only `SendTaskSuccess` was implemented
  - Now the handler properly sends `SendTaskFailure` when a job fails, allowing Step Functions to handle errors correctly
  - Added `sendTaskFailure()` method to send `SendTaskFailureCommand`
  - Handler now processes both `COMPLETED` and `FAILED` statuses for CSV import jobs
  - See [ImportStatusHandler API](/docs/import-export-patterns#importstatushandler-api) for details

---

## [0.1.74-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.73-beta.0...v0.1.74-beta.0) (2025-08-25)

### Features

- Import module implementation
- Infrastructure updates for import module
- Local infrastructure updates for import module

---

## [0.1.73-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.72-beta.0...v0.1.73-beta.0) (2025-07-31)

### Bug Fixes

- **master:** Fixed package installation issue

---

## [0.1.72-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.71-beta.0...v0.1.72-beta.0) (2025-07-24)

### Features

- Added case-insensitive search for master data and settings

---

## [0.1.71-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.70-beta.0...v0.1.71-beta.0) (2025-07-18)

### Bug Fixes

- Fixed core package test failures blocking CI
- Fixed GitHub workflow issues
- Handle Step Function name length limit
- StepFunctionService execution name length validation

### Features

- CLI package comprehensive test enhancement
- Core package service unit test enhancement
- Implemented comprehensive unit tests for controllers
- Master package service unit test enhancement
- Sequence service test enhancement
- Task service unit test enhancement
- Implemented missing service unit tests
- Implemented unit tests for high-priority packages

---

## [0.1.70-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.69-beta.0...v0.1.70-beta.0) (2025-07-14)

### Bug Fixes

- **master:** Fixed master-setting unit test
- Updated package version

### Features

- **master:** Added copy to tenant functionality

---

## [0.1.69-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.68-beta.0...v0.1.69-beta.0) (2025-07-07)

### Bug Fixes

- **master:** Updated unit test

### Features

- **master:** Added Prisma option

---

## [0.1.68-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.67-beta.0...v0.1.68-beta.0) (2025-07-01)

### Bug Fixes

- Fixed build lib CI
- Updated import template master data module

### Features

- Added template master API

---

## [0.1.67-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.66-beta.0...v0.1.67-beta.0) (2025-06-10)

### Features

- Enhanced EmailService to support attachments

---

## [0.1.65-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.64-beta.0...v0.1.65-beta.0) (2025-05-19)

### Bug Fixes

- Fixed empty AppSync URL issue
- Fixed test AppSync URL

### Features

- Added second AppSync support

---

## [0.1.58-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.57-beta.0...v0.1.58-beta.0) (2025-04-24)

### Bug Fixes

- Fixed get format sequence from master data item

---

## [0.1.55-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.54-beta.0...v0.1.55-beta.0) (2025-02-14)

### Features

- Updated template to use Node 20 runtime

---

## [0.1.53-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.52-beta.0...v0.1.53-beta.0) (2025-02-12)

### Features

- Added queue and Step Function for task processing
- Task processing by Step Function

---

## [0.1.51-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.50-beta.0...v0.1.51-beta.0) (2025-01-17)

### Bug Fixes

- Corrected description text

### Features

- Added logger
- Added schematic description
- Added schematic for generating controllers
- Added schematic for generating dto, service, entity
- Added schematic for generating module

---

## [0.1.50-beta.0](https://github.com/mbc-net/mbc-cqrs-serverless/compare/v0.1.49-beta.0...v0.1.50-beta.0) (2025-01-14)

### Bug Fixes

- Fixed serialize helper entity field processing

### Features

- Added serialize helper functions for internal/external structure conversion

---


## Related Documentation

- [Migration Guide v1.3.0](/docs/migration/v1.3.0) - Upgrade guide for v1.3.0 (nodemailer v8)
- [Migration Guide v1.2.0](/docs/migration/v1.2.0) - Upgrade guide for v1.2.0 (publishSync null return value)
- [Migration Guide v1.1.0](/docs/migration/v1.1.0) - Upgrade guide for v1.1.0 (TENANT_COMMON, tenant code normalization)
- [Version Conflict Guide](/docs/version-conflict-guide) - Handling version conflicts in upgrades
- [Web Changelog](/docs/web-changelog) - Release notes for master-web and survey-web frontend packages

## Related Links

- [GitHub Releases](https://github.com/mbc-net/mbc-cqrs-serverless/releases)
- [npm Package](https://www.npmjs.com/package/@mbc-cqrs-serverless/core)


---