@odvi/create-dtt-framework 0.1.2 → 0.1.5

package/template/docs/framework/what-did-i-miss.md

@@ -0,0 +1,526 @@
+# DTT Framework - What Did I Miss
+
+## Overview
+
+This document outlines potential improvements, features not included, and considerations for production use. While the DTT Framework provides a solid foundation, there are always areas for enhancement.
+
+---
+
+## Potential Improvements
+
+### 1. Testing Infrastructure
+
+**Current State:**
+- No test suite included
+- No CI/CD configuration
+- No test coverage reporting
+
+**Recommended Improvements:**
+
+- **Unit Tests**: Add Vitest for unit testing
+- **Component Tests**: Add React Testing Library for components
+- **E2E Tests**: Add Playwright for end-to-end testing
+- **CI/CD**: Add GitHub Actions for automated testing and deployment
+- **Coverage**: Add coverage reporting with `vitest --coverage`
+
+**Priority:** High - Testing is essential for maintainability
+
+### 2. Error Handling
+
+**Current State:**
+- Basic try-catch in API routes
+- No global error handler
+- No error logging service
+
+**Recommended Improvements:**
+
+- **Global Error Handler**: Add centralized error handling in Hono
+- **Error Logging**: Integrate Sentry or similar service
+- **Error Boundaries**: Add React Error Boundaries for client-side errors
+- **Custom Error Pages**: Add 404, 500, and other error pages
+- **Error Types**: Define custom error types for better error handling
+
+**Priority:** High - Error handling is critical for production
+
+### 3. Performance Monitoring
+
+**Current State:**
+- Response time tracking in health checks
+- No performance monitoring
+- No analytics
+
+**Recommended Improvements:**
+
+- **Vercel Analytics**: Add Vercel Analytics for performance monitoring
+- **Web Vitals**: Add web-vitals library for Core Web Vitals
+- **APM**: Add Application Performance Monitoring (e.g., Datadog, New Relic)
+- **Performance Budgets**: Define and enforce performance budgets
+- **Bundle Analysis**: Add bundle analyzer to monitor bundle size
+
+**Priority:** Medium - Important for production monitoring
+
+### 4. Internationalization (i18n)
+
+**Current State:**
+- No i18n support
+- Hardcoded English text
+
+**Recommended Improvements:**
+
+- **next-intl**: Add next-intl for internationalization
+- **Language Detection**: Auto-detect user's preferred language
+- **Translation Files**: Add translation files for supported languages
+- **RTL Support**: Add right-to-left language support
+
+**Priority:** Low - Only needed if supporting multiple languages
+
+### 5. Accessibility (a11y)
+
+**Current State:**
+- Shadcn/ui components are accessible
+- No comprehensive a11y testing
+- No a11y audit
+
+**Recommended Improvements:**
+
+- **axe-core**: Add axe-core for accessibility testing
+- **Playwright a11y**: Add Playwright accessibility testing
+- **ARIA Labels**: Ensure all interactive elements have ARIA labels
+- **Keyboard Navigation**: Ensure full keyboard navigation support
+- **Screen Reader Testing**: Test with screen readers
+
+**Priority:** Medium - Accessibility is important for inclusive design
+
+### 6. SEO Optimization
+
+**Current State:**
+- Basic meta tags
+- No structured data
+- No sitemap
+
+**Recommended Improvements:**
+
+- **Metadata API**: Use Next.js Metadata API for better SEO
+- **Structured Data**: Add JSON-LD for structured data
+- **Sitemap**: Generate sitemap.xml
+- **Robots.txt**: Add robots.txt
+- **Open Graph**: Add Open Graph tags for social sharing
+
+**Priority:** Low - Only needed for public-facing applications
+
+### 7. Security Enhancements
+
+**Current State:**
+- Basic auth middleware
+- Environment variables for secrets
+- No rate limiting
+- No CSRF protection
+
+**Recommended Improvements:**
+
+- **Rate Limiting**: Add rate limiting to API routes
+- **CSRF Protection**: Add CSRF tokens for form submissions
+- **CSP Headers**: Add Content Security Policy headers
+- **Security Headers**: Add security-related headers (HSTS, X-Frame-Options, etc.)
+- **Dependency Scanning**: Add automated dependency scanning
+
+**Priority:** High - Security is critical for production
+
+---
+
+## Features Not Included
+
+### 1. Real-time Features
+
+**Not Included:**
+- Real-time database subscriptions
+- WebSocket connections
+- Live updates
+
+**Potential Implementation:**
+- Use Supabase Realtime for real-time database subscriptions
+- Add WebSocket support for live updates
+- Implement server-sent events for push notifications
+
+### 2. File Processing
+
+**Not Included:**
+- Image processing
+- Video transcoding
+- Document conversion
+
+**Potential Implementation:**
+- Add Sharp for image processing
+- Add FFmpeg for video transcoding
+- Add file conversion utilities
+
+### 3. Email Service
+
+**Not Included:**
+- Email sending
+- Email templates
+- Email notifications
+
+**Potential Implementation:**
+- Add Resend or SendGrid for email sending
+- Add email templates with React Email
+- Add email notification system
+
+### 4. Background Jobs
+
+**Not Included:**
+- Job queue
+- Scheduled tasks
+- Background processing
+
+**Potential Implementation:**
+- Add BullMQ for job queuing
+- Add cron jobs for scheduled tasks
+- Implement background job processing
+
+### 5. Caching Layer
+
+**Not Included:**
+- Redis caching
+- CDN caching
+- API response caching
+
+**Potential Implementation:**
+- Add Redis for caching
+- Configure CDN for static assets
+- Implement API response caching
+
+### 6. Advanced Authentication Features
+
+**Not Included:**
+- Multi-factor authentication (MFA)
+- Social login providers
+- Passwordless authentication
+
+**Potential Implementation:**
+- Enable Clerk MFA
+- Add social login providers (Google, GitHub, etc.)
+- Implement magic link authentication
+
+### 7. Admin Panel
+
+**Not Included:**
+- Admin dashboard
+- User management
+- System configuration
+
+**Potential Implementation:**
+- Build admin panel for user management
+- Add system configuration interface
+- Implement admin analytics
+
+### 8. Analytics Dashboard
+
+**Not Included:**
+- User analytics
+- Usage metrics
+- Custom dashboards
+
+**Potential Implementation:**
+- Add analytics tracking
+- Build custom dashboards
+- Implement usage metrics
+
+---
+
+## Future Enhancements
+
+### 1. Mobile App Support
+
+**Potential:**
+- Add React Native or Expo for mobile app
+- Share API between web and mobile
+- Implement authentication for mobile
+
+### 2. Progressive Web App (PWA)
+
+**Potential:**
+- Add PWA support with next-pwa
+- Add offline support
+- Add push notifications
+
+### 3. GraphQL Support
+
+**Potential:**
+- Add GraphQL API alongside REST
+- Use Apollo Server or Yoga
+- Implement GraphQL subscriptions
+
+### 4. Microservices Architecture
+
+**Potential:**
+- Split into microservices
+- Use service mesh
+- Implement service discovery
+
+### 5. Event-Driven Architecture
+
+**Potential:**
+- Add event bus (e.g., Kafka, RabbitMQ)
+- Implement event sourcing
+- Add CQRS pattern
+
+---
+
+## Production Considerations
+
+### 1. Database Scaling
+
+**Considerations:**
+- **Connection Pooling**: Ensure proper connection pooling configuration
+- **Read Replicas**: Use read replicas for read-heavy workloads
+- **Database Sharding**: Consider sharding for very large datasets
+- **Backup Strategy**: Implement automated backups
+- **Monitoring**: Monitor database performance
+
+### 2. API Rate Limiting
+
+**Considerations:**
+- **Per-User Limits**: Implement per-user rate limits
+- **Per-IP Limits**: Implement per-IP rate limits
+- **Burst Handling**: Handle burst traffic gracefully
+- **Rate Limit Headers**: Include rate limit headers in responses
+
+### 3. CDN Configuration
+
+**Considerations:**
+- **Static Assets**: Serve static assets from CDN
+- **API Caching**: Cache API responses at CDN level
+- **Edge Computing**: Use edge computing for faster responses
+- **Cache Invalidation**: Implement cache invalidation strategy
+
+### 4. Monitoring and Alerting
+
+**Considerations:**
+- **Uptime Monitoring**: Use uptime monitoring services
+- **Error Tracking**: Use error tracking services (Sentry, Rollbar)
+- **Performance Monitoring**: Use APM tools (Datadog, New Relic)
+- **Alerting**: Set up alerts for critical issues
+- **Dashboards**: Create monitoring dashboards
+
+### 5. Deployment Strategy
+
+**Considerations:**
+- **Blue-Green Deployment**: Use blue-green deployment for zero downtime
+- **Canary Releases**: Use canary releases for gradual rollout
+- **Rollback Strategy**: Implement quick rollback strategy
+- **Environment Promotion**: Use proper environment promotion (dev → staging → prod)
+
+### 6. Security Hardening
+
+**Considerations:**
+- **Security Audit**: Conduct regular security audits
+- **Penetration Testing**: Perform penetration testing
+- **Dependency Updates**: Keep dependencies up to date
+- **Security Headers**: Implement all recommended security headers
+- **Input Validation**: Validate all user inputs
+
+### 7. Disaster Recovery
+
+**Considerations:**
+- **Backup Strategy**: Implement automated backups
+- **Disaster Recovery Plan**: Create disaster recovery plan
+- **Failover Strategy**: Implement failover strategy
+- **Data Replication**: Replicate data across regions
+- **Testing**: Regularly test disaster recovery procedures
+
+---
+
+## Known Limitations
+
+### 1. Single Database
+
+**Limitation:**
+- Only supports PostgreSQL via Supabase
+- No support for other databases
+
+**Workaround:**
+- Use database abstraction layer for multi-database support
+- Use database-agnostic ORM (e.g., Prisma)
+
+### 2. Single Auth Provider
+
+**Limitation:**
+- Only supports Clerk for authentication
+- No support for other auth providers
+
+**Workaround:**
+- Use auth abstraction layer for multi-provider support
+- Implement custom auth with NextAuth.js
+
+### 3. No Multi-Tenancy
+
+**Limitation:**
+- Organization support is basic
+- No advanced multi-tenancy features
+
+**Workaround:**
+- Implement advanced multi-tenancy with row-level security
+- Use tenant-aware queries
+
+### 4. Limited Real-time
+
+**Limitation:**
+- No real-time features implemented
+- Supabase Realtime not configured
+
+**Workaround:**
+- Implement real-time with Supabase Realtime
+- Use WebSocket for custom real-time features
+
+---
+
+## Lessons Learned
+
+### 1. Service Integration Complexity
+
+**Observation:**
+Integrating multiple third-party services (Clerk, Supabase, Snowflake) requires careful coordination of authentication, configuration, and error handling.
+
+**Takeaways:**
+- Each service has its own authentication mechanism and SDK quirks
+- Environment variable management becomes critical as the number of services grows
+- Health checks are essential for debugging integration issues
+- Documentation for each service varies in quality and completeness
+
+**Recommendation:**
+Start with a single service and add others incrementally. Build health checks early in the integration process.
+
+### 2. Type Safety Trade-offs
+
+**Observation:**
+While TypeScript provides excellent type safety, maintaining type consistency across service boundaries can be challenging.
+
+**Takeaways:**
+- Zod schemas are invaluable for runtime validation
+- Type inference from ORMs (Drizzle) saves time but requires careful schema design
+- Environment variable validation prevents runtime errors
+- Generated types from SDKs can sometimes be overly complex
+
+**Recommendation:**
+Invest time in creating shared type definitions and validation schemas early in the project.
+
+### 3. State Management Decisions
+
+**Observation:**
+Choosing between server state (TanStack Query) and client state (Zustand) requires understanding the data lifecycle.
+
+**Takeaways:**
+- Server state should be cached and synchronized with the backend
+- Client state should be limited to UI-specific concerns
+- Mixing concerns leads to complex bugs and hard-to-debug issues
+- TanStack Query's caching and invalidation strategies are powerful but require learning
+
+**Recommendation:**
+Clearly separate server state from client state in your architecture. Use TanStack Query for all data fetched from APIs and Zustand for UI state only.
+
+### 4. Database Connection Management
+
+**Observation:**
+Connection pooling configuration significantly impacts performance, especially with serverless functions.
+
+**Takeaways:**
+- Supabase Transaction mode requires specific connection string format
+- Connection leaks can occur if connections aren't properly closed
+- Serverless environments need connection pooling for performance
+- Drizzle's `prepare: false` option is required for Supabase pooling
+
+**Recommendation:**
+Always use connection pooling in production. Test connection behavior under load to identify issues early.
+
+### 5. Health Check Design
+
+**Observation:**
+A well-designed health check system is invaluable for debugging and monitoring, but requires thoughtful design.
+
+**Takeaways:**
+- Health checks should be fast and non-destructive
+- Response time tracking provides valuable performance insights
+- Status types (healthy, unhealthy, error, unconfigured) help distinguish issues
+- Aggregated health checks simplify monitoring
+
+**Recommendation:**
+Design health checks to be idempotent and fast. Include detailed error messages for debugging but keep the UI simple.
+
+### 6. API Layer Architecture
+
+**Observation:**
+Using Hono for the API layer provides a lightweight, type-safe alternative to Next.js API routes.
+
+**Takeaways:**
+- Hono's middleware system is elegant and composable
+- Type inference works well with TypeScript
+- Mounting Hono in Next.js requires careful configuration
+- Hono's performance is excellent for API endpoints
+
+**Recommendation:**
+Consider Hono for API-heavy applications. Its lightweight nature and excellent TypeScript support make it a great choice.
+
+### 7. Testing Strategy
+
+**Observation:**
+Testing is often neglected in boilerplate projects but is critical for long-term maintainability.
+
+**Takeaways:**
+- Unit tests are essential for business logic
+- Integration tests are valuable for service integrations
+- E2E tests catch issues that unit tests miss
+- Test coverage should be tracked and improved over time
+
+**Recommendation:**
+Set up testing infrastructure early. Write tests alongside features, not as an afterthought.
+
+### 8. Documentation Importance
+
+**Observation:**
+Good documentation is as important as good code, especially for framework projects.
+
+**Takeaways:**
+- Documentation should explain "why" not just "how"
+- Examples should be copy-pasteable and work out of the box
+- Troubleshooting sections save hours of debugging
+- Architecture diagrams help with mental models
+
+**Recommendation:**
+Document as you build. Keep documentation up to date with code changes.
+
+### 9. Environment Variable Management
+
+**Observation:**
+As the number of services grows, environment variable management becomes complex.
+
+**Takeaways:**
+- Validation at build time catches configuration errors early
+- Grouping related variables improves readability
+- Comments explaining each variable are essential
+- Separate .env files for different environments help prevent mistakes
+
+**Recommendation:**
+Use a validation library like `@t3-oss/env-nextjs` for type-safe environment variables.
+
+### 10. Performance Considerations
+
+**Observation:**
+Performance optimization should be considered from the start, not as an afterthought.
+
+**Takeaways:**
+- Bundle size impacts initial load time
+- Database query performance affects API response times
+- Caching strategies can dramatically improve perceived performance
+- Monitoring is necessary to identify performance bottlenecks
+
+**Recommendation:**
+Set up performance monitoring early. Optimize critical paths first.
+
+---
+
+## Related Documentation
+
+- [Overview](./01-overview.md) - Framework introduction
+- [Implementation](./implementation.md) - How framework was built
+- [Testing Guide](./testing-guide.md) - Testing patterns

