create-atsdc-stack 1.0.0

package/app/README.md

@@ -0,0 +1,251 @@
+# ATSDC Stack Application
+
+This is the main Astro application for the ATSDC Stack.
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Node.js >= 18.0.0
+- PostgreSQL database (Vercel Postgres, Neon, or local)
+- API keys for Clerk, OpenAI, and optionally Exa
+
+### Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Copy environment template
+cp .env.example .env
+
+# Configure your .env file with your credentials
+```
+
+### Environment Variables
+
+Create a `.env` file with the following variables:
+
+```env
+# Database
+DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
+
+# Clerk Authentication
+PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
+CLERK_SECRET_KEY="sk_test_..."
+
+# OpenAI (for Vercel AI SDK)
+OPENAI_API_KEY="sk-..."
+
+# Exa Search (optional)
+EXA_API_KEY="..."
+```
+
+### Database Setup
+
+```bash
+# Push schema to database
+npm run db:push
+
+# Or generate migrations
+npm run db:generate
+npm run db:migrate
+
+# Open Drizzle Studio (database GUI)
+npm run db:studio
+```
+
+### Development
+
+```bash
+# Start dev server
+npm run dev
+```
+
+Visit `http://localhost:4321`
+
+## 📝 Available Scripts
+
+- `npm run dev` - Start development server
+- `npm run build` - Build for production
+- `npm run preview` - Preview production build
+- `npm run astro` - Run Astro CLI commands
+- `npm run db:generate` - Generate database migrations
+- `npm run db:migrate` - Run database migrations
+- `npm run db:push` - Push schema changes to database
+- `npm run db:studio` - Open Drizzle Studio
+
+## 📁 Project Structure
+
+```text
+src/
+├── components/         # Reusable Astro components
+├── db/                 # Database schema and client
+│   ├── initialize.ts   # Database initialization
+│   ├── schema.ts       # Drizzle ORM schemas
+│   └── validations.ts  # Zod validation schemas
+├── layouts/            # Page layouts
+│   └── Layout.astro
+├── lib/                # Utility libraries
+│   ├── config.ts       # App configuration
+│   ├── content-converter.ts # Markdown/HTML conversion
+│   ├── dom-utils.ts    # DOM manipulation
+│   └── exa-search.ts   # AI-powered search
+├── pages/              # Routes and pages
+│   ├── api/            # API endpoints
+│   │   ├── chat.ts     # AI chat endpoint
+│   │   └── posts.ts    # Posts CRUD
+│   └── index.astro     # Home page
+└── styles/             # SCSS stylesheets
+    ├── variables/      # SCSS variables and mixins
+    ├── components/     # Component styles
+    ├── pages/          # Page styles
+    ├── reset.scss      # CSS reset
+    └── global.scss     # Global styles
+```
+
+## 🎨 SCSS Architecture
+
+This app uses a strict SCSS architecture:
+
+- **No inline `<style>` tags** in `.astro` files
+- **All styles in external SCSS files** for better maintainability
+- **Data attributes for modifiers** (preferred over BEM)
+- **Semantic class names** (no utility classes)
+
+Example:
+
+```astro
+---
+import '@/styles/components/button.scss';
+---
+<button class="btn" data-variant="primary" data-size="lg">
+    Click Me
+</button>
+```
+
+## 🗄️ Database
+
+### Schema Definition
+
+Define your database schema in `src/db/schema.ts` using Drizzle ORM:
+
+```typescript
+export const posts = pgTable('posts', {
+    id: varchar('id', { length: 21 })
+        .primaryKey()
+        .$defaultFn(() => nanoid()),
+    title: varchar('title', { length: 255 }).notNull(),
+    content: text('content').notNull(),
+    createdAt: timestamp('created_at').defaultNow().notNull(),
+});
+```
+
+### Validation
+
+Define Zod schemas in `src/db/validations.ts`:
+
+```typescript
+export const createPostSchema = z.object({
+    title: z.string().min(1).max(255),
+    content: z.string().min(1),
+});
+```
+
+## 🔐 Authentication
+
+Authentication is handled by Clerk. Configure in `astro.config.mjs`:
+
+```javascript
+clerk({
+    afterSignInUrl: '/',
+    afterSignUpUrl: '/',
+})
+```
+
+## 🤖 AI Features
+
+### Vercel AI SDK
+
+Chat endpoint example in `src/pages/api/chat.ts`:
+
+```typescript
+import { OpenAI } from 'ai';
+
+export const POST: APIRoute = async ({ request }) => {
+    // AI chat implementation
+};
+```
+
+### Exa Search
+
+AI-powered search utilities in `src/lib/exa-search.ts`.
+
+## 📱 Progressive Web App
+
+This app includes PWA support with offline capabilities:
+
+- Service worker auto-generated
+- Installable on mobile/desktop
+- Offline caching configured in `astro.config.mjs`
+
+## 🚀 Deployment
+
+### Vercel (Recommended)
+
+```bash
+# Install Vercel CLI
+npm i -g vercel
+
+# Deploy
+vercel
+```
+
+Make sure to set these environment variables in your Vercel project settings:
+
+- `DATABASE_URL`
+- `PUBLIC_CLERK_PUBLISHABLE_KEY`
+- `CLERK_SECRET_KEY`
+- `OPENAI_API_KEY`
+- `EXA_API_KEY` (optional)
+
+## 📚 Documentation
+
+- [Astro Documentation](https://docs.astro.build)
+- [Drizzle ORM](https://orm.drizzle.team)
+- [Clerk](https://clerk.com/docs)
+- [Vercel AI SDK](https://sdk.vercel.ai/docs)
+- [Zod](https://zod.dev)
+- [Exa Search](https://docs.exa.ai)
+
+## 🛠️ Utilities
+
+### Content Conversion
+
+```typescript
+import { htmlToMarkdown, markdownToHtml } from '@/lib/content-converter';
+
+const markdown = htmlToMarkdown('<h1>Hello</h1>');
+const html = markdownToHtml('# Hello');
+```
+
+### DOM Manipulation
+
+```typescript
+import { extractText, findLinks } from '@/lib/dom-utils';
+
+const text = extractText(htmlString);
+const links = findLinks(htmlString);
+```
+
+### AI Search
+
+```typescript
+import { searchWithExa } from '@/lib/exa-search';
+
+const results = await searchWithExa('your query');
+```
+
+## 📄 License
+
+MIT

package/app/astro.config.mjs

@@ -0,0 +1,83 @@
+import { defineConfig } from 'astro/config';
+import react from '@astrojs/react';
+import vercel from '@astrojs/vercel';
+import clerk from '@clerk/astro';
+import { VitePWA } from 'vite-plugin-pwa';
+
+// https://astro.build/config
+export default defineConfig({
+    output: 'server',
+    adapter: vercel({
+        imageService: true,
+    }),
+    image: {
+        service: {
+            entrypoint: 'astro/assets/services/noop',
+        },
+    },
+    integrations: [
+        react(),
+        clerk({
+            afterSignInUrl: '/',
+            afterSignUpUrl: '/',
+        }),
+    ],
+    vite: {
+        plugins: [
+            VitePWA({
+                registerType: 'autoUpdate',
+                includeAssets: ['favicon.ico', 'apple-touch-icon.png', 'mask-icon.svg'],
+                manifest: {
+                    name: 'ATSDC Stack App',
+                    short_name: 'ATSDC',
+                    description: 'Progressive Web App built with the ATSDC Stack',
+                    theme_color: '#ffffff',
+                    background_color: '#ffffff',
+                    display: 'standalone',
+                    icons: [
+                        {
+                            src: 'pwa-192x192.png',
+                            sizes: '192x192',
+                            type: 'image/png',
+                        },
+                        {
+                            src: 'pwa-512x512.png',
+                            sizes: '512x512',
+                            type: 'image/png',
+                        },
+                        {
+                            src: 'pwa-512x512.png',
+                            sizes: '512x512',
+                            type: 'image/png',
+                            purpose: 'any maskable',
+                        },
+                    ],
+                },
+                workbox: {
+                    globPatterns: ['**/*.{js,css,html,ico,png,svg,woff2}'],
+                    runtimeCaching: [
+                        {
+                            urlPattern: /^https:\/\/api\./i,
+                            handler: 'NetworkFirst',
+                            options: {
+                                cacheName: 'api-cache',
+                                expiration: {
+                                maxEntries: 50,
+                                maxAgeSeconds: 60 * 60 * 24, // 24 hours
+                                },
+                            },
+                        },
+                    ],
+                },
+            }),
+        ],
+        css: {
+            preprocessorOptions: {
+                scss: {
+                    api: 'modern-compiler',
+                    additionalData: `@use "@/styles/variables/globals.scss" as *;`,
+                },
+            },
+        },
+    },
+});

package/app/drizzle.config.ts

@@ -0,0 +1,16 @@
+import type { Config } from 'drizzle-kit';
+
+if (!process.env.DATABASE_URL) {
+    throw new Error('DATABASE_URL environment variable is required');
+}
+
+export default {
+    schema: './src/db/schema.ts',
+    out: './drizzle',
+    dialect: 'postgresql',
+    dbCredentials: {
+        url: process.env.DATABASE_URL,
+    },
+    verbose: true,
+    strict: true,
+} satisfies Config;

package/app/package.json

@@ -0,0 +1,52 @@
+{
+    "name": "atsdc-app",
+    "version": "1.0.0",
+    "description": "ATSDC Stack - Astro application",
+    "type": "module",
+    "scripts": {
+        "dev": "astro dev",
+        "build": "astro check && astro build",
+        "preview": "astro preview",
+        "astro": "astro",
+        "db:generate": "drizzle-kit generate",
+        "db:migrate": "drizzle-kit migrate",
+        "db:push": "drizzle-kit push",
+        "db:studio": "drizzle-kit studio"
+    },
+    "dependencies": {
+        "@astrojs/check": "^0.9.6",
+        "@astrojs/react": "^4.4.2",
+        "@astrojs/vercel": "^9.0.2",
+        "@clerk/astro": "^1.4.3",
+        "@clerk/clerk-react": "^5.17.3",
+        "@rocicorp/zero": "^0.2.0",
+        "@vercel/postgres": "^0.10.0",
+        "ai": "^5.0.0",
+        "astro": "^5.16.6",
+        "cheerio": "^1.0.0",
+        "drizzle-orm": "^0.36.4",
+        "exa-js": "^1.1.1",
+        "marked": "^14.1.3",
+        "nanoid": "^5.0.9",
+        "open-props": "^1.7.17",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1",
+        "sass": "^1.82.0",
+        "turndown": "^7.2.0",
+        "typescript": "^5.7.2",
+        "zod": "^3.24.1"
+    },
+    "devDependencies": {
+        "@types/node": "^22.10.5",
+        "@types/react": "^18.3.18",
+        "@types/react-dom": "^18.3.5",
+        "@types/turndown": "^5.0.5",
+        "@vite-pwa/assets-generator": "^0.2.6",
+        "drizzle-kit": "^0.29.1",
+        "vercel": "^39.2.0",
+        "vite-plugin-pwa": "^0.21.2"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/app/public/manifest.webmanifest

@@ -0,0 +1,36 @@
+{
+  "name": "ATSDC Stack App",
+  "short_name": "ATSDC",
+  "description": "Progressive Web App built with the ATSDC Stack",
+  "start_url": "/",
+  "display": "standalone",
+  "background_color": "#ffffff",
+  "theme_color": "#4f46e5",
+  "orientation": "portrait-primary",
+  "icons": [
+    {
+      "src": "/pwa-192x192.png",
+      "sizes": "192x192",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/pwa-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "any"
+    },
+    {
+      "src": "/pwa-512x512.png",
+      "sizes": "512x512",
+      "type": "image/png",
+      "purpose": "maskable"
+    }
+  ],
+  "categories": [
+    "productivity",
+    "utilities"
+  ],
+  "screenshots": [],
+  "shortcuts": []
+}

package/app/src/components/Card.astro

@@ -0,0 +1,36 @@
+---
+/**
+ * Card Component
+ * Demonstrates proper SCSS architecture:
+ * - No <style> tag in this file
+ * - Styles imported from external SCSS file
+ * - Reusable component with props
+ */
+
+interface Props {
+    title?: string;
+    href?: string;
+    class?: string;
+}
+
+const { title, href, class: className = '' } = Astro.props;
+
+// Import component-specific styles
+import '@/styles/components/card.scss';
+---
+
+{href ? (
+    <a href={href} class={`card-component ${className}`}>
+        {title && <h3 class="card-component__title">{title}</h3>}
+        <div class="card-component__content">
+            <slot />
+        </div>
+    </a>
+) : (
+    <div class={`card-component ${className}`}>
+        {title && <h3 class="card-component__title">{title}</h3>}
+        <div class="card-component__content">
+            <slot />
+        </div>
+    </div>
+)}

package/app/src/db/initialize.ts

@@ -0,0 +1,107 @@
+import { sql } from '@vercel/postgres';
+import { drizzle } from 'drizzle-orm/vercel-postgres';
+import * as schema from './schema';
+import { posts, comments } from './schema';
+
+/**
+ * Database client configuration
+ * Uses Vercel Postgres for production-ready connection pooling
+ */
+
+// Create Drizzle instance with schema
+export const db = drizzle(sql, { schema });
+
+// Export schema for convenience
+export { schema };
+
+/**
+ * Database initialization utilities
+ * Handles table creation, migrations, and initial setup
+ */
+
+/**
+ * Check if the database tables exist by attempting a simple query
+ */
+export async function checkTablesExist(): Promise<boolean> {
+    try {
+        await db.select().from(posts).limit(1);
+        return true;
+    } catch (error) {
+        console.error('Error checking if tables exist:', error);
+        return false;
+    }
+}
+
+/**
+ * Initialize the database by creating tables if they don't exist
+ * Note: In production, use Drizzle migrations instead
+ */
+export async function initializeDatabase(): Promise<void> {
+    try {
+        const tablesExist = await checkTablesExist();
+
+        if (!tablesExist) {
+            console.log('Database tables do not exist. Please run migrations using:');
+            console.log('  npm run db:push');
+            console.log('  or');
+            console.log('  npm run db:migrate');
+            throw new Error('Database tables not initialized');
+        }
+
+        console.log('Database tables verified successfully');
+    } catch (error) {
+        console.error('Database initialization failed:', error);
+        throw error;
+    }
+}
+
+/**
+ * Verify database connection
+ */
+export async function verifyConnection(): Promise<boolean> {
+    try {
+        await db.select().from(posts).limit(1);
+        return true;
+    } catch (error) {
+        console.error('Database connection failed:', error);
+        return false;
+    }
+}
+
+/**
+ * Get database health status
+ */
+export async function getDatabaseHealth(): Promise<{
+    connected: boolean;
+    tablesExist: boolean;
+    timestamp: Date;
+}> {
+    const connected = await verifyConnection();
+    const tablesExist = connected ? await checkTablesExist() : false;
+
+    return {
+        connected,
+        tablesExist,
+        timestamp: new Date(),
+    };
+}
+
+/**
+ * Seed initial data (optional - for development)
+ */
+export async function seedDatabase(): Promise<void> {
+    try {
+        // Check if data already exists
+        const existingPosts = await db.select().from(posts).limit(1);
+
+        if (existingPosts.length > 0) {
+            console.log('Database already contains data, skipping seed');
+            return;
+        }
+
+        console.log('Database seeding completed');
+    } catch (error) {
+        console.error('Database seeding failed:', error);
+        throw error;
+    }
+}

package/app/src/db/schema.ts

@@ -0,0 +1,72 @@
+import { pgTable, text, timestamp, boolean, varchar } from 'drizzle-orm/pg-core';
+import { nanoid } from 'nanoid';
+
+/**
+ * Posts table schema
+ * Uses NanoID for primary keys for better URL-safe unique identifiers
+ */
+export const posts = pgTable('posts', {
+    // Primary key using NanoID (21 characters, URL-safe)
+    id: varchar('id', { length: 21 })
+        .primaryKey()
+        .$defaultFn(() => nanoid()),
+
+    // Post content fields
+    title: varchar('title', { length: 255 }).notNull(),
+    slug: varchar('slug', { length: 255 }).notNull().unique(),
+    content: text('content').notNull(),
+    excerpt: text('excerpt'),
+
+    // Author information (Clerk user ID)
+    authorId: varchar('author_id', { length: 255 }).notNull(),
+    authorName: varchar('author_name', { length: 255 }),
+
+    // Post metadata
+    published: boolean('published').default(false).notNull(),
+    featured: boolean('featured').default(false).notNull(),
+
+    // SEO fields
+    metaTitle: varchar('meta_title', { length: 255 }),
+    metaDescription: text('meta_description'),
+
+    // Timestamps
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
+    publishedAt: timestamp('published_at', { withTimezone: true }),
+});
+
+/**
+ * Comments table schema
+ * Demonstrates relationship with posts using NanoID
+ */
+export const comments = pgTable('comments', {
+    id: varchar('id', { length: 21 })
+        .primaryKey()
+        .$defaultFn(() => nanoid()),
+
+    // Foreign key to posts table
+    postId: varchar('post_id', { length: 21 })
+        .notNull()
+        .references(() => posts.id, { onDelete: 'cascade' }),
+
+    // Comment content
+    content: text('content').notNull(),
+
+    // Author information (Clerk user ID)
+    authorId: varchar('author_id', { length: 255 }).notNull(),
+    authorName: varchar('author_name', { length: 255 }),
+
+    // Moderation
+    approved: boolean('approved').default(false).notNull(),
+    flagged: boolean('flagged').default(false).notNull(),
+
+    // Timestamps
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
+});
+
+// Type exports for use in application
+export type Post = typeof posts.$inferSelect;
+export type NewPost = typeof posts.$inferInsert;
+export type Comment = typeof comments.$inferSelect;
+export type NewComment = typeof comments.$inferInsert;