Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/CLERK_SUPABASE_INTEGRATION.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,10 @@
# Clerk + Supabase, without Supabase Auth

> **Historical reference:** the website no longer has a public leaderboard or
> profile editor. The current app only syncs private course completions; use
> [`SUPABASE_SETUP.md`](SUPABASE_SETUP.md) for the supported setup. Do not apply
> the public profile policies or leaderboard examples below.

A portable write-up of the pattern: **Clerk owns identity, Supabase owns data**, and
Supabase's row-level security reads the Clerk user id straight out of Clerk's JWT.
No Supabase Auth, no user-mirroring webhook, no `auth.users` table.
Expand Down
23 changes: 0 additions & 23 deletions docs/DEPENDENCY_OVERRIDES.md

This file was deleted.

58 changes: 24 additions & 34 deletions docs/SUPABASE_SETUP.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,32 @@
# Turning on accounts + the leaderboard (Clerk + Supabase)
# Turning on accounts + course progress sync (Clerk + Supabase)

The site works **without** any of this — every student's progress, XP, streak,
badges, and Kodas save locally on their own device. Accounts add two things on
top: **syncing that progress across devices** and a **leaderboard** so students
can compete. Both free tiers are plenty for this.
The site works **without** any of this — course completions save locally on the
learner's device. Accounts add **course progress sync across devices**. Both
free tiers are plenty for this.

Two services, one job each:

- **Clerk** = sign-in (Google + email/password, sessions, the user menu).
- **Supabase** = the database behind the leaderboard (`profiles`, `progress`).
- **Supabase** = the database for synced course completions (`progress`).

They connect through Clerk's **Supabase integration**: Clerk issues each signed-in
student a token, the app sends it to Supabase, and Supabase's row-level security
reads the Clerk user id from that token so a student can only ever write their
own rows.

The code is already wired. Until the keys below exist, the app quietly falls back
to local-first: `/login` shows "Accounts are coming soon", `/leaderboard` shows
"almost here", the header shows a plain **Log in** button, and nothing breaks.
to local-first: `/login` shows "Sign-in is coming soon", the header shows a
plain **Sign in** button, and nothing breaks.

---

## ⚠️ Before you collect a single real account

Most of our students are minors. **Settle COPPA / parental-consent and publish a
privacy policy before enabling accounts in production.** The leaderboard is public
by design — every visitor can read every display name — so the sign-up asks for a
*display name*, not a real full name. Keep it that way.
privacy policy before enabling accounts in production.** Account-linked course
completions are stored in Supabase. Row-level security limits browser access to
the signed-in learner's own rows; project operators and service-role clients can
also access the data under the project's administrative controls.

---

Expand Down Expand Up @@ -68,8 +68,8 @@ by design — every visitor can read every display name — so the sign-up asks
existed, re-running is how you get the `subscribers` table.

**Re-run `chapters.sql` every time you publish or retire a chapter.** A
completion for a chapter missing from that table is silently discarded and
earns no XP. `npm run learn:check` fails the build when the file has drifted
completion for a chapter missing from that table is silently discarded.
`npm run learn:check` fails the build when the file has drifted
from the curriculum, but it cannot tell whether you have applied it to the
database — that part is on you.

Expand Down Expand Up @@ -178,9 +178,10 @@ by design — every visitor can read every display name — so the sign-up asks
Clerk under **Configure → Domains** as well.

3. **Verify.** Run `npm run dev`, open `/login`, create an account (try both
Google and email), and confirm you land on the site signed in. Then check the
Supabase **Table editor → profiles** — a row with your Clerk id should appear.
Finally, `/leaderboard` should list you with "(you)" highlighted.
Google and email), and confirm you land on the courses page signed in. Complete
a chapter, then check Supabase **Table editor → progress** for a row with your
Clerk id and chapter slug. Sign in on another device to confirm the chapter
completion follows the account.

---

Expand All @@ -190,17 +191,14 @@ by design — every visitor can read every display name — so the sign-up asks
| --- | --- |
| Sign in / sign up (Google + email) | Clerk — `<SignIn>` / `<SignUp>` on `/login` and `/sign-up` |
| The account menu in the header | Clerk — `<UserButton>` |
| Who you are on the board | Supabase `profiles` — `display_name` + `avatar` only |
| Lesson completions | Supabase `progress` (one row per passed lesson) |
| XP and streak | Derived by trigger from `progress`; the browser cannot write them |
| Which chapters can be claimed | Supabase `chapters`, generated by `npm run learn:sql` |
| Leaderboard ranking | `select … from profiles order by xp desc` |
| Newsletter sign-ups | Supabase `subscribers`, written server-side; Resend sends the welcome |
| Access control | Row-level security on the Clerk `sub` claim (`schema.sql`) |

Key files, if you need them: `src/lib/clerk.ts` (config flag),
`src/lib/supabase/client.ts` (public/anon reads),
`src/lib/supabase/with-clerk.tsx` (token-bearing client + profile sync),
`src/lib/supabase/with-clerk.tsx` (token-bearing client + course progress sync),
`src/lib/supabase/server.ts` (service-role client, server-only),
`src/lib/supabase/subscribers.ts` + `src/app/api/subscribe/route.ts` (the
newsletter write), `src/components/auth/` (provider + login form), `src/proxy.ts`
Expand All @@ -212,20 +210,12 @@ The on-device store stays the thing the UI reads: every screen works signed out,
and nothing is collected without an account. Supabase sits behind it as the
durable copy.

`ClerkDataSync` (in `src/lib/supabase/with-clerk.tsx`) reconciles the two once per
sign-in — it pulls the learner's `progress` rows, merges them into the local store
(union of completions), pushes back whatever the server was missing, and then
reads the resulting XP back. After that, each passed quick check writes straight
through. So progress follows a student across devices, and the chapter gate
trusts a durable record rather than one browser's localStorage.

Note the direction of that last step. **XP is read from the server, never sent to
it.** The browser writes a claim about a *chapter*; the total follows from how
many such claims name a chapter that exists. It used to work the other way — the
browser posted the number and the database stored it, which meant a signed-in
student could type their own leaderboard position into the console. Signing in on
a device carrying an inflated local total will now correct it downward, which is
the system working.
`ClerkDataSync` (in `src/lib/supabase/with-clerk.tsx`) reconciles course
completions once per sign-in — it pulls the learner's `progress` rows, merges
them into the local store, and pushes back anything the server was missing.
After that, each passed quick check writes its completion through. The course
reader can therefore resume from a different device, while still working
locally when the services are unavailable.

Without keys, none of this mounts and the site behaves exactly as it did before.
All of it is isolated to `src/lib/supabase/`, so it never touches lesson code.
Loading
Loading