@kood/claude-code 0.6.6 → 0.7.0

package/templates/tanstack-start/docs/architecture.md

@@ -18,9 +18,10 @@
 | **라우트** | Flat 파일 라우트 (`routes/users.tsx`) |
 | **Route Export** | `export const IndexRoute`, `const Route` (export 안함) |
 | **API** | `/api` 라우터 생성 (Server Functions 사용) |
-| **레이어** | Service Layer 건너뛰기, Routes에서 직접 DB 접근 |
+| **레이어** | Features 건너뛰기, Routes에서 직접 DB 접근 |
 | **검증** | Handler 내부 수동 검증, 인증 로직 분산 |
-| **Barrel Export** | `functions/index.ts` 생성 (Tree Shaking 실패, 서버 라이브러리 Client 오염) |
+| **Barrel Export** | `functions/index.ts` 생성 (Tree Shaking 실패) |
+| **폴더 구조** | `lib/db`, `lib/store` (→ `database/`, `stores/` 사용) |
 
 </forbidden>
 
@@ -32,9 +33,10 @@
 |------|------|
 | **라우트 구조** | 페이지마다 폴더 생성 (`routes/users/index.tsx`) |
 | **Route Export** | `export const Route = createFileRoute(...)` 필수 |
-| **계층 구조** | Routes → Server Functions → Services → Database |
+| **계층 구조** | Routes → Server Functions → Features → Database |
 | **Route Group** | 목록 → `(main)/`, 생성/편집 → 외부 |
 | **페이지 분리** | 100줄+ → `-components`, 200줄+ → `-sections` |
+| **컴포넌트 분리** | 로직 있는 컴포넌트 → `-components/-hooks/`로 훅 분리 |
 | **beforeLoad** | 인증 체크, Context 전달, 리다이렉트 |
 | **loader** | 데이터 로딩 (beforeLoad 완료 후 병렬 실행) |
 | **Server Fn** | `createServerFn` 기본 사용 |
@@ -58,17 +60,29 @@
 │  │  React Router  │───▶│ TanStack Query │───▶│    React UI   │  │
 │  │  (Navigation)  │◀───│   (Caching)    │◀───│  (Components) │  │
 │  └────────────────┘    └───────┬────────┘    └───────────────┘  │
+│  ┌─────────────────────────────┴─────────────────────────────┐  │
+│  │              State: TanStack Query + Zustand               │  │
+│  └───────────────────────────────────────────────────────────┘  │
 └────────────────────────────────┼─────────────────────────────────┘
                                  ▼
 ┌─────────────────────────────────────────────────────────────────┐
 │                    TanStack Start Server                         │
 │  ┌────────────────────────────────────────────────────────────┐ │
+│  │              Security: CSP | Rate Limit | CORS              │ │
+│  └────────────────────────────┬───────────────────────────────┘ │
+│  ┌────────────────────────────▼───────────────────────────────┐ │
 │  │                    Server Functions                         │ │
-│  │   routes/-functions/ → 페이지 전용 | functions/ → 글로벌   │ │
+│  │      routes/-functions/ (페이지) | functions/ (글로벌)      │ │
+│  └────────────────────────────┬───────────────────────────────┘ │
+│  ┌────────────────────────────▼───────────────────────────────┐ │
+│  │     Features (내부 도메인)  |  Services (외부 SDK)          │ │
+│  │     Prisma 쿼리, 스키마     |  Stripe, S3, SendGrid        │ │
+│  └────────────────────────────┬───────────────────────────────┘ │
+│  ┌────────────────────────────▼───────────────────────────────┐ │
+│  │         Caching: Redis (분산) | Query (로컬) | CDN          │ │
 │  └────────────────────────────┬───────────────────────────────┘ │
 │  ┌────────────────────────────▼───────────────────────────────┐ │
-│  │                    Services Layer                           │ │
-│  │   Zod Validation | Business Logic | Data Transformation    │ │
+│  │         Monitoring: Sentry (에러) | OpenTelemetry           │ │
 │  └────────────────────────────┬───────────────────────────────┘ │
 └───────────────────────────────┼──────────────────────────────────┘
                                 ▼
@@ -84,6 +98,61 @@
 
 ---
 
