BlueLearn

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

---

📚 What is BlueLearn

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 →

---

🎥 Watch the overview

A 23-minute walkthrough of what BlueLearn is, why it's nonprofit, and how the prerequisite graph changes how you read a concept page.

---

🚀 Quick start

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

# 3. Copy env files and fill in the values supabase printed
cp api/.dev.vars.example api/.dev.vars

# 4. Run app + api side-by-side
pnpm dev:api          # Workers dev   → http://localhost:8787
pnpm dev:app          # Vite dev      → http://localhost:3000

The Vite dev server proxies API calls to localhost:8787, so the browser sees one origin and you don't have to fight CORS.

💡 Tip: pnpm dev runs both app and api in parallel through pnpm workspaces.

---

🗂️ Project layout

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>.

---

🛠️ Tech stack

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

Phase 3 R&D (bonus, not required)

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.

---

🧭 Roadmap

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/pages/roadmap.html

---

🤝 Contributing

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:

1. Find a good first issue or open one.
2. Comment that you'd like to take it.
3. Set up locally and open a draft PR early.
4. Ping #contributing on Discord anytime.

What we're hiring for (the contribution profile)

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.

---

📈 Star history

---

👥 Contributors

Thanks to everyone who has helped shape BlueLearn.

---

💛 Support the project

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

---

📊 At a glance

Stars
Forks
Open issues
Open PRs
Discord members

---

📜 License

• 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}