@mind-fold/open-flow 0.1.17 → 0.2.2

package/dist/templates/markdown/structure/backend/database-guidelines.md.txt

@@ -0,0 +1,247 @@
+# Database Guidelines
+
+> ORM patterns, batch operations, and query optimization
+
+---
+
+## Core Rules
+
+1. **No await in loops** - Use batch operations
+2. **Use transactions** - For multi-table operations
+3. **Define relations** - Enable relational queries
+4. **Handle timestamps** - Consistent format across layers
+
+---
+
+## No Await in Loops (N+1 Problem)
+
+The N+1 query problem is one of the most common performance issues.
+
+### Problem
+
+```typescript
+// ❌ BAD: N+1 queries (1 + N database calls)
+const users = await db.select().from(users).all();
+for (const user of users) {
+  const posts = await db.select().from(posts).where(eq(posts.userId, user.id)).all();
+  user.posts = posts;
+}
+```
+
+### Solution 1: Relational Queries
+
+```typescript
+// ✅ GOOD: Single query with JOIN
+const usersWithPosts = await db.query.users.findMany({
+  with: {
+    posts: true,
+  },
+});
+```
+
+### Solution 2: Batch Lookup with inArray
+
+```typescript
+// ✅ GOOD: Two queries total (1 for users, 1 for all posts)
+import { inArray } from 'drizzle-orm';
+
+const users = await db.select().from(users).all();
+const userIds = users.map(u => u.id);
+
+const allPosts = await db
+  .select()
+  .from(posts)
+  .where(inArray(posts.userId, userIds))
+  .all();
+
+// Group in memory
+const postsByUser = groupBy(allPosts, 'userId');
+```
+
+### Solution 3: Promise.all (Use Carefully)
+
+```typescript
+// ⚠️ OK for small N, but watch connection limits
+const results = await Promise.all(
+  ids.slice(0, 10).map(id => 
+    db.query.users.findFirst({ where: eq(users.id, id) })
+  )
+);
+```
+
+---
+
+## Batch Operations
+
+### Bulk Insert
+
+```typescript
+// Insert multiple rows in one statement
+await db.insert(users).values([
+  { id: '1', email: 'a@example.com', name: 'Alice' },
+  { id: '2', email: 'b@example.com', name: 'Bob' },
+]).run();
+```
+
+### Upsert (Insert or Update)
+
+```typescript
+await db.insert(users)
+  .values(userData)
+  .onConflictDoUpdate({
+    target: users.id,
+    set: {
+      name: userData.name,
+      updatedAt: new Date(),
+    },
+  })
+  .run();
+```
+
+### Bulk Update with inArray
+
+```typescript
+// Update multiple rows matching condition
+await db.update(users)
+  .set({ status: 'archived' })
+  .where(inArray(users.id, idsToArchive))
+  .run();
+```
+
+---
+
+## Transactions
+
+Use transactions for operations that must be atomic.
+
+```typescript
+// All-or-nothing: either all succeed or all rollback
+const result = db.transaction((tx) => {
+  // Create user
+  const user = tx.insert(users).values({
+    id: userId,
+    email: input.email,
+  }).returning().get();
+
+  // Create default settings
+  tx.insert(userSettings).values({
+    userId: user.id,
+    theme: 'light',
+  }).run();
+
+  // Create audit log
+  tx.insert(auditLogs).values({
+    action: 'user_created',
+    entityId: user.id,
+  }).run();
+
+  return user;
+});
+```
+
+---
+
+## Timestamp Handling
+
+### Use Milliseconds
+
+JavaScript `Date.now()` returns milliseconds. Store timestamps consistently.
+
+```typescript
+// Schema definition
+export const users = sqliteTable('users', {
+  // ...
+  createdAt: integer('created_at', { mode: 'timestamp_ms' })
+    .notNull()
+    .default(sql`(unixepoch() * 1000)`),
+  updatedAt: integer('updated_at', { mode: 'timestamp_ms' })
+    .notNull()
+    .default(sql`(unixepoch() * 1000)`)
+    .$onUpdate(() => new Date()),
+});
+```
+
+### Common Pitfall
+
+```typescript
+// ❌ BAD: Mixing seconds and milliseconds
+const timestamp = Math.floor(Date.now() / 1000);  // Seconds
+new Date(timestamp);  // Wrong! Expects milliseconds
+
+// ✅ GOOD: Consistent milliseconds
+const timestamp = Date.now();  // Milliseconds
+new Date(timestamp);  // Correct
+```
+
+---
+
+## Query Patterns
+
+### Pagination
+
+```typescript
+async function listUsers(page: number, pageSize: number) {
+  const offset = (page - 1) * pageSize;
+  
+  const [users, countResult] = await Promise.all([
+    db.select()
+      .from(users)
+      .limit(pageSize)
+      .offset(offset)
+      .all(),
+    db.select({ count: count() })
+      .from(users)
+      .get(),
+  ]);
+
+  return {
+    data: users,
+    total: countResult?.count ?? 0,
+    page,
+    pageSize,
+  };
+}
+```
+
+### Soft Delete
+
+```typescript
+// Schema with soft delete
+export const users = sqliteTable('users', {
+  // ...
+  isDeleted: integer('is_deleted', { mode: 'boolean' }).notNull().default(false),
+  deletedAt: integer('deleted_at', { mode: 'timestamp_ms' }),
+});
+
+// Query excludes deleted by default
+const activeUsers = await db
+  .select()
+  .from(users)
+  .where(eq(users.isDeleted, false))
+  .all();
+
+// Soft delete
+await db.update(users)
+  .set({ 
+    isDeleted: true, 
+    deletedAt: new Date() 
+  })
+  .where(eq(users.id, userId))
+  .run();
+```
+
+---
+
+## Summary
+
+| Rule | Description |
+|------|-------------|
+| No await in loops | Use `with:`, `inArray`, or batch queries |
+| Use transactions | For atomic multi-table operations |
+| Millisecond timestamps | Match JavaScript Date behavior |
+| Soft delete | Use `isDeleted` flag, not hard delete |
+| Pagination | Always limit results for list endpoints |
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/backend/directory-structure.md.txt

