swallowkit 0.1.0-alpha.1 → 0.1.0-beta.1

package/README.md

@@ -1,563 +1,690 @@
-# SwallowKit (暫定版)
+# SwallowKit
 
-Azure Static Web Apps + Cosmos DB 専用フレームワーク
+A type-safe, schema-driven development toolkit for Next.js applications on Azure, featuring seamless Zod schema sharing between frontend, backend, and Cosmos DB.
 
-> **注意**: これは暫定版のドキュメントです。API や機能は今後変更される可能性があります。
+SwallowKit enables developers to build full-stack Next.js applications with external Azure Functions backends while maintaining end-to-end type safety through shared Zod schemas. Deploy your Next.js app to Azure Static Web Apps using standalone mode, and connect to independent Azure Functions for backend operations—all with consistent type definitions and validation.
 
-## 🚀 特徴
+> **Note**: This project is in active development. APIs may change in future versions.
 
-- **Cosmos DB 標準搭載**: Cosmos DB をデフォルトデータベースとして採用
-- **React Hooks ベース**: `useServerFn` / `callServerFn` でサーバー関数を簡単に呼び出し
-- **型安全**: TypeScript による完全な型安全性
-- **自動セットアップ**: 開発環境起動時に Cosmos DB を自動セットアップ
-- **Azure 最適化**: Azure Static Web Apps + Azure Functions v4 に最適化
-- **開発者体験**: シンプルなコマンドで開発開始
+## 🚀 Features
 
-## 📋 前提条件
+- **Zod Schema Sharing**: Share type-safe schemas across frontend, backend, and database layers
+- **Type-Safe Cosmos DB**: Built-in Cosmos DB integration with automatic validation
+- **Next.js Standalone Deployment**: Deploy to Azure Static Web Apps with standalone mode
+- **External Backend Support**: Connect to independent Azure Functions backends
+- **Repository Pattern**: Simple, type-safe data access with BaseModel and SchemaRepository
+- **Full TypeScript**: End-to-end type safety from client to database
+- **Azure Optimized**: Designed specifically for Azure Static Web Apps + Azure Functions + Cosmos DB
+- **Developer Experience**: Simple CLI commands for development and deployment
+
+## 📋 Prerequisites
 
 - Node.js 22.x
