create-kuckit-app 0.1.1 → 0.2.0

package/templates/base/.claude/skills/kuckit/references/ARCHITECTURE.md

@@ -0,0 +1,388 @@
+# Kuckit Architecture Reference
+
+Quick reference for Clean Architecture layers and patterns in Kuckit.
+
+## Layer Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Interface Layer                                │
+│  ┌─────────────────────────────┐    ┌─────────────────────────────────┐ │
+│  │        apps/web             │    │         apps/server             │ │
+│  │  React + TanStack Router    │◄──►│  Express + oRPC + Better-Auth   │ │
+│  │     + sdk-react             │    │         + sdk                   │ │
+│  └─────────────────────────────┘    └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           SDK Layer (Module System)                      │
+│  ┌─────────────────────────────┐    ┌─────────────────────────────────┐ │
+│  │      packages/sdk           │    │     packages/sdk-react          │ │
+│  │  - DI Container (Awilix)    │    │  - Client Module Loader         │ │
+│  │  - Module Loader            │    │  - Route/Nav/Slot Registries    │ │
+│  │  - Core Services            │    │  - Context Providers            │ │
+│  │  - Lifecycle Hooks          │    │  - TanStack Router Integration  │ │
+│  └─────────────────────────────┘    └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Application Layer                                │
+│  ┌─────────────────────────────┐    ┌─────────────────────────────────┐ │
+│  │   packages/application      │    │        packages/api             │ │
+│  │  - Use Cases                │◄───│  - oRPC Procedures              │ │
+│  │  - Business Logic           │    │  - Request Context              │ │
+│  │  - Orchestration            │    │  - Validation                   │ │
+│  └─────────────────────────────┘    └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            Domain Layer                                  │
+│  ┌─────────────────────────────┐    ┌─────────────────────────────────┐ │
+│  │     packages/domain         │    │      packages/contracts         │ │
+│  │  - Business Entities        │    │  - DTOs                         │ │
+│  │  - Port Interfaces          │    │  - Zod Schemas                  │ │
+│  │  - Business Rules           │    │  - Validation                   │ │
+│  └─────────────────────────────┘    └─────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                        Infrastructure Layer                              │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐ │
+│  │ packages/infra  │  │  packages/db    │  │    packages/auth        │ │
+│  │ - Repositories  │  │ - Drizzle ORM   │  │ - Better-Auth Config    │ │
+│  │ - Adapters      │  │ - Migrations    │  │ - Session Management    │ │
+│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘ │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Dependency Rules
+
+### What Can Import What
+
+```
+                    ALLOWED IMPORTS
+                    ═══════════════
+
+┌─────────────┐
+│   domain    │◄─────────────────────────────────────┐
+│  (no deps)  │                                      │
+└─────────────┘                                      │
+      ▲                                              │
+      │                                              │
+┌─────────────┐     ┌─────────────┐     ┌──────────┴────┐
+│ application │     │  contracts  │     │ infrastructure │
+│             │     │   (zod)     │     │               │
+└─────────────┘     └─────────────┘     └───────────────┘
+      ▲                   ▲
+      │                   │
+      └────────┬──────────┘
+               │
+         ┌─────┴─────┐
+         │    api    │
+         └───────────┘
+               ▲
+               │
+         ┌─────┴─────┐
+         │    sdk    │◄─── (imports all core packages)
+         └───────────┘
+               ▲
+               │
+    ┌──────────┴──────────┐
+    │                     │
+┌───┴───┐           ┌─────┴─────┐
+│ server│           │ sdk-react │
+└───────┘           └───────────┘
+                          ▲
+                          │
+                    ┌─────┴─────┐
+                    │    web    │
+                    └───────────┘
+```
+
+### Dependency Matrix
+
+| Package        | Can Import From                |
+| -------------- | ------------------------------ |
+| domain         | (none)                         |
+| contracts      | zod                            |
+| application    | domain                         |
+| infrastructure | domain, external libs          |
+| api            | domain, application, contracts |
+| sdk            | all core packages, awilix      |
+| sdk-react      | sdk types                      |
+| server         | ALL packages                   |
+| web            | sdk-react, contracts           |
+
+---
+
+## Layer Responsibilities
+
+### Domain Layer (`packages/domain`)
+
+**Purpose:** Pure business logic, zero external dependencies
+
+**Contains:**
+
+- Business entities (User, Invoice, etc.)
+- Port interfaces (repository contracts)
+- Business rules and invariants
+- Value objects
+
+```typescript
+// packages/domain/src/entities/user.ts
+export interface User {
+	id: string
+	email: string
+	name: string
+	createdAt: Date
+}
+
+// packages/domain/src/ports/user-repository.ts
+export interface UserRepository {
+	findById(id: string): Promise<User | null>
+	findByEmail(email: string): Promise<User | null>
+	save(user: User): Promise<User>
+}
+```
+
+### Contracts Layer (`packages/contracts`)
+
+**Purpose:** DTOs and validation schemas shared between layers
+
+**Contains:**
+
+- Zod schemas for validation
+- DTOs for API requests/responses
+- Type definitions derived from schemas
+
+```typescript
+// packages/contracts/src/user.ts
+import { z } from 'zod'
+
+export const createUserSchema = z.object({
+	email: z.string().email(),
+	name: z.string().min(1).max(100),
+	password: z.string().min(8),
+})
+
+export type CreateUserInput = z.infer<typeof createUserSchema>
+
+export const userDTOSchema = z.object({
+	id: z.string().uuid(),
+	email: z.string().email(),
+	name: z.string(),
+	createdAt: z.string().datetime(),
+})
+
+export type UserDTO = z.infer<typeof userDTOSchema>
+```
+
+### Application Layer (`packages/application`)
+
+**Purpose:** Use cases and business workflows
+
+**Contains:**
+
+- Use case implementations
+- Business logic orchestration
+- Application services
+
+```typescript
+// packages/application/src/use-cases/create-user.ts
+import type { UserRepository } from '@kuckit/domain'
+import type { CreateUserInput } from '@kuckit/contracts'
+
+export function makeCreateUserUseCase(deps: {
+	userRepository: UserRepository
+	passwordHasher: PasswordHasher
+	eventBus: EventBus
+}) {
+	return async function createUser(input: CreateUserInput) {
+		const existing = await deps.userRepository.findByEmail(input.email)
+		if (existing) {
+			throw new UserAlreadyExistsError(input.email)
+		}
+
+		const hashedPassword = await deps.passwordHasher.hash(input.password)
+		const user = await deps.userRepository.save({
+			id: generateId(),
+			email: input.email,
+			name: input.name,
+			passwordHash: hashedPassword,
+			createdAt: new Date(),
+		})
+
+		await deps.eventBus.publish('user.created', { userId: user.id })
+		return user
+	}
+}
+```
+
+### Infrastructure Layer (`packages/infrastructure`)
+
+**Purpose:** Concrete implementations of domain ports
+
+**Contains:**
+
+- Repository implementations (Drizzle)
+- External service adapters
+- Third-party integrations
+
+```typescript
+// packages/infrastructure/src/repositories/drizzle-user-repository.ts
+import type { UserRepository, User } from '@kuckit/domain'
+import { eq } from 'drizzle-orm'
+import { users } from '@kuckit/db'
+
+export class DrizzleUserRepository implements UserRepository {
+	constructor(private db: DrizzleInstance) {}
+
+	async findById(id: string): Promise<User | null> {
+		return this.db.query.users.findFirst({
+			where: eq(users.id, id),
+		})
+	}
+
+	async findByEmail(email: string): Promise<User | null> {
+		return this.db.query.users.findFirst({
+			where: eq(users.email, email),
+		})
+	}
+
+	async save(user: User): Promise<User> {
+		const [result] = await this.db.insert(users).values(user).returning()
+		return result
+	}
+}
+```
+
+### API Layer (`packages/api`)
+
+**Purpose:** Expose use cases to clients via oRPC
+
+**Contains:**
+
+- oRPC procedures
+- Request context handling
+- Input validation
+- Response mapping
+
+```typescript
+// packages/api/src/procedures/user.ts
+import { createORPCRouter, createProcedure } from '@kuckit/api'
+import { createUserSchema, userDTOSchema } from '@kuckit/contracts'
+
+export function createUserRouter(container: AwilixContainer) {
+	return createORPCRouter({
+		create: createProcedure()
+			.input(createUserSchema)
+			.output(userDTOSchema)
+			.mutation(async ({ input, ctx }) => {
+				const createUser = container.resolve('createUser')
+				const user = await createUser(input)
+				return mapToDTO(user)
+			}),
+
+		get: createProcedure()
+			.input(z.object({ id: z.string().uuid() }))
+			.output(userDTOSchema)
+			.query(async ({ input }) => {
+				const userRepository = container.resolve('userRepository')
+				const user = await userRepository.findById(input.id)
+				if (!user) throw new NotFoundError('User not found')
+				return mapToDTO(user)
+			}),
+	})
+}
+```
+
+---
+
+## Module System Flow
+
+### Server-Side Loading
+
+```
+1. createKuckitContainer()
+   └─► Core services registered (logger, db, cache, eventBus)
+
+2. loadKuckitModules({ modules: [...] })
+   ├─► For each module:
+   │   ├─► register(ctx) - Register DI dependencies
+   │   ├─► registerApi(ctx) - Register API routes
+   │   └─► onBootstrap(ctx) - Run startup logic
+   └─► onApiRegistrations callback with all routes
+
+3. Application runs...
+
+4. disposeContainer()
+   └─► For each module: onShutdown(ctx)
+```
+
+### Client-Side Loading
+
+```
+1. loadKuckitClientModules({ modules: [...] })
+   └─► Returns: routes, navItems, slots, components
+
+2. TanStack Router receives routes
+   └─► Dynamic route registration
+
+3. KuckitNavProvider receives navItems
+   └─► useKuckitNav() hook for navigation
+
+4. Components render with SlotRegistry
+   └─► Module UI slots in shell
+```
+
+---
+
+## Core Services
+
+| Service         | Token              | Purpose                   |
+| --------------- | ------------------ | ------------------------- |
+| Configuration   | `config`           | Application settings      |
+| Database        | `db`               | Drizzle query builder     |
+| Connection Pool | `dbPool`           | PostgreSQL pool           |
+| Logging         | `logger`           | Structured logger         |
+| Events          | `eventBus`         | Pub/sub system            |
+| Time            | `clock`            | Testable time abstraction |
+| Caching         | `cacheStore`       | Key-value cache           |
+| Rate Limiting   | `rateLimiterStore` | Request rate limiting     |
+
+---
+
+## Adding a New Feature Checklist
+
+1. **Domain Layer**
+   - [ ] Create entity in `packages/domain/src/entities/`
+   - [ ] Define port interface in `packages/domain/src/ports/`
+
+2. **Contracts Layer**
+   - [ ] Create Zod schemas in `packages/contracts/src/`
+   - [ ] Export DTOs
+
+3. **Infrastructure Layer**
+   - [ ] Implement repository in `packages/infrastructure/src/repositories/`
+   - [ ] Add Drizzle schema in `packages/db/src/schema/`
+
+4. **Application Layer**
+   - [ ] Create use case in `packages/application/src/use-cases/`
+
+5. **API Layer**
+   - [ ] Add oRPC procedure in `packages/api/src/procedures/`
+
+6. **Module Integration**
+   - [ ] Register dependencies in module's `register()` hook
+   - [ ] Register API in module's `registerApi()` hook
+
+7. **Client Side** (if needed)
+   - [ ] Add route in client module
+   - [ ] Create page component
+   - [ ] Add navigation item