CodeFlow
CodeFlow teaches backend development by building real projects, level by level. A learner picks a
tech stack (MERN, Django or Spring Boot), then works through a journey: typing real setup commands,
filling in code, arranging logic blocks and fixing planted bugs. Every level adds files to a real
project, which the learner can push to their own GitHub repository from inside the app.
- Learners: the map at
/, levels at /learn/<journey>/<level>, profile at /profile
- Admins: see every learner's progress and create or edit journeys at
/admin
- Logic challenges:
/challenge/signup
Built with Next.js 16 (App Router), React 19, Tailwind CSS 4 and PostgreSQL (Supabase), using pg
directly with no ORM. The home map is a 3D world (three.js via react-three-fiber), with a 2D map for
devices without WebGL or with reduced motion.
Dependencies are locked in pnpm-lock.yaml, which Vercel installs from. If you add a package, update
that file too (npx [email protected] install --lockfile-only), or the deploy fails.
1. Run it locally
Prerequisites
- Node.js 20.18 or newer (22 LTS recommended)
- npm (comes with Node). pnpm 9 also works.
- A PostgreSQL database. The team uses Supabase; any Postgres 14+ works.
- Git
Steps
git clone https://github.com/Anubhavsaxena2004/codeflow.git
cd codeflow
npm install
cp .env.example .env.local # Windows (cmd): copy .env.example .env.local
Fill in .env.local (see Environment variables). At minimum set
DATABASE_URL. Then create the tables and start the app:
npm run db:migrate # creates or updates the tables; safe to run again
npm run dev # http://localhost:3000
Open http://localhost:3000, create an account and pick a stack (once: after that only the admin can
change it). The MERN Todo journey is ready to
play.
The Admin and Mentor mode links in the sidebar open /admin and /mentor. Only the admin
sees them; create the admin account with npm run admin:create (see Admin access).
Scripts
| Command | What it does |
|---|
npm run dev | Dev server with hot reload on http://localhost:3000 |
npm run build | Production build |
npm start | Serve the production build (run build first) |
npm run db:migrate | Apply new files from db/migrations/ to DATABASE_URL, in order, once each |
npm run admin:create -- <email> <password> | Create the admin account, or reset its password |
npm run test:journeys | Check the journey engine and prove every bundled level is solvable |
npm run test:github | Check the GitHub integration against a mocked GitHub (no network) |
npx tsc --noEmit | Type-check (the build skips type errors, so run this before pushing) |
2. Environment variables
Locally they live in .env.local, which is gitignored and must never be committed. On Vercel they go
under Project → Settings → Environment Variables.
| Variable | Needed for | Where it comes from |
|---|
DATABASE_URL | Everything that saves | Supabase → Connect (see below) |
DATABASE_POOL_MAX | Optional | Connections per server process (default 5). Use 1 on Vercel |
DATABASE_CA_CERT_PATH | Optional | Path to the database's CA certificate, for full TLS verification |
ADMIN_EMAILS | Optional | Comma-separated admin emails. Leave it unset: the only admin is then the owner, [email protected] (OWNER_ADMIN_EMAIL in lib/server/auth.ts). Setting it replaces the owner with the listed emails |
TOKEN_ENCRYPTION_KEY | GitHub push | Any random string of 16+ characters. Never change it once set: stored GitHub connections become unreadable |
GITHUB_CLIENT_ID | Optional | Your GitHub OAuth app, for the one-click Connect GitHub button (see section 4) |
GITHUB_CLIENT_SECRET | Optional | Your GitHub OAuth app |
GITHUB_REDIRECT_URI | Optional | Only if the app is behind a proxy. Defaults to <site>/api/github/callback |
Generate a TOKEN_ENCRYPTION_KEY with:
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
3. The database (Supabase)
Copy the connection string from Supabase → your project → Connect. Use a pooler string, not
the "Direct connection" one: the direct host db.<ref>.supabase.co is IPv6-only and fails on many
networks and on Vercel.
| Where | Connection | Port | Also set |
|---|
Your machine (.env.local) and migrations | Session pooler | 5432 | — |
| Vercel | Transaction pooler | 6543 | DATABASE_POOL_MAX=1 |
The format is:
postgres://postgres.<project-ref>:<password>@aws-0-<region>.pooler.supabase.com:5432/postgres?sslmode=require
URL-encode special characters in the password (! → %21, @ → %40, # → %23).
Why two ports? Each Vercel function instance opens its own connections, and the session pooler only
allows a few clients in total, so a handful of visitors can exhaust it and sign-in starts failing.
The transaction pooler shares connections between requests. The app has been tested against both.
Migrations are SQL files in db/migrations/. Vercel does not run them: run npm run db:migrate
from your machine against the same database before deploying code that needs a new table. Each
file runs once, and schema_migrations records what has been applied.
Supabase serves the public schema over its Data API, and by default anyone holding the publishable
key can read and write new tables there. Migration 004_lock_down_data_api.sql blocks that for every
CodeFlow table. Any migration that adds a table must also enable row level security on it.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
