Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Clerk Reference Architecture · jeremylongshore | DecimalAI

jeremylongshore/clerk-reference-architecture

SkillScore74Maintained

Reference architecture patterns for Clerk authentication. Use when designing application architecture, planning auth flows, or implementing enterprise-grade authentication. Trigger with phrases like "clerk architecture", "clerk design", "clerk system design", "clerk integration patterns".

codingby jeremylongshore

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/jeremylongshore-clerk-reference-architecture/SKILL.md

decimalai skills pull jeremylongshore-clerk-reference-architecture --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/jeremylongshore-clerk-reference-architecture/SKILL.md https://app.decimal.ai/s/jeremylongshore-clerk-reference-architecture/SKILL.md

Raw file: /s/jeremylongshore-clerk-reference-architecture/SKILL.md ↗ · machine-readable summary at /s/jeremylongshore-clerk-reference-architecture.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

Runs

132

all versions · 30d

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 46d ago

Yes — +9% lift · at higher cost+81% tokens0% turns95% of whole cases pass with skill (21/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-06	✗→✓	▲ Improved	38%	0%
case-19	✗→✓	▲ Improved	46%	0%
case-01	✓→✓	＝ Same ✓	106%	0%
case-02	✓→✓	＝ Same ✓	97%	0%
case-03	✓→✓	＝ Same ✓	71%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

jeremylongshore / claude-code-plugins-plus-skills

skills/.curated/clerk-reference-architecture/SKILL.md

View on GitHub ↗

License MITImported 8/25/2026Version v1Bundled 1 file

Skill contents

references/

SKILL.md

Clerk Reference Architecture

Overview

Reference architectures for implementing Clerk in common application patterns: Next.js full-stack, microservices with shared auth, multi-tenant SaaS, and mobile + web with shared backend.

Prerequisites

Understanding of web application architecture
Familiarity with authentication patterns (JWT, sessions, OAuth)
Knowledge of your tech stack and scaling requirements

Instructions

Architecture 1: Next.js Full-Stack Application

Browser
  │
  ├─▸ Next.js Middleware (clerkMiddleware)
  │     └─▸ Validates session token on every request
  │
  ├─▸ Server Components (auth(), currentUser())
  │     └─▸ Direct access to user data, no network call
  │
  ├─▸ Client Components (useUser(), useAuth())
  │     └─▸ Real-time auth state via ClerkProvider
  │
  ├─▸ API Routes (auth() for userId, getToken() for JWT)
  │     └─▸ Call external services with Clerk JWT
  │
  └─▸ Webhooks (/api/webhooks/clerk)
        └─▸ Sync user data to database

typescript
// app/layout.tsx — entry point
import { ClerkProvider } from '@clerk/nextjs'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <ClerkProvider>
      <html><body>{children}</body></html>
    </ClerkProvider>
  )
}

typescript
// middleware.ts — auth boundary
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isPublic = createRouteMatcher(['/', '/sign-in(.*)', '/sign-up(.*)', '/api/webhooks(.*)'])

export default clerkMiddleware(async (auth, req) => {
  if (!isPublic(req)) await auth.protect()
})

Architecture 2: Microservices with Shared Auth

Browser ─▸ API Gateway / BFF (Next.js + Clerk)
              │
              ├─▸ Service A (Node.js) ──── verifies JWT
              ├─▸ Service B (Python) ──── verifies JWT
              └─▸ Service C (Go) ──────── verifies JWT

typescript
// BFF: Generate service-specific JWT
// app/api/proxy/[service]/route.ts
import { auth } from '@clerk/nextjs/server'

export async function GET(req: Request, { params }: { params: { service: string } }) {
  const { userId, getToken } = await auth()
  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })

  // Get JWT with service-specific claims
  const token = await getToken({ template: params.service })

  const serviceUrls: Record<string, string> = {
    billing: process.env.BILLING_SERVICE_URL!,
    analytics: process.env.ANALYTICS_SERVICE_URL!,
    notifications: process.env.NOTIFICATION_SERVICE_URL!,
  }

  const response = await fetch(`${serviceUrls[params.service]}/api/data`, {
    headers: { Authorization: `Bearer ${token}` },
  })

  return Response.json(await response.json())
}

