Free knowledge, structured from the ground up.
A nonprofit, open-source education platform where every concept maps to its prerequisites.
What is it · Overview · Quick start · Layout · Stack · Roadmap · Contributing · Sponsor
Most "free" knowledge online is organized for retrieval, not for learning. You can look up what a Fourier transform is on Wikipedia in 30 seconds. Actually learning it without a class? That's a week of figuring out what to read first.
Bluelearn is a graph of concepts where every page declares its prerequisites. Hit a term you don't know? The prerequisite is one click away. Community-written, optionally expert-verified, AGPL-3.0, free forever.
This repository is the product monorepo: web client, API, and database. The marketing site is closed-source.
💬 Join the Discord → · 🌐 bluelearn.org → · 📺 YouTube →
A 23-minute walkthrough of what Bluelearn is, why it's nonprofit, and how the prerequisite graph changes how you read a concept page.
You'll need Node.js 20+, pnpm 10+, the Supabase CLI, and Docker (for the local Supabase stack).
# 1. Clone and install
git clone https://github.com/bluelearn-org/bluelearn.git
cd bluelearn
pnpm install
# 2. Start local Supabase (Postgres + Auth on docker)
pnpm supabase:start
# If your shell/OS does not resolve the local Supabase binary,
# use one of these instead:
# pnpm exec supabase start
# pnpx supabase start
# 3. Copy env files and fill in the values Supabase printed
cp api/.dev.vars.example api/.dev.vars
cp app/.env.example app/.env
# 4. Run app + api side-by-side
pnpm dev:api # Workers dev → http://localhost:8787
pnpm dev:app # Vite dev → http://localhost:3000The app reads VITE_API_BASE from app/.env (default http://localhost:8787),
and the API uses APP_URL from api/.dev.vars for CORS (default http://localhost:3000).
💡 Tip:
pnpm devruns bothappandapiin parallel through pnpm workspaces.
bluelearn/
├── app/ React 19 · TanStack Start · TanStack Router/Query
│ shadcn/ui · Tailwind 4 · Vite
├── api/ Hono on Cloudflare Workers
│ Routes: /subjects · /walkthroughs · /guides
├── supabase/ Postgres · Auth · Storage — migrations + RLS policies
├── docs/
│ ├── architecture.md System overview + diagram
│ ├── monorepo.md Why one repo instead of three
│ ├── overall-system.md Editorial pipeline + verifier design
│ ├── database-schema.md ERD walkthrough
│ └── open-questions.md Active design debates
└── .github/
├── workflows/ci.yml app + api in parallel
├── ISSUE_TEMPLATE/ bug · feature · guide proposal
├── PULL_REQUEST_TEMPLATE.md
├── CODEOWNERS
└── FUNDING.yml
Why a monorepo? See docs/monorepo.md — short
version: atomic cross-stack changes, one CI, one onboarding flow,
type-safety end-to-end via Hono's hc<AppType>.
| Layer | Tech | Why |
|---|---|---|
| Frontend | React 19 · TanStack Start · TanStack Router/Query · shadcn/ui | Type-safe routing, cache-aware data, accessible primitives |
| API | Hono on Cloudflare Workers · @hono/zod-validator |
Edge-fast, tiny, type-safe end-to-end with the frontend |
| Database | Supabase (Postgres 15 · GoTrue Auth · Storage) | Managed Postgres + RLS, JWT auth, file storage in one |
| Tooling | pnpm workspaces · TypeScript · ESLint · Prettier · Vitest | One install, one CI, one style |
| CI/CD | GitHub Actions (parallel jobs per package) | Fast feedback, easy to extend |
| Wire types | Hono AppType exported from api/src/index.ts |
hc<AppType> gives the frontend full request/response types |
Decentralized editorial verification: signing the canonical concept history into a verifiable log. Tools under exploration: SUI · Move · Walrus. Skills welcome from contributors interested — these are not on the Phase 1 critical path.
| Phase | Status | Focus |
|---|---|---|
| 1 | 🟢 Active | The Core — data model, graph traversal, basic UI, community seed |
| 2 | ⚪ Next | Universal Access — i18n, expert verification tooling, API formalize |
| 3 | ⚪ Future | Decentralization — protocol extraction, self-host, independent mirrors |
Full roadmap: bluelearn.org/roadmap
Small project, tight loop. New contributors land their first PR within a day on a good week. CONTRIBUTING.md is the full guide.
The shortest path:
- Find a
good first issueor open one. - Comment that you'd like to take it.
- Set up locally and open a draft PR early.
- Ping
#contributingon Discord anytime.
Frontend — TypeScript proficiency, React, TanStack ecosystem (router + query), UI/UX sense. Backend — TypeScript on Workers (Hono), Supabase / Postgres, RLS familiarity. Generalist bonus skills — accessibility, i18n, performance budgets. Phase 3 R&D bonus — web3 smart contracts (SUI, Move), Walrus storage.
Thanks to everyone who has helped shape Bluelearn.
Bluelearn is fiscally sponsored — 501(c)(3) pending. Every dollar funds infrastructure (Supabase, Cloudflare, Discord), editorial review, and making content available offline in low-bandwidth regions.
- One-time / recurring donation → bluelearn.org/donate
- GitHub Sponsors → coming once the org is live
- Help in other ways → star the repo, share the project, open an issue, send a PR
| Stars | |
| Forks | |
| Open issues | |
| Open PRs | |
| Discord members |
- Code — AGPL-3.0-or-later. Any service that exposes this code over a network must publish its source.
- Content — CC BY-SA 4.0. Concept pages and editorial material remix freely with attribution and share-alike.
By contributing you agree your work is licensed under the applicable license above. See CONTRIBUTING.md for sign-off details.
Built openly · bluelearn.org · Discord · GitHub