package/template/drizzle.config.ts

@@ -0,0 +1,12 @@
+import { type Config } from "drizzle-kit";
+
+import { env } from "~/env";
+
+export default {
+  schema: "./src/server/db/schema.ts",
+  dialect: "postgresql",
+  dbCredentials: {
+    url: env.DATABASE_URL,
+  },
+  tablesFilter: ["dtt-framework_*"],
+} satisfies Config;

package/template/next.config.js

@@ -0,0 +1,21 @@
+/**
+ * Run `build` or `dev` with `SKIP_ENV_VALIDATION` to skip env validation. This is especially useful
+ * for Docker builds.
+ */
+import "./src/env.js";
+
+/** @type {import("next").NextConfig} */
+const config = {
+  serverExternalPackages: ["snowflake-sdk"],
+  eslint: {
+    ignoreDuringBuilds: true,
+  },
+  outputFileTracingIncludes: {
+    "/": ["./docs/**/*", "./README.md", "./DESIGN.md", "./cli/template/README.md"],
+    "/*": ["./docs/**/*", "./README.md", "./DESIGN.md", "./cli/template/README.md"],
+  },
+  experimental: {
+  },
+};
+
+export default config;

package/template/postcss.config.js

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};

package/template/prettier.config.js

@@ -0,0 +1,4 @@
+/** @type {import('prettier').Config & import('prettier-plugin-tailwindcss').PluginOptions} */
+export default {
+  plugins: ["prettier-plugin-tailwindcss"],
+};

