knowfoolery/docs/1_requirements/functional-requirements.md

# Know Foolery - Functional requirements

## Core Game Flow

### 1. Game Session Initialization
```
Player Input: Name → Session Creation → Question Selection → Game Start
```

**Process:**
1. Player enters their name (required)
2. System creates new game session
3. System randomly selects first question
4. 30-minute timer starts
5. Game begins with question display

**Validation:**
- Player name: 2-50 characters, alphanumeric + spaces
- Session uniqueness: One active session per player
- Timer initialization: Server-side timestamp

### 2. Question Presentation

**Question Structure:**
- theme: e.g. "Geography", "History", "Science"
- text: The actual question
- answer: Correct answer (case-insensitive)
- hint: Optional hint text
- difficulty: Future enhancement

**Display Format:**
```
┌─────────────────────────────────────┐
│ Theme: Geography            ⏱️ 28:45 │
├─────────────────────────────────────┤
│                                     │
│ What is the capital of France?      │
│                                     │
│ [Your answer here...        ] 💡    │
│                                     │
│ Attempts remaining: 3/3             │
│ Current score: 4 points             │
└─────────────────────────────────────┘
```

### 3. Answer Submission Process

**Player Actions:**
1. **Direct Answer**: Submit answer without hint
2. **Request Hint**: View hint before answering
3. **Skip Question**: Move to next question (future enhancement)

**Answer Validation:**
1. Normalize both answers
2. Check for exact match of fuzzy matching with similarity above 85%

## Scoring System

### Point Values
- **Correct without hint**: 2 points
- **Correct with hint**: 1 point
- **Incorrect answer**: 0 points
- **Session timeout**: 0 points for remaining questions

## Attempt System

### Attempt Rules
- **Maximum Attempts**: 3 per question
- **Attempt Tracking**: Server-side validation
- **Attempt Consequences**: 
  - Attempt 1-3: Normal scoring if correct
  - After 3 failed attempts: Move to next question automatically

### Attempt Flow
1. Validate session is active
2. Check attempts remaining
3. Validate answer
4. Update score if correct
5. Move to next question if needed

## Hint System

### Hint Mechanics
- **Availability**: One hint per question
- **Timing**: Can be requested before any attempt
- **Impact**: Reduces maximum score from 2 to 1 points
- **Content**: Provides helpful clue without giving away answer


### Hint Examples
- Hint 1
  - question: "What is the capital of France?",
  - hint: "This city is famous for the Eiffel Tower and is located on the Seine River.",
  
- Hint 2
  - question: "Who painted the Mona Lisa?",
  - hint: "This Italian Renaissance artist was also an inventor and scientist.",
  
- Hint 3
  - question: "What is the largest planet in our solar system?",
  - hint: "This gas giant is named after the king of the Roman gods."

## Time Management

### Session Timer
- **Duration**: 30 minutes maximum per session
- **Display**: Real-time countdown timer
- **Warnings**: Visual alerts at 5 minutes and 1 minute remaining
- **Timeout**: Automatic session termination when time expires

### Timer Events
- **warning**: 
  - at: 300 seconds, message: "5 minutes remaining!"
  - at: 60 seconds, message: "1 minutes remaining!"
  - at: 10 seconds, message: "10 seconds left!"
- **timeout**: 

## Question Selection

### Random Selection Algorithm
1. Exclude questions already answered in this session
2. Pick a random question in the database

### Question Difficulty (Future Enhancement)
- 3 levels of difficulty: Easy, Medium, Hard
- Adaptive difficulty based on player performance (consider player's success rate, current score, etc.)

## Leaderboard System

### Leaderboard Display
```
🏆 LEADERBOARD

Rank | Player    | Score | Questions | Success Rate | Duration
-----|-----------|-------|-----------|--------------|----------
  1  | Alice     |   24  |    14     |     86%      |   28m
  2  | Bob       |   22  |    13     |     85%      |   25m  
  3  | Charlie   |   20  |    12     |     83%      |   30m
  4  | Diana     |   18  |    11     |     82%      |   22m
  5  | Eve       |   16  |    10     |     80%      |   27m
```

### Leaderboard Calculation
- Sort by score (descending), then by completion time (ascending)
- Only the top 10
- Success Rate: Percentage of correct answers

## Game State Management

### Session States Transitions
```
Created → Active → {Completed, TimedOut, Abandoned}
                ↓
              Paused → Active (future enhancement)
```

## Anti-Cheating Measures

### Server-Side Validation
1. Check minimum time between question show and answer submit
2. Validate session state
3. Check if question belongs to session

### Client-Side Integrity
- Disable browser dev tools (basic deterrent)
- Prevent copy-paste in answer input
- Include timing in submission for server validation

This game mechanics documentation ensures consistent implementation across all platforms and provides clear guidelines for future enhancements.