ai6-m2/quiz_game/docs/technical-specs/teacher-project-guide.md

Teacher - Complete Project Manager Guide

YOUR ROLES:

• Team Lead - Guide students through development
• Git Master - Manage repositories and merges
• User Tester - Verify all components work
• Integration Manager - Combine all student work

PROJECT TIMELINE (6 Lessons)

=========================================

LESSON 1-2: SETUP & FOUNDATION

=========================================

STUDENT GOALS:

• Dima: Implement prize money system and game logic in app.py
• Danil: Create first 5 Russian culture questions
• Inna: Make basic question loading and display work
• Artyom: Start Russian color theme in CSS

TEACHER TASKS:

✅ Setup Verification:

1. Ensure main repo is ready: https://gitea.techshare.cc/technolyceum/ai6-m2

2. Verify all students have:

   • Forked the repository
   • Created their role-specific branch
   • Made first commit

3. Quick Progress Check (Terminal):

# Check each student's fork manually in Gitea web interface
# Look for 4 branches: 
# - dima-backend-work
# - inna-frontend-work  
# - danil-database-work
# - artyom-graphics-work

✅ Individual Progress Checks:

# Temporary check for each student:
git clone [STUDENT-FORK-URL] temp-check
cd temp-check
git checkout [THEIR-BRANCH]

# Dima Check:
grep -A 15 "PRIZE_LEVELS" app.py

# Danil Check:
python3 -c "import json; print('Questions:', len(json.load(open('questions.json'))))"

# Inna Check:
grep -c "function" static/script.js

# Artyom Check:
grep -c "background" static/style.css

cd ..
rm -rf temp-check

=========================================

LESSON 3-4: CORE DEVELOPMENT

=========================================

STUDENT GOALS:

• Dima: Complete game session management and answer validation
• Danil: 10+ questions completed
• Inna: Answer handling system and lifelines
• Artyom: Enhanced question/option styling

TEACHER TASKS:

✅ Code Review Workshop: Show examples of DRY (Don't Repeat Yourself) principles:

Before (repetitive code):

document.getElementById('q-number').textContent = data.question_number;
document.getElementById('question-text').textContent = data.question;
document.getElementById('prize').textContent = data.current_prize;

After (DRY code with utility functions):

updateElementText('q-number', data.question_number);
updateElementText('question-text', data.question);
updateElementText('prize', data.current_prize);

✅ Git Workshop:

# Help students resolve merge conflicts:
git fetch origin
git checkout main
git pull origin main
git checkout [THEIR-BRANCH]
git merge main

# If conflicts occur:
# 1. Edit conflicted files
# 2. Remove conflict markers
# 3. git add .
# 4. git commit

=========================================

LESSON 5-6: INTEGRATION & TESTING

=========================================

STUDENT GOALS:

• Dima: Finalize lifelines and error handling
• Danil: Complete 15 questions with difficulty progression
• Inna: Complete game flow and end game screens
• Artyom: Polish all visual elements and animations

FINAL INTEGRATION:

✅ Integration Steps:

1. Merge all branches to main:

# On main branch:
git merge dima-backend-work
git merge danil-database-work
git merge inna-frontend-work
git merge artyom-graphics-work

2. Resolve any conflicts

3. Test complete game flow:

   • Start game from index.html
   • Play through all questions
   • Test lifelines
   • Verify scoring system
   • Check end game states

✅ Final Testing Checklist:

• All 15 questions load correctly
• Answer validation works
• Scoring system functions properly
• Lifelines function correctly
• Game over states work (win/lose)
• Restart functionality works
• Responsive design on different screens
• No console errors in browser

=========================================

PROJECT ARCHITECTURE OVERVIEW

=========================================

File Structure:

/ai6-m2
├── app.py              # Flask backend (Dima)
├── questions.json      # Question database (Danil)
├── static/
│   ├── script.js       # Frontend logic (Inna)
│   └── style.css       # Styling (Artyom)
├── templates/
│   ├── index.html      # Landing page
│   └── game.html       # Game interface
├── docs/
│   ├── roles/          # Role-specific instructions
│   └── technical-specs/ # Technical documentation
└── README.md           # Project overview

Technical Implementation:

Backend (app.py):

• Flask routes for game operations
• Session management for game state
• JSON data handling for questions
• Helper functions for DRY code

Frontend (script.js):

• API communication with backend
• DOM manipulation for game interface
• Utility functions for common operations
• Event handling for user interactions

Database (questions.json):

• JSON format for easy parsing
• Structured question data with options
• Correct answer validation

Styling (style.css):

• Responsive design principles
• Russian-themed color scheme
• Component-based styling approach

=========================================

TROUBLESHOOTING GUIDE

=========================================

Common Issues and Solutions:

1. "TypeError: Cannot read properties of undefined"

   • Usually caused by API returning error instead of data
   • Solution: Check backend implementation and JSON formatting

2. Lifelines not working

   • Check session management for lifeline state
   • Verify frontend-backend communication

3. Scoring issues

   • Verify prize structure in backend
   • Check guaranteed level calculations

4. Git merge conflicts

   • Use systematic approach to resolve conflicts
   • Communicate with team members about changes

Verification Commands:

# Run the application
export FLASK_APP=app.py
python -m flask run

# Check for syntax errors
python -m py_compile app.py
npx eslint static/script.js

# Validate JSON
python -m json.tool questions.json

=========================================

ASSESSMENT CRITERIA

=========================================

Technical Skills:

• Code quality and organization (20%)
• Implementation of requirements (30%)
• Problem-solving and debugging (20%)
• Git usage and collaboration (15%)
• Documentation and comments (15%)

Collaboration:

• Team communication
• Code review participation
• Helpfulness to teammates
• Integration contribution

Final Product:

• Game functions without errors
• All features implemented
• Visually appealing interface
• Good user experience

🎉 Congratulations on completing the Russian Millionaire Quiz Game project!