Day 6: Core Quiz Service - Business Logic

The Brain Behind Your Quiz Platform

Think of your quiz platform like a restaurant. Yesterday, we built the kitchen storage (data layer) - organized fridges, pantries, and inventory systems. Today, we're creating the head chef who knows the recipes, understands dietary restrictions, and ensures every dish meets quality standards before leaving the kitchen.

This head chef is your business logic layer - the intelligent decision-maker that sits between raw data and user interactions.

Why Business Logic Matters in Real Systems

Netflix doesn't just store movies; it applies complex business rules about licensing, regional availability, and recommendation algorithms. Similarly, your quiz service needs intelligence beyond basic CRUD operations.

Real-world example: Khan Academy's quiz system validates question difficulty progression, prevents cheating through answer timing analysis, and adapts quiz length based on student performance - all business logic decisions.

The Service Layer Pattern: Your System's Intelligence Hub

The service layer pattern creates a dedicated space for business rules, keeping them separate from database operations and API endpoints. This separation is crucial for several reasons:

Maintainability: When business rules change (and they always do), you modify one place, not scattered code across controllers and repositories.

Testability: Business logic becomes isolated and unit-testable without database dependencies.

Reusability: The same business logic can serve web APIs, mobile apps, or batch processes.

Architecture Deep Dive

In our quiz platform, the service layer orchestrates three key responsibilities:

1. Validation Logic: Ensuring quiz data integrity before persistence

2. Business Rules: Implementing domain-specific requirements

3. Coordination: Managing interactions between different system components

# Service layer coordinates multiple concerns
class QuizService:
    def create_quiz(self, quiz_data):
        # Validation logic
        self._validate_quiz_structure(quiz_data)
        
        # Business rules
        if not self._user_can_create_quiz(quiz_data.creator_id):
            raise PermissionError("User quota exceeded")
        
        # Coordination
        quiz = self.quiz_repository.create(quiz_data)
        self.notification_service.notify_creation(quiz)
        return quiz

Component Architecture & Data Flow

Your business logic layer sits strategically between the presentation layer (controllers) and data access layer (repositories):

Request Flow:

1. Controller receives HTTP request

2. Controller calls service method with validated input

3. Service applies business rules and validation

4. Service coordinates with repositories and external services

5. Service returns structured response to controller

State Management: Services are typically stateless, receiving all necessary context through method parameters. This design enables horizontal scaling and simplifies testing.

Implementation Strategy

Our quiz service implements four core operations with embedded business intelligence:

Quiz Creation: Validates question types, enforces creation quotas, and applies content filtering rules.

Quiz Retrieval: Implements access control, applies user-specific filtering, and handles draft vs. published states.

Quiz Validation: Ensures structural integrity, validates question-answer relationships, and enforces platform constraints.

Error Handling: Provides meaningful error messages while abstracting internal implementation details.

Key Design Decisions

Dependency Injection: Services receive repository instances through constructors, enabling easy testing and loose coupling.

Exception Hierarchy: Custom exceptions provide clear error semantics while maintaining abstraction boundaries.

Response Formatting: Services return domain objects, leaving serialization concerns to the presentation layer.

Production Considerations

Performance: Business logic often becomes a bottleneck. Design for caching where possible and minimize database round trips.

Monitoring: Log business rule violations and validation failures - they often indicate user behavior patterns or system abuse.

Scalability: Stateless design enables horizontal scaling, but watch for shared resource contention (database connections, external API limits).

Integration Context

This business logic layer prepares your system for tomorrow's session management lesson. Clean separation of concerns enables complex features like quiz attempt tracking, progress persistence, and adaptive questioning without architectural changes.

Success Criteria: After implementation, your quiz service should handle validation errors gracefully, enforce business rules consistently, and provide clear, actionable error messages to API consumers.

Project Implementation Guide

Source code repository —> https://github.com/sysdr/aie/tree/main/day6

Core Quiz Service - Business Logic Implementation

Learning Objectives

By the end of this hands-on session, you will:

• Understand and implement the service layer pattern for business logic separation

• Create robust validation mechanisms with custom exception handling

• Build a scalable architecture that separates concerns effectively

• Implement dependency injection for testable, maintainable code

• Apply business rules consistently across your application

Prerequisites

• Completed Day 5 (Data Layer/Repository Pattern)

• Basic understanding of Python classes and async/await

• Familiarity with FastAPI basics

• Understanding of HTTP status codes and REST principles

Project Structure Overview