package/template/src/app/(auth)/layout.tsx

@@ -0,0 +1,4 @@
+// Auth layout placeholder
+export default function AuthLayout({ children }: { children: React.ReactNode }) {
+  return <div>{children}</div>
+}

package/template/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx

@@ -0,0 +1,10 @@
+// Clerk Sign In page placeholder
+import { SignIn } from '@clerk/nextjs'
+
+export default function SignInPage() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <SignIn />
+    </div>
+  )
+}

package/template/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx

@@ -0,0 +1,10 @@
+// Clerk Sign Up page placeholder
+import { SignUp } from '@clerk/nextjs'
+
+export default function SignUpPage() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <SignUp />
+    </div>
+  )
+}

package/template/src/app/(dashboard)/dashboard/page.tsx

@@ -0,0 +1,8 @@
+// Dashboard index page placeholder
+export default function DashboardPage() {
+  return (
+    <div className="container py-8">
+      <h1 className="text-2xl font-semibold">Dashboard</h1>
+    </div>
+  )
+}

package/template/src/app/(dashboard)/health/page.tsx

@@ -0,0 +1,16 @@
+// Health check dashboard page placeholder
+import { HealthDashboard } from '@/features/health-check'
+
+export default function HealthPage() {
+  return (
+    <div className="container mx-auto py-8">
+      <div className="mb-8">
+        <h1 className="text-2xl font-semibold">Health Check Dashboard</h1>
+        <p className="text-muted-foreground">
+          Verify all services are connected and working correctly.
+        </p>
+      </div>
+      <HealthDashboard />
+    </div>
+  )
+}