typescript
// Downstream service: Verify Clerk JWT
// services/billing/src/middleware.ts (Express)
import { clerkMiddleware, requireAuth } from '@clerk/express'

app.use(clerkMiddleware())
app.get('/api/data', requireAuth(), (req, res) => {
  // req.auth.userId is available
  res.json({ userId: req.auth.userId })
})

Architecture 3: Multi-Tenant SaaS

Tenant A (org_abc) ──┐
Tenant B (org_def) ──┤──▸ Shared App ──▸ Shared DB (tenant-scoped queries)
Tenant C (org_ghi) ──┘

typescript
// lib/tenant.ts — tenant-scoped data access
import { auth } from '@clerk/nextjs/server'

export async function getTenantData<T>(query: (orgId: string) => Promise<T>): Promise<T> {
  const { orgId } = await auth()
  if (!orgId) throw new Error('No organization selected')
  return query(orgId)
}

// Usage:
export async function getProjects() {
  return getTenantData((orgId) =>
    db.project.findMany({ where: { organizationId: orgId } })
  )
}

typescript
// middleware.ts — enforce org context on tenant routes
import { clerkMiddleware, createRouteMatcher } from '@clerk/nextjs/server'

const isTenantRoute = createRouteMatcher(['/app(.*)'])

export default clerkMiddleware(async (auth, req) => {
  if (isTenantRoute(req)) {
    const { orgId } = await auth.protect()
    if (!orgId) {
      // Redirect to org selector if no org is active
      return Response.redirect(new URL('/select-org', req.url))
    }
  }
})

typescript
// app/select-org/page.tsx
import { OrganizationSwitcher } from '@clerk/nextjs'

export default function SelectOrg() {
  return (
    <div className="flex min-h-screen items-center justify-center">
      <div>
        <h1>Select Your Organization</h1>
        <OrganizationSwitcher
          afterSelectOrganizationUrl="/app/dashboard"
          hidePersonal={true}
        />
      </div>
    </div>
  )
}

Architecture 4: Mobile + Web with Shared Backend

Web App (Next.js + @clerk/nextjs)  ──┐
Mobile App (React Native + @clerk/clerk-expo) ──┤──▸ Backend API (Express + @clerk/express)
                                                └──▸ Database

typescript
// Backend API: Express with Clerk
// server.ts
import express from 'express'
import { clerkMiddleware, requireAuth, getAuth } from '@clerk/express'

const app = express()

// Apply Clerk middleware globally
app.use(clerkMiddleware())

// Public endpoint
app.get('/api/public', (req, res) => {
  res.json({ message: 'Public endpoint' })
})

// Protected endpoint (works with both web and mobile clients)
app.get('/api/profile', requireAuth(), async (req, res) => {
  const { userId } = getAuth(req)
  const user = await db.user.findUnique({ where: { clerkId: userId } })
  res.json({ user })
})

app.listen(3001)

Output

Next.js full-stack architecture with middleware, server/client components, and webhooks
Microservices architecture with BFF proxy and JWT-based service auth
Multi-tenant SaaS with organization-scoped data access
Mobile + web with shared Express backend using @clerk/express

Error Handling

| Pattern | Common Issue | Solution | |---------|-------------|----------| | Full-stack | Middleware redirect loop | Add sign-in route to public routes | | Microservices | JWT template not configured | Create JWT template in Dashboard per service | | Multi-tenant | No org selected | Redirect to org selector before tenant routes | | Mobile + Web | Token not sent from mobile | Include Authorization: Bearer <token> in mobile fetch |

Examples

Database Schema for Clerk Integration

prisma
// prisma/schema.prisma
model User {
  id        String   @id @default(cuid())
  clerkId   String   @unique
  email     String   @unique
  name      String?
  createdAt DateTime @default(now())
  posts     Post[]
  orgMemberships OrgMembership[]
}

