MakeCode Tutorial Builder

Goal: Build a standalone web application (TutorialChat) for AI-powered MakeCode tutorial authoring.

No OpenClaw dependency - Self-contained web app with its own LLM backend.

Why This Exists

The MakeCode web UI is fine for quick demos, but harder for:

• Version control (tutorials live in MakeCode cloud)
• Collaboration (no easy way to review/edit)
• Reuse (can't easily fork/remix tutorials)
• Backup (tutorials can get lost)

This project aims to:

1. Use natural language to create a tutorial
2. Convert tutorials to markdown (familiar, version-controlled)
3. Automatically convert to MakeCode tutorial format
4. Generate shareable URLs for students
5. Support images, code blocks, hints, validation

User Story

As a teacher, I want to:

1. Use natural language to create a tutorial
2. Write a tutorial in markdown (with images + code)
3. Run a command to publish it
4. Get a shareable makecode.microbit.org/#tutorial:... URL
5. Push the source to GitHub for backup/collaboration

Architecture

Standalone Web App Architecture

TutorialChat Web App
  ├─ Frontend: Next.js + React (chat UI + preview)
  ├─ Backend: FeathersJS API
  ├─ LLM: Claude/OpenAI API (direct integration)
  ├─ Database: PostgreSQL (users + tutorials)
  └─ GitHub: API integration (publishing)

User Flow:
  Natural language → AI generation → Live preview → Publish to GitHub → Share URL

Key difference: No OpenClaw involved. Standalone app anyone can use.

See: architecture.md for complete technical specification.

MakeCode supports GitHub-hosted tutorials via:

https://makecode.microbit.org/#tutorial:github:username/repo/path/to/tutorial

So we need:

• Markdown source files (versioned in git)
• Converter script (markdown → MakeCode tutorial format)
• GitHub repo (public, for hosting)
• URL generator (constructs shareable links)

Components

0. TutorialChat Web App (In Development)

Status: Architecture complete, implementation pending
Docs: See architecture.md for full specification

Tech Stack:

• Frontend: Next.js + React + Tailwind CSS
• Backend: FeathersJS (Node.js + TypeScript)
• LLM: Anthropic Claude API (direct integration, no OpenClaw)
• Database: PostgreSQL
• Hosting: DigitalOcean App Platform or Vercel

Core Features:

• Chat interface for conversational tutorial creation
• Natural language → MakeCode markdown generation
• Live tutorial preview
• One-click GitHub publishing
• QR code generation
• User accounts + tutorial library

MVP Timeline:

• Week 1: Boilerplate + Claude integration + basic chat UI
• Week 2-3: Auth + database + tutorial CRUD + preview
• Month 1-2: GitHub integration + deployment + testing
• Month 3+: Pro features + public launch

Prototyping Tools (Temporary):

• scripts/generate-tutorial.py - CLI prototype (for testing prompts)
• skill/SKILL.md - OpenClaw integration (development helper only)

These will be replaced by the web app backend.

1. Tutorial Format Spec

Define the markdown format Brian will write in:

• Frontmatter (title, description, tags)
• Step structure (## headings = steps)
• Code blocks (TypeScript/blocks hybrid)
• Images (local paths, auto-uploaded)
• Hints, validation rules

See: format-spec.md

2. Converter Script

• Input: markdown file + images
• Output: MakeCode-compatible tutorial JSON
• Language: Python or Node (TBD based on MakeCode schema)

See: scripts/convert.py (or convert.js)

3. GitHub Workflow

• Repo structure (tutorials/, assets/)
• Publish script (convert → commit → push)
• GitHub Pages config (if needed)

See: github-workflow.md

4. URL Generator

• Takes: repo, path
• Returns: makecode.microbit.org/#tutorial:... URL
• Bonus: QR code generation for classroom handouts

See: scripts/generate-url.sh

Roadmap

Phase 1: Architecture & Prototyping (current - 2026-04-12)

• Project scaffolding
• Research MakeCode tutorial format
• Define markdown format spec
• Build URL/QR code generators (standalone scripts)
• Create publish workflow scripts
• Example tutorial (blink-led)
• Complete technical architecture (standalone web app)
• CLI prototype for prompt testing (optional)
• Test live tutorial URL
• Generate 3-5 example tutorials (for testing)

Phase 2: TutorialChat MVP (Week 1-4)

Week 1:

• Next.js + FeathersJS boilerplate
• Claude API integration
• Basic chat UI (message input + response)
• Tutorial generation endpoint

Week 2-3:

• User authentication (JWT + email/password)
• Database setup (PostgreSQL + models)
• Tutorial CRUD operations
• Markdown preview panel
• Save/load drafts

Week 3-4:

• Download markdown (export)
• Tutorial library UI
• Edit existing tutorials
• Basic error handling
• Deploy to staging

Phase 3: GitHub Integration (Month 2)

• GitHub OAuth flow
• Repository selection/creation
• One-click publish to GitHub
• Generate MakeCode tutorial URLs
• QR code generation endpoint
• Publish status tracking

Phase 4: Polish & Launch (Month 3+)

• Pro tier features (unlimited, priority)
• AI image generation
• Tutorial templates library
• Analytics dashboard
• Localization support
• Cross-linking with MicroChat
• Public launch + marketing

Resources

• MakeCode Tutorials Docs: https://makecode.com/writing-docs/tutorials
• micro:bit MakeCode: https://makecode.microbit.org
• Example Tutorials: (TBD - find popular tutorials, inspect source)

Open Questions

1. MakeCode tutorial schema: What's the exact JSON format? (need examples)
2. Hosting: GitHub Pages sufficient, or need CDN for images?
3. Code blocks: How to specify blocks vs TypeScript? MakeCode supports both.
4. Validation rules: How are step completion checks defined?
5. Existing tools: Does MakeCode have official markdown converters?

---

Status: Project created 2026-04-12. Research phase.