quiz-platform-day6/
├── src/
│   ├── services/           # Business logic layer
│   │   └── quiz_service.py
│   ├── models/            # Domain models and DTOs
│   │   └── quiz.py
│   ├── repositories/      # Data access layer
│   │   └── quiz_repository.py
│   ├── controllers/       # API endpoints
│   │   └── quiz_controller.py
│   ├── exceptions/        # Custom exceptions
│   │   └── quiz_exceptions.py
│   ├── tests/            # Test suite
│   │   ├── test_quiz_service.py
│   │   ├── test_integration.py
│   │   └── test_data_generator.py
│   └── main.py           # FastAPI application
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── scripts/
    ├── run_tests.sh
    └── start_server.sh

Component-by-Component Implementation

1. Custom Exception Hierarchy

File: src/exceptions/quiz_exceptions.py

Purpose: Provide clear, specific error handling that maps to appropriate HTTP status codes.

Key Concepts:

• Exception inheritance for categorized error handling

• Error codes for client-side error identification

• Meaningful error messages for debugging

Implementation Notes:

class QuizServiceError(Exception):
    """Base exception with error code support"""
    def __init__(self, message: str, error_code: str = None):
        super().__init__(message)
        self.message = message
        self.error_code = error_code

Why This Matters: In production systems, clear error boundaries help with monitoring, debugging, and user experience. Each exception type corresponds to a specific business rule violation.

2. Domain Models and DTOs

File: src/models/quiz.py

Purpose: Define data structures that represent business concepts clearly and provide validation.

Key Concepts:

• Pydantic models for automatic validation

• Enum types for constrained values

• Custom validators for business rule enforcement

• Separation between request/response DTOs and domain models

Critical Implementation Details:

@validator('questions')
def validate_questions(cls, v):
    if len(v) < 1:
        raise ValueError('Quiz must have at least one question')
    return v

Why This Matters: Strong typing and validation at the model level prevent invalid data from entering your system, reducing bugs and improving data integrity.

3. Business Logic Service

File: src/services/quiz_service.py

Purpose: Implement core business logic, validation rules, and coordinate between layers.

Architecture Pattern: Service Layer Pattern

• Single Responsibility: Each method handles one business operation

• Dependency Injection: Repository injected via constructor

• Stateless Design: No instance variables that change between calls

Key Business Rules Implemented:

A. User Quota Validation

async def _validate_user_quota(self, creator_id: str):
    quiz_count = await self.quiz_repository.get_creator_quiz_count(creator_id)
    if quiz_count >= self.max_quizzes_per_user:
        raise QuizCreationLimitError(...)

B. Difficulty Progression (Assignment Challenge)

def _validate_difficulty_progression(self, questions):
    # Rule 1: Must have all difficulty levels
    difficulties = [q.difficulty for q in questions]
    required_difficulties = {DifficultyLevel.EASY, DifficultyLevel.MEDIUM, DifficultyLevel.HARD}
    missing_difficulties = required_difficulties - set(difficulties)
    
    if missing_difficulties:
        raise ValidationError(...)

C. Question Type Distribution

Prevents quizzes from being dominated by a single question type (max 80% rule).

Why These Rules Matter:

• User Quota: Prevents system abuse and ensures fair resource usage

• Difficulty Progression: Ensures educational value and proper learning curve

• Type Distribution: Maintains quiz variety and engagement

4. API Controllers

File: src/controllers/quiz_controller.py

Purpose: Handle HTTP concerns, delegate to services, and map exceptions to HTTP responses.

Key Patterns:

• Dependency Injection: Service injected via FastAPI's dependency system

• Exception Mapping: Business exceptions mapped to appropriate HTTP status codes

• Clear Separation: Controllers only handle HTTP concerns, not business logic

Exception to HTTP Status Mapping:

ValidationError → 400 Bad Request
QuizCreationLimitError → 429 Too Many Requests
UnauthorizedError → 403 Forbidden
QuizNotFoundError → 404 Not Found

5. Testing Strategy

Unit Tests (test_quiz_service.py):

• Test business logic in isolation

• Mock repository dependencies

• Verify exception handling

• Test edge cases and boundary conditions

Integration Tests (test_integration.py):

• Test full HTTP request/response cycle

• Verify exception mapping works correctly

• Test actual API endpoints

Test Data Generation (test_data_generator.py):

• Generate realistic test data

• Ensure tests cover various scenarios

• Support for both valid and invalid data generation

Step-by-Step Implementation Process

Phase 1: Foundation (30 minutes)

1. Set up project structure and virtual environment

2. Install dependencies from requirements.txt

3. Create base exception classes with inheritance hierarchy

4. Define domain models with Pydantic validation

Phase 2: Core Business Logic (45 minutes)

1. Implement QuizService class with constructor dependency injection

2. Add user quota validation with repository interaction

3. Implement quiz structure validation with business rules

4. Create difficulty progression validation (assignment challenge)

5. Add access control logic for draft vs. published quizzes

