@odvi/create-dtt-framework 0.1.3 → 0.1.6

package/template/docs/framework/02-techstack.md

@@ -0,0 +1,503 @@
+# DTT Framework - Tech Stack
+
+## Complete Technology Stack
+
+The DTT Framework uses a carefully curated set of modern technologies to provide a robust, type-safe, and developer-friendly foundation for building enterprise applications.
+
+### Technology Stack Overview
+
+| Layer | Technology | Version | Purpose |
+|-------|-----------|---------|---------|
+| **Framework** | Next.js | ^15.2.3 | Full-stack React framework with App Router |
+| **Language** | TypeScript | ^5.8.2 | Type-safe development |
+| **Runtime** | Node.js | 20+ | JavaScript runtime |
+| **Package Manager** | pnpm | 10.26.1 | Fast, disk space efficient package manager |
+| **Styling** | Tailwind CSS | ^4.0.15 | Utility-first CSS framework |
+| **UI Components** | Shadcn/ui | Latest | Accessible component primitives |
+| **Icons** | Lucide React | ^0.562.0 | Icon library |
+| **Authentication** | Clerk | ^6.36.5 | User authentication & management |
+| **Webhooks** | Svix | ^1.82.0 | Webhook delivery and verification |
+| **Database** | Supabase (PostgreSQL) | Latest | Primary database |
+| **ORM** | Drizzle ORM | ^0.41.0 | Type-safe database queries |
+| **Database Driver** | postgres | ^3.4.4 | PostgreSQL driver |
+| **Storage** | Supabase Storage | Latest | File storage |
+| **Edge Functions** | Supabase Edge Functions | Latest | Serverless compute |
+| **Data Warehouse** | Snowflake SDK | ^2.3.3 | Analytics & reporting |
+| **API Framework** | Hono | ^4.11.3 | Lightweight API framework |
+| **Server State** | TanStack Query | ^5.90.14 | Data fetching & caching |
+| **Client State** | Zustand | ^5.0.9 | UI state management |
+| **Validation** | Zod | ^3.24.2 | Schema validation |
+| **Environment** | @t3-oss/env-nextjs | ^0.12.0 | Type-safe environment variables |
+| **CSS Utilities** | clsx | ^2.1.1 | Conditional className utility |
+| **CSS Utilities** | tailwind-merge | ^3.4.0 | Merge Tailwind classes |
+| **Component Variants** | class-variance-authority | ^0.7.1 | Component variant management |
+| **UI Primitives** | @radix-ui/react-slot | ^1.2.4 | Radix UI primitives |
+| **UI Primitives** | @radix-ui/react-collapsible | ^1.1.12 | Collapsible component |
+
+### Dev Dependencies
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| **Drizzle Kit** | ^0.30.5 | Database migrations and studio |
+| **ESLint** | ^9.23.0 | Code linting |
+| **ESLint Config Next** | ^15.2.3 | Next.js ESLint configuration |
+| **ESLint Plugin Drizzle** | ^0.2.3 | Drizzle ORM linting |
+| **TypeScript ESLint** | ^8.27.0 | TypeScript linting |
+| **Prettier** | ^3.5.3 | Code formatting |
+| **Prettier Plugin Tailwind** | ^0.6.11 | Tailwind class sorting |
+| **PostCSS** | ^8.5.3 | CSS processing |
+| **Tailwind PostCSS** | ^4.0.15 | Tailwind CSS PostCSS plugin |
+| **Tw Animate CSS** | ^1.4.0 | Tailwind animations |
+| **Type Definitions** | @types/node | ^20.14.10 | Node.js type definitions |
+| **Type Definitions** | @types/react | ^19.0.0 | React type definitions |
+| **Type Definitions** | @types/react-dom | ^19.0.0 | React DOM type definitions |
+| **Type Definitions** | @types/snowflake-sdk | ^1.6.24 | Snowflake SDK type definitions |
+
+---
+
+## Technology Choices Explained
+
+### Framework Layer
+
+#### Next.js 15 with App Router
+
+**Why Next.js?**
+- **Full-Stack Capability**: Combines frontend and backend in a single framework
+- **App Router**: Modern routing with React Server Components
+- **Built-in Optimizations**: Image optimization, font optimization, automatic code splitting
+- **API Routes**: Built-in API endpoint support
+- **Edge Runtime**: Support for edge computing
+- **Vercel Integration**: Seamless deployment to Vercel
+
+**Why App Router?**
+- **React Server Components**: Reduced client-side JavaScript
+- **Streaming**: Progressive rendering for faster perceived performance
+- **Nested Layouts**: Shared UI across routes
+- **Route Groups**: Organize routes without affecting URL structure
+
+**Version Requirements:**
+- Node.js 20+ required
+- React 19+ required
+
+#### TypeScript 5.8
+
+**Why TypeScript?**
+- **Type Safety**: Catch errors at compile time
+- **Better IDE Support**: Autocomplete, refactoring, inline documentation
+- **Self-Documenting Code**: Types serve as documentation
+- **Improved Maintainability**: Easier to understand and modify code
+- **AI-Friendly**: Type information helps AI assistants understand code better
+
+**Key Features Used:**
+- **Type Inference**: Automatic type deduction
+- **Generics**: Reusable type-safe components
+- **Utility Types**: `Pick`, `Omit`, `Partial`, etc.
+- **Strict Mode**: Maximum type safety
+
+---
+
+### Styling Layer
+
+#### Tailwind CSS 4
+
+**Why Tailwind CSS?**
+- **Utility-First**: Rapid UI development without writing custom CSS
+- **Consistency**: Design system enforced by utility classes
+- **Responsive Design**: Built-in responsive modifiers
+- **Dark Mode**: Native dark mode support
+- **Small Bundle Size**: Purge unused styles in production
+- **Customization**: Easy to extend with custom utilities
+
+**Tailwind CSS 4 Features:**
+- **New Syntax**: Improved CSS-first configuration
+- **Better Performance**: Faster build times
+- **Native CSS Variables**: Improved theming support
+
+#### Shadcn/ui
+
+**Why Shadcn/ui?**
+- **Copy-Paste Components**: Components are copied to your codebase, full control
+- **Radix UI Primitives**: Accessible, unstyled components
+- **Tailwind Integration**: Styled with Tailwind CSS
+- **Customizable**: Easy to modify to fit your design
+- **No Runtime Dependencies**: Lightweight, no library overhead
+
+**Components Used:**
+- `Button` - Interactive buttons
+- `Card` - Content containers
+- `Badge` - Status indicators
+- `Collapsible` - Expandable content
+
+#### Lucide React
+
+**Why Lucide?**
+- **Tree-Shakeable**: Only import icons you use
+- **Consistent Style**: Uniform icon design
+- **Customizable**: Easy to modify size, color, stroke
+- **React Native Support**: Same icons across platforms
+
+---
+
+### Authentication Layer
+
+#### Clerk 6
+
+**Why Clerk?**
+- **Complete Auth Solution**: Sign-in, sign-up, password reset, email verification
+- **Built-in Components**: Pre-built auth UI components
+- **Organization Support**: Multi-tenant architecture out of the box
+- **Webhooks**: Real-time user data synchronization
+- **Session Management**: Secure session handling
+- **Social Providers**: Easy integration with OAuth providers
+- **MFA Support**: Multi-factor authentication
+
+**Key Features Used:**
+- `<SignIn />` - Sign-in page component
+- `<SignUp />` - Sign-up page component
+- `<UserButton />` - User menu component
+- `getAuth()` - Server-side auth access
+- `clerkMiddleware()` - Route protection
+- Webhooks - User data sync
+
+#### Svix
+
+**Why Svix?**
+- **Webhook Delivery**: Reliable webhook delivery
+- **Verification**: Webhook signature verification
+- **Retry Logic**: Automatic retries on failure
+- **Webhook Dashboard**: Monitor webhook delivery
+
+---
+
+### Database Layer
+
+#### Supabase (PostgreSQL)
+
+**Why Supabase?**
+- **PostgreSQL**: Powerful, open-source relational database
+- **Managed Service**: No database administration needed
+- **Real-time**: Real-time database subscriptions
+- **Storage**: Built-in file storage
+- **Edge Functions**: Serverless functions
+- **Auth Integration**: Built-in authentication (not used, we use Clerk)
+- **Connection Pooling**: Transaction mode for serverless
+
+**PostgreSQL Features:**
+- **ACID Compliance**: Reliable transactions
+- **JSON Support**: Store and query JSON data
+- **Full-Text Search**: Built-in search capabilities
+- **Extensions**: Rich ecosystem of extensions
+
+#### Drizzle ORM 0.41
+
+**Why Drizzle?**
+- **Type-Safe**: Full TypeScript support with inferred types
+- **SQL-Like**: Queries resemble SQL, easy to learn
+- **Lightweight**: Small bundle size, minimal overhead
+- **Migration Support**: Built-in migration system
+- **Multiple Dialects**: Support for PostgreSQL, MySQL, SQLite
+- **Performance**: No query builder overhead, compiles to SQL
+
+**Key Features Used:**
+- **Schema Definition**: Define tables with TypeScript
+- **Type Inference**: Infer types from schema
+- **Query Building**: Type-safe query construction
+- **Migrations**: Database schema management
+
+#### postgres (Driver)
+
+**Why postgres driver?**
+- **Recommended by Drizzle**: Officially supported by Drizzle
+- **Connection Pooling**: Built-in connection pooling
+- **Prepared Statements**: SQL injection protection
+- **Async/Await**: Modern async API
+
+---
+
+### Storage & Edge Computing
+
+#### Supabase Storage
+
+**Why Supabase Storage?**
+- **S3-Compatible**: S3-compatible API
+- **CDN Integration**: Built-in CDN for fast delivery
+- **Signed URLs**: Temporary access URLs
+- **Bucket Management**: Organized file storage
+- **Transformations**: Image transformations on the fly
+
+**Features Used:**
+- **Upload**: File upload to buckets
+- **Download**: File download with signed URLs
+- **Delete**: File deletion
+- **List**: List files in buckets
+
+#### Supabase Edge Functions
+
+**Why Supabase Edge Functions?**
+- **Deno Runtime**: Secure, fast JavaScript runtime
+- **Edge Deployment**: Deploy close to users
+- **Auth Integration**: Built-in auth context
+- **TypeScript Support**: Full TypeScript support
+- **Environment Variables**: Secure environment variable access
+
+**Features Used:**
+- **Function Invocation**: Call edge functions from app
+- **Auth Header Passthrough**: Forward auth headers
+
+---
+
+### Data Warehouse
+
+#### Snowflake SDK
+
+**Why Snowflake?**
+- **Cloud-Native**: Fully managed data warehouse
+- **Separation of Compute and Storage**: Scale independently
+- **Performance**: Fast query execution
+- **SQL Support**: Standard SQL with extensions
+- **Data Sharing**: Secure data sharing
+- **Ecosystem**: Rich partner ecosystem
+
+**Snowflake SDK Features:**
+- **Connection Management**: Create and manage connections
+- **Query Execution**: Execute SQL queries
+- **Result Streaming**: Stream large result sets
+- **Parameter Binding**: Secure parameter binding
+
+---
+
+### API Layer
+
+#### Hono 4
+
+**Why Hono?**
+- **Lightweight**: Small bundle size, fast execution
+- **Type-Safe**: Full TypeScript support
+- **Middleware Support**: Composable middleware
+- **Fast**: Built on Web Standards, optimized for performance
+- **Flexible**: Works with multiple runtimes (Node.js, Edge, Deno)
+- **Easy to Learn**: Simple, intuitive API
+
+**Key Features Used:**
+- **Route Organization**: Modular route structure
+- **Middleware**: Auth, logging, CORS
+- **Type Inference**: Infer request/response types
+- **Error Handling**: Centralized error handling
+
+**Comparison with tRPC:**
+- **Hono**: More flexible, framework-agnostic, better for REST APIs
+- **tRPC**: Type-safe client-server communication, better for full-stack TypeScript
+
+---
+
+### State Management
+
+#### TanStack Query 5
+
+**Why TanStack Query?**
+- **Server State**: Specialized for server state management
+- **Caching**: Automatic caching and invalidation
+- **Background Updates**: Keep data fresh
+- **Optimistic Updates**: Better UX with instant feedback
+- **Pagination**: Built-in pagination support
+- **DevTools**: Excellent debugging tools
+
+**Key Features Used:**
+- **useQuery**: Fetch and cache data
+- **useMutation**: Mutate server data
+- **Query Keys**: Cache management
+- **Stale Time**: Control cache freshness
+
+#### Zustand 5
+
+**Why Zustand?**
+- **Lightweight**: Small bundle size (~1KB)
+- **Simple**: Minimal boilerplate, easy to learn
+- **No Context**: Avoids context-related re-renders
+- **Type-Safe**: Full TypeScript support
+- **DevTools**: Built-in DevTools integration
+- **Persistence**: Optional state persistence
+
+**Key Features Used:**
+- **Create Store**: Define state and actions
+- **Hooks**: React hooks for accessing state
+- **Selectors**: Subscribe to specific state slices
+
+---
+
+### Validation
+
+#### Zod 3
+
+**Why Zod?**
+- **Type-Safe**: Infer TypeScript types from schemas
+- **Composable**: Combine schemas for complex validation
+- **Error Messages**: Customizable error messages
+- **Runtime Validation**: Validate data at runtime
+- **Parser Integration**: Works with many parsers
+
+**Key Features Used:**
+- **Schema Definition**: Define validation schemas
+- **Type Inference**: Infer types from schemas
+- **Environment Validation**: Validate environment variables
+
+---
+
+### Environment Variables
+
+#### @t3-oss/env-nextjs
+
+**Why @t3-oss/env-nextjs?**
+- **Type-Safe**: Infer types from environment variable schemas
+- **Runtime Validation**: Validate environment variables at startup
+- **Client/Server Separation**: Separate client and server variables
+- **Error Messages**: Clear error messages for missing variables
+- **Build-Time Validation**: Catch missing variables at build time
+
+---
+
+## Technology Interactions and Dependencies
+
+### Dependency Graph
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Application Layer                         │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
+│  │  Next.js     │  │  React 19    │  │  TypeScript  │        │
+│  └──────────────┘  └──────────────┘  └──────────────┘        │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+        ┌─────────────────────┼─────────────────────┐
+        ▼                     ▼                     ▼
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│  Clerk Auth  │    │  Hono API    │    │  TanStack Q  │
+└──────────────┘    └──────────────┘    └──────────────┘
+        │                     │                     │
+        ▼                     ▼                     ▼
+┌──────────────┐    ┌──────────────┐    ┌──────────────┐
+│  Svix Web-   │    │  Drizzle ORM │    │  Zustand    │
+│     hooks    │    └──────────────┘    └──────────────┘
+└──────────────┘             │
+        ▼                     ▼
+┌──────────────┐    ┌──────────────┐
+│  Supabase    │    │  Snowflake   │
+│  (PostgreSQL)│    │  Warehouse   │
+└──────────────┘    └──────────────┘
+```
+
+### Key Interactions
+
+#### Authentication Flow
+1. User signs in via Clerk components
+2. Clerk creates session and stores tokens
+3. Clerk middleware validates session on protected routes
+4. Svix handles webhook delivery for user data sync
+5. Webhook handler updates local database via Drizzle
+
+#### Data Fetching Flow
+1. Component renders and calls TanStack Query hook
+2. TanStack Query calls Hono API endpoint
+3. Hono middleware validates Clerk auth
+4. Hono route handler queries database via Drizzle
+5. Drizzle executes SQL via postgres driver
+6. Results flow back through the chain
+
+#### State Management Flow
+1. Server state fetched via TanStack Query
+2. Client state managed via Zustand
+3. UI components subscribe to state changes
+4. State updates trigger re-renders
+
+---
+
+## Version Requirements
+
+### Minimum Requirements
+
+| Technology | Minimum Version | Recommended Version |
+|------------|-----------------|---------------------|
+| Node.js | 20.x | Latest LTS |
+| pnpm | 10.x | Latest |
+| Next.js | 15.x | Latest |
+| React | 19.x | Latest |
+| TypeScript | 5.x | Latest |
+
+### Compatibility Matrix
+
+| Next.js | React | TypeScript | Status |
+|---------|-------|------------|--------|
+| 15.x | 19.x | 5.8+ | ✅ Supported |
+| 14.x | 18.x | 5.x | ⚠️ Legacy |
+| 13.x | 18.x | 5.x | ❌ Not Supported |
+
+---
+
+## Technology Alternatives
+
+### Authentication Alternatives
+
+| Alternative | Pros | Cons |
+|-------------|------|------|
+| **NextAuth.js** | Open source, flexible | More setup required |
+| **Auth0** | Enterprise features | Expensive for small teams |
+| **Supabase Auth** | Built-in to Supabase | Less feature-rich than Clerk |
+
+### Database Alternatives
+
+| Alternative | Pros | Cons |
+|-------------|------|------|
+| **Prisma** | More features | Larger bundle size |
+| **TypeORM** | Mature, widely used | Less type-safe than Drizzle |
+| **Sequelize** | Mature, SQL/NoSQL support | Less TypeScript support |
+
+### API Framework Alternatives
+
+| Alternative | Pros | Cons |
+|-------------|------|------|
+| **Express** | Widely used | Less type-safe |
+| **tRPC** | End-to-end type safety | Requires React on client |
+| **Fastify** | Fast performance | Less middleware ecosystem |
+
+### State Management Alternatives
+
+| Alternative | Pros | Cons |
+|-------------|------|------|
+| **Redux Toolkit** | Rich ecosystem | More boilerplate |
+| **SWR** | Simpler API | Fewer features than TanStack Query |
+| **Jotai** | Atomic state | Different mental model |
+
+---
+
+## Technology Roadmap
+
+### Current Stack (v0.1.0)
+
+- ✅ Next.js 15 with App Router
+- ✅ Clerk Authentication
+- ✅ Supabase Database & Storage
+- ✅ Drizzle ORM
+- ✅ Hono API
+- ✅ TanStack Query & Zustand
+- ✅ Snowflake Integration
+
+### Potential Future Additions
+
+- 🔄 Real-time subscriptions (Supabase Realtime)
+- 🔄 Email service (Resend/SendGrid)
+- 🔄 File processing (FFmpeg/ImageMagick)
+- 🔄 Caching layer (Redis)
+- 🔄 Queue system (BullMQ)
+- 🔄 Monitoring (Sentry/Vercel Analytics)
+- 🔄 Testing (Vitest/Playwright)
+
+---
+
+## Related Documentation
+
+- [Environment Variables](./environment-variables.md) - Configuration details
+- [Clerk Authentication](./clerk-authentication.md) - Auth setup
+- [Supabase Integration](./supabase-integration.md) - Database setup
+- [Snowflake Integration](./snowflake-integration.md) - Data warehouse setup
+- [API Layer](./api-layer.md) - Hono API details
+- [State Management](./state-management.md) - State management patterns