🐍 Python Academy

An interactive Python learning platform with AST-based code analysis, AI tutoring, and intelligent grading — built as a full-stack SaaS application.

Python Academy is a production-grade e-learning platform designed to teach Python programming through hands-on exercises, real-time code execution, and intelligent feedback. The platform features a modular FastAPI backend with advanced Python services and a modern Vue 3 frontend.

---

✨ Key Features

🎯 Core Learning

• 100 structured lessons across 12 categories (Nhập Môn → LeetCode Hard)
• Interactive code editor with real-time execution and output display
• Quiz system with scoring, history tracking, and chapter-based organization
• Progress tracking — XP system, lesson completion, study streaks

🧠 Intelligent Code Analysis (Python ast module)

• AST-based Code Analyzer — Static analysis engine that parses student code into Abstract Syntax Trees to evaluate complexity, detect patterns (functions, loops, comprehensions, classes), calculate nesting depth, and generate actionable refactoring suggestions
• Smart Hint Engine — Uses difflib.SequenceMatcher + AST node comparison to structurally compare student code against the expected solution, providing targeted hints like "Missing a for loop" or "Try using a function definition"

📊 Code Similarity Checker with Anti-Cheat

A 4-dimensional partial credit scoring system — not just text matching:

Dimension	Weight	Method
Output Correctness	50%	Exact, normalized & line-by-line output comparison
Code Quality	20%	AST structural analysis (independent of answer)
Code Style	20%	Indentation, naming, comments, docstrings
Text Similarity	10%	difflib ratio (reference only)

Scoring Philosophy — Output is King:

• ✅ Output correct → minimum grade B regardless of approach
• 🌟 Different approach (e.g. while vs for) + correct output → creativity bonus +10%
• 🚫 Hardcoded answer detected (e.g. print(15) when logic is required) → capped at grade D
• ⚠️ Syntax errors → capped at grade C

🔄 Real-Time Execution

• WebSocket Live Streaming (asyncio subprocess) — Output streamed line-by-line to frontend
• REST API Fallback — Reliable execution with sandboxed subprocess
• Security Sandbox — Multi-level regex-based blocklist prevents os, subprocess, eval, exec, open, infinite loops

📈 Recommendation Engine

• Weighted scoring algorithm analyzing quiz performance, lesson gaps, and completion patterns
• Personalized "next lesson" suggestions based on student weak areas
• Category-level progress analysis with priority scoring

📄 PDF Export

• Professional PDF reports & certificates via reportlab
• Student progress summary with lesson completion stats

🤖 AI Tutor Integration

• Local Ollama-powered AI assistant for code explanation, hints, and code review
• Streaming chat interface with contextual code understanding

---

🏗️ Architecture

python-academy/
├── 📁 server/                    # FastAPI Backend (3,783 LoC Python)
│   ├── main.py                   # App entry point + lifespan events
│   ├── config.py                 # Centralized configuration
│   ├── 📁 models/
│   │   └── schemas.py            # Pydantic request/response models
│   ├── 📁 routers/
│   │   ├── analysis.py           # /api/analyze, /api/hints, /api/similarity
│   │   ├── execution.py          # /api/run, WebSocket /api/ws/execute
│   │   ├── export.py             # /api/export/pdf
│   │   └── progress.py           # /api/progress, /api/analytics
│   ├── 📁 services/              # Business Logic Layer
│   │   ├── code_analyzer.py      # AST visitor, complexity scoring
│   │   ├── code_similarity.py    # 4-dim scoring + anti-cheat detection
│   │   ├── smart_hints.py        # difflib + AST hint generation
│   │   ├── recommendation.py     # Weighted learning path algorithm
│   │   ├── database.py           # SQLite ORM (6 tables)
│   │   ├── sandbox.py            # Secure code execution
│   │   ├── live_executor.py      # asyncio WebSocket streaming
│   │   └── pdf_generator.py      # reportlab PDF builder
│   ├── 📁 utils/
│   │   ├── security.py           # Code safety checker
│   │   └── storage.py            # File-based storage (legacy)
│   └── 📁 tests/                 # 87 unit tests
│       ├── test_analyzer.py      # 13 tests — AST analysis
│       ├── test_similarity.py    # 30 tests — scoring + anti-cheat
│       ├── test_hints.py         # 12 tests — smart hints
│       ├── test_sandbox.py       # 15 tests — security & execution
│       └── test_database.py      # 17 tests — SQLite operations
│
├── 📁 src/                       # Vue 3 Frontend (4,689 LoC)
│   ├── App.vue                   # Root component + routing
│   ├── 📁 components/
│   │   ├── HomeView.vue          # Dashboard with stats & streaks
│   │   ├── LearnView.vue         # Lesson browser + sidebar
│   │   ├── LessonView.vue        # Code editor + all panels
│   │   ├── QuizView.vue          # Quiz engine
│   │   └── AITutorView.vue       # Chat interface
│   ├── 📁 composables/
│   │   ├── useBackend.js         # FastAPI + WebSocket client
│   │   ├── usePyodide.js         # Browser-side Python (fallback)
│   │   └── useAITutor.js         # Ollama integration
│   ├── 📁 stores/
│   │   └── academy.js            # Pinia state management
│   ├── 📁 data/
│   │   └── index.js              # 100 lessons + quizzes content
│   └── 📁 assets/
│       └── style.css             # Premium dark glassmorphism (1,400+ lines)
│
└── 📁 server/data/
    └── academy.db                # SQLite database (auto-created)

