ultra-dex 1.7.3 → 1.8.0

package/assets/cursor-rules/11-nextjs-v15.mdc

@@ -0,0 +1,307 @@
+# Next.js 15 Production Patterns
+
+> Modern App Router patterns for production-grade Next.js 15 applications
+
+## Architecture Rules
+
+1. **ALWAYS use App Router** - `src/app/` directory structure
+2. **Route Groups** for organization - `(marketing)/`, `(dashboard)/`, `(auth)/`
+3. **Parallel Routes** for complex layouts - `@modal`, `@sidebar`
+4. **Intercepting Routes** for modals - `(.)photo/[id]`
+
+## File Structure
+
+```
+src/app/
+├── (marketing)/
+│   ├── page.tsx              # Landing page
+│   ├── pricing/page.tsx
+│   └── layout.tsx            # Marketing layout
+├── (dashboard)/
+│   ├── dashboard/
+│   │   ├── page.tsx          # Main dashboard
+│   │   ├── loading.tsx       # Suspense fallback
+│   │   └── error.tsx         # Error boundary
+│   ├── settings/page.tsx
+│   └── layout.tsx            # Dashboard layout with sidebar
+├── (auth)/
+│   ├── login/page.tsx
+│   ├── signup/page.tsx
+│   └── layout.tsx            # Auth layout (no navbar)
+├── api/
+│   └── [...]/route.ts        # API routes
+├── layout.tsx                # Root layout
+└── globals.css
+```
+
+## Server Components (Default)
+
+```tsx
+// This is a Server Component by default
+export default async function DashboardPage() {
+  const data = await prisma.user.findMany()
+
+  return (
+    <div>
+      {data.map(user => <UserCard key={user.id} user={user} />)}
+    </div>
+  )
+}
+```
+
+## Client Components (When Needed)
+
+```tsx
+'use client'
+
+import { useState } from 'react'
+
+export function Counter() {
+  const [count, setCount] = useState(0)
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>
+}
+```
+
+## Server Actions
+
+```tsx
+// app/actions.ts
+'use server'
+
+import { revalidatePath } from 'next/cache'
+import { redirect } from 'next/navigation'
+
+export async function createPost(formData: FormData) {
+  const title = formData.get('title') as string
+
+  await prisma.post.create({ data: { title } })
+
+  revalidatePath('/posts')
+  redirect('/posts')
+}
+```
+
+## Loading States
+
+```tsx
+// app/dashboard/loading.tsx
+export default function Loading() {
+  return (
+    <div className="animate-pulse">
+      <div className="h-8 bg-gray-200 rounded w-1/4 mb-4" />
+      <div className="h-4 bg-gray-200 rounded w-full mb-2" />
+      <div className="h-4 bg-gray-200 rounded w-3/4" />
+    </div>
+  )
+}
+```
+
+## Error Boundaries
+
+```tsx
+// app/dashboard/error.tsx
+'use client'
+
+export default function Error({
+  error,
+  reset,
+}: {
+  error: Error & { digest?: string }
+  reset: () => void
+}) {
+  return (
+    <div className="p-4 bg-red-50 rounded-lg">
+      <h2 className="text-red-800 font-semibold">Something went wrong!</h2>
+      <button
+        onClick={() => reset()}
+        className="mt-2 px-4 py-2 bg-red-600 text-white rounded"
+      >
+        Try again
+      </button>
+    </div>
+  )
+}
+```
+
+## Middleware for Auth/Tenant
+
+```tsx
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  // Get tenant from subdomain or header
+  const hostname = request.headers.get('host') || ''
+  const subdomain = hostname.split('.')[0]
+
+  // Add tenant to headers for downstream use
+  const response = NextResponse.next()
+  response.headers.set('x-tenant-id', subdomain)
+
+  // Auth check
+  const session = request.cookies.get('session')
+  if (!session && request.nextUrl.pathname.startsWith('/dashboard')) {
+    return NextResponse.redirect(new URL('/login', request.url))
+  }
+
+  return response
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+}
+```
+
+## Streaming with Suspense
+
+```tsx
+import { Suspense } from 'react'
+
+export default function Dashboard() {
+  return (
+    <div>
+      <h1>Dashboard</h1>
+
+      {/* This loads immediately */}
+      <StaticContent />
+
+      {/* This streams in when ready */}
+      <Suspense fallback={<LoadingStats />}>
+        <AsyncStats />
+      </Suspense>
+
+      {/* This streams separately */}
+      <Suspense fallback={<LoadingChart />}>
+        <AsyncChart />
+      </Suspense>
+    </div>
+  )
+}
+```
+
+## Metadata API
+
+```tsx
+// app/dashboard/page.tsx
+import { Metadata } from 'next'
+
+export const metadata: Metadata = {
+  title: 'Dashboard | MyApp',
+  description: 'Your personal dashboard',
+}
+
+// Dynamic metadata
+export async function generateMetadata({ params }): Promise<Metadata> {
+  const user = await getUser(params.id)
+  return {
+    title: `${user.name}'s Profile`,
+    openGraph: {
+      images: [user.avatar],
+    },
+  }
+}
+```
+
+## Data Fetching Patterns
+
+```tsx
+// Parallel data fetching
+async function Dashboard() {
+  // These run in parallel
+  const [user, posts, stats] = await Promise.all([
+    getUser(),
+    getPosts(),
+    getStats(),
+  ])
+
+  return <DashboardView user={user} posts={posts} stats={stats} />
+}
+
+// Sequential (when dependent)
+async function Profile({ params }) {
+  const user = await getUser(params.id)
+  const posts = await getPostsByUser(user.id) // Needs user.id
+
+  return <ProfileView user={user} posts={posts} />
+}
+```
+
+## Route Handlers (API)
+
+```tsx
+// app/api/users/route.ts
+import { NextResponse } from 'next/server'
+
+export async function GET(request: Request) {
+  const users = await prisma.user.findMany()
+  return NextResponse.json(users)
+}
+
+export async function POST(request: Request) {
+  const body = await request.json()
+  const user = await prisma.user.create({ data: body })
+  return NextResponse.json(user, { status: 201 })
+}
+```
+
+## Multi-Tenancy Pattern
+
+```tsx
+// lib/tenant.ts
+import { headers } from 'next/headers'
+
+export async function getTenant() {
+  const headersList = headers()
+  const tenantId = headersList.get('x-tenant-id')
+
+  if (!tenantId) throw new Error('No tenant')
+
+  return prisma.organization.findUniqueOrThrow({
+    where: { subdomain: tenantId },
+  })
+}
+
+// Usage in any server component
+export default async function Dashboard() {
+  const tenant = await getTenant()
+  const data = await prisma.post.findMany({
+    where: { organizationId: tenant.id },
+  })
+  // ...
+}
+```
+
+## Vercel AI SDK Integration
+
+```tsx
+// app/api/chat/route.ts
+import { openai } from '@ai-sdk/openai'
+import { streamText } from 'ai'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+
+  const result = await streamText({
+    model: openai('gpt-4-turbo'),
+    messages,
+  })
+
+  return result.toDataStreamResponse()
+}
+```
+
+## Production Checklist
+
+- [ ] All routes have `loading.tsx`
+- [ ] All routes have `error.tsx`
+- [ ] Metadata on all pages
+- [ ] Server Actions for mutations
+- [ ] Proper auth middleware
+- [ ] Multi-tenant isolation (if applicable)
+- [ ] Streaming for slow data
+- [ ] Edge runtime where beneficial
+
+---
+
+*Ultra-Dex v1.7.0 - Next.js 15 Production Patterns*

package/assets/cursor-rules/12-multi-tenancy.mdc

@@ -0,0 +1,282 @@
+# SaaS Multi-Tenancy Patterns
+
+> Patterns for building secure multi-tenant SaaS applications
+
+## Core Principles
+
+1. **Tenant Isolation** - Data from one tenant NEVER visible to another
+2. **Consistent Filtering** - ALL queries must include tenant context
+3. **Defense in Depth** - Multiple layers of tenant validation
+
+## Tenant Identification
+
+### Subdomain-Based (Recommended for SaaS)
+```typescript
+// middleware.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+  const hostname = request.headers.get('host') || ''
+  const subdomain = hostname.split('.')[0]
+
+  // Skip for main domain
+  if (subdomain === 'www' || subdomain === 'app') {
+    return NextResponse.next()
+  }
+
+  const response = NextResponse.next()
+  response.headers.set('x-tenant-id', subdomain)
+  return response
+}
+```
+
+### Header-Based (API Clients)
+```typescript
+// For API-first architectures
+const tenantId = request.headers.get('x-tenant-id')
+if (!tenantId) {
+  return Response.json({ error: 'Tenant ID required' }, { status: 400 })
+}
+```
+
+### User Association (After Auth)
+```typescript
+// Get tenant from authenticated user
+const session = await getSession()
+const tenantId = session?.user?.organizationId
+```
+
+## Database Patterns
+
+### Row-Level Security (Recommended)
+
+**Prisma Schema:**
+```prisma
+model Organization {
+  id        String   @id @default(cuid())
+  subdomain String   @unique
+  name      String
+  users     User[]
+  posts     Post[]
+  // All tenant-owned data has organizationId
+}
+
+model User {
+  id             String       @id @default(cuid())
+  email          String       @unique
+  organization   Organization @relation(fields: [organizationId], references: [id])
+  organizationId String
+  posts          Post[]
+}
+
+model Post {
+  id             String       @id @default(cuid())
+  title          String
+  content        String
+  organization   Organization @relation(fields: [organizationId], references: [id])
+  organizationId String
+  author         User         @relation(fields: [authorId], references: [id])
+  authorId       String
+
+  @@index([organizationId]) // ALWAYS index tenant column
+}
+```
+
+**Query Pattern (ALWAYS include organizationId):**
+```typescript
+// lib/db.ts - Tenant-scoped client
+export function getTenantDb(organizationId: string) {
+  return {
+    post: {
+      findMany: (args?: Prisma.PostFindManyArgs) =>
+        prisma.post.findMany({
+          ...args,
+          where: { ...args?.where, organizationId }
+        }),
+      create: (data: Prisma.PostCreateInput) =>
+        prisma.post.create({
+          data: { ...data, organizationId }
+        }),
+      // ... other methods
+    }
+  }
+}
+
+// Usage
+const db = getTenantDb(session.user.organizationId)
+const posts = await db.post.findMany() // Auto-filtered
+```
+
+### PostgreSQL Row-Level Security (RLS)
+
+```sql
+-- Enable RLS
+ALTER TABLE posts ENABLE ROW LEVEL SECURITY;
+
+-- Policy: Users can only see their org's posts
+CREATE POLICY posts_tenant_isolation ON posts
+  USING (organization_id = current_setting('app.current_tenant')::text);
+
+-- Set tenant context in your app
+SET app.current_tenant = 'org_123';
+SELECT * FROM posts; -- Only org_123 posts returned
+```
+
+### Schema-Per-Tenant (Enterprise)
+
+```typescript
+// For highest isolation (enterprise customers)
+const schema = `tenant_${tenantId}`
+
+// Prisma with schema
+const prisma = new PrismaClient({
+  datasources: {
+    db: {
+      url: `${DATABASE_URL}?schema=${schema}`
+    }
+  }
+})
+```
+
+## Middleware Pattern
+
+```typescript
+// lib/tenant.ts
+import { headers } from 'next/headers'
+import { cache } from 'react'
+
+export const getTenant = cache(async () => {
+  const headersList = headers()
+  const tenantId = headersList.get('x-tenant-id')
+
+  if (!tenantId) {
+    throw new Error('Tenant context required')
+  }
+
+  const tenant = await prisma.organization.findUnique({
+    where: { subdomain: tenantId }
+  })
+
+  if (!tenant) {
+    throw new Error('Tenant not found')
+  }
+
+  return tenant
+})
+
+// Usage in any Server Component or API route
+export default async function Dashboard() {
+  const tenant = await getTenant()
+  const posts = await prisma.post.findMany({
+    where: { organizationId: tenant.id }
+  })
+  // ...
+}
+```
+
+## API Route Pattern
+
+```typescript
+// app/api/posts/route.ts
+import { getTenant } from '@/lib/tenant'
+import { getSession } from '@/lib/auth'
+
+export async function GET() {
+  const session = await getSession()
+  if (!session) {
+    return Response.json({ error: 'Unauthorized' }, { status: 401 })
+  }
+
+  const tenant = await getTenant()
+
+  // Verify user belongs to this tenant
+  if (session.user.organizationId !== tenant.id) {
+    return Response.json({ error: 'Forbidden' }, { status: 403 })
+  }
+
+  const posts = await prisma.post.findMany({
+    where: { organizationId: tenant.id }
+  })
+
+  return Response.json(posts)
+}
+```
+
+## Testing Multi-Tenancy
+
+```typescript
+// tests/multi-tenancy.test.ts
+describe('Tenant Isolation', () => {
+  it('should not leak data between tenants', async () => {
+    // Create data for tenant A
+    const tenantA = await createTenant('tenant-a')
+    const postA = await createPost({
+      title: 'Secret',
+      organizationId: tenantA.id
+    })
+
+    // Create tenant B
+    const tenantB = await createTenant('tenant-b')
+
+    // Query as tenant B - should NOT see tenant A's post
+    const postsForB = await prisma.post.findMany({
+      where: { organizationId: tenantB.id }
+    })
+
+    expect(postsForB).not.toContainEqual(
+      expect.objectContaining({ id: postA.id })
+    )
+  })
+
+  it('should prevent cross-tenant access via API', async () => {
+    const response = await fetch('/api/posts', {
+      headers: {
+        'x-tenant-id': 'wrong-tenant',
+        'Authorization': `Bearer ${validToken}`
+      }
+    })
+
+    expect(response.status).toBe(403)
+  })
+})
+```
+
+## Checklist
+
+- [ ] All database tables have `organizationId` column
+- [ ] All queries filter by `organizationId`
+- [ ] Middleware extracts tenant from subdomain/header
+- [ ] API routes verify user belongs to tenant
+- [ ] Indexes on `organizationId` columns
+- [ ] Cross-tenant access tests written
+- [ ] No raw SQL without tenant filter
+- [ ] Admin routes have additional protection
+
+## Common Mistakes
+
+```typescript
+// ❌ BAD - No tenant filter
+const posts = await prisma.post.findMany()
+
+// ✅ GOOD - Always filter
+const posts = await prisma.post.findMany({
+  where: { organizationId: tenant.id }
+})
+
+// ❌ BAD - Trusting client-provided tenant ID for data access
+const { tenantId } = req.body
+const posts = await prisma.post.findMany({
+  where: { organizationId: tenantId }
+})
+
+// ✅ GOOD - Use server-verified tenant context
+const tenant = await getTenant() // From middleware/session
+const posts = await prisma.post.findMany({
+  where: { organizationId: tenant.id }
+})
+```
+
+---
+
+*Ultra-Dex v1.7.1 - Multi-Tenancy Patterns for Production SaaS*

package/assets/cursor-rules/README.md

@@ -0,0 +1,78 @@
+# Ultra-Dex Cursor Rules
+
+> Modular AI rules for Cursor, Copilot, and other AI coding assistants.
+
+## What is This?
+
+The 34-section Ultra-Dex template, atomized into small, focused rule files. Each file is under 200 lines and optimized for AI context windows.
+
+## How to Use
+
+### Option 1: Copy to `.cursor/rules/`
+
+```bash
+# In your project root
+mkdir -p .cursor/rules
+cp path/to/ultra-dex/cursor-rules/*.mdc .cursor/rules/
+```
+
+### Option 2: Reference in System Prompt
+
+Paste the relevant rule into your AI assistant's system prompt when working on that domain.
+
+### Option 3: Selective Loading
+
+Only load rules relevant to your current task:
+
+| Working On | Load These |
+|------------|------------|
+| Database schema | `00-ultra-dex-core.mdc` + `01-database.mdc` |
+| API endpoints | `00-ultra-dex-core.mdc` + `02-api.mdc` |
+| Authentication | `00-ultra-dex-core.mdc` + `03-auth.mdc` |
+| Frontend components | `00-ultra-dex-core.mdc` + `04-frontend.mdc` |
+| Payments | `00-ultra-dex-core.mdc` + `05-payments.mdc` |
+| Testing | `00-ultra-dex-core.mdc` + `06-testing.mdc` |
+| Security review | `00-ultra-dex-core.mdc` + `07-security.mdc` |
+| Deployment | `00-ultra-dex-core.mdc` + `08-deployment.mdc` |
+| Error handling | `00-ultra-dex-core.mdc` + `09-error-handling.mdc` |
+| Performance | `00-ultra-dex-core.mdc` + `10-performance.mdc` |
+| Next.js 15 app | `00-ultra-dex-core.mdc` + `11-nextjs-v15.mdc` |
+| Multi-tenant SaaS | `00-ultra-dex-core.mdc` + `12-multi-tenancy.mdc` |
+
+## Files
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `00-ultra-dex-core.mdc` | ~60 | Base rules (always load) |
+| `01-database.mdc` | ~70 | Prisma, schema, queries |
+| `02-api.mdc` | ~100 | API routes, validation, responses |
+| `03-auth.mdc` | ~70 | NextAuth configuration |
+| `04-frontend.mdc` | ~100 | React, components, state |
+| `05-payments.mdc` | ~90 | Stripe integration |
+| `06-testing.mdc` | ~100 | Vitest, Playwright |
+| `07-security.mdc` | ~100 | Input validation, auth, headers |
+| `08-deployment.mdc` | ~90 | Vercel, CI/CD, migrations |
+| `09-error-handling.mdc` | ~100 | Error patterns, logging |
+| `10-performance.mdc` | ~100 | Optimization, caching |
+| `11-nextjs-v15.mdc` | ~200 | Next.js 15 App Router patterns |
+| `12-multi-tenancy.mdc` | ~200 | SaaS multi-tenant patterns |
+
+## Why Modular?
+
+1. **AI Context Limits**: LLMs perform better with focused context (<500 lines)
+2. **"Lost in the Middle"**: Long contexts degrade AI attention on middle content
+3. **Relevance**: Load only what you need for the current task
+4. **Maintainability**: Update one domain without touching others
+
+## Customization
+
+These are starting points. Customize for your stack:
+
+- Using Supabase instead of Prisma? Modify `01-database.mdc`
+- Using Clerk instead of NextAuth? Replace `03-auth.mdc`
+- Using Paddle instead of Stripe? Replace `05-payments.mdc`
+
+## Full Template
+
+For the complete 34-section template with all details:
+- [04-Imp-Template.md](../@%20Ultra%20DeX/Saas%20plan/04-Imp-Template.md)