Hermes Wiki
TechResearch/Clerk_Based_Auth/clerk_based_auth

FullStackFusions (unresolved) — Combined Auth Architecture

For the actual step-by-step production setup (dashboard gotchas, real DNS records, OAuth credential setup), see clerk_production_setup_walkthrough.md — this doc is the plan, that one is what actually happened setting up hermes-wiki.

For restricting sign-in to specific people without a paid Clerk plan, see clerk_free_tier_access_control.md.

1. Project map

Subdomain Project Stack Auth needed? Providers required Audience
fullstackfusions.com Portfolio Cloudflare Pages (static) No — Public
wiki.fullstackfusions.com Hermes PKM Custom app, markdown-backed, Claude Code as the Hermes agent, read-only UI Yes Google + GitHub You (+ maybe a few trusted people)
courses.fullstackfusions.com Course CMS React + FastAPI, S3 storage, Supabase (Postgres) Yes Google only Public learners
localz (domain TBD — see open item below) Marketplace MVP React + FastAPI, reuses shared stack Yes Google + GitHub Public, early MVP scale

All three auth-needing projects are apps you built yourself — not off-the-shelf software. That means all three use Pattern A (native SDK) from the earlier architecture doc: Clerk's React SDK wraps the frontend, and your FastAPI backends verify the session JWT on protected routes. You don't need the nginx auth_request gateway pattern anywhere here — that pattern exists specifically for apps you can't modify.

2. One Clerk app per project — not one shared login

It's tempting to reuse a single Clerk application across all subdomains (you get SSO for free between sibling subdomains, as established last time). But don't here, for this specific set of projects — use three independent Clerk applications, one each for wiki, courses, and localz.

Why separate instead of shared:

  • Different audiences. Wiki is personal/small-circle. Courses and Localz are public. There's no real user who needs a session valid across all three — SSO would just be unused capability, not a benefit.
  • Different provider requirements. Wiki and Localz need Google + GitHub; Courses needs Google only. That's naturally per-app configuration in Clerk's dashboard, so separate apps map cleanly to that difference — no need to hide/show buttons conditionally in one shared app.
  • Independent 50,000 MRU pools. Free tier gives 50k MRU per app, and you get unlimited applications on Hobby. Three separate apps means three separate 50k allowances at zero extra cost — strictly more headroom than cramming everything into one app.
  • Blast-radius isolation. If Localz (public MVP, higher exposure surface) ever has an incident — bad actor, leaked key, abuse — it's contained to Localz's user pool. Your personal Wiki access isn't touched.
  • Independent scaling decisions. When Localz grows and needs Pro-tier features, you upgrade that Clerk workspace/app without dragging Wiki or Courses into a paid plan they don't need.

The cost of this approach: each project needs its own publishable/secret key pair, and technically its own custom domain (Clerk's Frontend API needs a dedicated hostname per app, conventionally clerk.<subdomain> — e.g. clerk.wiki.fullstackfusions.com, clerk.courses.fullstackfusions.com). That's a few extra DNS CNAME records, not real complexity.

3. Per-project setup snapshot

Wiki (Hermes PKM) — private/personal

  • Clerk app: hermes-wiki
  • Providers: Google + GitHub only (no email/password needed if it's just you)
  • Custom domain for Clerk: clerk.wiki.fullstackfusions.com
  • Since this is read-only and low-traffic, restrict access to just your own account so it's not even theoretically open to strangers — a wiki with your notes shouldn't have a public sign-up flow at all. Note: Clerk's dashboard-level allowlist is a paid-plan feature, not available on Hobby — this is enforced in app code instead, see clerk_free_tier_access_control.md.

Courses — public CMS

  • Clerk app: fsf-courses
  • Providers: Google only
  • Custom domain for Clerk: clerk.courses.fullstackfusions.com
  • FastAPI backend verifies Clerk JWT per request; tie user_id from the token to your Supabase user/enrollment records.

Localz — public marketplace MVP

  • Clerk app: localz-mvp
  • Providers: Google + GitHub
  • Custom domain for Clerk: TBD once Localz's own domain/subdomain is confirmed
  • Since this is explicitly MVP-scale ("only expecting a few people"), Hobby tier comfortably covers it. Revisit the plan question only when you have real usage data, not before.

4. What's in Clerk's Hobby (free) tier — brief recap

  • 50,000 MRU per app, unlimited applications — this is the core number; you won't approach it for any of these three projects for a long time.
  • Google, GitHub, and most other social/OAuth sign-in providers — included, no extra cost.
  • Custom domain support (so Clerk's hosted pages live on your own subdomain, not a *.clerk.accounts.dev URL).
  • Fixed 7-day session lifetime (not configurable on Hobby).
  • 1-day auth log retention.
  • Up to 3 dashboard seats, 5 user impersonations (admin/debug tooling, not user-facing).
  • Not included: enforced/configurable MFA policy, >7-day sessions, >1-day log retention, removing Clerk branding on hosted pages, Enterprise SSO (SAML/OIDC) connections.

None of the "not included" items are relevant to Wiki, Courses, or Localz at their current stage — this is a genuine "free tier fits your actual scale" situation, not a trial that nudges you toward paying.

5. When to move Localz to a paid tier (or elsewhere)

Worth tracking loosely, not deciding now:

  • Signal to watch: Localz's MRU approaching 50,000/month, or you needing longer sessions / MFA enforcement for marketplace trust reasons (buyers/sellers handling money-adjacent flows tend to want this earlier than you'd expect).
  • Decision when it happens: Clerk's billing is per-workspace, not per-individual-app-family, so confirm in Clerk's own billing docs whether upgrading affects only the localz-mvp application or the whole account — worth a quick check before assuming it's scoped narrowly. (I'd rather flag this as something to verify than state it confidently, since it directly affects cost if you're wrong about the scope.)
  • Alternative if cost becomes the blocker instead of features: Supabase Auth (since you're already using Supabase for Localz's DB) is a reasonable fallback — free, self-managed within infrastructure you already run, though you'd lose Clerk's prebuilt UI components and would need to wire up your own sign-in screens.

6. Open item to confirm

What's Localz's actual domain going to be — localz.fullstackfusions.com (subdomain of the same root, giving you the sibling-subdomain benefits from the earlier doc if you ever did want shared session with something else), or a fully separate domain (localz.com or similar, since it's positioned as "the main important" standalone product)? This decides whether Localz's Clerk custom domain follows the same clerk.<subdomain>.fullstackfusions.com pattern or needs its own independent Clerk custom domain setup entirely.

Hermes Wiki