@@ -0,0 +1,153 @@
+# Directory Structure
+
+> Module organization and file layout for backend development
+
+---
+
+## Standard Layout
+
+```
+server/
+├── db/                      # Database layer
+│   ├── client.ts            # Database client initialization
+│   ├── schema.ts            # Table definitions
+│   └── migrations/          # Migration files
+│
+├── lib/                     # Shared utilities
+│   ├── logger.ts            # Logger setup
+│   ├── errors.ts            # Custom error classes
+│   └── utils.ts             # Helper functions
+│
+├── middleware/              # Middleware
+│   ├── auth.ts              # Authentication
+│   ├── error-handler.ts     # Error handling
+│   └── request-context.ts   # Request context
+│
+├── routes/                  # API routes (domain-driven)
+│   └── {domain}/
+│       ├── types.ts         # Zod schemas + TypeScript types
+│       ├── router.ts        # Route definitions
+│       ├── procedures/      # One file per endpoint
+│       │   ├── list.ts
+│       │   ├── get.ts
+│       │   ├── create.ts
+│       │   ├── update.ts
+│       │   └── delete.ts
+│       └── lib/             # Domain-specific logic
+│
+└── types.ts                 # Shared types (AppContext, etc.)
+```
+
+---
+
+## Module Structure
+
+Each domain module follows this pattern:
+
+### types.ts - Schema Definitions
+
+```typescript
+import { z } from 'zod';
+
+// Input schemas
+export const createUserInput = z.object({
+  email: z.string().email(),
+  name: z.string().min(1),
+});
+
+export const updateUserInput = z.object({
+  name: z.string().min(1).optional(),
+});
+
+// Output schemas
+export const userOutput = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string(),
+  createdAt: z.date(),
+});
+
+// Infer types from schemas
+export type CreateUserInput = z.infer<typeof createUserInput>;
+export type UpdateUserInput = z.infer<typeof updateUserInput>;
+export type UserOutput = z.infer<typeof userOutput>;
+```
+
+### router.ts - Route Definitions
+
+```typescript
+import { Hono } from 'hono';
+import { zValidator } from '@hono/zod-validator';
+import { createUserInput, updateUserInput } from './types';
+import { createUser } from './procedures/create';
+import { getUser } from './procedures/get';
+import { listUsers } from './procedures/list';
+
+const app = new Hono();
+
+app.get('/', listUsers);
+app.get('/:id', getUser);
+app.post('/', zValidator('json', createUserInput), createUser);
+app.patch('/:id', zValidator('json', updateUserInput), updateUser);
+
+export default app;
+```
+
+### procedures/*.ts - Business Logic
+
+```typescript
+// procedures/create.ts
+import type { Context } from 'hono';
+import { db } from '@/db/client';
+import { users } from '@/db/schema';
+import type { CreateUserInput } from '../types';
+
+export async function createUser(c: Context) {
+  const input = c.req.valid('json') as CreateUserInput;
+  const logger = c.get('logger');
+
+  logger.info('creating_user', { email: input.email });
+
+  const user = await db.insert(users).values({
+    id: generateId(),
+    email: input.email,
+    name: input.name,
+  }).returning().get();
+
+  return c.json(user);
+}
+```
+
+---
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Files | kebab-case | `user-service.ts` |
+| Directories | kebab-case | `user-management/` |
+| Types | PascalCase | `UserOutput` |
+| Functions | camelCase | `createUser` |
+| Constants | SCREAMING_SNAKE | `MAX_RETRY_COUNT` |
+
+---
+
+## Best Practices
+
+### DO
+
+- Keep procedures focused on single responsibility
+- Put shared logic in `lib/` directory
+- Use descriptive file names (`create-with-team.ts` not `create2.ts`)
+- Group related functionality in domain modules
+
+### DON'T
+
+- Mix multiple domains in one module
+- Put business logic in router files
+- Create deeply nested directory structures
+- Use generic names like `utils.ts` in domain modules
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/structure/backend/error-handling.md.txt

