Skip to content

python-app.md

Latest commit

 

History

History
175 lines (139 loc) · 14.4 KB

python-app.md

File metadata and controls

175 lines (139 loc) · 14.4 KB
Raw

Master Build Prompt: "Python 💻" — Full Python Learning App for Android

Use this entire prompt as the instruction set for an AI code generator (Claude Code, Cursor, etc.) to build the app end-to-end.

1. App Identity

  • App Name (display): Python 💻
  • Package Name: com.python.learn
  • Platform: Android (APK), built to also run smoothly as a PWA/web build for testing in-browser before packaging
  • Recommended stack: React + Vite + Capacitor (wraps as native Android APK) with Pyodide (WebAssembly Python runtime) embedded so real Python code executes on-device, no server required, fully offline after first load. This fits a Termux/mobile dev workflow better than Buildozer/Kivy, which is heavy to compile on-device.
  • State/progress persistence: local SQLite (via Capacitor SQLite plugin) or IndexedDB, so all progress survives app restarts without internet.
  • No ads, no account requirement — everything works offline once installed.

2. Visual Identity — "Dark Hacker Glassmorphism"

  • Theme: Pure dark background (#0a0e14 / near-black), neon-green and cyan accent (#00ff9c, #39d6ff), monospace font (JetBrains Mono / Fira Code) for all code blocks.
  • Glassmorphism: frosted-glass cards (backdrop-filter: blur(16px), semi-transparent panels rgba(255,255,255,0.05), thin 1px glowing borders) on every screen — chapter cards, modals, buttons, progress panels.
  • Animations/transitions:
    • Smooth page transitions (slide + fade) between menu → chapter → lesson → quiz.
    • Typing/terminal-style animated text reveal for lesson intros (like a hacker terminal typing effect).
    • Glowing pulse animation on "Continue" and "Run Code" buttons.
    • Progress bars that fill with an animated gradient glow.
    • Confetti/particle burst animation on level/chapter completion.
    • Subtle animated matrix-style falling code in background of the home menu (low opacity, non-distracting).
    • Micro-interactions: button press ripple, card hover/tap scale, haptic feedback on key actions (Capacitor Haptics plugin).
  • Navigation: persistent bottom nav bar (glass style) with: Home, Chapters, Practice Arena, Boss Level, Profile/Progress.
  • Home menu: grid/list of chapter cards showing lock/unlock state, completion %, XP earned, and a streak counter.

3. Core App Architecture / Screens

  1. Splash Screen — animated terminal boot-up sequence showing "Python 💻" logo.
  2. Home Dashboard — XP total, level, streak, daily goal, "Continue where you left off" card, quick-access to Practice Arena and Boss Level.
  3. Chapters Menu — scrollable list/grid of all chapters (see Section 4), each showing progress ring, lock status (sequential unlock or free-roam toggle in settings).
  4. Chapter Detail Screen — sub-levels within the chapter: Theory → Guided Example → Mini Challenge → Quiz → Fun Task → Boss Checkpoint (every 5th chapter).
  5. Code Editor Screen — syntax-highlighted editor (CodeMirror or Monaco-lite), Run button executing via Pyodide, live console output panel, error highlighting, hint button, "Show Solution" (locked until 2 failed attempts), reset button.
  6. Quiz Engine — MCQ, fill-in-the-blank, code-output-prediction, drag-and-reorder-code-blocks, and "spot the bug" question types.
  7. Practice Arena — free-play space with random challenge generator pulling from all unlocked chapters, timed challenge mode, daily challenge.
  8. Boss Level (Section 6 below)
  9. Profile / Progress — XP graph over time, badges/achievements earned, chapters mastered, total lines of code run, streak calendar.
  10. Settings — theme intensity toggle, font size, sound/haptics on-off, reset progress, free-roam vs sequential unlock.

4. Chapters — Full Curriculum (create ALL of these, fully functional, not stubs)

Each chapter below must include: Theory page(s) with hacker-terminal-style explanations, at least 3 worked examples, 3–5 interactive coding challenges with auto-grading via Pyodide output comparison, a quiz (8–10 questions), and one "Fun Task" (a small game, riddle, or creative micro-project reinforcing the concept — e.g., a Mad-Libs generator for string chapter, a number-guessing AI for conditionals, a Caesar-cipher decoder for loops/strings).

  1. Chapter 0 – Welcome to the Terminal (what is Python, installing mindset, running your first print(), comments)
  2. Chapter 1 – Variables & Data Types (int, float, str, bool, None, type casting, dynamic typing)
  3. Chapter 2 – All Operators (must cover every category explicitly):
    • Arithmetic: + - * / // % **
    • Assignment: = += -= *= /= //= %= **= &= |= ^= >>= <<=
    • Comparison: == != > < >= <=
    • Logical: and or not
    • Identity: is is not
    • Membership: in not in
    • Bitwise: & | ^ ~ << >>
    • Operator precedence & chaining challenges
  4. Chapter 3 – Strings & Text Manipulation (slicing, f-strings, methods, formatting) — Fun Task: Mad-Libs generator
  5. Chapter 4 – Conditionals (if/elif/else, ternary, nested conditions, match-case) — Fun Task: number-guessing riddle bot
  6. Chapter 5 – Loops (for, while, range, break/continue/else, nested loops) — Fun Task: pattern-printing art generator + Caesar cipher — Boss Checkpoint #1
  7. Chapter 6 – Lists (indexing, slicing, methods, list comprehensions)
  8. Chapter 7 – Tuples & Sets
  9. Chapter 8 – Dictionaries (CRUD, nested dicts, comprehension) — Fun Task: build a mini contact book
  10. Chapter 9 – Functions (def, args, kwargs, default/positional/keyword args, return, scope, lambda) — Fun Task: build a calculator engine — Boss Checkpoint #2
  11. Chapter 10 – Recursion
  12. Chapter 11 – Error Handling (try/except/else/finally, raise, custom exceptions)
  13. Chapter 12 – File Handling (read/write/append, with-statement, JSON I/O)
  14. Chapter 13 – Modules & Packages (import, standard library tour: math, random, datetime, os)
  15. Chapter 14 – Object-Oriented Programming I (classes, objects, __init__, attributes, methods) — Fun Task: build a virtual pet class — Boss Checkpoint #3
  16. Chapter 15 – OOP II (inheritance, polymorphism, encapsulation, dunder methods, super())
  17. Chapter 16 – Iterators & Generators (yield, generator expressions)
  18. Chapter 17 – Decorators & Closures
  19. Chapter 18 – Comprehensions Deep Dive (list/dict/set/generator comprehensions, nested)
  20. Chapter 19 – Regular Expressions
  21. Chapter 20 – Working with APIs & JSON (simulated offline JSON datasets since no network in-app)
  22. Chapter 21 – Algorithmic Thinking (sorting, searching, complexity intuition, puzzles) — Fun Task: build a maze solver
  23. Chapter 22 – Data Structures Mini-Series (stacks, queues, linked lists using classes) — Boss Checkpoint #4
  24. Chapter 23 – Mini Projects Capstone (guided build: text adventure engine, contributing directly toward Boss Level skills)

Chapters should be sequentially numbered in-app and expandable — the architecture (JSON/DB-driven chapter schema) must allow adding more chapters later without code changes, so "create as many chapters as you want" is satisfied by design, not just content volume.

Each chapter's data should be structured as a JSON schema, e.g.:

{
  "id": "ch05_loops",
  "title": "Loops",
  "theory": [...],
  "examples": [...],
  "challenges": [{"prompt": "", "starterCode": "", "expectedOutput": "", "hints": []}],
  "quiz": [...],
  "funTask": {...},
  "xpReward": 150
}

5. Fun Tasks / Language Practice Layer (cross-cutting, not just per-chapter)

  • "Code Riddles" — daily bite-size logic riddles solved with one line of Python.
  • "Debug the Hacker" — a broken code snippet themed as "someone's exploit script has a bug," user fixes it.
  • "Predict the Output" — timed rapid-fire mode showing code, user predicts console output before running it.
  • "Vocabulary Terminal" — flashcard-style drills on Python keywords/terminology (e.g., "What does is check vs ==?") to build language fluency, not just syntax.
  • "Speed Type" — hacker-typing-simulator mode where users retype correct Python syntax fast and accurately for muscle memory.

6. Boss Level — User-Built Game (the capstone feature)

After Chapter 23 (or once core chapters are complete), unlock the Boss Level Arena:

  • A 10-level guided game-building journey where the user constructs their own simple game in Python using only concepts they've already unlocked (variables, conditionals, loops, functions, lists, OOP).
  • Structure:
    1. Level 1–2: Choose a game template direction (Number Guesser, Text Adventure, Rock-Paper-Scissors, Quiz Game, or Tic-Tac-Toe) — scaffolded starter code provided in the in-app editor.
    2. Level 3–4: Add game state (variables, score tracking) — guided prompts, not fully solved.
    3. Level 5–6: Add core game loop logic (while/for loop driving gameplay) — user writes it, auto-graded against required behaviors, not exact output.
    4. Level 7–8: Add decision logic / win-lose conditions (conditionals + functions).
    5. Level 9: Add replay/restart logic and input validation with error handling.
    6. Level 10 (Boss Fight): Full integration test — the user's assembled game runs live in the in-app console; a "Boss Judge" checklist (rubric-based auto-check via test harness comparing behavior, not exact text) confirms all 10 requirements are met; success triggers a big animated "BOSS DEFEATED" sequence with a shareable certificate/badge.
  • The Boss Level code editor should let the user freely edit their accumulating game file across all 10 levels (it's one continuous project, not disconnected snippets).
  • Store the finished user-built game permanently in their Profile as a trophy project they can reopen, edit, and re-run anytime.

7. Gamification System

  • XP per challenge/quiz/fun-task, level-up thresholds, streak tracking (daily use), badges (e.g., "Loop Master," "Bug Slayer," "Boss Conqueror").
  • Optional sound effects (typing clicks, success chime, error buzz) — togglable.

7.5 Enhancements — Signature Features That Make This App Stand Out

Build these in as first-class features, not afterthoughts:

  • Skill Tree Map — replace/augment the flat chapter list with a glowing "network graph" view (hacking-map style): chapters as nodes, animated connector lines that light up as paths unlock. Use this as the primary Chapters screen; keep the list view as an alternate toggle.
  • "The Oracle" — offline rubber-duck mentor — a small animated terminal avatar the user "explains their code to" (types a short explanation) before the Hint button unlocks. Reinforces articulating logic, not just answer-seeking. Fully offline, no AI backend needed — canned prompts/responses keyed to chapter/challenge id.
  • White-Hat Practice Track — a dedicated cybersecurity-flavored challenge set threaded through relevant chapters: password-strength checker, Caesar/XOR encode-decode, simple log-file parser. Teaches real syntax through an ethical "white-hat" narrative; stays clearly educational/defensive, no actual exploit content.
  • Code Golf Mode — on challenge completion, show the user's solution length vs. the shortest known valid solution, purely local scoring (no server/leaderboard). Optional toggle per challenge.
  • Unlockable Terminal Skins — alternate color themes (blood-red, cyberpunk-purple, matrix-green, amber-crt) earned via XP milestones, on top of the default neon-green/cyan theme. Makes the visual identity itself part of progression.
  • Hidden Easter-Egg Chapter — a Konami-code-style tap/swipe sequence on the Home screen unlocks a bonus secret chapter (Python history, obscure one-liners, fun trivia). Low-cost to build, high memorability.
  • Exportable Boss Level Game — let the user export their finished 10-level Boss project as a real standalone .py file (share sheet / save to device), so the capstone project is usable outside the app, not locked in.
  • Adaptive Difficulty — lightweight local heuristic: 3 correct in a row bumps the next challenge up a difficulty tier; 2 wrong in a row scaffolds the next one down (more starter code / more hints pre-shown). Applies within Practice Arena and chapter challenge sets.
  • Free Completion Certificate — on finishing all core chapters (and separately, on defeating the Boss Level), generate a free downloadable "Certificate of Completion — Python 💻" entirely on-device (no server, no payment, no login):
    • Auto-fills the user's chosen display name, completion date, total XP, and a unique local certificate ID (e.g., hash of user id + timestamp) for a personal sense of authenticity.
    • Rendered in the same dark-hacker-glassmorphism style as the app (terminal-green border glow, monospace typography, subtle circuit/matrix background), generated as an image/PDF via an on-device canvas/HTML-to-image or PDF library.
    • Exportable via the Android share sheet (save to gallery, share to socials/chat apps, or save as PDF).
    • Two tiers: a Core Curriculum Certificate (all chapters complete) and a Boss Conqueror Certificate (Boss Level's user-built game finished) — both stored in Profile for re-download anytime.
    • Clearly labeled as a personal-learning-achievement certificate (not an accredited/institutional credential) to keep expectations honest.

8. Technical Requirements Checklist

  • Capacitor Android project configured with applicationId: com.python.learn and app label Python 💻
  • Pyodide loaded and cached on first launch for fully offline code execution afterward
  • All chapter/quiz/challenge content stored as local JSON, loaded into SQLite/IndexedDB on first run
  • Progress, XP, badges, and Boss Level project persisted locally, survives app kill/reopen
  • Smooth 60fps animations (use Framer Motion or CSS transitions, avoid jank)
  • Responsive layout for various Android screen sizes
  • App icon and splash screen matching the dark-hacker glassmorphism theme
  • Build instructions included: npm run build → npx cap sync android → open in Android Studio (or cap run android) → generate signed APK

9. Deliverable Expectation

Build this as a complete, runnable project — not placeholders. Every chapter listed must have real theory content, real working challenges validated through actual Pyodide execution, a real quiz, and a real fun task. The Boss Level must be a fully working 10-level guided project builder, not a mockup