This Software Architecture Document (SAD) outlines the technical foundation of the "Gamified-Programming" project. It defines the architecture, key components, design principles, technology stack, and database integration strategy.

The project is a gamified learning platform designed to teach fundamental Python programming concepts using interactive quizzes and coding challenges. It supports real-time feedback, user tracking, and modular lesson content delivered from JSON files.

• MVC: Model-View-Controller
• SRS: Software Requirements Specification
• TSX/JSX: TypeScript/JavaScript XML
• RPC: Remote Procedure Call

• n/a

This document outlines architectural design, logical layers, component interactions, database use, performance, constraints, and quality standards. It also complements the Software Requirements Specification (SRS) hosted on the project's wiki.

• Model: Supabase PostgreSQL for user data, quiz results, and progress.
• View: React (JSX/TSX) + TailwindCSS UI components.
• Controller: Flask APIs that coordinate between Python quiz logic and Supabase.

• Modular code using MVC.
• Real-time user feedback and progress tracking.
• Simple, maintainable design that scales with content and users.

• Multi-language stack: Python, TypeScript, Node.js.
• Frontend uses htmx and HTML5 for partial reloads.
• Backend must coordinate Flask, Express.js, and Supabase RPCs.

See Use Case Diagram in the SRS

• User registers/logs in via Supabase.
• User loads lessons, submits answers, and receives feedback.
• Admin uploads JSON quiz content.

• Frontend: React, htmx, and TailwindCSS
• Backend: Flask API for Python logic, Express.js endpoints
• Database: Supabase for user data, progress, quiz results

• game_logic/ – Python modules (`loader.py`, `quiz_logic.py`, etc.)
• users – Supabase table (firebase_uid, email, username)
• quiz_progress – Stores score, task_id, user_id, and timestamps

React or htmx triggers API call → Flask handles validation → Python evaluates input → Supabase stores result → frontend shows feedback.

• Frontend: currently local or in-progress
• Backend: currently local or in-progress
• Database: Supabase PostgreSQL

Modular file structure: `/src` for React, `/backend` for Python + Supabase code, `/game_logic` for core logic, `/tests` for unit testing.

• Presentation: React (TSX), htmx, HTML5
• Logic: Flask APIs and Python quiz validator
• Data: Supabase tables (users, quiz_progress), JSON content files

• Tables: `users`, `quiz_progress`
• Upserts: Quiz data saved via `upsert_quiz_progress` RPC
• Data Backup: Supabase manages backups; data is saved in real-time

• Lightweight styling using TailwindCSS
• Fast, indexed Supabase queries

• Clean Code Standards (PEP8, ESLint)
• Version Control: Git + GitHub branching, and code reviews
• Cross-browser compatible and mobile-friendly

• Wiki: Version-controlled documentation and SRS updates

• Quiz Interface: Input field, submit button, feedback area
• Dashboard: Tracks user progress across lessons

• Python: PEP8
• JavaScript/TypeScript: ESLint + Prettier

• Follow clean code
• Isolated Python logic for easy testing and maintenance