@@ -0,0 +1,257 @@
+# Error Handling
+
+> Error types, handling strategies, and user-facing messages
+
+---
+
+## Error Types
+
+### Application Errors
+
+Define custom error classes for different error categories:
+
+```typescript
+// lib/errors.ts
+export class AppError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode: number = 500,
+    public details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = 'AppError';
+  }
+}
+
+export class NotFoundError extends AppError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'NOT_FOUND', 404, details);
+    this.name = 'NotFoundError';
+  }
+}
+
+export class ValidationError extends AppError {
+  constructor(message: string, details?: Record<string, unknown>) {
+    super(message, 'VALIDATION_ERROR', 400, details);
+    this.name = 'ValidationError';
+  }
+}
+
+export class UnauthorizedError extends AppError {
+  constructor(message: string = 'Unauthorized') {
+    super(message, 'UNAUTHORIZED', 401);
+    this.name = 'UnauthorizedError';
+  }
+}
+
+export class ForbiddenError extends AppError {
+  constructor(message: string = 'Forbidden') {
+    super(message, 'FORBIDDEN', 403);
+    this.name = 'ForbiddenError';
+  }
+}
+```
+
+---
+
+## Error Handling Middleware
+
+```typescript
+// middleware/error-handler.ts
+import type { Context, Next } from 'hono';
+import { AppError } from '@/lib/errors';
+
+export async function errorHandler(c: Context, next: Next) {
+  try {
+    await next();
+  } catch (error) {
+    const logger = c.get('logger');
+
+    if (error instanceof AppError) {
+      logger.warn('app_error', {
+        code: error.code,
+        message: error.message,
+        details: error.details,
+      });
+
+      return c.json({
+        error: {
+          code: error.code,
+          message: error.message,
+          details: error.details,
+        },
+      }, error.statusCode);
+    }
+
+    // Unexpected errors
+    logger.error('unhandled_error', error);
+
+    return c.json({
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: 'An unexpected error occurred',
+      },
+    }, 500);
+  }
+}
+```
+
+---
+
+## Error Handling Patterns
+
+### Route Handlers
+
+```typescript
+app.get('/users/:id', async (c) => {
+  const userId = c.req.param('id');
+  
+  const user = await db.query.users.findFirst({
+    where: eq(users.id, userId),
+  });
+  
+  if (!user) {
+    throw new NotFoundError(`User ${userId} not found`);
+  }
+  
+  return c.json(user);
+});
+```
+
+### Service Layer
+
+```typescript
+async function transferFunds(fromId: string, toId: string, amount: number) {
+  const fromAccount = await getAccount(fromId);
+  if (!fromAccount) {
+    throw new NotFoundError('Source account not found');
+  }
+  
+  if (fromAccount.balance < amount) {
+    throw new ValidationError('Insufficient funds', {
+      available: fromAccount.balance,
+      requested: amount,
+    });
+  }
+  
+  // Proceed with transfer...
+}
+```
+
+### External API Calls
+
+```typescript
+async function fetchExternalData(id: string) {
+  try {
+    const response = await fetch(`https://api.example.com/data/${id}`);
+    
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new NotFoundError('External resource not found');
+      }
+      throw new AppError(
+        'External API error',
+        'EXTERNAL_API_ERROR',
+        502,
+        { status: response.status }
+      );
+    }
+    
+    return await response.json();
+  } catch (error) {
+    if (error instanceof AppError) {
+      throw error;
+    }
+    throw new AppError(
+      'Failed to fetch external data',
+      'EXTERNAL_API_ERROR',
+      502,
+      { originalError: String(error) }
+    );
+  }
+}
+```
+
+---
+
+## Validation Errors
+
+### Zod Integration
+
+```typescript
+import { z, ZodError } from 'zod';
+
+app.post('/users', async (c) => {
+  try {
+    const input = createUserSchema.parse(await c.req.json());
+    // Process valid input...
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw new ValidationError('Invalid input', {
+        errors: error.errors.map(e => ({
+          path: e.path.join('.'),
+          message: e.message,
+        })),
+      });
+    }
+    throw error;
+  }
+});
+```
+
+### Response Format
+
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid input",
+    "details": {
+      "errors": [
+        { "path": "email", "message": "Invalid email format" },
+        { "path": "age", "message": "Must be a positive number" }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Error Codes
+
+Maintain a consistent set of error codes:
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `NOT_FOUND` | 404 | Resource not found |
+| `VALIDATION_ERROR` | 400 | Invalid input |
+| `UNAUTHORIZED` | 401 | Authentication required |
+| `FORBIDDEN` | 403 | Permission denied |
+| `CONFLICT` | 409 | Resource conflict (duplicate) |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `INTERNAL_ERROR` | 500 | Unexpected server error |
+| `EXTERNAL_API_ERROR` | 502 | External service failure |
+
+---
+
+## Best Practices
+
+### DO
+
+- Use specific error types for different scenarios
+- Include helpful details for debugging
+- Log errors with context
+- Return consistent error response format
+
+### DON'T
+
+- Expose internal error details to clients
+- Use generic error messages
+- Swallow errors silently
+- Return stack traces in production
+
+---
+
+**Language**: All documentation must be written in **English**.