create-fullstack-scaffold 0.1.0

package/template/CLAUDE.md

@@ -0,0 +1,296 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Todo Application Template - A full-stack React + Hono application demonstrating best practices for monorepo-style architecture with single-port development.
+
+## Commands
+
+```bash
+npm run dev          # Start Vite dev server on port 3010 with Hono backend
+npm run build        # Production build
+npm run preview      # Preview production build
+npm run test         # Run all Vitest tests
+npm run test:unit    # Run unit tests only
+npm run test:integration  # Run integration tests only
+npm run lint         # Run ESLint
+npm run format       # Run Prettier format
+npm run typecheck    # Run TypeScript type check
+```
+
+## Architecture Overview
+
+**Monorepo-style structure** with client/server separation and shared types:
+
+```
+src/
+├── client/          # React frontend
+│   ├── components/  # UI components
+│   ├── stores/      # Zustand state management
+│   ├── services/    # API clients (apiClient)
+│   ├── hooks/       # Custom hooks
+│   ├── pages/      # Page components
+│   └── App.tsx
+├── server/          # Hono backend
+│   ├── module-todos/     # Todo module
+│   ├── module-chat/      # WebSocket chat module
+│   ├── module-notifications/ # SSE notifications module
+│   ├── core/             # Core services (runtime, realtime)
+│   ├── middleware/       # Express middleware
+│   ├── test-utils/       # Test utilities
+│   └── entries/          # Entry points (node.ts, cloudflare.ts)
+└── shared/              # Shared types
+    ├── core/             # Framework layer (ws-client, sse-client, api-schemas)
+    ├── modules/          # Business layer (chat, todos, notifications schemas)
+    └── schemas/          # Unified exports
+```
+
+**Path Aliases** (configured in vite.config.ts and tsconfig.json):
+
+- `@shared/*` → src/shared/\*
+- `@client/*` → src/client/\*
+- `@server/*` → src/server/\*
+
+## Key Technical Concepts
+
+### Single-Port Development
+
+Uses "@hono/vite-dev-server" to run both frontend and backend on port 3010:
+
+- No CORS issues in development
+- Type safety across the boundary
+- Simplified developer experience
+
+### Hono RPC
+
+Type-safe API calls from frontend to backend:
+
+```typescript
+import { apiClient } from '@client/services/apiClient'
+
+// HTTP API
+const response = await apiClient.api.todos.$get()
+const result = await response.json()
+
+// WebSocket
+const ws = apiClient.api.chat.ws.$ws()
+const result = await ws.call('echo', { message: 'hello' })
+
+// SSE
+const conn = await apiClient.api.notifications.stream.$sse()
+conn.on('notification', n => console.log(n))
+```
+
+### Real-time Features
+
+| Feature   | Method              | Type Safety | Testing          |
+| --------- | ------------------- | ----------- | ---------------- |
+| HTTP API  | `$get()`, `$post()` | ✅          | No server needed |
+| WebSocket | `$ws()`             | ✅          | Requires server  |
+| SSE       | `$sse()`            | ✅          | No server needed |
+
+### Module Pattern
+
+Backend organized by feature modules:
+
+```
+module-{feature}/
+├── routes/         # API endpoints (Hono RPC)
+├── services/      # Business logic
+└── __tests__/     # Unit tests
+```
+
+### Framework Layer vs Business Layer
+
+The project has clear separation between framework and business layers:
+
+**Framework Layer** (`src/shared/core/`):
+
+- Generic, reusable infrastructure code
+- Examples: `ws-client.ts`, `sse-client.ts`, `api-schemas.ts`
+- Should not be modified by business code directly
+
+**Business Layer** (`src/shared/modules/`):
+
+- Business-specific schemas and protocols
+- Examples: `chat/`, `todos/`, `notifications/`
+- Organized by feature modules
+
+### Layer Boundary Rules (ESLint)
+
+The project enforces layer boundaries with `layer-boundary` rule:
+
+- Business code cannot directly modify framework layer code
+- Business code importing framework code needs `@framework-import` comment
+- Framework code modification needs `@framework-allow-modification` comment
+
+### State Management with Zustand
+
+Global application state in `src/client/stores/`:
+
+- **Minimal Re-renders**: Use precise selector hooks
+- **Selector Pattern**: `const todos = useTodoStore((state) => state.todos)`
+- **Action Selectors**: Stable function references
+
+### Testing Strategy
+
+- **Unit Tests**: `__tests__/*.test.ts` (jsdom for client, node for server)
+- **Integration Tests**: `src/server/__tests__/integration/*.test.ts`
+- **E2E Tests**: `tests/e2e/*.spec.ts` (Playwright)
+- **WebSocket Tests**: Require real server (`createTestServer`)
+- **SSE Tests**: No server needed (`$sse()` works with `app.fetch()`)
+
+## Important Conventions
+
+### Import Path Aliases
+
+Always use path aliases instead of relative imports:
+
+```typescript
+import { Todo } from '@shared/schemas'
+import { useTodoStore } from '@client/stores/todoStore'
+```
+
+### Environment Variables
+
+Required variables (see `.env.example`):
+
+```bash
+API_BASE_URL=http://localhost:3010
+```
+
+### Module Manifest System
+
+Each module under `src/server/module-*/` has a `module.ts` manifest declaring:
+
+- Dependencies on other modules
+- Route registrations (client, admin, standalone)
+- Shared schemas, DB schemas, client/admin pages
+- Middleware it provides
+- Whether it has SSE or WebSocket
+
+#### Module Categories
+
+| Category      | Modules                          |
+| ------------- | -------------------------------- |
+| core          | todos                            |
+| communication | chat, notifications              |
+| business      | order, ticket, dispute, content  |
+| system        | permission, admin, captcha, file |
+
+#### Dependency Graph
+
+```
+todos ──── (standalone)
+chat ──── (standalone)
+notifications ── (standalone)
+file ──── (standalone)
+captcha ── (standalone)
+permission ── (standalone, foundational)
+admin ──→ permission + notifications
+order ──→ permission
+ticket ──→ permission
+dispute ──→ permission
+content ──→ permission
+```
+
+#### Validation
+
+```bash
+npm run validate:modules
+```
+
+#### Template Presets
+
+Defined in `modules.config.ts`:
+
+- `fullstack-admin` — All modules (default)
+- `todo-app` — todos + chat + notifications
+- `minimal` — todos only
+
+### Module Creation
+
+To add a new feature module:
+
+1. Create `src/server/module-{feature}/` with routes, services, tests
+2. Create shared schemas in `src/shared/modules/{feature}/`
+3. Add `module.ts` manifest in the module directory
+4. Register routes in `route-registry.ts`
+5. Add DB schemas to `server/db/schema/`
+6. Add client store if needed
+7. Add integration tests
+8. Run `npm run validate:modules` to verify
+
+### API Route Pattern
+
+Use Hono RPC with chain syntax:
+
+```typescript
+app.openapi(listRoute, async c => {
+  const todos = await todoService.listTodos()
+  return c.json({ success: true, data: todos })
+})
+```
+
+### WebSocket Pattern
+
+Use `$ws()` method for type-safe WebSocket:
+
+```typescript
+// Server: Define protocol in src/shared/modules/chat/
+import { ChatProtocolSchema } from '@shared/modules/chat'
+
+// Client: Use $ws()
+const ws = apiClient.api.chat.ws.$ws()
+const result = await ws.call('echo', { message: 'hello' })
+ws.on('notification', n => console.log(n))
+```
+
+### SSE Pattern
+
+Use `$sse()` method for type-safe SSE:
+
+```typescript
+// Server: Define protocol in src/shared/modules/notifications/
+import { AppSSEProtocolSchema } from '@shared/schemas'
+
+// Client: Use $sse()
+const conn = await apiClient.api.notifications.stream.$sse()
+conn.on('notification', n => console.log(n))
+conn.on('ping', p => console.log(p.timestamp))
+```
+
+### SSE Broadcast Pattern
+
+When creating notifications, broadcast to all connected SSE clients:
+
+```typescript
+// In service layer - use createNotificationAndBroadcast
+import { createNotificationAndBroadcast } from '@server/module-notifications/services/notification-service'
+
+// The service automatically handles broadcasting via realtime middleware
+const notification = await createNotificationAndBroadcast(input)
+```
+
+## Project Rules
+
+See `.claude/rules/` for detailed development constraints:
+
+- `project-rules.md` - Environment & constants management
+- `client-component-rules.md` - React component patterns
+- `client-service-rules.md` - Service layer patterns
+- `zustand-rules.md` - Zustand store patterns
+- `websocket-rules.md` - WebSocket development patterns
+- `sse-rules.md` - SSE development patterns
+- `shared-types-rules.md` - Shared types organization
+- `layer-boundary-rules.md` - Framework/Business layer separation
+- `testing-standards.md` - Testing conventions
+- `hono-testing-best-practices.md` - Hono testing patterns
+
+## Documentation
+
+- `README.md` - User-facing feature overview
+- `DESIGN.md` - Technical architecture
+- `QUICKSTART.md` - Quick start guide

