The open-source engine behind toastcrumb — a habit-forming micro-learning app that makes software engineering concepts click through short, addictive, real-world scenarios.
This repository is the runnable application: the swipe-based learning UI, the user-state API, the shared types, and a small sample of learning content so the app works end to end. The full concept library and the AI content-generation pipeline that produce it power the hosted product and are not part of this repo.
Core architectural principle: content is static, user state is dynamic. The database never stores learning content — only a user's progress, streaks, and XP.
| Path | What | Stack |
|---|---|---|
apps/web |
Swipe-based learning UI | Next.js 15 · Tailwind v4 · Framer Motion |
apps/api |
User state, XP, streaks, progress, events | NestJS 11 · Prisma 6 · PostgreSQL |
packages/types |
Shared domain types + content rules | TypeScript |
content/ |
Static concept/lesson JSON (sample set — see note below) | JSON |
graph/ |
The full concept graph, exported (graph.json + GRAPH.md) |
JSON · Markdown/Mermaid |
This is the open application. The full concept library and the pipeline that generates it are proprietary and live in a private repository — they're the product, not the code.
content/concepts/ships with a small, self-contained sample (the caching cluster) so the app is fully functional from a clean clone with no secrets. Each file is oneConceptmatching the type inpackages/types; drop in morecontent/concepts/<id>.jsonfiles and they appear automatically.- In the hosted deployment, the web build overlays the full library:
scripts/fetch-content.mjsruns beforenext buildand, when aCONTENT_REPO_TOKENis set, pullscontent/from the private repo. Without the token it's a no-op and the sample is used. See that file's header for the env vars (CONTENT_REPO_TOKEN,CONTENT_REPO,CONTENT_REPO_REF).
The whole map is here, for every concept — not just the sample: graph/GRAPH.md
(rendered Mermaid diagrams per domain, plus a table of every concept) and
graph/graph.json (the same data, machine-readable).
- What it contains: each concept's
id,title,description,difficulty,domain,prerequisitesandnext— that is, the graph structure and the metadata needed to read it. - What it does not contain: the lessons. Cards, quizzes, answer options and explanations are
the product and are not exported. The per-concept
contextsare excluded too. - Yes,
graph/andcontent/concepts/disagree in size — deliberately. The graph covers every concept;content/concepts/here holds only the sample set described above. Full map, sample lessons. - How it gets here: generated from the private content library by
content:export-graphand copied here by hand, under the same manual, one-directional sync policy as the rest of this repo (docs/ARCHITECTURE.md). Both files are generated artifacts — don't hand-edit them; a PR that does will be regenerated away. - Licence: the export is content, so it is CC BY-NC 4.0 like the rest of
content/— seecontent/LICENSE.
- Node ≥ 20 (see
.nvmrc) - pnpm 11
- A PostgreSQL database for the API (any Postgres — local Docker, Neon, etc.)
pnpm install
# API: configure DB and generate the Prisma client
cp apps/api/.env.example apps/api/.env # set DATABASE_URL
pnpm db:generate
pnpm db:migrate # creates tables
# Web: point at the API
cp apps/web/.env.local.example apps/web/.env.localpnpm dev # runs web (:3000) and api (:4000) together
pnpm dev:web # web only
pnpm dev:api # api only- Web: http://localhost:3000
- API health: http://localhost:4000/api/health
- Architecture — system shape, boundaries, content delivery
- Data model — the dynamic-state tables
- Content system — concept/lesson/card shapes and authoring rules
- Concept graph — how concepts link and unlock
- Game loop — XP, streaks, review, daily challenge
- UI guidelines — design direction
Code is licensed under the Apache License 2.0. The sample learning content under
content/ is licensed separately under CC BY-NC 4.0 — see that file.