@odvi/create-dtt-framework 0.1.2 → 0.1.5

package/template/docs/framework/implementation.md

@@ -0,0 +1,559 @@
+# DTT Framework - Implementation Guide
+
+## Overview
+
+This document explains how the DTT Framework was implemented, including key design decisions, architecture patterns, and code organization principles. Understanding these decisions will help you maintain and extend the framework.
+
+---
+
+## How the Framework Was Implemented
+
+### Initial Setup
+
+The framework was initialized using the T3 Stack template:
+
+```bash
+npx create-t3-app@latest dtt-framework --typescript --tailwind --eslint --app --src-dir
+```
+
+The T3 Stack provided:
+- Next.js 15 with App Router
+- TypeScript configuration
+- Tailwind CSS
+- ESLint
+- Prettier
+
+### Core Integrations Added
+
+After initial setup, the following integrations were added:
+
+1. **Clerk Authentication** - User management and auth
+2. **Supabase** - Database, storage, and edge functions
+3. **Drizzle ORM** - Type-safe database queries
+4. **Hono** - API layer
+5. **TanStack Query** - Server state management
+6. **Zustand** - Client state management
+7. **Snowflake SDK** - Data warehouse integration
+
+---
+
+## Key Design Decisions
+
+### 1. Next.js App Router over Pages Router
+
+**Decision:** Use App Router instead of Pages Router
+
+**Rationale:**
+- **React Server Components**: Better performance with server-side rendering
+- **Streaming**: Progressive rendering for faster perceived performance
+- **Nested Layouts**: Shared UI across routes
+- **Route Groups**: Organize routes without affecting URL structure
+- **Future-Proof**: App Router is the recommended approach
+
+**Trade-offs:**
+- Slightly steeper learning curve
+- Some third-party libraries still catching up
+
+### 2. Clerk over NextAuth.js
+
+**Decision:** Use Clerk for authentication
+
+**Rationale:**
+- **Complete Solution**: Built-in UI components, no need to build auth screens
+- **Organization Support**: Multi-tenant architecture out of the box
+- **Webhooks**: Real-time user data synchronization
+- **Developer Experience**: Less boilerplate code
+- **Security**: SOC 2 Type II compliant
+
+**Trade-offs:**
+- Additional service dependency
+- Cost for production use
+
+### 3. Drizzle ORM over Prisma
+
+**Decision:** Use Drizzle ORM for database access
+
+**Rationale:**
+- **Type Safety**: Full TypeScript support with inferred types
+- **SQL-Like**: Queries resemble SQL, easy to learn
+- **Lightweight**: Small bundle size, minimal overhead
+- **Performance**: No query builder overhead, compiles to SQL
+- **Migration System**: Built-in migration management
+
+**Trade-offs:**
+- Smaller ecosystem than Prisma
+- Less mature tooling
+
+### 4. Hono over tRPC
+
+**Decision:** Use Hono for API layer instead of tRPC
+
+**Rationale:**
+- **Framework Agnostic**: Can be used outside Next.js
+- **REST API**: Standard REST endpoints, easier to consume
+- **Flexibility**: More control over request/response
+- **Performance**: Smaller bundle size, faster execution
+- **Middleware**: Composable middleware system
+
+**Trade-offs:**
+- No end-to-end type safety like tRPC
+- Manual type definitions for API contracts
+
+### 5. TanStack Query + Zustand over Redux
+
+**Decision:** Use TanStack Query for server state and Zustand for client state
+
+**Rationale:**
+- **Separation of Concerns**: Clear distinction between server and client state
+- **TanStack Query**: Specialized for server state with caching and synchronization
+- **Zustand**: Lightweight, simple, no boilerplate
+- **Better Performance**: No context re-renders with Zustand
+- **Developer Experience**: Simpler mental model
+
+**Trade-offs:**
+- Two different state management systems to learn
+- Need to decide where to put state
+
+### 6. Supabase Transaction Mode over Session Mode
+
+**Decision:** Use Transaction mode for database connection pooling
+
+**Rationale:**
+- **Serverless Optimization**: Designed for serverless environments
+- **Connection Pooling**: Efficient connection reuse
+- **Better Performance**: Faster connection times in serverless
+- **Cost Effective**: Fewer active connections
+
+**Trade-offs:**
+- Requires `prepare: false` in postgres client
+- Different connection URL format
+
+### 7. Shadcn/ui over Component Libraries
+
+**Decision:** Use Shadcn/ui for UI components
+
+**Rationale:**
+- **Copy-Paste**: Components are copied to codebase, full control
+- **Radix UI Primitives**: Accessible, unstyled components
+- **Tailwind Integration**: Styled with Tailwind CSS
+- **Customizable**: Easy to modify to fit design
+- **No Runtime Dependencies**: Lightweight, no library overhead
+
+**Trade-offs:**
+- More initial setup than pre-built component libraries
+- Need to copy components individually
+
+---
+
+## Architecture Patterns Used
+
+### 1. Feature-Based Organization
+
+**Pattern:** Organize code by feature, not by file type
+
+**Implementation:**
+
+```
+src/features/health-check/
+├── components/
+│   └── health-dashboard.tsx
+├── config.ts
+├── types.ts
+└── index.ts
+```
+
+**Benefits:**
+- **Co-location**: Related code is together
+- **Easy Navigation**: Find all code for a feature in one place
+- **Better Boundaries**: Clear feature boundaries
+- **AI-Friendly**: Easier for AI to understand feature context
+
+### 2. Route Groups
+
+**Pattern:** Use Next.js route groups for logical organization
+
+**Implementation:**
+
+```
+src/app/
+├── (auth)/              # Auth routes group
+│   ├── sign-in/
+│   ├── sign-up/
+│   └── layout.tsx
+└── (dashboard)/         # Dashboard routes group
+    ├── health/
+    ├── page.tsx
+    └── layout.tsx
+```
+
+**Benefits:**
+- **Shared Layouts**: Different layouts for different route groups
+- **Clean URLs**: Group names don't affect URLs
+- **Logical Organization**: Clear separation of concerns
+
+### 3. API Route Aggregation
+
+**Pattern:** Aggregate related routes under a common prefix
+
+**Implementation:**
+
+```typescript
+// src/server/api/routes/health/index.ts
+import { clerkHealthRoutes } from './clerk'
+import { databaseHealthRoutes } from './database'
+// ... other routes
+
+export const healthRoutes = new Hono()
+
+healthRoutes.route('/clerk', clerkHealthRoutes)
+healthRoutes.route('/database', databaseHealthRoutes)
+// ... other routes
+```
+
+**Benefits:**
+- **Modular Routes**: Each service has its own route file
+- **Clean Organization**: Easy to find and modify routes
+- **Scalable**: Easy to add new services
+
+### 4. Middleware Pipeline
+
+**Pattern:** Use middleware for cross-cutting concerns
+
+**Implementation:**
+
+```typescript
+// src/server/api/index.ts
+const app = new Hono().basePath('/api')
+
+app.use('*', logger())        // Logging
+app.use('*', cors())          // CORS
+
+app.get('/ping', handler)     // Public route
+
+app.use('*', authMiddleware)  // Auth protection
+
+app.route('/health', healthRoutes)
+app.route('/users', usersRoutes)
+```
+
+**Benefits:**
+- **Separation of Concerns**: Middleware handles cross-cutting logic
+- **Reusability**: Middleware can be applied to multiple routes
+- **Clean Handlers**: Route handlers focus on business logic
+
+### 5. Type-Safe Environment Variables
+
+**Pattern:** Use @t3-oss/env-nextjs for type-safe environment variables
+
+**Implementation:**
+
+```typescript
+// src/config/env.ts
+import { createEnv } from '@t3-oss/env-nextjs'
+import { z } from 'zod'
+
+export const env = createEnv({
+  server: {
+    DATABASE_URL: z.string().url(),
+    CLERK_SECRET_KEY: z.string().startsWith('sk_'),
+  },
+  client: {
+    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: z.string().startsWith('pk_'),
+  },
+  runtimeEnv: {
+    DATABASE_URL: process.env.DATABASE_URL,
+    CLERK_SECRET_KEY: process.env.CLERK_SECRET_KEY,
+    NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY,
+  },
+})
+```
+
+**Benefits:**
+- **Type Safety**: Catch missing variables at build time
+- **Validation**: Ensure variables are correctly formatted
+- **Auto-Completion**: IDE suggestions for environment variables
+- **Clear Errors**: Helpful error messages for missing variables
+
+### 6. Custom Hooks Pattern
+
+**Pattern:** Create custom hooks for reusable logic
+
+**Implementation:**
+
+```typescript
+// src/hooks/queries/use-health-checks.ts
+'use client'
+
+import { useQuery } from '@tanstack/react-query'
+
+export function useHealthChecks() {
+  return useQuery({
+    queryKey: ['health-checks'],
+    queryFn: async () => {
+      const response = await fetch('/api/health/all')
+      if (!response.ok) throw new Error('Failed to fetch health checks')
+      return response.json()
+    },
+  })
+}
+```
+
+**Benefits:**
+- **Reusability**: Logic can be reused across components
+- **Testability**: Hooks can be tested independently
+- **Separation of Concerns**: Data fetching logic separated from UI
+- **Cleaner Components**: Components focus on rendering
+
+### 7. Webhook Synchronization
+
+**Pattern:** Use webhooks to sync data between services
+
+**Implementation:**
+
+```typescript
+// src/app/api/webhooks/clerk/route.ts
+export async function POST(req: Request) {
+  // Verify webhook signature
+  const wh = new Webhook(env.CLERK_WEBHOOK_SECRET)
+  const event = wh.verify(body, headers) as WebhookEvent
+
+  // Handle events
+  if (event.type === 'user.created') {
+    await db.insert(users).values(event.data)
+  }
+
+  return new Response(JSON.stringify({ received: true }), { status: 200 })
+}
+```
+
+**Benefits:**
+- **Real-time Sync**: Data is synced immediately
+- **Decoupled**: Services don't need to know about each other
+- **Reliable**: Webhooks are retried on failure
+- **Audit Trail**: Webhook events provide audit trail
+
+---
+
+## Code Organization Principles
+
+### 1. Separation of Concerns
+
+Each module has a single responsibility:
+
+- **Components**: Handle rendering and user interaction
+- **Hooks**: Handle data fetching and state management
+- **API Routes**: Handle HTTP requests and responses
+- **Database Queries**: Handle database operations
+- **Utilities**: Handle pure functions and helpers
+
+### 2. Explicit Imports
+
+Use explicit imports for better tree-shaking:
+
+```typescript
+// ✅ Good - Explicit import
+import { Button } from '@/components/ui/button'
+
+// ❌ Bad - Barrel import
+import * as UI from '@/components/ui'
+```
+
+### 3. Path Aliases
+
+Use path aliases for clean imports:
+
+```typescript
+// tsconfig.json
+{
+  "compilerOptions": {
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+### 4. TypeScript Strict Mode
+
+Always use TypeScript in strict mode:
+
+```typescript
+// tsconfig.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+  }
+}
+```
+
+### 5. Consistent Naming
+
+Follow consistent naming conventions:
+
+- **Components**: PascalCase (`UserProfile.tsx`)
+- **Hooks**: camelCase with `use` prefix (`useUserProfile.ts`)
+- **Utilities**: camelCase (`formatDate.ts`)
+- **Types**: PascalCase (`UserProfile.ts`)
+- **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`)
+
+### 6. File Naming
+
+Use clear, descriptive file names:
+
+```
+src/features/health-check/
+├── components/health-dashboard.tsx  # Component
+├── config.ts                      # Configuration
+├── types.ts                       # Type definitions
+└── index.ts                       # Public exports
+```
+
+---
+
+## File Structure Decisions
+
+### Why This Structure?
+
+```
+src/
+├── app/                    # Next.js App Router
+├── components/             # React components
+├── features/               # Feature modules
+├── hooks/                  # React hooks
+├── lib/                    # Utilities and clients
+├── server/                 # Server-side code
+├── stores/                 # Zustand stores
+├── types/                  # TypeScript types
+└── config/                 # Configuration
+```
+
+**Rationale:**
+- **Framework Conventions**: Follows Next.js and React conventions
+- **Clear Separation**: Client and server code are separate
+- **Feature-Based**: Features are self-contained
+- **Scalable**: Easy to add new features
+
+### Server-Side Code Organization
+
+```
+src/server/
+├── api/                    # API layer
+│   ├── index.ts            # Hono app instance
+│   ├── middleware/         # API middleware
+│   └── routes/            # API routes
+└── db/                     # Database layer
+    ├── index.ts            # Drizzle client
+    ├── schema/             # Database schemas
+    ├── queries/            # Database queries
+    └── migrations/         # Migration files
+```
+
+**Rationale:**
+- **API vs DB**: API routes and database queries are separate
+- **Modular**: Each module is self-contained
+- **Testable**: Each module can be tested independently
+
+---
+
+## Performance Considerations
+
+### 1. Connection Pooling
+
+Using Supabase Transaction mode for efficient connection reuse:
+
+```typescript
+const conn = globalForDb.conn ?? postgres(env.DATABASE_URL, { prepare: false })
+```
+
+### 2. Response Time Tracking
+
+All health check endpoints track response time:
+
+```typescript
+const start = performance.now()
+// ... perform check
+return c.json({
+  responseTimeMs: Math.round(performance.now() - start),
+})
+```
+
+### 3. TanStack Query Caching
+
+Configuring stale time to reduce unnecessary requests:
+
+```typescript
+new QueryClient({
+  defaultOptions: { 
+    queries: { 
+      staleTime: 60 * 1000, // 60 seconds
+      retry: 1
+    } 
+  },
+})
+```
+
+### 4. React Server Components
+
+Using Server Components to reduce client-side JavaScript:
+
+```typescript
+// Server Component (default)
+export default async function ServerComponent() {
+  const data = await fetchData()
+  return <div>{data}</div>
+}
+```
+
+---
+
+## Security Considerations
+
+### 1. Environment Variables
+
+All sensitive data in environment variables:
+
+```typescript
+// ✅ Good - Environment variable
+const apiKey = env.API_KEY
+
+// ❌ Bad - Hardcoded
+const apiKey = 'sk_test_xxx'
+```
+
+### 2. Webhook Verification
+
+Verifying webhook signatures to prevent spoofing:
+
+```typescript
+const wh = new Webhook(env.CLERK_WEBHOOK_SECRET)
+const event = wh.verify(body, headers)
+```
+
+### 3. Auth Middleware
+
+Protecting all API routes with authentication:
+
+```typescript
+app.use('*', authMiddleware)
+```
+
+### 4. Service Role Key
+
+Using service role key for server-side operations:
+
+```typescript
+// Server-side - bypasses RLS
+const supabaseAdmin = createClient(url, serviceRoleKey)
+```
+
+---
+
+## Related Documentation
+
+- [Overview](./01-overview.md) - Framework introduction
+- [Tech Stack](./02-techstack.md) - Technology choices
+- [API Layer](./api-layer.md) - API implementation
+- [State Management](./state-management.md) - State patterns
+- [What Did I Miss](./what-did-i-miss.md) - Potential improvements