package/template/DESIGN.md

@@ -0,0 +1,260 @@
+# Design Document
+
+## Architecture Overview
+
+This template implements a **monorepo-style architecture** with client/server separation while maintaining a single development port.
+
+### Key Design Decisions
+
+#### 1. Single-Port Development
+
+- **Why**: Simplifies local development, no CORS issues
+- **How**: `@hono/vite-dev-server` serves both React and Hono
+- **Benefit**: Developer experience, type safety across boundary
+
+#### 2. Hono RPC
+
+- **Why**: End-to-end type safety between frontend and backend
+- **How**: Shared types exported from `src/server/index.ts`
+- **Benefit**: Compile-time error detection, better DX
+
+#### 3. Modular Backend
+
+- **Why**: Scalability, clear separation of concerns
+- **How**: Feature-based modules (`module-todos/`, `module-chat/`, etc.)
+- **Benefit**: Easy to add new features, maintainable codebase
+
+#### 4. Zustand for State
+
+- **Why**: Minimal boilerplate, no context provider hell
+- **How**: Global store with selector hooks
+- **Benefit**: Performance (minimal re-renders), simplicity
+
+#### 5. Real-time Support
+
+- **Why**: Modern apps need real-time features
+- **How**: WebSocket (`$ws()`) and SSE (`$sse()`) with type safety
+- **Benefit**: Type-safe real-time communication
+
+## Module Pattern
+
+Each backend module follows this structure:
+
+```
+module-{feature}/
+├── routes/         # API endpoints (Hono RPC)
+├── services/       # Business logic
+└── __tests__/      # Unit tests
+```
+
+### Example: Adding a New Module
+
+1. Create directory: `src/server/module-features/`
+2. Add routes: `src/server/module-features/routes/features-routes.ts`
+3. Add service: `src/server/module-features/services/feature-service.ts`
+4. Add tests: `src/server/module-features/__tests__/feature-service.test.ts`
+5. Register in `src/server/app.ts`:
+
+```typescript
+import { featureRoutes } from './module-features/routes/features-routes'
+app.route('/api', featureRoutes)
+```
+
+**参考现有模块**:
+
+- `src/server/module-todos/` - Todo 模块
+- `src/server/module-admin/` - Admin 模块
+
+## Real-time Architecture
+
+### WebSocket (`$ws()`)
+
+**Type Safety Flow**:
+
+```
+Server: WSProtocol Schema
+    ↓
+@hono/zod-openapi: TypedResponse
+    ↓
+Hono: ToSchemaOutput
+    ↓
+Client: $ws() → WSClient<Protocol>
+    ↓
+Developer: ws.call('method', params)  // Type-safe!
+```
+
+**Testing**: Requires real server (`createTestServer`)
+
+### SSE (`$sse()`)
+
+**Type Safety Flow**:
+
+```
+Server: SSEProtocol Schema
+    ↓
+@hono/zod-openapi: TypedResponse
+    ↓
+Hono: ToSchemaOutput
+    ↓
+Client: $sse() → SSEClient<Protocol>
+    ↓
+Developer: conn.on('event', handler)  // Type-safe!
+```
+
+**Testing**: No server needed, works with `app.fetch()`
+
+### Comparison
+
+| Feature   | WebSocket                  | SSE                              |
+| --------- | -------------------------- | -------------------------------- |
+| Direction | Bidirectional              | Unidirectional (server → client) |
+| Methods   | `call()`, `emit()`, `on()` | `on()`, `onStatusChange()`       |
+| Protocol  | `WSProtocol`               | `SSEProtocol`                    |
+| Testing   | Requires server            | No server needed                 |
+| Use Case  | Chat, gaming               | Notifications, feeds             |
+
+## Testing Strategy
+
+### Unit Tests
+
+- Location: `src/**/__tests__/*.test.ts`
+- Framework: Vitest
+- Environment: `jsdom` (client), `node` (server)
+- Coverage: Services, stores, utilities
+
+### Integration Tests
+
+- Location: `src/server/integration/*.test.ts`
+- Framework: Vitest
+- Environment: `node`
+- Coverage: API endpoints
+
+### WebSocket Tests
+
+- Location: `src/server/module-chat/__tests__/*.test.ts`
+- Framework: Vitest
+- Environment: `node`
+- Requires: `createTestServer()`
+
+### SSE Tests
+
+- Location: `src/server/module-notifications/__tests__/*.test.ts`
+- Framework: Vitest
+- Environment: `node`
+- Requires: No server needed
+
+### E2E Tests
+
+- Location: `tests/e2e/*.spec.ts`
+- Framework: Playwright
+- Environment: Browser
+- Coverage: User workflows
+
+## Type Safety Flow
+
+### HTTP API
+
+```
+┌─────────────────┐
+│  Server Routes  │ ──export──> AppType
+└─────────────────┘                          │
+                                             │
+┌─────────────────┐                          ▼
+│  RPC Client     │ <──import── AppType
+│  (Frontend)     │
+└─────────────────┘
+```
+
+### WebSocket
+
+```
+┌─────────────────┐
+│  WSProtocol     │ ──schema──> TypedResponse
+└─────────────────┘                          │
+                                             │
+┌─────────────────┐                          ▼
+│  $ws() Method   │ <──type inference──
+│  (Frontend)     │
+└─────────────────┘
+```
+
+### SSE
+
+```
+┌─────────────────┐
+│  SSEProtocol    │ ──schema──> TypedResponse
+└─────────────────┘                          │
+                                             │
+┌─────────────────┐                          ▼
+│  $sse() Method  │ <──type inference──
+│  (Frontend)     │
+└─────────────────┘
+```
+
+## Database Schema
+
+Using Drizzle ORM with SQLite:
+
+```typescript
+export const todos = sqliteTable('todos', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  title: text('title').notNull(),
+  description: text('description'),
+  status: text('status').notNull().default('pending'),
+  createdAt: integer('created_at', { mode: 'timestamp' }),
+  updatedAt: integer('updated_at', { mode: 'timestamp' }),
+})
+```
+
+## Performance Considerations
+
+### Frontend
+
+- **Selector Hooks**: Use precise selectors to minimize re-renders
+- **Code Splitting**: Lazy load routes/components
+- **Bundle Size**: Tree-shaking with Vite
+
+### Backend
+
+- **Connection Pooling**: Reuse database connections
+- **Query Optimization**: Index frequently queried columns
+- **Caching**: Consider Redis for production
+
+### Real-time
+
+- **WebSocket**: Connection pooling, message batching
+- **SSE**: Automatic reconnection, event buffering
+
+## Security Best Practices
+
+1. **Input Validation**: Zod schemas on all endpoints
+2. **SQL Injection**: Drizzle ORM parameterized queries
+3. **CORS**: Whitelist origins in production
+4. **Environment Variables**: Never commit `.env` files
+5. **Error Messages**: Don't leak sensitive info
+6. **WebSocket**: Validate all incoming messages
+7. **SSE**: Rate limiting on event streams
+
+## Migration Path
+
+### From Mock to Real Backend
+
+1. Set `USE_MOCK_SERVER = false` in `apiClient.ts`
+2. Configure production API base URL
+3. Deploy backend separately
+4. Update CORS configuration
+
+### From SQLite to PostgreSQL
+
+1. Update `drizzle.config.ts`
+2. Change `sqliteTable` to `pgTable`
+3. Update column types
+4. Run `drizzle-kit push`
+
+### Adding Real-time Features
+
+1. Define protocol schema (`WSProtocol` or `SSEProtocol`)
+2. Create route with schema
+3. Implement server-side logic
+4. Use `$ws()` or `$sse()` on client
+5. Add tests (with or without server)