docs(ALL): enhance project documentation with comprehensive README updates

.cursor/commands/create-pr.md

@@ -21,8 +21,8 @@
 
 ## ルール
 
-- 日本語での回答・作成を基本とする
-- 文体は常体で回答・作成すること
+- タイトルは英語で作成し、descriptionは日本語での回答・作成を基本とする
+- 文体は常体で作成すること
 
 ## 手順
 
@@ -37,7 +37,7 @@
    - このIssueが何をするものでどのような変更を行うものかを確認する
    - このIssueのラベルを確認する
    - `gh issue` コマンドを使用してIssueを確認すること
-     - 対象のIssueがない場合はユーザーに確認する
+     - 対象のIssueがない場合やIssueの内容とbranch名がおおよそ一致しない場合はユーザーに確認する
 
 3. **変更点を確認する**
 
@@ -55,6 +55,7 @@
 
    - PRのタイトルはIssueのタイトルや内容、Branchでの変更点をを詳しくかつ内容を簡潔に反映したものにする。
    - Titleの形式は `<Task Type>(<Area>): <Subject>` であり、この形式で作成すること。
+   - 英語で作成すること
 
 6. **Descriptionを作成する**
    - テンプレートは`.github/pull_request_template.md`を利用すること

.github/act/README.md

@@ -0,0 +1,27 @@
+# Act Debug
+
+Run CI performed by Github Action in a local environment
+
+Install [`act`](https://github.com/nektos/act) and Start `Docker` for local environment.
+
+## Setup
+
+1. add .env file in the root directory ref .env.example
+2. add .secrets file in the root directory ref .secrets.example
+
+## Run
+
+```sh
+# run all workflows
+act --container-architecture linux/amd64\
+ --secret-file ./.github/act/.secrets\
+ --env-file ./.github/act/.env\
+ --defaultbranch main
+
+# run specific workflow
+act --container-architecture linux/amd64\
+ --secret-file ./.github/act/.secrets\
+ --env-file ./.github/act/.env\
+ --defaultbranch main\
+ -W "target-flow"
+```

README.md

@@ -116,18 +116,3 @@ bun run test
 # Other
 # See `scripts` field in `package.json`
 ```
-
-## CI in the local environment
-
-Perform CI performed by Github Action in a local environment
-
-Install [`act`](https://github.com/nektos/act) and Start `Docker`
-
-```sh
-act --container-architecture linux/amd64 --secret-file ./.github/act/.secrets --env-file ./.github/act/.env --defaultbranch main -W "target-flow"
-```
-
-## Note
-
-> [!NOTE]
-> Since Biome's VSCode extension does not support workspaces, all settings are rolled up and configured in root's `biome.json`.

apps/api/README.md

@@ -1,90 +1,242 @@
 # mona-ca Backend API Server
 
-## What's this ?
+Backend API server for mona-ca.
 
-This is the code for the Server-Side API of mona-ca.
+## 📖 Table of Contents
+
+- [Overview](#overview)
+- [Tech Stack](#tech-stack)
+- [Architecture](#architecture)
+- [Setup](#setup)
+- [Development](#development)
+- [Testing](#testing)
+- [Database](#database)
+- [Deployment](#deployment)
+
+## Overview
+
+mona-ca Backend API is a serverless API server running on Cloudflare Workers.
+Built with Clean Architecture principles to ensure high maintainability and extensibility.
+
+## Tech Stack
 
 It is made by these:
 
-* __Bun__ 🥟: All-in-one JavaScript runtime
-* __Wrangler__ ☁️: The Cloudflare Developer Platform
-* __ElysiaJS__ 🦊: Ergonomic web framework
-* __Drizzle ORM__ 🌦️: Headless TypeScript ORM
-* __Lucia__ 🔐: Auth library
-* __Oslo__ 🔒: Many auth utilities
-* __Arctic__ 🔏: Collection of OAuth 2.0 clients
-* __Resend__ ✉️: Library for the Resend API.
+__Bun__ 🥟: All-in-one JavaScript runtime
+
+__Wrangler__ ☁️: The Cloudflare Developer Platform
+
+__ElysiaJS__ 🦊: Ergonomic web framework
+
+__Drizzle ORM__ 🌦️: Headless TypeScript ORM
+
+__Lucia__ 🔐: Auth library
+
+__Oslo__ 🔒: Many auth utilities
+
+__Arctic__ 🔏: Collection of OAuth 2.0 clients
+
+__Resend__ ✉️: Library for the Resend API.
+
+## Architecture
+
+Built on Clean Architecture, DDD, and Onion Architecture with a layered architecture pattern.
 
-Project Architecture:
+### Architecture Principles
 
-* __Clean Architecture__ 📚: to ensure independence
-* __Repository Pattern__ 🗄️: Abstraction of data access
-* __SOLID Principles__ 🔄: Programming Principles
+- **Clean Architecture**: Keep business logic independent from frameworks and infrastructure
+- **DDD**: Domain-Driven Design
+- **Onion Architecture**: Onion Architecture
+- **Repository Pattern**: Abstract data access logic
+- **SOLID Principles**: Design principles for maintainability and extensibility
+- **Dependency Injection**: Improve testability
+- **Feature-based Organization**: Organize code by domain features
 
-## Start Development Server
+### Layer Structure
 
-To start the development server run:
+```text
+┌─────────────────────────────────────┐
+│      Presentation Layer             │  routes/
+│      (ElysiaJS Routes)              │
+├─────────────────────────────────────┤
+│      Adapter Layer                  │  features/*/adapters/
+│  (Presenters, Repositories,         │
+│   Gateways)                         │
+├─────────────────────────────────────┤
+│      Application Layer              │  features/*/application/
+│      (Use Cases, Ports)             │
+├─────────────────────────────────────┤
+│      Domain Layer                   │  features/*/domain/
+│  (Entities, Value Objects)          │
+├─────────────────────────────────────┤
+│      Infrastructure Layer           │  core/infra/
+│  (Drizzle, Crypto, Config)          │
+└─────────────────────────────────────┘
+```
+
+See [Architecture Documentation](./docs/architecture.md) for details.
+
+### Directory Structure
+
+```text
+apps/api/
+├── src/
+│   ├── core/                 # Common infrastructure & libraries
+│   │   ├── adapters/         # Common adapter implementations
+│   │   ├── di/               # DI container
+│   │   ├── domain/           # Common domain objects
+│   │   ├── infra/            # Infrastructure implementations
+│   │   ├── lib/              # Common libraries
+│   │   ├── ports/            # Common interfaces
+│   │   └── testing/          # Testing support
+│   ├── features/             # Feature modules
+│   │   └── [feature]/        # Each feature
+│   │       ├── adapters/     # Adapter layer
+│   │       ├── application/  # Application layer
+│   │       ├── di/           # Feature DI container
+│   │       ├── domain/       # Domain layer
+│   │       └── testing/      # Testing support
+│   ├── plugins/              # Elysia plugins
+│   ├── routes/               # Route definitions
+│   └── index.ts              # Entry point
+├── tests/                    # E2E tests
+├── drizzle/                  # DB migrations
+├── docs/                     # Documentation
+├── types/                    # Type definitions
+├── package.json              # Package configuration
+├── tsconfig.json
+├── vitest.config.ts
+├── wrangler.jsonc            # Cloudflare configuration
+└── drizzle.config.ts         # Drizzle configuration
+```
+
+## Setup
+
+### Installation
 
 ```sh
-# install
-bun i
+# Install dependencies
+bun install
+```
+
+### Environment Variables
+
+Create a `.dev.vars` file and set the required environment variables.
+
+### Database Setup
+
+```sh
+# Generate migration files
+bun run db:gen
+
+# Apply migrations (local)
+bun run db:mig
+```
 
-# dev server start
-bun dev
+## Development
+
+### Start Development Server
+
+```sh
+bun run dev
 ```
 
-## OpenAPI
+The development server starts at `http://localhost:8787`.
+
+### OpenAPI/Swagger
+
+API documentation is available at:
 
 ```sh
 open http://localhost:8787/swagger
 ```
 
-## Development Tool Commands
+### Code Quality Checks
 
-### Check
+#### Static Code Analysis
 
-static code check about syntax, format, import
+Check syntax, format, and import order.
 
 ```sh
-# not fixed
-bun check
+# Check only
+bun run check
 
-# force fix
-bun check:fix
+# Auto-fix
+bun run check:fix
 ```
 
-### Test
+#### Type Checking
 
 ```sh
-# run test
-bun run test # not `bun test`
+bun run typecheck
+```
+
+### Coding Guidelines
 
-# run test (watch mode)
-bun run test:watch
+See [Implementation Guide](./docs/guides.md) for detailed implementation guidelines.
+
+## Testing
+
+### Run Tests
+
+```sh
+# Run all tests
+bun run test
+
+# Watch mode
+bun run test:w
 ```
 
-### Type Check
+### Testing Strategy
+
+- **Unit Test**: Test Use Cases and Repositories
+- **Integration Test**: Test Plugins and Routes
+
+Tests use Vitest and Cloudflare Workers Simulator.
+
+See [Implementation Guide - Testing Strategy](./docs/guides.md#テスト戦略) for details.
+
+## Database
+
+### Migrations
 
 ```sh
-bun type-check
+# Generate migration files
+bun run db:gen
+
+# Apply migrations (local)
+bun run db:mig
 ```
 
-### Database
+### Drizzle Studio
+
+GUI tool for database management.
 
 ```sh
-# generate migration files
-db:gen
+# Open local DB
+bun run db:std
 
-# migration
-db:mig
+# Open remote DB (production)
+bun run db:std:remote
+```
 
-# start Drizzle studio(local)
-db:std
+Opens `https://local.drizzle.studio` in your browser.
 
-# start Drizzle studio(remote)
-db:std:remote
+## Deployment
+
+### Build
+
+```sh
+# Build (dry-run)
+bun run build
 ```
 
-### Other
+### Deploy
 
-See `scripts` field in [`package.json`](https://github.com/koutyuke/mona-ca/blob/main/apps/api/package.json)
+```sh
+# Deploy to Cloudflare Workers
+wrangler deploy
+
+# Deploy to production
+wrangler deploy --env production
+```