CodeLah is a browser-first learning product that helps beginners progress from understanding a coding concept to pseudocode, real Python, and a working program. Lessons adapt their context to a learner's chosen interests while keeping the learning objective and correctness criteria fixed.
The first local, anonymous learning slice is implemented. It contains the interest picker, a formative concept check, drag-and-drop or keyboard pseudocode planning, five checked Python modules, an assembled calculator run, and a transfer check. No AWS resources, authentication, or production data exist.
The first vertical slice is a personalised Python calculator lesson:
interest selection -> concept check -> pseudocode blocks
-> code one block at a time -> deterministic tests -> assembled program
Run it locally with bun install followed by bun run dev.
Run the deterministic calculator checks with bun run test:lesson; run the browser regression suite with bun run test:e2e.
- Teach reasoning before syntax.
- Learners build real Python; the product never silently completes their work.
- Pseudocode, code execution, and mastery rules are deterministic.
- AI may personalise explanations and questions; it never determines correctness or supplies a complete solution.
- Interest context is explicit, editable, and optional.
- Start with browser-memory-only lessons. Sign-up, sign-in, remote sessions, tutor, analytics, and authoring surfaces are out of scope for the initial core product.
| Document | Purpose |
|---|---|
| Product requirements | Customer problem, MVP scope, requirements, and measures |
| System architecture | Runtime, AWS topology, data, security, and decisions |
| Software design | Interfaces, state machine, lesson schema, and component contracts |
| Roadmap | Outcome-led milestones and decision gates |
| Runbook | Build, release, incident, rollback, and operational procedures |
| Security and privacy | Threat model, data boundaries, and access controls |
| Quality strategy | Test, accessibility, and AI-evaluation requirements |
| Infrastructure plan | No-apply, cost-first CloudFormation plan and owner review gate |
| ADRs | Durable architectural decisions |
- No account system, social feed, leaderboard, payments, or public sharing.
- No full Scratch clone or visual-programming language.
- No server-side execution of untrusted learner Python.
- No unbounded chatbot or live-web research inside lessons.
- No AWS provisioning before owner review of the no-apply infrastructure plan, cost path, blast radius, and rollback handle.
Use the supplied Scratch/Blockly clone as behaviour inspiration only; its repository page does not display a licence. Build directly on the maintained Apache-2.0 licensed Blockly package. Do not adopt the AGPL-3.0 scratch-gui application.