init

.agents/skills/kiranism-shadcn-dashboard/references/migration-from-clerk-and-mocks.md

@@ -0,0 +1,81 @@
+# 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