docs: add documentation for migration runner and deployment process (#73)

## Overview

This PR adds comprehensive documentation for the database migration
runner and deployment process to improve developer experience and
clarify how the system works.

## Changes

### 1. Enhanced Migration Runner Documentation
(`webapp/src/jobs/migration-runner.ts`)
- Added detailed comments explaining the two invocation contexts:
- **CDK Trigger**: Automatically invoked during `cdk deploy` with
default payload
  - **Manual Invocation**: Using AWS CLI with custom commands
- Included example AWS CLI command for manual execution
- Referenced CloudFormation stack outputs for function name and command
template

### 2. Improved CDK Infrastructure Comments
(`cdk/lib/constructs/webapp.ts`)
- Added comments to Trigger construct explaining automatic invocation
with default payload
- Added comments to CfnOutput section with available commands and
execution examples
- Clarified the relationship between CDK Trigger and manual Lambda
invocation

### 3. Extended README.md Deploy Section
Added two new subsections under the Deploy section:

#### WebApp Deployment
- Explains that Next.js webapp is built and deployed during CDK
deployment using `deploy-time-build`
- Links to implementation file for details

#### Database Migration
- Explains that migrations are automatically executed during CDK
deployment using CDK Trigger
- Links to implementation files (webapp.ts and migration-runner.ts)
- Provides AWS CLI command example for manual migration execution
- Lists available commands: `deploy` (default), `force` (with
--accept-data-loss)

## Benefits

- Developers can now easily understand how to manually run database
migrations
- Clear documentation of the deployment process and migration workflow
- Improved code maintainability with inline comments
- Better onboarding experience for new developers

## Testing

- Verified all links in README.md point to correct files
- Confirmed code comments are accurate and helpful
- No functional changes - documentation only

<!-- DO NOT EDIT: System generated metadata -->
<!-- WORKER_ID:1765116242720649 -->

Co-authored-by: remote-swe-app[bot] <123456+remote-swe-app[bot]@users.noreply.github.com>

Author: konokenj

README.md

@@ -84,6 +84,26 @@ ServerlessWebappStarterKitStack.FrontendDomainName = https://web.exmaple.com
 
 Opening the URL in `FrontendDomainName` output, you can now try the sample app on your browser.
 
+### WebApp Deployment
+
+The Next.js webapp is built and deployed during the CDK deployment process using [deploy-time-build](https://github.com/tmokmss/deploy-time-build). This approach ensures your application is containerized and deployed to AWS Lambda as part of the infrastructure deployment. See the [implementation](./cdk/lib/constructs/webapp.ts) for details.
+
+### Database Migration
+
+Database migrations are automatically executed during CDK deployment using a [CDK Trigger](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.triggers-readme.html). The migration runs with the default `deploy` command. See the [implementation](./cdk/lib/constructs/webapp.ts) and [migration runner](./webapp/src/jobs/migration-runner.ts) for details.
+
+To manually run migrations with different commands:
+
+```sh
+aws lambda invoke \
+  --function-name <MigrationFunctionName from CDK output> \
+  --payload '{"command":"deploy"}' \
+  --cli-binary-format raw-in-base64-out \
+  /dev/stdout
+```
+
+Available commands: `deploy` (default), `force` (with --accept-data-loss).
+
 ## Add your own features
 To implement your own features, you may want to add frontend pages, API routes, or async jobs. The project uses Next.js App Router, which provides a unified approach for both frontend and backend development. You can follow the conventional Next.js patterns to add pages and API routes. For more details, please refer to the [`webapp/README.md`](./webapp/README.md) guide.
 

cdk/lib/constructs/webapp.ts

@@ -157,13 +157,18 @@ export class Webapp extends Construct {
     });
     migrationRunner.connections.allowToDefaultPort(database);
 
-    // run database migration during CDK deployment
+    // Run database migration during CDK deployment
+    // The Trigger construct automatically invokes the migration runner with default payload (command: 'deploy')
+    // To manually run migrations with different commands (e.g., 'force'), use the AWS CLI command shown in the CDK output below
     const trigger = new Trigger(this, 'MigrationTrigger', {
       handler: migrationRunner,
     });
     // make sure migration is executed after the database cluster is available.
     trigger.node.addDependency(database.cluster);
 
+    // Output migration-related information for manual invocation
+    // Available commands: "deploy" (default), "force" (with --accept-data-loss)
+    // Example: aws lambda invoke --function-name <FUNCTION_NAME> --payload '{"command":"force"}' --cli-binary-format raw-in-base64-out /dev/stdout
     new CfnOutput(Stack.of(this), 'MigrationFunctionName', { value: migrationRunner.functionName });
     new CfnOutput(Stack.of(this), 'MigrationCommand', {
       value: `aws lambda invoke --function-name ${migrationRunner.functionName} --payload '{"command":"deploy"}' --cli-binary-format raw-in-base64-out /dev/stdout`,

webapp/src/jobs/migration-runner.ts

@@ -3,6 +3,12 @@ import { execFile } from 'child_process';
 import path from 'path';
 
 export const handler: Handler = async (event, _) => {
+  // This Lambda function is invoked in two contexts:
+  // 1. CDK Trigger: Automatically invoked during `cdk deploy` with default payload (no command specified, defaults to 'deploy')
+  // 2. Manual Invocation: Use AWS CLI to invoke with custom commands
+  //    Example: aws lambda invoke --function-name <FUNCTION_NAME> --payload '{"command":"force"}' --cli-binary-format raw-in-base64-out /dev/stdout
+  //    The function name and command template are available in the CloudFormation stack outputs after deployment
+  //
   // Available commands are:
   //   deploy: create new database if absent and apply all migrations to the existing database.
   //   reset: delete existing database, create new one, and apply all migrations. NOT for production environment.