package/template/src/app/(dashboard)/layout.tsx

@@ -0,0 +1,17 @@
+// Dashboard layout placeholder
+import { UserButton } from '@clerk/nextjs'
+import Link from 'next/link'
+
+export default function DashboardLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <div className="min-h-screen bg-background">
+      <header className="border-b">
+        <div className="container mx-auto flex h-14 items-center justify-between">
+          <Link href="/" className="font-semibold">DTT Framework</Link>
+          <UserButton afterSignOutUrl="/sign-in" />
+        </div>
+      </header>
+      <main>{children}</main>
+    </div>
+  )
+}

package/template/src/app/api/[[...route]]/route.ts

@@ -0,0 +1,11 @@
+// Hono catch-all route placeholder
+import { handle } from 'hono/vercel'
+import { app } from '@/server/api'
+
+export const runtime = 'nodejs'
+
+export const GET = handle(app)
+export const POST = handle(app)
+export const PUT = handle(app)
+export const DELETE = handle(app)
+export const PATCH = handle(app)

package/template/src/app/api/debug-files/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from 'next/server';
+import fs from 'fs';
+import path from 'path';
+
+export async function GET() {
+  const root = process.cwd();
+  const files: any = {
+    root,
+    rootFiles: [],
+    docsFiles: [],
+    docsExists: false,
+  };
+
+  try {
+    files.rootFiles = await fs.promises.readdir(root);
+  } catch (e: any) {
+    files.rootError = e.message;
+  }
+
+  try {
+    const docsPath = path.join(root, 'docs');
+    files.docsPath = docsPath;
+    files.docsExists = fs.existsSync(docsPath);
+    if (files.docsExists) {
+        files.docsFiles = await fs.promises.readdir(docsPath);
+    }
+  } catch (e: any) {
+    files.docsError = e.message;
+  }
+
+  return NextResponse.json(files);
+}
+