mypepoes/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):
```bash
# 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:
```bash
# 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):**
```javascript
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):**
```javascript
updateElementText('q-number', data.question_number);
updateElementText('question-text', data.question);
updateElementText('prize', data.current_prize);
```

✅ Git Workshop:
```bash
# 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:
```bash
# 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:

```bash
# 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!