Knowledge as code
Built on tools anyone can read on day one.
No proprietary frameworks, no magic. Bluelearn is one global prerequisite graph behind a typed API on the edge, chosen so a new contributor can be productive without a week of onboarding. Everything here lives in a public, open-source monorepo.
Three layers, strict boundaries
React SPA
TanStack Start renders the UI. It never queries the database directly for content. All data flows through the API.
Hono on Cloudflare Workers
The typed API runs at the edge. It validates every request, checks auth, and is the single door to the data.
Postgres + Auth + RLS
Supabase holds the graph as ground truth. Row-level security and GoTrue auth guard every row.
End-to-end type safety, no codegen. The app imports the API's type and calls it through Hono's hc<AppType> client. A route signature change surfaces as a TypeScript error in the frontend immediately. Auth runs app ↔ Supabase (GoTrue JWT); every API request carries that token and middleware validates it.
The stack, layer by layer.
// app/src/routes/guide.$slug.tsx import { useQuery } from '@tanstack/react-query' import { api } from '@/lib/client' // hc<AppType> const { slug } = Route.useParams() const { data: guide } = useQuery({ queryKey: ['guide', slug], queryFn: () => api.guides[slug].$get(), })
Frontend. React 19 on TanStack Start, Router & Query. shadcn/ui components over Tailwind. File-based, type-safe routes and cache-aware data fetching.
// api/src/routes/guides.ts import { Hono } from 'hono' export const guides = new Hono<Env>() .get('/:slug', async (c) => { const { slug } = c.req.param() const g = await topGuide(c, slug) return c.json(g) })
Backend.
Hono on Cloudflare Workers, a tiny, fast API at the edge. Zod validates every input; supabase-js talks to the database. Deployed with Wrangler.
-- walk the prereq DAG in one query WITH RECURSIVE prereqs AS ( SELECT from_guide, to_guide, 1 AS depth FROM guide_edges WHERE to_guide = $1 UNION ALL SELECT e.from_guide, e.to_guide, p.depth+1 FROM guide_edges e JOIN prereqs p ON e.to_guide = p.from_guide ) SELECT * FROM prereqs;
Storage.
PostgreSQL on Supabase holds the typed guide_edges DAG. A single recursive CTE walks every prerequisite. Row-level security and GoTrue auth are built in.
The data model
Store the graph. Derive everything else.
The schema records exactly two things as ground truth: the graph, and the governance trail. Anything that can be computed from those is computed, never stored, never allowed to drift.
guide_basesA topic node in the graph. Points to its top-ranked guide and carries the knowledge_type (theory or practice).
guidesContent pages under a base: the top-ranked write-up plus its ranked alternatives and methods, each with its own URL and votes.
guide_revisionsImmutable, append-only history. Every edit is a new revision; rollback copies an old one forward. Nothing is silently overwritten.
guide_edgesThe prerequisite edges: the actual graph. subjects tag nodes as filters over it, not as containers.
votes · review_casesRubric-tagged votes and the verifier/moderator review trail. Review state is derived from cases, never duplicated onto revisions.
content_holdsLegal and moderation holds (reversible hide, audited purge, and mandated legal preservation), designed into the schema from the start.
Ground truth
Guides, edges, revisions, votes, review cases, legal holds.
Computed on demand
Levels, frontiers, reachability, walkthroughs, sibling ordering, all derived from the graph, so they can never disagree with it.
At a glance
Read it, run it, improve it.
The whole stack is in one public monorepo with a documented local setup. New contributors can clone, run pnpm dev, and ship a real change.