@odvi/create-dtt-framework 0.1.6 → 0.1.8

package/template/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 DTT Framework
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/README.md

@@ -2,25 +2,64 @@
 
 This is a DTT Framework application created with the CLI.
 
-## Getting Started
+## Quick Start
 
-First, install dependencies:
+### Prerequisites
+
+- **Node.js** 20 or higher
+- **pnpm** 10 or higher
+- **Supabase account** ([Sign up](https://supabase.com/))
+- **Clerk account** ([Sign up](https://clerk.com/))
+- **Snowflake account** (optional)
+
+### 1. Environment Setup
+
+Copy the example environment file and fill in your credentials:
 
 ```bash
-pnpm install
+cp .env.example .env
 ```
 
-Then, run the development server:
+Edit `.env` and fill in the required keys for Clerk and Supabase. See [Environment Variables](docs/framework/environment-variables.md) for details.
+
+### 2. Database Setup
+
+Push the database schema to your Supabase project:
+
+```bash
+pnpm db:push
+```
+
+This will create the necessary tables, including `health_check_tests` required for the health dashboard.
+
+### 3. Deploy Edge Functions
+
+The health check system requires a Supabase Edge Function. Deploy it using the Supabase CLI:
+
+```bash
+# Login to Supabase
+npx supabase login
+
+# Link your project (get your-project-ref from Supabase dashboard URL)
+npx supabase link --project-ref your-project-ref
+
+# Deploy the function
+npx supabase functions deploy health-check
+```
+
+### 4. Start Development Server
 
 ```bash
 pnpm dev
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+Open [http://localhost:3000](http://localhost:3000) with your browser.
+
+### 5. Verify Health
 
-## Learn More
+Visit [http://localhost:3000/health](http://localhost:3000/health) to verify all services are connected and working.
 
-To learn more about DTT Framework, visit the [documentation](./docs/framework/01-overview.md).
+---
 
 ## Documentation
 
@@ -28,3 +67,114 @@ To learn more about DTT Framework, visit the [documentation](./docs/framework/01
 - [Tech Stack](./docs/framework/02-techstack.md)
 - [Environment Variables](./docs/framework/environment-variables.md)
 - [CLI Installation](./docs/framework/cli-installation.md)
+- [Health Check System](./docs/framework/health-check-system.md)
+- [Clerk Authentication](./docs/framework/clerk-authentication.md)
+- [Supabase Integration](./docs/framework/supabase-integration.md)
+- [Snowflake Integration](./docs/framework/snowflake-integration.md)
+
+## Key Features
+
+### 1. Authentication & User Management
+- **Clerk Integration**: Complete authentication solution with sign-in, sign-up, and user management
+- **Organization Support**: Multi-tenant architecture with organization memberships
+- **Webhook Synchronization**: Automatic user data sync to local database
+- **Protected Routes**: Middleware-based route protection
+
+### 2. Database Layer
+- **PostgreSQL**: Robust relational database via Supabase
+- **Drizzle ORM**: Type-safe database queries with excellent TypeScript support
+- **Connection Pooling**: Optimized for Supabase Transaction mode
+- **Schema Management**: Migration-based schema evolution
+
+### 3. Storage & Edge Computing
+- **Supabase Storage**: File upload/download with signed URLs
+- **Edge Functions**: Serverless compute with auth header passthrough
+- **Bucket Management**: Organized file storage structure
+
+### 4. Data Warehouse
+- **Snowflake Integration**: Direct connection to Snowflake data warehouse
+- **Query Execution**: Execute SQL queries from the application
+- **Warehouse Configuration**: Support for multiple warehouses and databases
+
+### 5. API Layer
+- **Hono Framework**: Lightweight and fast API framework
+- **Middleware Support**: Authentication, logging, CORS
+- **Route Organization**: Modular route structure
+- **Type Safety**: Full TypeScript support with inferred types
+
+### 6. State Management
+- **TanStack Query**: Server state management with caching and synchronization
+- **Zustand**: Lightweight client state management
+- **React Hooks**: Custom hooks for common patterns
+
+### 7. Health Check System
+- **Comprehensive Monitoring**: Health checks for all integrated services
+- **Dashboard UI**: Visual health status display
+- **Response Time Tracking**: Performance monitoring
+- **Error Reporting**: Detailed error messages and status codes
+
+### 8. Developer Experience
+- **TypeScript**: Full type safety across the stack
+- **Tailwind CSS**: Utility-first styling
+- **Shadcn/ui**: Beautiful, accessible UI components
+- **Hot Reload**: Fast development with Next.js Turbo
+- **Linting & Formatting**: ESLint and Prettier configured
+
+## Folder Structure
+
+```
+dtt-framework/
+├── docs/                          # Framework documentation
+├── public/                        # Static assets
+├── src/                           # Source code
+│   ├── app/                       # Next.js App Router
+│   ├── components/                # React components
+│   ├── features/                  # Feature modules
+│   ├── hooks/                     # React hooks
+│   ├── lib/                       # Utility libraries and clients
+│   ├── server/                    # Server-side code (API, database)
+│   ├── stores/                    # Zustand state stores
+│   ├── types/                     # TypeScript types
+│   ├── config/                    # Configuration files
+│   ├── env.js                     # Environment variables
+│   ├── middleware.ts              # Next.js middleware
+│   └── styles/                    # Styles
+├── .env.example                   # Environment variables template
+├── drizzle.config.ts              # Drizzle ORM configuration
+├── next.config.js                 # Next.js configuration
+├── package.json                   # Dependencies and scripts
+└── README.md                      # This file
+```
+
+## Development
+
+### Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm dev` | Start development server with Turbo |
+| `pnpm build` | Build for production |
+| `pnpm start` | Start production server |
+| `pnpm lint` | Run ESLint |
+| `pnpm format:write` | Format code with Prettier |
+| `pnpm typecheck` | Run TypeScript type checking |
+| `pnpm db:generate` | Generate database migrations |
+| `pnpm db:migrate` | Apply database migrations |
+| `pnpm db:push` | Push schema changes to database |
+| `pnpm db:studio` | Open Drizzle Studio |
+
+## Deployment
+
+For deployment instructions, please refer to the [Deployment Guide](docs/framework/deployment/vercel.md).
+
+## Support
+
+If you need help:
+
+1. **Check the documentation** in `docs/` folder
+2. **Check the health dashboard** at `/health`
+3. **Open an issue** on GitHub
+
+## License
+
+MIT

package/template/drizzle/0000_awesome_argent.sql

@@ -0,0 +1,18 @@
+CREATE TABLE "users" (
+	"id" text PRIMARY KEY NOT NULL,
+	"email" varchar(255) NOT NULL,
+	"first_name" varchar(255),
+	"last_name" varchar(255),
+	"image_url" text,
+	"clerk_org_id" text,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"updated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "users_email_unique" UNIQUE("email")
+);
+--> statement-breakpoint
+CREATE TABLE "health_check_tests" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"test_key" text NOT NULL,
+	"test_value" text,
+	"created_at" timestamp DEFAULT now() NOT NULL
+);

package/template/drizzle/meta/0000_snapshot.json

@@ -0,0 +1,129 @@
+{
+  "id": "8ef2966f-b7b3-4fd4-adfc-84bfe2fdbf38",
+  "prevId": "00000000-0000-0000-0000-000000000000",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.users": {
+      "name": "users",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "first_name": {
+          "name": "first_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "last_name": {
+          "name": "last_name",
+          "type": "varchar(255)",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "image_url": {
+          "name": "image_url",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "clerk_org_id": {
+          "name": "clerk_org_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "users_email_unique": {
+          "name": "users_email_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "email"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.health_check_tests": {
+      "name": "health_check_tests",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "test_key": {
+          "name": "test_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "test_value": {
+          "name": "test_value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}

package/template/drizzle/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "postgresql",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "7",
+      "when": 1767269294126,
+      "tag": "0000_awesome_argent",
+      "breakpoints": true
+    }
+  ]
+}

package/template/eslint.config.js

@@ -0,0 +1,61 @@
+import { FlatCompat } from "@eslint/eslintrc";
+import tseslint from "typescript-eslint";
+// @ts-ignore -- no types for this plugin
+import drizzle from "eslint-plugin-drizzle";
+
+const compat = new FlatCompat({
+  baseDirectory: import.meta.dirname,
+});
+
+export default tseslint.config(
+  {
+    ignores: [".next"],
+  },
+  ...compat.extends("next/core-web-vitals"),
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    plugins: {
+      drizzle,
+    },
+    extends: [
+      ...tseslint.configs.recommended,
+      ...tseslint.configs.recommendedTypeChecked,
+      ...tseslint.configs.stylisticTypeChecked,
+    ],
+    rules: {
+      "@typescript-eslint/array-type": "off",
+      "@typescript-eslint/consistent-type-definitions": "off",
+      "@typescript-eslint/consistent-type-imports": [
+        "warn",
+        { prefer: "type-imports", fixStyle: "inline-type-imports" },
+      ],
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        { argsIgnorePattern: "^_" },
+      ],
+      "@typescript-eslint/require-await": "off",
+      "@typescript-eslint/no-misused-promises": [
+        "error",
+        { checksVoidReturn: { attributes: false } },
+      ],
+      "drizzle/enforce-delete-with-where": [
+        "error",
+        { drizzleObjectName: ["db", "ctx.db"] },
+      ],
+      "drizzle/enforce-update-with-where": [
+        "error",
+        { drizzleObjectName: ["db", "ctx.db"] },
+      ],
+    },
+  },
+  {
+    linterOptions: {
+      reportUnusedDisableDirectives: true,
+    },
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+      },
+    },
+  },
+);

package/template/start-database.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Use this script to start a docker container for a local development database
+
+# TO RUN ON WINDOWS:
+# 1. Install WSL (Windows Subsystem for Linux) - https://learn.microsoft.com/en-us/windows/wsl/install
+# 2. Install Docker Desktop or Podman Deskop
+# - Docker Desktop for Windows - https://docs.docker.com/docker-for-windows/install/
+# - Podman Desktop - https://podman.io/getting-started/installation
+# 3. Open WSL - `wsl`
+# 4. Run this script - `./start-database.sh`
+
+# On Linux and macOS you can run this script directly - `./start-database.sh`
+
+# import env variables from .env
+set -a
+source .env
+
+DB_PASSWORD=$(echo "$DATABASE_URL" | awk -F':' '{print $3}' | awk -F'@' '{print $1}')
+DB_PORT=$(echo "$DATABASE_URL" | awk -F':' '{print $4}' | awk -F'\/' '{print $1}')
+DB_NAME=$(echo "$DATABASE_URL" | awk -F'/' '{print $4}')
+DB_CONTAINER_NAME="$DB_NAME-postgres"
+
+if ! [ -x "$(command -v docker)" ] && ! [ -x "$(command -v podman)" ]; then
+  echo -e "Docker or Podman is not installed. Please install docker or podman and try again.\nDocker install guide: https://docs.docker.com/engine/install/\nPodman install guide: https://podman.io/getting-started/installation"
+  exit 1
+fi
+
+# determine which docker command to use
+if [ -x "$(command -v docker)" ]; then
+  DOCKER_CMD="docker"
+elif [ -x "$(command -v podman)" ]; then
+  DOCKER_CMD="podman"
+fi
+
+if ! $DOCKER_CMD info > /dev/null 2>&1; then
+  echo "$DOCKER_CMD daemon is not running. Please start $DOCKER_CMD and try again."
+  exit 1
+fi
+
+if command -v nc >/dev/null 2>&1; then
+  if nc -z localhost "$DB_PORT" 2>/dev/null; then
+    echo "Port $DB_PORT is already in use."
+    exit 1
+  fi
+else
+  echo "Warning: Unable to check if port $DB_PORT is already in use (netcat not installed)"
+  read -p "Do you want to continue anyway? [y/N]: " -r REPLY
+  if ! [[ $REPLY =~ ^[Yy]$ ]]; then
+    echo "Aborting."
+    exit 1
+  fi
+fi
+
+if [ "$($DOCKER_CMD ps -q -f name=$DB_CONTAINER_NAME)" ]; then
+  echo "Database container '$DB_CONTAINER_NAME' already running"
+  exit 0
+fi
+
+if [ "$($DOCKER_CMD ps -q -a -f name=$DB_CONTAINER_NAME)" ]; then
+  $DOCKER_CMD start "$DB_CONTAINER_NAME"
+  echo "Existing database container '$DB_CONTAINER_NAME' started"
+  exit 0
+fi
+
+if [ "$DB_PASSWORD" = "password" ]; then
+  echo "You are using the default database password"
+  read -p "Should we generate a random password for you? [y/N]: " -r REPLY
+  if ! [[ $REPLY =~ ^[Yy]$ ]]; then
+    echo "Please change the default password in the .env file and try again"
+    exit 1
+  fi
+  # Generate a random URL-safe password
+  DB_PASSWORD=$(openssl rand -base64 12 | tr '+/' '-_')
+  if [[ "$(uname)" == "Darwin" ]]; then
+    # macOS requires an empty string to be passed with the `i` flag
+    sed -i '' "s#:password@#:$DB_PASSWORD@#" .env
+  else
+    sed -i "s#:password@#:$DB_PASSWORD@#" .env
+  fi
+fi
+
+$DOCKER_CMD run -d \
+  --name $DB_CONTAINER_NAME \
+  -e POSTGRES_USER="postgres" \
+  -e POSTGRES_PASSWORD="$DB_PASSWORD" \
+  -e POSTGRES_DB="$DB_NAME" \
+  -p "$DB_PORT":5432 \
+  docker.io/postgres && echo "Database container '$DB_CONTAINER_NAME' was successfully created"

package/template/supabase/.temp/cli-latest

@@ -0,0 +1 @@
+v2.67.1

package/template/supabase/functions/health-check/index.ts

@@ -0,0 +1,84 @@
+// Follow this setup guide to deploy the function:
+// https://supabase.com/docs/guides/functions/deploy
+
+import { serve } from "https://deno.land/std@0.168.0/http/server.ts"
+
+const corsHeaders = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
+}
+
+serve(async (req) => {
+  if (req.method === 'OPTIONS') {
+    return new Response('ok', { headers: corsHeaders })
+  }
+
+  try {
+    const { message } = await req.json()
+    let authHeader = req.headers.get('Authorization')
+    const testAuthHeader = req.headers.get('x-test-auth')
+
+    // Handle ping check
+    if (message === 'ping') {
+      return new Response(
+        JSON.stringify({
+          message: 'pong',
+          timestamp: new Date().toISOString(),
+        }),
+        {
+          headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+          status: 200,
+        },
+      )
+    }
+
+    // Handle auth check
+    if (message === 'auth-check') {
+      // Prioritize test header if present (allows testing without bypassing Supabase Gateway auth)
+      if (testAuthHeader) {
+        authHeader = testAuthHeader
+      }
+
+      if (!authHeader) {
+        return new Response(
+          JSON.stringify({ error: 'No authorization header provided' }),
+          {
+            headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+            status: 401,
+          },
+        )
+      }
+
+      return new Response(
+        JSON.stringify({
+          message: 'Auth header received',
+          hasAuth: true,
+          // Don't log/return the full token in production for security
+          tokenPrefix: authHeader.substring(0, 10) + '...',
+          source: testAuthHeader ? 'x-test-auth' : 'Authorization'
+        }),
+        {
+          headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+          status: 200,
+        },
+      )
+    }
+
+    return new Response(
+      JSON.stringify({ error: 'Unknown message type' }),
+      {
+        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+        status: 400,
+      },
+    )
+  } catch (error) {
+    return new Response(
+      JSON.stringify({ error: error.message }),
+      {
+        headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+        status: 400,
+      },
+    )
+  }
+})
+