+<folder_structure>
+
+## Folder Structure
+
+```
+src/
+├── routes/           # 라우팅 (파일 기반)
+├── components/       # UI 컴포넌트
+│   ├── ui/          # shadcn/ui
+│   ├── layout/      # Header, Sidebar, Footer
+│   └── shared/      # 공용 컴포넌트
+├── features/         # 내부 도메인 (DB 레이어)
+│   └── <domain>/
+│       ├── schemas.ts
+│       ├── queries.ts
+│       └── mutations.ts
+├── services/         # 외부 SDK 연동
+│   ├── stripe/
+│   ├── sendgrid/
+│   ├── s3/
+│   └── openai/
+├── functions/        # 글로벌 Server Functions
+│   └── middlewares/
+├── database/         # Prisma Client
+├── stores/           # Zustand 스토어
+├── hooks/            # 글로벌 훅
+├── types/            # 전역 타입
+├── env/              # 환경 변수 검증 (t3-env)
+├── styles/           # CSS
+├── config/           # 설정
+│   ├── auth.ts
+│   ├── query-client.ts
+│   └── sentry.ts
+└── lib/              # 유틸리티
+    ├── utils/
+    ├── constants/
+    └── validators/
+```
+
+### 폴더 역할
+
+| 폴더 | 역할 | 예시 |
+|------|------|------|
+| **features/** | 내부 도메인, Prisma 쿼리 | users, projects, billing |
+| **services/** | 외부 SDK 래퍼 | Stripe, SendGrid, S3, OpenAI |
+| **functions/** | Server Functions | API 레이어 |
+| **database/** | Prisma Client | 싱글톤 인스턴스 |
+| **stores/** | Zustand 스토어 | 클라이언트 전역 상태 |
+| **config/** | 설정 파일 | auth, query-client, sentry |
+| **lib/** | 유틸리티 | utils, constants, validators |
+
+</folder_structure>
+
+---
+
 <route_export_rule>
 
 ## Route Export 규칙
@@ -91,8 +160,6 @@
 > ⚠️ **`export const Route` 필수**
 >
 > TanStack Router는 모든 라우트 파일에서 **정확히 `Route`라는 이름**으로 내보내야 합니다.
->
-> `tsr generate` 및 `tsr watch` 명령어가 자동으로 경로를 생성하고 업데이트합니다.
 
 | ❌ 금지 | ✅ 필수 |
 |--------|--------|
@@ -101,16 +168,6 @@
 | `export default createFileRoute(...)` | `export const Route = createFileRoute(...)` |
 
 ```typescript
-// ❌ 금지: export 없음
-const Route = createFileRoute('/users')({
-  component: UsersPage,
-})
-
-// ❌ 금지: 다른 이름
-export const UsersRoute = createFileRoute('/users')({
-  component: UsersPage,
-})
-
 // ✅ 필수: 정확히 'Route' 이름으로 export
 export const Route = createFileRoute('/users')({
   component: UsersPage,
@@ -129,10 +186,6 @@ export const Route = createFileRoute('/users')({
 
 > ⚠️ **페이지마다 폴더 생성 필수**
 >
-> 모든 페이지는 **반드시 폴더 구조**로 만들어야 합니다. Flat 파일 방식(`routes/users.tsx`)은 금지됩니다.
->
-> **이유:** -components/, -functions/, -hooks/ 등 페이지 전용 리소스를 체계적으로 관리하기 위함입니다.
->
 > | ❌ 금지 | ✅ 필수 |
 > |--------|--------|
 > | `routes/users.tsx` | `routes/users/index.tsx` |
@@ -143,117 +196,174 @@ routes/<route-name>/
 ├── (main)/                # route group (목록 페이지)
 │   ├── index.tsx          # 페이지 컴포넌트
 │   ├── -components/       # 페이지 전용 컴포넌트
-│   ├── -sections/         # UI 섹션 분리 (200줄+ 페이지)
-│   ├── -tabs/             # 탭 콘텐츠 분리
+│   ├── -sections/         # UI 섹션 분리 (200줄+)
 │   ├── -hooks/            # 페이지 전용 훅
 │   └── -utils/            # 상수, 헬퍼
-├── new/                   # 생성 페이지 (route group 외부)
+├── new/                   # 생성 페이지
 │   └── index.tsx
-├── route.tsx              # route 설정 (loader, beforeLoad)
+├── route.tsx              # 레이아웃 (loader, beforeLoad)
 └── -functions/            # 페이지 전용 서버 함수
 ```
 
-| 패턴 | 위치 | 용도 |
-|------|------|------|
-| **Route Group** | `(main)/` | 목록 페이지, URL에 미포함 |
-| **-components/** | 100-200줄 | 페이지 전용 컴포넌트 분리 |
-| **-sections/** | 200줄+ | 논리적 섹션 분리 |
-| **-tabs/** | 탭 UI | 탭 콘텐츠 분리 |
-| **route.tsx** | 레이아웃 | 하위 경로 공통 레이아웃 |
+| 패턴 | 용도 |
+|------|------|
+| **Route Group `()`** | URL 미포함, 레이아웃 공유 |
+| **-components/** | 페이지 전용 컴포넌트 (100줄+) |
+| **-sections/** | 논리적 섹션 분리 (200줄+) |
+| **route.tsx** | 하위 경로 공통 레이아웃 |
 
-#### Layout Routes 패턴
+#### Component + Hook 분리
 
-> ⚠️ **route.tsx로 레이아웃 구성**
->
-> `route.tsx`는 하위 경로의 공통 레이아웃 역할을 합니다.
-> `index.tsx`는 Route Group `()`으로 묶어야 합니다.
->
-> **필수:** `route.tsx`는 반드시 `component`를 export해야 합니다.
->
-> | ❌ 금지 | ✅ 필수 |
-> |--------|--------|
-> | `export const Route = createFileRoute(...)({})` | `export const Route = createFileRoute(...)({ component: ... })` |
+> 컴포넌트에 로직(서버 연동, 상태 관리)이 있으면 폴더로 묶고 훅 분리
 
 ```
-routes/
-├── (auth)/
-│   ├── route.tsx           # 레이아웃 (<Outlet />)
-│   ├── (main)/
-│   │   └── index.tsx       # /auth (목록/메인)
-│   ├── login/
-│   │   └── index.tsx       # /auth/login
-│   └── register/
-│       └── index.tsx       # /auth/register
+-components/
+├── user-card/
+│   ├── index.tsx              # UI만
+│   └── -hooks/
+│       └── use-user-card.ts   # 서버 연동, 상태 로직
+└── user-form/
+    ├── index.tsx              # UI만
+    └── -hooks/
+        └── use-user-form.ts   # 폼 로직, mutation
 ```
 
 ```typescript
-// ❌ 금지: component 없음
-export const Route = createFileRoute('/(auth)')({
-  beforeLoad: async () => ({ user: await getUser() }),
-})
+// -components/user-form/-hooks/use-user-form.ts
+export function useUserForm(userId?: string) {
+  const queryClient = useQueryClient()
+
+  const { data: user } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => getUser(userId!),
+    enabled: !!userId,
+  })
 
-// ✅ 필수: component 반드시 포함
-// routes/(auth)/route.tsx - 레이아웃
-export const Route = createFileRoute('/(auth)')({
-  component: () => (
-    <div className="auth-container">
-      <Outlet />
-    </div>
-  ),
-})
+  const mutation = useMutation({
+    mutationFn: userId ? updateUser : createUser,
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+  })
+
+  return { user, mutation, isLoading: mutation.isPending }
+}
+
+// -components/user-form/index.tsx
+export function UserForm({ userId }: Props) {
+  const { user, mutation, isLoading } = useUserForm(userId)
+
+  return (
+    <form onSubmit={(e) => mutation.mutate(formData)}>
+      {/* UI만 */}
+    </form>
+  )
+}
+```
+
+| 분리 기준 | 컴포넌트 (`index.tsx`) | 훅 (`-hooks/`) |
+|----------|----------------------|----------------|
+| **역할** | UI 렌더링 | 로직 처리 |
+| **내용** | JSX, 스타일 | useQuery, useMutation, 상태 |
 
-// routes/(auth)/(main)/index.tsx - 메인 페이지
-export const Route = createFileRoute('/(auth)/')({
-  component: AuthMainPage,
+### 2. Features Layer
+
+> 내부 도메인 로직, Prisma 쿼리
+
+```
+features/<domain>/
+├── schemas.ts          # Zod 스키마
+├── queries.ts          # TanStack Query 옵션
+└── mutations.ts        # useMutation 옵션
+```
+
+```typescript
+// features/users/schemas.ts
+export const createUserSchema = z.object({
+  email: z.email(),
+  name: z.string().min(1),
 })
 
