Coding Course Generator

Local-first, open-source software for learning healthy coding fundamentals in the age of AI.

This project is a build-in-public social experiment. The goal is not to ship a hosted product. The goal is to help learners run the app locally, scaffold a real project into their own GitHub repository, and learn fundamentals, debugging habits, and engineering discipline through guided milestones.

• The source code in this repository is licensed under MIT.
• The repo is intentionally private at the package-manager level in package.json to prevent accidental npm publishing.
• This repository is publicly visible on GitHub and is intended to be cloned and run locally.
• Treat the codebase, docs, screenshots, and git history as public-facing project material.

• Teach programming fundamentals through real projects
• Teach professional engineering habits, not just syntax
• Help AI-assisted builders develop better judgment, debugging ability, and maintainable code instincts
• Keep the whole system inspectable and hackable for learners by running locally and staying open source

• Lists guided project-based courses
• Scaffolds a starter project into your GitHub repository
• Tracks milestone progression through GitHub pull requests and validation checks
• Can optionally post advisory AI review comments on PRs when AI mode is enabled
• Can generate local custom courses focused on one skill intent:
  • debugging
  • error_handling

The app is meant to run on your machine.

• apps/web: Next.js UI + local APIs
• apps/worker: local background worker for scaffold jobs, GitHub sync, AI review, and custom-course generation
• packages/core: Prisma + shared runtime utilities
• packages/jobs: background job logic
• packages/llm: direct OpenAI / Anthropic integration for local AI features
• packages/archetype: starter project scaffold generator

The default auth mode is local. You do not need Supabase for normal local use.

• Node.js 22+
• pnpm
• Postgres
• A GitHub repository for each course instance you want to use

Optional for AI features:

• OPENAI_API_KEY or ANTHROPIC_API_KEY

• See SECURITY.md for reporting guidance and secret-handling expectations.
• Keep all secrets in local env files such as .env or .env.local, never in tracked files.
• Admin pages are locked down by default. Use ADMIN_USER_IDS for authenticated admins, or set ALLOW_DEV_ADMIN_BYPASS=true only for explicit local debugging.

1. Install dependencies

pnpm install

2. Copy your env file

cp .env.example .env

3. Configure your local env

The app is local-first, but it still needs a real Postgres database and a GitHub token to scaffold repos and track PR progress.

LOCAL_AUTH_MODE=true only controls authentication. It does not remove the database requirement.

You must point DATABASE_URL at a working Postgres instance, and the target database must already exist before you run pnpm db:migrate.

Two supported examples:

# Matches the default example in .env.example
DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:54322/postgres

# Standard local Postgres on port 5432
DATABASE_URL=postgresql://myuser:mypassword@127.0.0.1:5432/coding_course_generator

DATABASE_URL is:

• postgresql://
• database user
• database password
• database host
• database port
• database name

If you already have Postgres installed locally, create a database and point DATABASE_URL at it.

If you want a quick disposable local Postgres with Docker, this is a valid option:

docker run --name coding-course-generator-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=coding_course_generator \
  -p 5432:5432 \
  -d postgres:16

Then set:

DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/coding_course_generator

For the default local workflow, keep:

LOCAL_AUTH_MODE=true

This enables the local anonymous user flow. You do not need Supabase auth for the normal local setup.

Set a GitHub token so the app can:

• create or update scaffold files in your practice repo
• read pull requests, workflow checks, and merge state
• post advisory AI review comments when AI mode is enabled

For the simplest local setup, use a classic personal access token with:

• repo
• workflow

Create it from GitHub account settings under developer settings / personal access tokens, then store it in .env:

GITHUB_SCAFFOLD_TOKEN=ghp_your_token_here

Do not commit this token. Keep it only in your local .env.

Optional but recommended for stored GitHub tokens:

GITHUB_TOKEN_ENCRYPTION_KEY=your-32-plus-character-key

This is used when the app stores repo-specific GitHub tokens internally.

• if it is set, stored repo tokens can be encrypted and reused
• if it is missing, the fallback GITHUB_SCAFFOLD_TOKEN still works
• stored per-repo tokens will not work correctly without it

Use a random string with at least 32 characters.

Optional AI setup:

OPENAI_API_KEY=sk-...
# or
ANTHROPIC_API_KEY=...

