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.