CareBridge Development Standards

This skill provides comprehensive coding standards, architectural patterns, and best practices for developing the CareBridge application - a multi-case eldercare management SaaS platform.

Overview

CareBridge has specific architectural patterns that MUST be followed to ensure:

• •Case context preservation across all navigation
• •Consistent Stripe integration for SaaS subscriptions and concierge packages
• •Next.js 15 compliance with async request APIs
• •UI consistency using shadcn/ui components only
• •Database security with proper RLS policies and migrations

Breaking these patterns causes critical bugs, build errors, and scalability issues.

When to Use This Skill

ALWAYS use this skill when:

• •Adding new features to CareBridge
• •Fixing bugs in the CareBridge codebase
• •Creating new pages or components
• •Implementing navigation or routing
• •Working with Stripe payments
• •Creating database migrations
• •Reviewing or refactoring code

Critical scenarios that require this skill:

• •Any page that displays case-specific data
• •Any navigation component or link
• •Any Stripe checkout or webhook code
• •Any new UI component creation
• •Any database schema changes

Core Standards

🚨 Rule #1: NEVER Break Case Context

Every navigation link, redirect, or router.push MUST preserve the caseId query parameter.

Bad example:

<Link href="/dashboard">Dashboard</Link>

Good example:

const caseId = searchParams.get('caseId')
<Link href={caseId ? `/dashboard?caseId=${caseId}` : '/dashboard'}>Dashboard</Link>

See references/case-context.md for complete patterns.

🚨 Rule #2: NEVER Create Custom Components

Always use shadcn/ui. Never create custom UI components.

Bad example:

export function CustomButton({ children }) {
  return <button className="custom-btn">{children}</button>
}

Good example:

import { Button } from '@/components/ui/button'
<Button variant="default">{children}</Button>

Add components with: npx shadcn@latest add button

See references/component-standards.md for the complete list of available components.

🚨 Rule #3: ALWAYS Await Params in Next.js 15

Next.js 15 requires awaiting params and searchParams.

Bad example:

export default function Page({ params }: { params: { id: string } }) {
  const { id } = params // ERROR!
}

Good example:

type Props = { params: Promise<{ id: string }> }

export default async function Page({ params }: Props) {
  const { id } = await params
}

See references/nextjs-15-patterns.md for all Next.js 15 changes.

🚨 Rule #4: ALWAYS Use Metadata in Stripe Checkouts

Stripe webhooks route based on metadata.package_type.

Bad example:

const session = await stripe.checkout.sessions.create({
  line_items: [...],
  mode: 'subscription',
})

Good example:

const session = await stripe.checkout.sessions.create({
  line_items: [...],
  mode: 'subscription',
  metadata: {
    clerk_user_id: userId,
    package_type: 'concierge_plus',
    payment_type: 'subscription',
  },
})

See references/stripe-integration.md for the complete integration guide.

🚨 Rule #5: ALWAYS Use Supabase CLI for Migrations

Never create tables via SQL in application code.

Bad example:

await supabase.sql`CREATE TABLE ...` // Don't do this!

Good example:

npx supabase migration new create_table
# Edit the generated .sql file
npx supabase db push

See references/database-patterns.md for migration workflows.

Implementation Workflow

When implementing any feature in CareBridge, follow this workflow:

Step 1: Identify the Domain

Before writing any code, identify which domain(s) you're working in:

• •Navigation/Routing → Read references/case-context.md
• •Payments/Subscriptions → Read references/stripe-integration.md
• •Pages/API Routes → Read references/nextjs-15-patterns.md
• •UI Components → Read references/component-standards.md
• •Database Operations → Read references/database-patterns.md

Step 2: Follow the Patterns

Each reference document contains:

• •✅ CORRECT patterns to follow
• •❌ WRONG anti-patterns to avoid
• •Executable code examples
• •Common mistakes section
• •Checklists

Step 3: Validate Against Standards

Before completing any task, verify:

Case Context Checklist:

• • All navigation links preserve caseId query parameter
• • Page components await params in Next.js 15
• • Client components use useEffect for caseId to prevent hydration mismatch
• • Empty states shown when caseId is missing

Stripe Integration Checklist:

• • Pricing uses src/lib/config/concierge-pricing.ts as single source of truth
• • Checkout sessions include proper metadata for webhook routing
• • Webhook handlers check metadata.package_type for routing
• • Price validation happens before checkout creation

Next.js 15 Checklist:

• • All params are typed as Promise<{ ... }> and awaited
• • All searchParams are typed as Promise<{ ... }> and awaited
• • 'use client' only added when needed (hooks, interactivity, browser APIs)
• • Server components used for data fetching by default

Component Standards Checklist:

• • Using shadcn/ui components (added via npx shadcn@latest add)
• • NO custom UI components created
• • NO custom CSS variables defined
• • Using Tailwind classes instead of inline styles
• • Proper TypeScript types defined

Database Patterns Checklist:

• • Migrations created via npx supabase migration new
• • RLS enabled on all tables
• • RLS policies created for SELECT, INSERT, UPDATE, DELETE
• • Indexes added for frequently queried columns
• • Using createServerClient() in server components
• • Using createBrowserClient() in client components

Common Mistakes to Avoid

Based on real bugs encountered during development:

1. •Losing case context - Navigation without preserving caseId
2. •Not awaiting params - Using Next.js 14 patterns in Next.js 15
3. •Creating custom components - Instead of using shadcn/ui
4. •Defining custom CSS variables - Instead of using existing ones
5. •Forgetting RLS policies - Creating tables without Row-Level Security
6. •Skipping migrations - Creating tables in application code
7. •Missing webhook metadata - Webhooks unable to route correctly
8. •Using client Supabase in server - Wrong client type for component

Project Context

Application: CareBridge - Multi-case eldercare management platform

Tech Stack:

• •Next.js 15.5.4 with App Router
• •React 19.1.0
• •TypeScript 5.x
• •Supabase (PostgreSQL with RLS)
• •Clerk (Authentication)
• •Stripe (Payments)
• •shadcn/ui (Components)
• •Tailwind CSS (Styling)

Architecture:

• •Multi-tenant: Users can manage multiple care cases
• •Case-centric: All data scoped to caseId
• •SaaS subscription: $19.99/month platform access
• •Concierge packages: 4 service tiers (one-time, project-based, subscription)

Resources

This skill includes comprehensive reference documentation in the references/ directory:

references/

1. •

   case-context.md

   • •How caseId preservation works
   • •Reading case context in server/client components
   • •Navigation patterns
   • •Common mistakes and fixes
2. •

   stripe-integration.md

   • •Pricing configuration (single source of truth)
   • •Creating checkout sessions
   • •Webhook handling and metadata routing
   • •Database structure
   • •Testing checklist
3. •

   nextjs-15-patterns.md

   • •Async params and searchParams
   • •Server vs client components
   • •Data fetching patterns
   • •Metadata API
   • •Common migration errors
4. •

   component-standards.md

   • •Using shadcn/ui components
   • •CSS variables (read-only)
   • •Form patterns with React Hook Form + Zod
   • •Dialog/modal patterns
   • •Loading and empty states
5. •

   database-patterns.md

   • •Supabase client patterns
   • •Migration creation and structure
   • •RLS policies and patterns
   • •Query patterns (CRUD, joins, filtering)
   • •Transaction patterns with RPC
   • •Error handling

Getting Help

When stuck, refer to the reference documents for:

• •Copy-paste ready code examples
• •Step-by-step checklists
• •Anti-patterns to avoid
• •Testing procedures

Remember: These patterns exist because they've been proven through real development. Breaking them leads to bugs, build errors, and technical debt.