Phase 3: API Integration (30 minutes)

1. Create FastAPI controllers with proper dependency injection

2. Implement exception handling with HTTP status code mapping

3. Add request/response models for API documentation

4. Test endpoints using FastAPI's automatic docs

Phase 4: Testing & Verification (30 minutes)

1. Write unit tests for each business rule

2. Create integration tests for API endpoints

3. Run test suite and verify coverage

4. Test error scenarios manually

Key Learning Points

1. Service Layer Benefits

• Centralized Business Logic: All rules in one place

• Testability: Easy to unit test without HTTP concerns

• Reusability: Same logic can serve multiple interfaces

• Maintainability: Changes to business rules are isolated

2. Dependency Injection Advantages

• Loose Coupling: Service doesn't know about specific repository implementation

• Testability: Easy to inject mock repositories for testing

• Flexibility: Can swap implementations without changing service code

3. Exception Design Principles

• Specific Exception Types: Each business rule violation has its own exception

• Error Codes: Programmatic error identification for clients

• Meaningful Messages: Help developers understand what went wrong

4. Validation Strategy

• Multi-Layer Validation: Model validation + business rule validation

• Early Validation: Fail fast with clear error messages

• Contextual Validation: Different rules for different operations (create vs. publish)

Common Pitfalls and Solutions

Pitfall 1: Putting Business Logic in Controllers

Problem: Controllers become bloated and hard to test Solution: Keep controllers thin, delegate all business logic to services

Pitfall 2: Tight Coupling to Database

Problem: Hard to test, difficult to change data storage Solution: Use repository pattern with dependency injection

Pitfall 3: Generic Error Handling

Problem: Unclear errors, poor user experience Solution: Specific exception types with clear messages and error codes

Pitfall 4: Inconsistent Validation

Problem: Same rules implemented differently in different places Solution: Centralize validation in service layer

Success Criteria

After completing this implementation, you should be able to:

✅ Create quizzes with proper validation and business rule enforcement ✅ Handle errors gracefully with specific exception types and HTTP status codes ✅ Test business logic independently of HTTP and database concerns ✅ Explain the benefits of service layer pattern and dependency injection ✅ Extend the system by adding new business rules without breaking existing code

Build, Test, Verify Guide

Complete Step-by-Step Commands with Expected Output

Method 1: Manual Setup and Testing

Step 1: Project Setup

# Create project directory
mkdir quiz-platform-day6
cd quiz-platform-day6

# Create project structure
mkdir -p src/{services,models,repositories,controllers,exceptions,tests}
mkdir -p docs scripts

Step 2: Dependencies Installation

# Create requirements.txt
cat > requirements.txt << 'EOF'
fastapi==0.104.1
uvicorn==0.24.0
pydantic==2.5.0
pytest==7.4.3
pytest-asyncio==0.21.1
httpx==0.25.2
python-multipart==0.0.6
faker==20.1.0
EOF

# Install dependencies
pip install -r requirements.txt

Step 3: Core Implementation Files

Create Exception Classes:

# Create the exception hierarchy
 src/exceptions/quiz_exceptions.py 

Create Domain Models:

# Create comprehensive domain models (abbreviated for brevity)
cat > src/models/quiz.py 

Step 4: Build and Test Service Layer

Create Repository Interface:

src/repositories/quiz_repository.py 

Create Service Layer:

# Create the core business logic service (abbreviated)
src/services/quiz_service.py 

Step 5: Unit Testing

Create Test Suite:

src/tests/test_quiz_service.py 

# Run unit tests
python -m pytest src/tests/test_quiz_service.py -v

Expected Output:

src/tests/test_quiz_service.py::test_create_quiz_success PASSED      [33%]
src/tests/test_quiz_service.py::test_quota_exceeded PASSED           [66%]
src/tests/test_quiz_service.py::test_missing_difficulty_validation PASSED [100%]

Step 6: API Integration Testing

Create FastAPI Application:

 src/main.py 

Create Integration Tests:

src/tests/test_integration.py 

# Run integration tests
python -m pytest src/tests/test_integration.py -v

Expected Output:

src/tests/test_integration.py::test_health_check PASSED          [33%]
src/tests/test_integration.py::test_create_quiz_success PASSED   [66%]
src/tests/test_integration.py::test_validation_error PASSED     [100%]Step 7: Live Server Testing

Start the server:

# Terminal 1: Start the server
export PYTHONPATH="${PWD}"
python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

Expected Output:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using StatReload
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Test the running server (Terminal 2):

# Test health endpoint
curl http://localhost:8000/health
# Expected: {"status":"healthy","service":"quiz-service-day6"}

Step 8: Complete Test Suite

Run all tests:

# Run complete test suite
python -m pytest src/tests/ -v --tb=short

# Run with coverage (optional)
pip install pytest-cov
python -m pytest src/tests/ --cov=src --cov-report=html

Expected Summary Output:

==================== test session starts ====================

src/tests/test_integration.py::test_health_check PASSED     [16%]
src/tests/test_integration.py::test_create_quiz_success PASSED [33%]
src/tests/test_integration.py::test_validation_error PASSED [50%]
src/tests/test_quiz_service.py::test_create_quiz_success PASSED [66%]
src/tests/test_quiz_service.py::test_quota_exceeded PASSED [83%]
src/tests/test_quiz_service.py::test_missing_difficulty_validation PASSED [100%]

Method 2: Docker-based Testing

Docker Setup and Testing

# Create Dockerfile
 Dockerfile 

# Build and test with Docker
docker-compose build
docker-compose --profile test run test-runner

Expected Docker Test Output:

==================== test session starts ====================
platform linux -- Python 3.11.x, pytest-7.4.3
collected 6 items

src/tests/test_integration.py::test_health_check PASSED     [16%]
src/tests/test_integration.py::test_create_quiz_success PASSED [33%]
src/tests/test_integration.py::test_validation_error PASSED [50%]
src/tests/test_quiz_service.py::test_create_quiz_success PASSED [66%]
src/tests/test_quiz_service.py::test_quota_exceeded PASSED [83%]
src/tests/test_quiz_service.py::test_missing_difficulty_validation PASSED [100%]

==================== 6 passed in 0.30s ====================

Start service with Docker:

# Start the service
docker-compose up quiz-service

# Test the containerized service
curl http://localhost:8000/health
# Expected: {"status":"healthy","service":"quiz-service-day6"}

Verification Checklist

✅ Functional Verification

• [ ] Health endpoint responds with 200 status

• [ ] Valid quiz creation returns 201 with proper response structure

• [ ] Validation errors return 400 with specific error messages

• [ ] Quota enforcement returns 429 when limit exceeded

• [ ] Difficulty progression validation catches missing difficulty levels

• [ ] API documentation accessible at /docs

✅ Technical Verification

• [ ] All unit tests pass (6/6 tests)

• [ ] Integration tests pass (API endpoints work correctly)

• [ ] Exception handling maps correctly to HTTP status codes

• [ ] Dependency injection works (service receives repository)

• [ ] Business logic isolation (service layer independent of HTTP)

✅ Code Quality Verification

• [ ] Clear separation of concerns between layers

• [ ] Consistent error handling with custom exceptions

• [ ] Proper validation at model and business logic levels

• [ ] Testable architecture with dependency injection

• [ ] Documentation available via FastAPI automatic docs

Performance Verification

# Simple load testing (optional)
pip install httpx

python -c "
import asyncio
import httpx
import time

async def test_performance():
    async with httpx.AsyncClient() as client:
        start_time = time.time()
        tasks = []
        for i in range(10):
            task = client.get('http://localhost:8000/health')
            tasks.append(task)
        
        responses = await asyncio.gather(*tasks)
        end_time = time.time()
        
        print(f'10 requests completed in {end_time - start_time:.2f} seconds')
        print(f'All responses successful: {all(r.status_code == 200 for r in responses)}')

asyncio.run(test_performance())
"

Expected Output:

10 requests completed in 0.05 seconds
All responses successful: True

Success Criteria Summary

🎉 You have successfully completed Day 6 if:

1. All tests pass (6/6 unit and integration tests)

2. Service starts without errors and responds to health checks

3. Business logic validation works (quota, difficulty progression, etc.)

4. API endpoints return correct HTTP status codes for various scenarios

5. Exception handling provides clear, specific error messages

6. Architecture demonstrates clean separation between presentation, business, and data layers

Ready for Day 7: Quiz Session Management! 🚀

Your business logic foundation is solid and ready to support advanced features like session tracking, state management, and real-time quiz interactions.

Assignment Challenge

Extend the quiz service with a "difficulty progression" business rule: questions within a quiz must progress from easy to hard, with at least one question of each difficulty level. Implement validation logic that checks this constraint during quiz creation and provides specific guidance when violations occur.

Hint: Create a difficulty scoring system (1-5) and implement ascending order validation with gap detection logic.

Your quiz platform now has a brain that thinks before it acts - the hallmark of production-ready systems that scale gracefully and maintain data integrity under pressure.

Next Steps Preview

Day 7 will build upon this business logic foundation to implement quiz session management. The clean separation we've established today will make it easy to add:

• Quiz attempt tracking

• Session state management

• Progress persistence

• Time limit enforcement

The business logic patterns you've learned today form the backbone of scalable web applications and will serve you well in building complex, maintainable systems.