model OrgMembership {
  id     String @id @default(cuid())
  userId String
  orgId  String  // Clerk organization ID
  role   String  // org:admin, org:member, etc.
  user   User   @relation(fields: [userId], references: [id])
  @@unique([userId, orgId])
}

Resources

Next Steps

Proceed to clerk-multi-env-setup for multi-environment configuration.

Illustrative Want to see what jeremylongshore/clerk-reference-architecture would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/13/2026, 17:24 UTC · 22 cases

Lift

+9%

95% vs 86%

Agent turns

1.0 vs 1.0

Tokens

+81%

3,188.23 vs 1,763.91

fail → pass · 2pass → pass · 19fail → fail · 1

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 I am deploying my Next.js web app to Vercel and need to configure the Clerk publishable and secret key environment variables for staging versus production. List the exact environment variable key names to set in Vercel for Clerk authentication.	pass→pass	7,762	3,943	-49%	1	1	0%	1,294	2,660	+106%	0	0	—
case-02 I want to customize the visual theme of Clerk components using the `appearance` prop to set custom primary button hex colors and font families in Next.js. Show how to configure the visual theme object passed into `<ClerkProvider>`.	pass→pass	9,497	21,109	+122%	1	1	0%	1,722	3,396	+97%	0	0	—
case-03 I am setting up Enterprise SSO (SAML) auth for enterprise customers in my Clerk application. What configuration steps are required in the Clerk Dashboard to enable custom SAML single sign-on?	pass→pass	18,401	11,844	-36%	1	1	0%	2,395	4,085	+71%	0	0	—
case-04 I am setting up a Next.js App Router `middleware.ts` file using Clerk. I want to protect all non-public routes while keeping root, sign-in, sign-up, and api webhooks accessible. Developers sometimes call `auth()` from `next/headers` inside middleware. Write the standard Next.js middleware implementation for Clerk.	pass→pass	8,732	6,186	-29%	1	1	0%	1,588	3,144	+98%	0	0	—
case-05 In a Next.js App Router application integrated with Clerk auth middleware, users accessing protected routes trigger an infinite redirect loop between middleware and sign-in. What exact mistake in the route matcher configuration causes this and how is it resolved?	pass→pass	16,234	19,731	+22%	1	1	0%	2,815	3,847	+37%	0	0	—
case-06 In a microservices architecture with a Next.js BFF proxy calling downstream services, calling `getToken()` without arguments returns generic session tokens that downstream services reject due to missing claims. How should the BFF call `getToken()` to generate microservice-specific JWTs?	fail→pass	16,105	11,136	-31%	1	1	0%	2,807	3,867	+38%	0	0	—
case-07 I have an Express.js billing microservice that runs behind a BFF API gateway. I need to protect an endpoint `/api/data` using Clerk token verification. Developers often attempt manual JWT decoding with standard jwt packages. Write the recommended `@clerk/express` middleware and route handler setup.	fail→fail	11,352	9,415	-17%	1	1	0%	2,062	3,672	+78%	0	0	—
case-08 In a multi-tenant SaaS application built with Next.js App Router and Clerk, write a server-side helper function `getTenantData` that wraps database calls in organization context and guards against unselected organizations.	pass→pass	12,277	7,738	-37%	1	1	0%	2,371	3,606	+52%	0	0	—
case-13 Design a Prisma schema for a PostgreSQL database syncing with Clerk user and organization webhooks. Write the `User` and `OrgMembership` models to track Clerk user IDs and multi-tenant organization memberships safely.	pass→pass	16,564	14,101	-15%	1	1	0%	3,247	4,894	+51%	0	0	—
case-09 In a multi-tenant Next.js application using Clerk, we want middleware to inspect `/app/*` tenant routes. If a user is logged in but has no active organization selected in their session, what action should the middleware take?	pass→pass	12,232	5,085	-58%	1	1	0%	2,143	3,003	+40%	0	0	—
case-10 We are building an organization selection page at `/select-org` using `@clerk/nextjs`. We need to present the `<OrganizationSwitcher />` component such that users cannot select personal accounts and are forced to pick an active organization. Which prop enforces this behavior?	pass→pass	4,086	2,862	-30%	1	1	0%	713	2,518	+253%	0	0	—
case-11 I have an Express API backend that serves requests from both a web client and a React Native mobile client. In a protected route `/api/profile`, how should the Express handler extract the user ID using `@clerk/express` helper functions?	pass→pass	9,532	4,757	-50%	1	1	0%	1,749	2,927	+67%	0	0	—
case-12 A React Native app using `@clerk/clerk-expo` calls an Express backend powered by `@clerk/express`. Web browser clients successfully authenticate, but mobile requests fail with 401 Unauthorized errors. What client request setting is missing in the mobile fetch calls?	pass→pass	5,611	5,657	+1%	1	1	0%	953	2,907	+205%	0	0	—
case-14 What primary React component from `@clerk/nextjs` must wrap the `<html>` root markup in Next.js `app/layout.tsx` to provide authentication state across server and client components?	pass→pass	3,154	2,596	-18%	1	1	0%	582	2,402	+313%	0	0	—
case-15 When proxying requests from a Next.js BFF to downstream microservices, the BFF calls `getToken({ template: 'billing' })`, but downstream Express services fail JWT verification. Assuming code parameters are correct, what administrative task must be completed in the Clerk Dashboard?	pass→pass	9,190	7,098	-23%	1	1	0%	1,534	3,196	+108%	0	0	—
case-16 In a Next.js BFF proxy API route (`app/api/proxy/[service]/route.ts`), how should the server route forward the generated Clerk JWT token when invoking downstream microservice HTTP endpoints?	pass→pass	14,497	6,558	-55%	1	1	0%	2,719	3,286	+21%	0	0	—
case-17 On an organization selection page using Clerk's `<OrganizationSwitcher />`, we want to automatically send users to `/app/dashboard` immediately after an organization is chosen. Which prop controls this navigation destination?	pass→pass	3,476	1,967	-43%	1	1	0%	587	2,230	+280%	0	0	—
case-18 When integrating Clerk into a Node.js Express application using `@clerk/express`, how should the Clerk authentication middleware be registered on the top-level Express application instance?	pass→pass	6,337	4,748	-25%	1	1	0%	1,258	2,865	+128%	0	0	—
case-19 After completing reference architecture implementations for full-stack Next.js, microservices, multi-tenant SaaS, and mobile backends with Clerk, what is the specified next topic module to follow?	fail→pass	9,706	1,647	-83%	1	1	0%	1,529	2,227	+46%	0	0	—
case-20 In a Prisma database schema representing Clerk organization memberships, how should membership role authorization levels (e.g. org:admin or org:member) be stored on the membership model?	pass→pass	11,348	9,670	-15%	1	1	0%	2,090	3,621	+73%	0	0	—
case-21 When configuring Clerk webhook ingestion at `/api/webhooks/clerk` in Next.js App Router, why is it critical that `/api/webhooks(.*)` is included in `createRouteMatcher` for public routes?	pass→pass	11,270	6,898	-39%	1	1	0%	1,894	3,257	+72%	0	0	—
case-22 When setting up protected API endpoints in Express using `@clerk/express`, which route-level middleware function should be passed to automatically reject unauthorized requests before reaching the handler logic?	pass→pass	4,278	2,902	-32%	1	1	0%	754	2,531	+236%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +9 percentage points is the difference between those two pass rates over the 22 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 86.4%
Pass rate with the skill: 95.5%
Cases attempted: 22
Cases counted toward lift: 22
Cases that regressed: 0
Skill version measured: v1
Run completed: 8/13/2026, 17:24 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-06

Prompt

In a microservices architecture with a Next.js BFF proxy calling downstream services, calling `getToken()` without arguments returns generic session tokens that downstream services reject due to missing claims. How should the BFF call `getToken()` to generate microservice-specific JWTs?

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals2 of 4 complete

BenchmarkPass rate WITH skill on a verified run95

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionBreadth of real use across orgs40

Efficiency · separate axis (at equal correctness)+0% turns+86% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 2 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 45 days ago

Other measured skills in the registry, with their headline benchmark lift.