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

app/

React SPA

TanStack Start renders the UI. It never queries the database directly for content. All data flows through the API.

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.

supabase/

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_bases

A topic node in the graph. Points to its top-ranked guide and carries the knowledge_type (theory or practice).

guides

Content pages under a base: the top-ranked write-up plus its ranked alternatives and methods, each with its own URL and votes.

guide_revisions

Immutable, append-only history. Every edit is a new revision; rollback copies an old one forward. Nothing is silently overwritten.

guide_edges

The prerequisite edges: the actual graph. subjects tag nodes as filters over it, not as containers.

votes · review_cases

Rubric-tagged votes and the verifier/moderator review trail. Review state is derived from cases, never duplicated onto revisions.

content_holds

Legal 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

Layer Tech Why
FrontendReact 19 · TanStack Start/Router/Query · shadcn/ui · TailwindType-safe routes, cache-aware data, familiar to most web contributors.
APIHono on Cloudflare Workers · ZodTiny, fast, runs at the edge; one validated door to the data.
DatabaseSupabase: Postgres · GoTrue auth · RLSRecursive CTEs walk the DAG; row-level security guards every row.
Type bridgeHono hc<AppType>Frontend imports the API's types. No codegen, no drift.
Toolingpnpm workspace · Vite + nitro · WranglerOne monorepo; pnpm dev runs API and app together locally.
LicensingAGPL-3.0 (code) · CC BY-SA 4.0 (content)Open source, copyleft. Improvements stay open.

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.