# Migration From Clerk And Mock APIs

Use this guide when the task is explicitly about converting this starter toward Auth.js and Drizzle.

## What exists today

This repo still contains two major demo-era seams:

- auth and workspace flows built around Clerk
- feature data flows built around `src/constants/mock-api*.ts`

The important thing is not to rewrite everything at once.

## Recommended migration order

### 1. Establish auth shell

Introduce Auth.js primitives first:

- auth config file
- protected route or middleware strategy
- session helper
- sign-in and sign-out surface

Do this before touching feature CRUD so server handlers have a stable way to identify the user.

### 2. Establish organization and membership model

Add app-owned tables and types for:

- organizations
- memberships
- roles
- optional permissions or entitlements

This replaces Clerk Organizations as the architectural source of truth.

### 3. Migrate one feature end-to-end

Pick a contained feature such as `products` or `users`.

Per feature:

- define Drizzle schema
- replace route-handler mocks with Drizzle queries
- point `service.ts` to local route handlers
- leave UI query usage stable where possible

### 4. Convert RBAC-aware UI

After shared membership utilities exist:

- migrate `use-nav.ts`
- migrate workspace or billing placeholders
- replace Clerk-only UI pieces with app-owned equivalents

## How to speak about legacy files

Use accurate migration language:

- "legacy mock source"
- "route-handler shell ready for Drizzle"
- "Clerk-coupled hotspot"
- "migration seam in `service.ts`"

Avoid language that suggests the old path is still the preferred architecture.

## Safe recommendations

Good:

- migrate feature-by-feature
- centralize auth checks
- centralize membership lookup
- keep HTTP contracts stable while swapping the backing store

Risky:

- editing every page before the auth shell exists
- mixing direct Drizzle calls into client-facing feature services
- rebuilding UI and auth simultaneously without preserving route contracts