# optional provider/model overrides
LLM_PROVIDER=openai
OPENAI_MODEL=gpt-4.1-mini
ANTHROPIC_MODEL=claude-3-5-haiku-latest

AI features remain disabled unless OPENAI_API_KEY or ANTHROPIC_API_KEY is set.

LLM setup is required for:

• the AI assistance toggle during course-instance creation
• local advisory AI PR reviews
• custom skill-course generation

4. Generate Prisma client and apply migrations

pnpm db:generate
pnpm db:migrate

5. Seed the base curated course

pnpm db:seed

6. Run the app and worker locally

pnpm dev

The web app runs on http://localhost:3001.

Before using the app, verify:

• DATABASE_URL points to a reachable Postgres database
• pnpm db:migrate completed successfully
• pnpm db:seed completed successfully
• pnpm dev is running both the web app and worker
• GITHUB_SCAFFOLD_TOKEN is present if you want to scaffold or sync GitHub repos
• OPENAI_API_KEY or ANTHROPIC_API_KEY is present if you want AI assistance enabled

For an already-public repository, verify on an ongoing basis:

• LICENSE and SECURITY.md are present and accurate for the project you want to run in public
• no real credentials appear in tracked files, docs, screenshots, copied terminal output, or reachable git history
• .env, .env.local, and any local key material remain untracked
• supabase/.branches and supabase/.temp stay out of version control because they are local CLI state
• any seeded curriculum content, prompts, examples, and scaffold templates are yours to redistribute
• admin access is configured intentionally and ALLOW_DEV_ADMIN_BYPASS is not enabled unless you are actively debugging locally

Local auth is the default.

• LOCAL_AUTH_MODE=true means the app uses a local anonymous development user
• Supabase is optional and no longer required for the normal local workflow
• If you want to re-enable hosted auth behavior later, set LOCAL_AUTH_MODE=false and provide the Supabase env vars

The app now uses outbound GitHub sync as the primary local integration model.

That means:

• you do not need a public production webhook endpoint
• the local worker polls GitHub for PRs, comments, checks, and merges
• milestone progression and AI reviews happen from your local runtime

For the simplest local setup, use a classic PAT with:

• repo
• workflow

Set it as:

GITHUB_SCAFFOLD_TOKEN=ghp_...

This token is used for:

• scaffolding the starter repo
• reading PRs and checks
• posting AI review comments

AI assistance is optional and per course instance.

When creating a course instance:

• connect the GitHub repo first
• if the app detects OPENAI_API_KEY or ANTHROPIC_API_KEY, the AI assistance toggle becomes available
• if enabled, the local worker can:
  • post an automatic advisory review when a PR opens
  • rerun the review when someone comments /review on the PR

Important:

• AI reviews are advisory only
• milestone progression is still controlled by validation + merge rules

This repository includes seeded course content and starter template material. Confirm that all included instructional text, prompts, examples, and scaffold assets are either authored by you or intentionally licensed for public redistribution.

Use /courses/custom to generate a local course template focused on one skill intent.

Current supported intents:

• debugging
• error_handling

How it works:

• the app reuses the existing JavaScript full-stack scaffold family
• the LLM generates custom milestone framing, skill overlays, and hints
• deterministic validation keeps the course compatible with the scaffold and progression model
• the generated course is stored locally and appears in the normal course catalog

1. Open /courses
2. Pick a curated course or generate a custom skill-focused course
3. Create a GitHub repository
4. Connect the repo in the app
5. Scaffold the starter project into that repo
6. Clone the repo locally and work milestone by milestone
7. Open PRs on GitHub
8. Let milestone validation and optional AI review guide the next step

• Install: pnpm install
• Run app + worker: pnpm dev
• Run web only: pnpm dev:web
• Run worker only: pnpm dev:worker
• Generate Prisma client: pnpm db:generate
• Migrate local DB: pnpm db:migrate
• Seed curated course data: pnpm db:seed
• Typecheck: pnpm typecheck
• Lint: pnpm lint
• Test: pnpm test
• Full local CI mirror: pnpm ci:check

• Existing course instances stay pinned to the template version they were created from
• Generated custom courses are local templates, not a hosted multi-tenant feature
• The app still contains optional webhook compatibility paths, but local outbound sync is the intended default

This repo is meant to stay understandable to learners. Prefer changes that:

• make fundamentals more explicit
• reduce hidden operational knowledge
• improve the local-first setup
• make AI assistance safer and more inspectable