# Convex Backend — Migration Architecture

## Overview

Mawidi is migrating from Prisma + NextAuth to Convex + Clerk using a
**Strangler Fig** pattern. Both backends run in parallel — each domain
(auth, bookings, billing, etc.) can be individually switched between
Prisma and Convex via the Data Source Router.

## Directory Structure

```
convex/
  convex.config.ts          # Convex app definition
  auth.config.ts            # Clerk authentication provider config
  tsconfig.json             # TypeScript config for Convex functions
  README.md                 # This file
  _generated/               # Auto-generated by `npx convex dev`
  schema/                   # Convex schema definitions (tables, indexes)
  helpers/
    cascade-delete.ts       # Cascade delete utility (no ON DELETE CASCADE in Convex)
    validation.ts           # Unique constraint enforcement
  auth/                     # Auth domain functions
  bookings/                 # Bookings domain functions
  billing/                  # Billing domain functions
  notifications/            # Notifications domain functions
  support/                  # Support domain functions
  social/                   # Social media domain functions
  leads/                    # Lead management domain functions
  quotations/               # Quotation domain functions
  whatsapp/                 # WhatsApp domain functions
  voice_agents/             # Voice agent domain functions
  content/                  # Content/CMS domain functions
  careers/                  # Careers domain functions
  reviews/                  # Reviews domain functions
  expenses/                 # Expenses domain functions
  real_estate/              # Real estate domain functions
  analytics/                # Analytics domain functions
  organizations/            # Organizations domain functions
```

## Data Source Router

The router at `lib/data-source.ts` controls which backend serves each domain:

```typescript
import { getDataSource, isConvex, isPrisma } from "@/lib/data-source";

// Check which backend a domain uses
if (isConvex("bookings")) {
  // Use Convex query
} else {
  // Use Prisma query
}
```

### Environment Override

Switch any domain by setting `DS_<DOMAIN>=convex` in your environment:

```bash
# Switch bookings to Convex
DS_BOOKINGS=convex

# Rollback to Prisma instantly
DS_BOOKINGS=prisma
```

## Migration Phases

1. **Foundation** (current) — Schema translation, function scaffolds, infrastructure
2. **Auth Migration** — Clerk replaces NextAuth, OTP, staff JWT
3. **Domain Migration** — Switch domains one-by-one via Data Source Router
4. **Cleanup** — Remove Prisma, Supabase, and legacy code

## Development Commands

```bash
# Start Convex dev server (watches for changes)
npx convex dev

# Deploy to production
npx convex deploy

# Generate types after schema changes
npx convex codegen

# View Convex dashboard
npx convex dashboard
```

## Key Differences from Prisma

| Feature            | Prisma                   | Convex                                 |
| ------------------ | ------------------------ | -------------------------------------- |
| Cascade deletes    | `onDelete: Cascade`      | Manual via `helpers/cascade-delete.ts` |
| Unique constraints | `@@unique`               | Manual via `helpers/validation.ts`     |
| Migrations         | `prisma migrate`         | Automatic (push schema)                |
| Real-time          | Manual polling/websocket | Built-in reactive queries              |
| File storage       | External (Supabase)      | Built-in `ctx.storage`                 |
| Cron jobs          | External (API routes)    | Built-in `crons.ts`                    |

## Rollback Procedure

To rollback any domain to Prisma:

1. Set `DS_<DOMAIN>=prisma` in environment
2. Redeploy (the app immediately routes to Prisma)
3. No data migration needed — Prisma DB stays in sync during dual-write phase
