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.