-// routes/(auth)/login/index.tsx
-export const Route = createFileRoute('/(auth)/login')({
-  component: LoginPage,
+// features/users/queries.ts
+export const userQueryOptions = queryOptions({
+  queryKey: ['users'],
+  queryFn: getUsers,
+  staleTime: 5 * 60 * 1000,
 })
 ```
 
-### 2. Services Layer
+### 3. Services Layer
+
+> 외부 SDK 연동
 
 ```
-services/<domain>/
-├── index.ts            # 진입점 (re-export)
-├── schemas.ts          # Zod 스키마
-├── queries.ts          # GET 요청
-└── mutations.ts        # POST/PUT/PATCH
+services/<provider>/
+├── client.ts           # SDK 클라이언트
+├── types.ts            # 타입 정의
+└── utils.ts            # 헬퍼 함수
+```
+
+```typescript
+// services/stripe/client.ts
+import Stripe from 'stripe'
+
+export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)
+
+// services/stripe/utils.ts
+export async function createCheckoutSession(priceId: string) {
+  return stripe.checkout.sessions.create({
+    mode: 'subscription',
+    line_items: [{ price: priceId, quantity: 1 }],
+  })
+}
 ```
 
-### 3. Server Functions Layer
+### 4. Server Functions Layer
 
 ```
-functions/                    # 글로벌 (재사용)
-├── <function-name>.ts        # 파일당 하나
+functions/                    # 글로벌
+├── <function-name>.ts
 └── middlewares/
-    └── <middleware-name>.ts
+    ├── auth.ts
+    └── logging.ts
 
 routes/<route>/-functions/    # 페이지 전용
 └── <function-name>.ts
 ```
 
-> ⚠️ **`functions/index.ts` 생성 금지**
->
-> `functions/` 폴더에 `index.ts` (barrel export) 파일을 만들지 마세요.
->
-> **문제점:**
-> 1. **Tree Shaking 실패** - 번들러가 사용하지 않는 함수도 포함
-> 2. **Client 번들 오염** - `pg`, `prisma` 등 서버 전용 라이브러리가 클라이언트에 import되어 빌드 에러 발생
->
-> ```typescript
-> // ❌ functions/index.ts 만들지 말 것
-> export * from './get-users'
-> export * from './create-post'  // pg import → 클라이언트 빌드 실패
->
-> // ✅ 개별 파일에서 직접 import
-> import { getUsers } from '@/functions/get-users'
-> import { createPost } from '@/functions/create-post'
-> ```
+> ⚠️ **`functions/index.ts` 생성 금지** - Tree Shaking 실패, Client 번들 오염
+
+```typescript
+// ✅ 개별 파일에서 직접 import
+import { getUsers } from '@/functions/get-users'
+import { createPost } from '@/functions/create-post'
+```
+
+### 5. State Management Layer
 
-### 4. Database Layer
+| 상태 유형 | 도구 | 사용 |
+|----------|------|------|
+| **서버 상태** | TanStack Query | API 데이터, 캐싱 (80%) |
+| **클라이언트 상태** | Zustand | UI 상태, 설정 (20%) |
+
+```typescript
+// stores/app.ts
+import { create } from 'zustand'
+import { persist } from 'zustand/middleware'
+
+export const useAppStore = create(
+  persist(
+    (set) => ({
+      theme: 'dark' as 'light' | 'dark',
+      sidebarOpen: true,
+      setTheme: (theme) => set({ theme }),
+    }),
+    { name: 'app-store' }
+  )
+)
+```
+
+### 6. Database Layer
 
 ```typescript
 // database/prisma.ts
@@ -282,16 +392,7 @@ if (process.env.NODE_ENV !== 'production') {
 |------|-----------|--------|
 | **실행 순서** | 순차 (outermost → innermost) | 병렬 (beforeLoad 완료 후) |
 | **용도** | 인증, Context 전달, 리다이렉트 | 데이터 로딩 |
-| **블로킹** | 모든 loader 차단 | 다른 loader와 병렬 |
-| **성능 영향** | ⚠️ 높음 | ✅ 낮음 |
-
-```
-1. Parent beforeLoad (순차) ──┐
-2. Child beforeLoad (순차)  ──┼→ 완료 후
-3. All loaders (병렬) ────────┘
-```
-
-### 코드 패턴
+| **성능 영향** | ⚠️ 높음 (블로킹) | ✅ 낮음 (병렬) |
 
 ```typescript
 // ✅ beforeLoad: 인증 & Context
@@ -311,11 +412,6 @@ loader: async () => {
 }
 ```
 
-| ❌ 금지 | ✅ 권장 |
-|--------|--------|
-| beforeLoad에서 데이터 로딩 | loader에서 데이터 로딩 |
-| loader 차단 | 병렬 실행 |
-
 </route_lifecycle>
 
 ---
@@ -340,22 +436,14 @@ export const Route = createRootRouteWithContext<RouterContext>()({
   beforeLoad: async () => ({ user: await getUser() }),
 })
 
-// 2. 확장: Context 확장
+// 2. 확장
 beforeLoad: async ({ context }) => ({
   ...context,
   permissions: await getPermissions(context.user.id),
 })
 
-// 3. 사용: Component
+// 3. 사용
 const { user, permissions } = useRouteContext({ from: '/dashboard' })
-
-// 4. 사용: Loader
-loader: async ({ context }) => {
-  if (!context.permissions.includes('users:read')) {
-    throw new Error('Unauthorized')
-  }
-  return { users: await getUsers() }
-}
 ```
 
 </context_management>
@@ -369,17 +457,14 @@ loader: async ({ context }) => {
 ### Query Flow (읽기)
 
 ```
-Page → useQuery → Server Function → Prisma → Database
+Page → useQuery → Server Function → Features → Prisma → Database
           ↑
     TanStack Query (Cache)
 ```
 
 ```typescript
 // Page
-const { data } = useQuery({
-  queryKey: ['users'],
-  queryFn: getUsers,
-})
+const { data } = useQuery(userQueryOptions)
 
 // Server Function
 export const getUsers = createServerFn()
@@ -390,13 +475,9 @@ export const getUsers = createServerFn()
 ### Mutation Flow (쓰기)
 
 ```
-Form → useMutation → Server Function
-                          ↓
-                    inputValidator
-                          ↓
-                    Prisma → Database
-                          ↓
-                    invalidateQueries
+Form → useMutation → Server Function → inputValidator → Features → Database
+                                                             ↓
+                                                    invalidateQueries
 ```
 
 ```typescript
@@ -425,18 +506,16 @@ export const createUser = createServerFn({ method: 'POST' })
 
 ### Server Functions 타입
 
-| 타입 | 실행 위치 | 사용 시나리오 |
-|------|----------|-------------|
-| **createServerFn** | 서버 | DB 접근, 비밀키, 서버 로직 (기본) |
+| 타입 | 실행 위치 | 사용 |
+|------|----------|------|
+| **createServerFn** | 서버 | DB 접근, 비밀키 (기본) |
 | createClientOnlyFn | 클라이언트 | localStorage, window |
 | createIsomorphicFn | 양쪽 | 환경별 구현 |
 
-**기본 규칙**: 별도 요청 없으면 `createServerFn` 사용
-
 ### Middleware 패턴
 
 ```typescript
-// 1. authMiddleware
+// functions/middlewares/auth.ts
 export const authMiddleware = createMiddleware()
   .server(async ({ next, context }) => {
     const session = await getSession()
@@ -444,9 +523,19 @@ export const authMiddleware = createMiddleware()
     return next({ context: { ...context, user: session.user } })
   })
 
-// 2. 사용
+// functions/middlewares/logging.ts
+export const loggingMiddleware = createMiddleware()
+  .server(async ({ next }) => {
+    const start = Date.now()
+    const traceId = crypto.randomUUID()
+    const result = await next({ context: { traceId } })
+    console.log({ traceId, duration: Date.now() - start })
+    return result
+  })
+
+// 사용
 export const createPost = createServerFn({ method: 'POST' })
-  .middleware([authMiddleware])
+  .middleware([loggingMiddleware, authMiddleware])
   .inputValidator(createPostSchema)
   .handler(async ({ data, context }) => {
     return prisma.post.create({
@@ -482,27 +571,6 @@ export const Route = createRootRoute({
 export const Route = createFileRoute('/dashboard')({
   errorComponent: ({ error }) => <div>{error.message}</div>,
 })
-
-// Loader 에러
-loader: async () => {
-  try {
-    return { users: await getUsers() }
-  } catch (error) {
-    throw new Error('데이터 로딩 실패')
-  }
-}
-
-// Server Function 에러
-.handler(async ({ data }) => {
-  try {
-    return await prisma.user.create({ data })
-  } catch (error) {
-    if (error.code === 'P2002') {
-      throw new Error('이미 존재하는 이메일')
-    }
-    throw new Error('사용자 생성 실패')
-  }
-})
 ```
 
 </error_handling>
@@ -518,9 +586,12 @@ loader: async () => {
 | Framework | TanStack Start | latest |
 | Router | TanStack Router | latest |
 | Data | TanStack Query | latest |
+| State | Zustand | latest |
 | ORM | Prisma | 7.x |
 | Validation | Zod | 4.x |
 | Database | PostgreSQL | - |
-| UI | React 18+ | - |
+| Cache | Redis | - |
+| Monitoring | Sentry | latest |
+| UI | React 19+ | - |
 
 </tech_stack>