-- Azure Cosmos DB Emulator (ローカル開発用)
-  - Windows: [公式サイト](https://aka.ms/cosmosdb-emulator)からインストール
+- Azure Cosmos DB Emulator (for local development)
+  - Windows: Install from [official site](https://aka.ms/cosmosdb-emulator)
   - Docker: `docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator`
 
-## 📦 インストール
+## 📦 Installation
 
 ```bash
-npm install swallowkit
+npm install swallowkit next react react-dom zod
 ```
 
-## 🛠️ クイックスタート
+SwallowKit requires Next.js 14+ and Zod as peer dependencies.
+
+## 🛠️ Quick Start
 
-### 1. プロジェクトの初期化
+### 1. Initialize SwallowKit Project
 
 ```bash
-npx swallowkit init my-todo-app
-cd my-todo-app
+npx swallowkit init my-app
+cd my-app
 npm install
 ```
 
-これにより以下が生成されます:
-- `src/` - React アプリケーション (Vite + React + TypeScript)
-- `src/serverFns.ts` - サーバー関数の型定義 (クライアント側スタブ)
-- `swallowkit.config.json` - SwallowKit 設定ファイル
+This creates a complete full-stack project with:
+- Next.js app with App Router, TypeScript, and Tailwind CSS
+- Azure Functions project with HTTP triggers
+- BFF (Backend For Frontend) API routes
+- Example Todo app with Cosmos DB integration
+- Greet function demonstrating BFF → Azure Functions pattern
 
-### 2. Cosmos DB Emulator の起動
+### 2. Install Azure Functions Core Tools
+
+To run Azure Functions locally, install the Azure Functions Core Tools:
 
 ```bash
-# Windowsの場合: スタートメニューから起動
-# Dockerの場合:
-docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator
+npm install -g azure-functions-core-tools@4
 ```
 
-### 3. 開発環境の起動
-
+Or via chocolatey (Windows):
 ```bash
-npx swallowkit dev
+choco install azure-functions-core-tools
 ```
 
-このコマンドは:
-1. Cosmos DB Emulator の起動確認
-2. Cosmos DB のデータベース・コンテナの自動作成 (冪等性あり)
-3. Azure Functions API の自動ビルド
-4. Vite 開発サーバーの起動
-5. SWA CLI による統合環境の起動
+### 3. Start Development Environment
 
-開発サーバーが起動したら、`http://localhost:4280` でアプリにアクセスできます。
+The init command creates two projects:
+- **Next.js app** (frontend + BFF API routes)
+- **Azure Functions** (backend services in `functions/` directory)
 
-## 📝 サーバー関数の実装
+Start both servers with a single command:
 
-### クライアント側の型定義 (`src/serverFns.ts`)
+```bash
+npx swallowkit dev
+```
 
-```typescript
-// クライアント側のスタブ - ブラウザでは実行されない
-interface Todo {
-  id: string;
-  text: string;
-  completed: boolean;
-}
+This will:
+- ✅ Check and setup Cosmos DB Emulator
+- ✅ Start Azure Functions (automatically installs dependencies if needed)
+- ✅ Start Next.js development server
 
-export async function getTodos(): Promise<Todo[]> {
-  throw new Error("This is a server function and should be called via useServerFn");
-}
+The demo app will be available at:
+- Next.js: http://localhost:3000
+- Azure Functions: http://localhost:7071
 
-export async function addTodo({ text }: { text: string }): Promise<Todo> {
-  throw new Error("This is a server function and should be called via useServerFn");
-}
+**Options:**
+```bash
+# Customize ports
+npx swallowkit dev --port 3001 --functions-port 7072
 
-export async function deleteTodo({ id }: { id: string }): Promise<{ success: boolean }> {
-  throw new Error("This is a server function and should be called via useServerFn");
-}
+# Skip Azure Functions (Next.js only)
+npx swallowkit dev --no-functions
 
-export async function toggleTodo({ id }: { id: string }): Promise<Todo | null> {
-  throw new Error("This is a server function and should be called via useServerFn");
-}
+# Open browser automatically
+npx swallowkit dev --open
+
+# Verbose output
+npx swallowkit dev --verbose
 ```
 
-### API の生成
+### 4. Project Structure
 
-```bash
-npx swallowkit generate
+```
+my-app/
+├── app/                      # Next.js App Router
+│   ├── api/                  # BFF API Routes
+│   │   └── greet/            # Example: Calls Azure Functions
+│   │       └── route.ts
+│   └── page.tsx              # Homepage with demos
+├── components/               # React Components
+│   ├── AddTodoForm.tsx       # Todo form with Zod validation
+│   ├── TodoItem.tsx          # Todo item component
+│   └── GreetingDemo.tsx      # BFF → Functions demo
+├── lib/
+│   ├── database/             # Cosmos DB client & repository
+│   │   ├── base-model.ts     # BaseModel class
+│   │   ├── client.ts         # DatabaseClient
+│   │   └── repository.ts     # SchemaRepository
+│   ├── models/               # Zod schemas + models
+│   │   └── todo.ts           # Todo schema & model
+│   └── server/               # Server actions
+│       └── todos.ts          # Todo CRUD operations
+├── functions/                # Azure Functions Project
+│   ├── src/
+│   │   └── functions/
+│   │       └── greet.ts      # Example HTTP trigger
+│   ├── host.json
+│   ├── local.settings.json
+│   └── package.json
+├── .env.local                # Environment variables
+├── swallowkit.config.js      # SwallowKit configuration
+└── staticwebapp.config.json  # Azure SWA config
 ```
 
-これにより `api/` ディレクトリに以下が生成されます:
-- `api/src/shared/server-functions.ts` - Cosmos DB を使った実装
-- `api/src/functions/rpc.ts` - RPC エンドポイント (`/api/_swallowkit`)
-- Azure Functions v4 の設定ファイル
-
-**重要**: `server-functions.ts` は自動生成されますが、**ビジネスロジックを実装するファイル**です。
-初回生成後はテンプレートをカスタマイズして使用してください。
+### 5. Define Shared Zod Schemas
 
-### サーバー側の実装例 (`api/src/shared/server-functions.ts`)
+Create type-safe schemas that will be used across your entire stack:
 
 ```typescript
-import { CosmosClient } from '@azure/cosmos';
-
-// Cosmos DB クライアントの初期化
-const endpoint = process.env.COSMOS_ENDPOINT || 'http://localhost:8081';
-const key = process.env.COSMOS_KEY || 'C2y6yDjf5/R+...'; // Emulator key
-const client = new CosmosClient({ endpoint, key });
+// lib/schemas/todo.ts
+import { z } from 'zod';
+
+export const TodoSchema = z.object({
+  id: z.string(),
+  text: z.string().min(1, 'Todo text is required'),
+  completed: z.boolean().default(false),
+  createdAt: z.string().default(() => new Date().toISOString()),
+});
 
-const database = client.database('swallowkit-db');
-const container = database.container('todos');
+export type Todo = z.infer<typeof TodoSchema>;
+```
 
-interface Todo {
-  id: string;
-  text: string;
-  completed: boolean;
-}
+### 5. Define Shared Zod Schemas
 
-export async function getTodos(): Promise<Todo[]> {
-  const { resources } = await container.items.query('SELECT * FROM c').fetchAll();
-  return resources as Todo[];
-}
+Create type-safe schemas that will be used across your entire stack:
 
-export async function addTodo({ text }: { text: string }): Promise<Todo> {
-  const newTodo: Todo = {
-    id: Date.now().toString(),
-    text,
-    completed: false,
-  };
-  const { resource } = await container.items.create(newTodo);
-  return resource as Todo;
-}
+```typescript
+// lib/models/todo.ts
+import { z } from 'zod';
+import { BaseModel } from '@/lib/database/base-model';
+
+export const todoSchema = z.object({
+  id: z.string(),
+  text: z.string().min(1, 'Todo text is required').max(200),
+  completed: z.boolean().default(false),
+  createdAt: z.string().default(() => new Date().toISOString()),
+});
 
-export async function deleteTodo({ id }: { id: string }): Promise<{ success: boolean }> {
-  await container.item(id, id).delete();
-  return { success: true };
-}
+export type TodoType = z.infer<typeof todoSchema>;
 
-export async function toggleTodo({ id }: { id: string }): Promise<Todo | null> {
-  const { resource: todo } = await container.item(id, id).read<Todo>();
-  if (todo) {
-    todo.completed = !todo.completed;
-    const { resource } = await container.item(id, id).replace(todo);
-    return resource as Todo;
+export class Todo extends BaseModel<TodoType> {
+  constructor() {
+    super('AppDatabase', 'Todos', todoSchema);
   }
-  return null;
 }
 ```
 
-## 🎯 React での使用
+### 6. Use BFF Pattern for Azure Functions
 
-### クエリ用: `useServerFn`
+Next.js API routes act as a BFF (Backend For Frontend) layer that calls Azure Functions:
 
-データ取得など、状態管理が必要な操作に使用:
-
-```tsx
-import { useServerFn } from "swallowkit";
-import { getTodos } from "./serverFns";
+```typescript
+// app/api/greet/route.ts
+import { NextRequest, NextResponse } from 'next/server';
 
-function TodoList() {
-  const { data: todos, loading, error, refetch } = useServerFn(getTodos, []);
+const FUNCTIONS_BASE_URL = process.env.FUNCTIONS_BASE_URL || 'http://localhost:7071';
 
-  if (loading) return <div>読み込み中...</div>;
-  if (error) return <div>エラー: {error.message}</div>;
+export async function GET(request: NextRequest) {
+  const { searchParams } = new URL(request.url);
+  const name = searchParams.get('name') || 'World';
 
-  return (
-    <div>
-      <ul>
-        {todos?.map((todo) => (
-          <li key={todo.id}>{todo.text}</li>
-        ))}
-      </ul>
-      <button onClick={refetch}>再読み込み</button>
-    </div>
-  );
+  // Call Azure Functions backend
+  const response = await fetch(`${FUNCTIONS_BASE_URL}/api/greet?name=${encodeURIComponent(name)}`);
+  const data = await response.json();
+  
+  return NextResponse.json(data);
 }
 ```
 
-### ミューテーション用: `callServerFn`
-
-追加・更新・削除など、状態管理が不要な操作に使用:
+```typescript
+// functions/src/functions/greet.ts
+import { app, HttpRequest, HttpResponseInit, InvocationContext } from '@azure/functions';
+import { z } from 'zod';
 
-```tsx
-import { useServerFn, callServerFn } from "swallowkit";
-import { getTodos, addTodo, deleteTodo, toggleTodo } from "./serverFns";
+const greetRequestSchema = z.object({
+  name: z.string().min(1).max(50),
+});
 
-function TodoApp() {
-  const [newTodoText, setNewTodoText] = useState("");
-  const { data: todos, loading, error, refetch } = useServerFn(getTodos, []);
+export async function greet(request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> {
+  const name = request.query.get('name') || 'World';
+  const result = greetRequestSchema.safeParse({ name });
+  
+  if (!result.success) {
+    return { status: 400, jsonBody: { error: result.error.errors[0].message } };
+  }
 
-  const handleAddTodo = async () => {
-    if (!newTodoText.trim()) return;
-    
-    await callServerFn(addTodo, { text: newTodoText });
-    setNewTodoText("");
-    refetch(); // クエリを再実行して最新データを取得
+  return {
+    status: 200,
+    jsonBody: {
+      message: `Hello, ${result.data.name}! This message is from Azure Functions.`,
+      timestamp: new Date().toISOString()
+    }
   };
+}
 
-  const handleToggleTodo = async (id: string) => {
-    await callServerFn(toggleTodo, { id });
-    refetch();
-  };
+app.http('greet', {
+  methods: ['GET', 'POST'],
+  authLevel: 'anonymous',
+  handler: greet
+});
+```
 
-  const handleDeleteTodo = async (id: string) => {
-    await callServerFn(deleteTodo, { id });
-    refetch();
-  };
+### 7. Use Schemas in Client Components
 
-  // ... レンダリング
-}
-```
+```typescript
+// components/AddTodoForm.tsx
+'use client'
 
-## 📚 API リファレンス
+import { useState } from 'react';
+import { addTodo } from '@/lib/server/todos';
+import { todoSchema } from '@/lib/models/todo';
 
-### `useServerFn<TResult>(serverFn, args, options?)`
+export function AddTodoForm() {
+  const [text, setText] = useState('');
 
-**パラメータ:**
-- `serverFn`: サーバー関数
-- `args`: 関数の引数の配列
-- `options?`: オプション設定
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    
+    // Client-side validation with Zod
+    const result = todoSchema.pick({ text: true }).safeParse({ text });
+    if (!result.success) {
+      alert(result.error.errors[0].message);
+      return;
+    }
+
+    await addTodo(text);
+    setText('');
+  };
 
-**戻り値:**
-```typescript
-{
-  data: TResult | null;
-  loading: boolean;
-  error: Error | null;
-  refetch: () => Promise<void>;
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={text} onChange={(e) => setText(e.target.value)} />
+      <button type="submit">Add Todo</button>
+    </form>
+  );
 }
 ```
 
-**使用例:**
-```typescript
-const { data, loading, error, refetch } = useServerFn(getTodos, []);
-```
-
-### `callServerFn<TArgs, TResult>(serverFn, ...args)`
+### 8. Develop and Deploy
 
-**パラメータ:**
-- `serverFn`: サーバー関数
-- `...args`: 関数の引数
+```bash
+# Start Next.js + Azure Functions + Cosmos DB with one command
+npx swallowkit dev
 
-**戻り値:**
-- `Promise<TResult>`: サーバー関数の実行結果
+# Build for production
+npx swallowkit build
 
-**使用例:**
-```typescript
-const result = await callServerFn(addTodo, { text: "新しいTodo" });
+# Deploy to Azure
+npx swallowkit deploy --swa-name my-app --resource-group my-rg
 ```
 
-## 🔧 CLI コマンド
+## 🏗️ Architecture
 
-### `swallowkit init <project-name>`
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Next.js App                          │
+│  ┌──────────────┐      ┌──────────────────────────┐    │
+│  │  Frontend    │      │  BFF API Routes          │    │
+│  │  Components  │─────▶│  /api/*                  │    │
+│  │  (Client)    │      │  (Next.js API Routes)    │    │
+│  └──────────────┘      └──────────┬───────────────┘    │
+│                                   │                      │
+│                                   │ HTTP                 │
+└───────────────────────────────────┼──────────────────────┘
+                                    │
+                    ┌───────────────▼─────────────────┐
+                    │   Azure Functions (External)    │
+                    │   - HTTP Triggers               │
+                    │   - Business Logic              │
+                    │   - Zod Validation              │
+                    └───────────────┬─────────────────┘
+                                    │
+                    ┌───────────────▼─────────────────┐
+                    │      Azure Cosmos DB            │
+                    │   - NoSQL Database              │
+                    │   - Schema Validation           │
+                    └─────────────────────────────────┘
+```
 
-新しい SwallowKit プロジェクトを作成します。
+**Key Patterns:**
+- **BFF (Backend For Frontend)**: Next.js API routes proxy requests to Azure Functions
+- **Shared Schemas**: Zod schemas used in frontend, BFF, Functions, and database
+- **Type Safety**: End-to-end TypeScript types derived from Zod schemas
+- **Standalone Deployment**: Next.js deployed as standalone to Azure Static Web Apps
+- **External Backend**: Azure Functions deployed independently
 
-```bash
-npx swallowkit init my-app
-```
+### Development & Deployment Flow
 
-### `swallowkit dev`
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     Development                              │
+├─────────────────────────────────────────────────────────────┤
+│  Next.js App (localhost:3000)                               │
+│    ├─ Frontend Components                                    │
+│    ├─ BFF API Routes (/api/*)                               │
+│    └─ Server Actions (Cosmos DB)                            │
+│                                                               │
+│  Azure Functions (localhost:7071)                           │
+│    └─ HTTP Triggers (greet, etc.)                           │
+│                                                               │
+│  Cosmos DB Emulator (localhost:8081)                        │
+└─────────────────────────────────────────────────────────────┘
 
-統合開発環境を起動します:
-- Cosmos DB の自動セットアップ
-- Azure Functions の自動ビルド
-- Vite + SWA CLI の統合サーバー起動
+                        ↓ swallowkit build
 
-```bash
-npx swallowkit dev
+┌─────────────────────────────────────────────────────────────┐
+│                     Production (Azure)                       │
+├─────────────────────────────────────────────────────────────┤
+│  Azure Static Web Apps                                       │
+│    └─ Next.js (standalone mode)                             │
+│         ├─ Server Components (SSR)                           │
+│         ├─ Client Components                                 │
+│         └─ BFF API Routes                                    │
+│                                                               │
+│  Azure Functions (separate deployment)                      │
+│    └─ Backend API (CRUD, business logic)                    │
+│                                                               │
+│  Azure Cosmos DB                                             │
+│    └─ Data storage with Zod validation                      │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-**オプション:**
-- `--port <port>`: SWA CLI のポート (デフォルト: 4280)
-- `--api-port <port>`: Azure Functions のポート (デフォルト: 7071)
-- `--host <host>`: ホスト名 (デフォルト: localhost)
-- `--open`: ブラウザを自動で開く
+### Why This Approach?
 
-### `swallowkit generate`
+**Problem**: Managing type consistency across frontend, backend, and database is error-prone and time-consuming.
 
-`src/serverFns.ts` から Azure Functions API を生成します。
+**Solution**: SwallowKit provides a unified Zod schema layer that ensures type safety and validation across your entire stack:
 
-```bash
-npx swallowkit generate
+```
+Zod Schema (Single Source of Truth)
+    ├─ Frontend: Client-side validation
+    ├─ Next.js: Server component validation
+    ├─ Backend: Azure Functions validation
+    └─ Database: Cosmos DB document validation
 ```
 
-**オプション:**
-- `--output <dir>`: 出力ディレクトリ (デフォルト: ./api)
-- `--force`: 既存ファイルを上書き
+## 🎯 Core Feature: Zod Schema Sharing
 
-### `swallowkit setup`
+### Why Zod Schema Sharing?
 
-開発環境の依存関係をチェックします:
-- Azure CLI
-- Azure Static Web Apps CLI
-- Cosmos DB Emulator
+1. **Single Source of Truth**: Define your data schema once with Zod
+2. **Frontend Validation**: Use the same schema for client-side form validation
+3. **Backend Validation**: Automatically validate inputs in Server Actions and API routes
+4. **Database Schema**: Type-safe Cosmos DB operations with runtime validation
+5. **No Code Duplication**: Share schemas between client, server, and database
 
-```bash
-npx swallowkit setup
+### Basic Usage
+
+```typescript
+// lib/schemas/user.ts - Shared schema definition
+import { z } from 'zod';
+
+export const UserSchema = z.object({
+  id: z.string(),
+  name: z.string().min(1),
+  email: z.string().email(),
+  createdAt: z.string().default(() => new Date().toISOString()),
+});
+
+export type User = z.infer<typeof UserSchema>;
 ```
 
-## 🔧 設定ファイル
+```typescript
+// lib/server/users.ts - Server-side repository
+import { createRepository } from 'swallowkit';
+import { UserSchema } from '../schemas/user';
 
-## 🔧 設定ファイル
+const userRepo = createRepository('users', UserSchema);
 
-### `swallowkit.config.json`
+export async function getUsers() {
+  return userRepo.findAll(); // Type-safe, validated
+}
 
-```json
-{
-  "database": {
-    "type": "cosmos",
-    "endpoint": "http://localhost:8081",
-    "key": "C2y6yDjf5/R+...",
-    "databaseName": "swallowkit-db"
-  },
-  "api": {
-    "endpoint": "/api/_swallowkit"
-  },
-  "functions": {
-    "outputDir": "api"
-  }
+export async function createUser(data: { name: string; email: string }) {
+  return userRepo.create({
+    id: crypto.randomUUID(),
+    ...data,
+  }); // Validated by Zod before saving to Cosmos DB
 }
 ```
 
-**プロパティ:**
-- `database.type`: データベースタイプ (現在は `"cosmos"` のみ)
-- `database.endpoint`: Cosmos DB エンドポイント
-- `database.key`: Cosmos DB アクセスキー
-- `database.databaseName`: データベース名
-- `api.endpoint`: RPC エンドポイントのパス
-- `functions.outputDir`: Azure Functions の出力ディレクトリ
-
-### 環境変数 (`api/local.settings.json`)
-
-```json
-{
-  "IsEncrypted": false,
-  "Values": {
-    "FUNCTIONS_WORKER_RUNTIME": "node",
-    "FUNCTIONS_WORKER_RUNTIME_VERSION": "~22",
-    "AzureWebJobsStorage": "",
-    "COSMOS_ENDPOINT": "http://localhost:8081",
-    "COSMOS_KEY": "C2y6yDjf5/R+ob0N8A7Cgv30VRDJIWEHLM+4QDU5DE2nQ9nDuVTqobD4b8mGGyPMbIZnqyMsEcaGQy67XIw/Jw=="
-  },
-  "Host": {
-    "CORS": "*",
-    "LocalHttpPort": 7071
+```typescript
+// app/actions.ts - Server Actions with validation
+'use server'
+
+import { UserSchema } from '@/lib/schemas/user';
+import { createUser } from '@/lib/server/users';
+import { revalidatePath } from 'next/cache';
+
+export async function createUserAction(formData: FormData) {
+  // Validate input using the same schema
+  const result = UserSchema.pick({ name: true, email: true }).safeParse({
+    name: formData.get('name'),
+    email: formData.get('email'),
+  });
+  
+  if (!result.success) {
+    return { error: result.error.message };
   }
+  
+  await createUser(result.data);
+  revalidatePath('/users');
 }
 ```
 
-## 🏗️ アーキテクチャ
-
-### クライアント・サーバー分離
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ クライアント (Browser)                                        │
-│                                                              │
-│  src/App.tsx                                                 │
-│    ↓ import                                                  │
-│  src/serverFns.ts (型定義スタブ)                              │
-│    ↓ useServerFn / callServerFn                             │
-│  swallowkit (hooks/useServerFn.ts)                          │
-│    ↓ POST /api/_swallowkit                                  │
-└──────────────────────────────────────────────────────────────┘
-                              │
-                              │ HTTP Request
-                              ↓
-┌─────────────────────────────────────────────────────────────┐
-│ サーバー (Azure Functions v4)                                │
-│                                                              │
-│  api/src/functions/rpc.ts                                   │
-│    ↓ import                                                  │
-│  api/src/shared/server-functions.ts (Cosmos DB実装)         │
-│    ↓ @azure/cosmos                                          │
-│  Cosmos DB                                                   │
-└─────────────────────────────────────────────────────────────┘
+```typescript
+// components/UserForm.tsx - Client-side validation
+'use client'
+
+import { UserSchema } from '@/lib/schemas/user';
+import { createUserAction } from '@/app/actions';
+import { useState } from 'react';
+
+export function UserForm() {
+  const [error, setError] = useState('');
+  
+  const handleSubmit = async (formData: FormData) => {
+    // Client-side validation using the same schema
+    const result = UserSchema.pick({ name: true, email: true }).safeParse({
+      name: formData.get('name'),
+      email: formData.get('email'),
+    });
+    
+    if (!result.success) {
+      setError(result.error.errors[0].message);
+      return;
+    }
+    
+    setError('');
+    await createUserAction(formData);
+  };
+  
+  return (
+    <form action={handleSubmit}>
+      <input name="name" required />
+      <input name="email" type="email" required />
+      {error && <p className="error">{error}</p>}
+      <button>Create User</button>
+    </form>
+  );
+}
 ```
 
-### データフロー
+## 🔧 Database Integration
 
-1. **クエリ (useServerFn)**
-   - コンポーネントマウント時に自動実行
-   - ローディング状態を管理
-   - データをキャッシュ
-   - `refetch()` で再実行可能
+### Repository API
 
-2. **ミューテーション (callServerFn)**
-   - イベントハンドラから明示的に呼び出し
-   - 状態管理なし
-   - 完了後に `refetch()` を呼び出してクエリを更新
+```typescript
+import { createRepository } from 'swallowkit';
+import { z } from 'zod';
 
-### Cosmos DB 自動セットアップ
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
 
-`swallowkit dev` コマンド実行時:
+const userRepo = createRepository('users', UserSchema);
 
-```typescript
-// dev コマンドの処理フロー
-1. Cosmos DB Emulator の起動確認
-2. CosmosClient で接続
-3. database.createIfNotExists('swallowkit-db')
-4. container.createIfNotExists('todos', {
-     partitionKey: {
-       paths: ['/id'],
-       kind: PartitionKeyKind.Hash
-     }
-   })
-5. Azure Functions API のビルド
-6. Vite + SWA CLI の起動
-```
+// Create (with validation)
+await userRepo.create({
+  id: '1',
+  name: 'John',
+  email: 'john@example.com'
+});
 
-## 📁 プロジェクト構造
+// Find by ID
+const user = await userRepo.findById('1');
 
-```
-my-app/
-├── src/
-│   ├── App.tsx                    # React アプリケーション
-│   ├── serverFns.ts               # サーバー関数の型定義 (クライアント側)
-│   ├── index.tsx                  # エントリーポイント
-│   └── index.css                  # スタイル
-├── api/                           # Azure Functions (自動生成)
-│   ├── src/
-│   │   ├── functions/
-│   │   │   ├── rpc.ts            # RPC エンドポイント
-│   │   │   └── crud.ts           # CRUD エンドポイント (未使用)
-│   │   └── shared/
-│   │       └── server-functions.ts # サーバー側実装 (Cosmos DB)
-│   ├── host.json
-│   ├── local.settings.json
-│   ├── tsconfig.json
-│   └── package.json
-├── swallowkit.config.json        # SwallowKit 設定
-├── staticwebapp.config.json      # Azure SWA 設定
-├── package.json
-└── vite.config.ts
-```
+// Find all
+const users = await userRepo.findAll();
 
-## 🚨 重要な注意事項
+// Update (with validation)
+await userRepo.update({
+  id: '1',
+  name: 'John Doe',
+  email: 'john@example.com'
+});
 
-### 1. サーバー関数の戻り値
+// Delete
+await userRepo.delete('1');
 
-**❌ NG: `Promise<void>`**
-```typescript
-export async function deleteTodo({ id }: { id: string }): Promise<void> {
-  await container.item(id, id).delete();
-  // JSON レスポンスがないため RPC 呼び出しが失敗
-}
+// Custom queries
+const activeUsers = await userRepo.findWhere('c.isActive = true');
 ```
 
-**✅ OK: 必ず値を返す**
+### Advanced: Custom Repository
+
 ```typescript
-export async function deleteTodo({ id }: { id: string }): Promise<{ success: boolean }> {
-  await container.item(id, id).delete();
-  return { success: true }; // JSON レスポンスを返す
+import { SchemaRepository } from 'swallowkit';
+import { z } from 'zod';
+
+const UserSchema = z.object({
+  id: z.string(),
+  email: z.string().email(),
+  isActive: z.boolean(),
+});
+
+class UserRepository extends SchemaRepository<z.infer<typeof UserSchema>> {
+  constructor() {
+    super('users', UserSchema);
+  }
+  
+  async findActiveUsers() {
+    return this.findWhere('c.isActive = true');
+  }
+  
+  async findByEmail(email: string) {
+    const users = await this.findWhere('c.email = @email', [email]);
+    return users[0] || null;
+  }
 }
+
+export const userRepo = new UserRepository();
 ```
 
-### 2. パーティションキーの指定
+### Cosmos DB Client
 
-Cosmos DB Emulator では `kind: PartitionKeyKind.Hash` の明示が必須:
+For advanced use cases, you can use the Cosmos DB client directly:
 
 ```typescript
-await database.containers.createIfNotExists({
-  id: 'todos',
-  partitionKey: {
-    paths: ['/id'],
-    kind: PartitionKeyKind.Hash // 必須！
-  }
-});
-```
+import { getDatabaseClient } from 'swallowkit';
 
-### 3. クライアント・サーバーの分離
+const client = getDatabaseClient();
 
-- `src/serverFns.ts` - **クライアント側の型定義のみ** (throw Error)
-- `api/src/shared/server-functions.ts` - **サーバー側の実装** (Cosmos DB アクセス)
+// Direct operations
+await client.createDocument('users', { id: '1', name: 'John' });
+await client.getDocument('users', '1');
+await client.updateDocument('users', { id: '1', name: 'John Doe' });
+await client.deleteDocument('users', '1');
+await client.query('users', 'SELECT * FROM c WHERE c.isActive = true');
+```
 
-この2つは **別ファイル** です。混同しないでください。
+## 📚 CLI Commands
 
-### 4. generateコマンドの動作
+### `swallowkit init [project-name]`
 
-`swallowkit generate` は:
-- `src/serverFns.ts` がクライアントスタブ (throw Error を含む) の場合
-  → デフォルトの Cosmos DB テンプレートを使用
-- `src/serverFns.ts` が既に実装を含む場合
-  → その実装を `api/src/shared/server-functions.ts` にコピー
+Initialize a new SwallowKit project with Next.js template.
 
-## 🐛 トラブルシューティング
+```bash
+npx swallowkit init my-app
+```
 
-### Cosmos DB Emulator が起動しない
+### `swallowkit dev`
+
+Start development server with Cosmos DB setup and Next.js.
 
-**Windows:**
 ```bash
-# スタートメニューから "Azure Cosmos DB Emulator" を起動
-# または、サービスから起動
+npx swallowkit dev
 ```
 
-**Docker:**
+Options:
+- `-p, --port <port>`: Next.js port (default: `3000`)
+- `--host <host>`: Host name (default: `localhost`)
+- `--open`: Open browser automatically
+- `--verbose`: Show detailed logs
+
+### `swallowkit build`
+
+Build the Next.js app for production using standalone mode.
+
 ```bash
-docker run -p 8081:8081 mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator
+npx swallowkit build
 ```
 
-### パーティションキーエラー
+Options:
+- `--output <dir>`: Output directory (default: `dist`)
 
-`PartitionKeyKind.Hash` を指定してください:
+### `swallowkit deploy`
 
-```typescript
-import { CosmosClient, PartitionKeyKind } from '@azure/cosmos';
+Deploy to Azure Static Web Apps.
 
-await database.containers.createIfNotExists({
-  id: 'your-container',
-  partitionKey: {
-    paths: ['/id'],
-    kind: PartitionKeyKind.Hash
-  }
-});
+```bash
+npx swallowkit deploy --swa-name my-app --resource-group my-rg
 ```
 
-### API が古い実装のまま
+Options:
+- `--swa-name <name>`: Azure Static Web Apps resource name (required)
+- `--resource-group <name>`: Azure resource group (required)
+- `--location <location>`: Azure region (default: `japaneast`)
+- `--skip-build`: Skip build step
 
-`generate --force` で強制的に再生成:
+### `swallowkit setup`
+
+Install required tools (Azure CLI, SWA CLI, Cosmos DB Emulator).
 
 ```bash
-npx swallowkit generate --force
-cd api
-npm run build
+npx swallowkit setup
 ```
 
-## 🎯 今後の予定 (TODO)
+## 🔧 Configuration
+
+Create `swallowkit.config.js` in your project root:
+
+```javascript
+module.exports = {
+  database: {
+    connectionString: process.env.COSMOS_DB_CONNECTION_STRING,
+    databaseName: 'MyAppDB',
+  },
+  api: {
+    endpoint: '/api/_swallowkit',
+    cors: {
+      origin: ['http://localhost:3000'],
+      credentials: true,
+    },
+  },
+};
+```
 
-- [ ] Zod スキーマ統合
-- [ ] 認証・認可機能
-- [ ] ファイルアップロード機能
-- [ ] リアルタイム通信 (SignalR)
-- [ ] デプロイコマンド (`swallowkit deploy`)
-- [ ] テストユーティリティ
-- [ ] 本番環境用の設定管理
+## 🚀 Connecting to External Azure Functions
 
-## 🤝 コントリビューション
+SwallowKit is designed to work with external Azure Functions backends. Your Next.js app acts as a BFF (Backend for Frontend), while independent Azure Functions handle business logic and data operations.
 
-このプロジェクトは開発中です。フィードバックや提案を歓迎します！
+### Backend Connection Pattern
 
-## 📄 ライセンス
+```typescript
+// lib/api/backend.ts
+const BACKEND_URL = process.env.BACKEND_API_URL || 'http://localhost:7071';
 
-MIT
+export async function fetchFromBackend<T>(endpoint: string, options?: RequestInit): Promise<T> {
+  const response = await fetch(`${BACKEND_URL}${endpoint}`, options);
+  if (!response.ok) {
+    throw new Error(`Backend API error: ${response.statusText}`);
+  }
+  return response.json();
+}
+```
+
+```typescript
+// app/api/todos/route.ts - Next.js API Route (BFF)
+import { fetchFromBackend } from '@/lib/api/backend';
+import { TodoSchema } from '@/lib/schemas/todo';
+
+export async function GET() {
+  const todos = await fetchFromBackend('/api/todos');
+  
+  // Validate response using shared schema
+  const validated = z.array(TodoSchema).parse(todos);
+  
+  return Response.json(validated);
+}
+```
+
+## 🤝 Contributing
+
+This project is in active development. Feedback and suggestions are welcome!
 
-## 🔗 関連リンク
+## 📄 License
+
+MIT
 
-- [Azure Static Web Apps](https://azure.microsoft.com/ja-jp/services/app-service/static/)
-- [Azure Functions](https://azure.microsoft.com/ja-jp/services/functions/)
-- [Azure Cosmos DB](https://azure.microsoft.com/ja-jp/services/cosmos-db/)
-- [React](https://reactjs.org/)
-- [Vite](https://vitejs.dev/)
+## 🔗 Related Links
 
+- [Azure Static Web Apps](https://azure.microsoft.com/services/app-service/static/)
+- [Azure Functions](https://azure.microsoft.com/services/functions/)
+- [Azure Cosmos DB](https://azure.microsoft.com/services/cosmos-db/)
+- [Next.js](https://nextjs.org/)
+- [Zod](https://zod.dev/)
+- [TypeScript](https://www.typescriptlang.org/)