---

💾 Database Schema

-- Normalized SQLite schema with 6 tables
students            -- User profiles (id, name, created_at)
lesson_completions  -- Completed lessons (student_id, lesson_id, xp, timestamp)
quiz_attempts       -- Quiz history (chapter, score, total, percent, timestamp)
code_runs           -- Execution logs (code, output, success, exec_time)
analysis_logs       -- AST analysis history (complexity, features, suggestions)
study_sessions      -- Daily activity tracking (date, lessons, quiz, code_runs)

---

🚀 Quick Start

Prerequisites

• Python 3.11+
• Node.js 18+

1. Backend Setup

cd server
pip install -r requirements.txt
python main.py
# ✅ Server running at http://localhost:8000
# 📖 API docs at http://localhost:8000/docs

2. Frontend Setup

npm install
npm run dev -- --port 5180
# ✅ App running at http://localhost:5180

3. (Optional) AI Tutor

# Install Ollama → https://ollama.ai
ollama pull llama3.2
# AI Tutor auto-connects at localhost:1434

---

🧪 Testing

cd server
python -m pytest tests/ -v

tests/test_analyzer.py    — 13 passed ✅  (AST analysis, complexity scoring)
tests/test_similarity.py  — 30 passed ✅  (scoring, anti-cheat, output-first)
tests/test_hints.py       — 12 passed ✅  (difflib, AST comparison, hints)
tests/test_sandbox.py     — 15 passed ✅  (security blocklist, execution)
tests/test_database.py    — 17 passed ✅  (SQLite CRUD, analytics)
─────────────────────────────────────────
Total                       87 passed ✅  in 1.84s

---

🔑 Python Skills Demonstrated

Skill	Where Used
ast module	Code analyzer, structural quality scoring, anti-cheat detection
difflib	Text similarity, smart hints, code comparison
asyncio	WebSocket live execution streaming, subprocess management
sqlite3	Normalized database with 6 tables, row factory, transactions
FastAPI	REST API, WebSocket endpoints, Pydantic validation, CORS
reportlab	PDF certificate & progress report generation
Data Structures	Weighted scoring algorithms, frequency maps, AST trees
Design Patterns	Service layer, router pattern, dependency injection
Security	Regex-based code blocklist, sandboxed execution, env isolation
Testing	87 unit tests with pytest, edge cases, anti-cheat validation

---

📊 Project Stats

Metric	Value
Total Python LoC	3,783
Total Frontend LoC	4,689
Python Files	29
Unit Tests	87 (all passing)
API Endpoints	12 REST + 1 WebSocket
Lessons	100 across 12 categories
Database Tables	6 (normalized schema)
Services	8 modular business logic modules

---

📡 API Endpoints

Method	Endpoint	Description
POST	/api/run	Execute Python code in sandbox
WS	/api/ws/execute	WebSocket live output streaming
POST	/api/analyze	AST code analysis
POST	/api/hints	Smart hint generation
POST	/api/similarity	Code similarity + anti-cheat scoring
GET	/api/recommendations	Personalized learning path
GET/POST	/api/progress	Load/save student progress
GET	/api/analytics	Study stats & activity heatmap
POST	/api/export/pdf	Generate PDF report
GET	/api/health	Backend health check
POST	/api/quiz	Submit quiz attempt
GET	/api/quiz/:chapter	Quiz history by chapter

---

🛠️ Tech Stack

Layer	Technology
Frontend	Vue 3 (Composition API), Vite 8, Pinia, Chart.js
Backend	FastAPI, Uvicorn, Pydantic v2
Database	SQLite 3 (persistent, auto-initialized)
Analysis	Python ast, difflib, custom AST visitors
PDF	ReportLab 4.0
AI	Ollama (local LLM, optional)
Testing	pytest, pytest-asyncio
Styling	Custom CSS — dark glassmorphism, 1,400+ lines

---

📜 License

This project was built as a demonstration of Python engineering skills for the Vingroup AI Talent program application.

---

Built with 🐍 Python + ⚡ FastAPI + 💚 Vue 3