Othello AI - Design Document

1. Overview of the Design

The Othello AI project is a web-based implementation of the classic board game Othello (also known as Reversi). The application allows users to play against a configurable AI opponent with multiple difficulty levels. A key feature is the real-time analysis heatmap, which visualizes the AI's strategic evaluation of potential moves, serving as an educational tool for players.

The system is built using a modern full-stack architecture, with a Python FastAPI backend and a vanilla JavaScript frontend. This approach demonstrates core software engineering principles, including API design, database management, AI algorithm implementation, and user interface development.

The primary purpose of the application is twofold:

1. To provide an engaging and challenging Othello experience for players of all skill levels.
2. To serve as a practical case study for developers, demonstrating how to integrate various AI models into a web application.

The application handles failure conditions, such as invalid user moves, by providing immediate feedback through the UI. Upon first use, the application presents a default game board, allowing a guest user to play against the "Easy" AI immediately. The main limitations are that guest users cannot play against harder AI difficulties, and their game history is not saved.

1.1 Assumptions, Constraints, and Risks

2. Detailed Design

2.1 Data Models and Database Design

The database is designed to store information about users, games, leaderboard rankings, and user feedback.

2.1.1 Logical Data Model (ERD)

2.1.2 Data Dictionary

2.1.3 Database Schema (SQL)

CREATE TABLE users (
    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(100) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL,
    is_admin BOOLEAN NOT NULL DEFAULT 0,
    is_active BOOLEAN NOT NULL DEFAULT 1
);

CREATE TABLE games (
    id INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    ai_level VARCHAR(20) NOT NULL,
    user_color VARCHAR(5) NOT NULL,
    winner VARCHAR(20) NOT NULL,
    user_score INTEGER NOT NULL,
    ai_score INTEGER NOT NULL,
    timestamp DATETIME NOT NULL DEFAULT (CURRENT_TIMESTAMP),
    FOREIGN KEY(user_id) REFERENCES users (id)
);

-- Other CREATE TABLE statements would go here...

2.2 User Interface

The user interface is a single-page application (SPA) built with vanilla JavaScript, HTML, and CSS.

2.2.1 Structure and Navigation

Navigation is handled via buttons and links in the header and modals that overlay the main view.

2.2.2 Screen Descriptions

1. Main Game Screen

The central view of the application, consisting of the game board and info panel.

2. New Game Modal

Appears when the "New Game" button is clicked, allowing game configuration.

3. Leaderboard Modal

Displays a table of the top-ranked players.

4. Admin Dashboard

An admin-only view for managing users and viewing feedback.

2.3 API Development

The backend provides a RESTful API for the frontend to consume. Key endpoints include:

• POST /api/token: Authenticates a user and returns a JWT.
• POST /api/users/: Registers a new user.
• POST /api/game/move: Submits a player's move and gets the AI's response.
• GET /api/leaderboard/: Retrieves the leaderboard rankings.
• GET /api/admin/users/: (Admin) Retrieves a list of all users.

3. Non-Functional Requirements

• Security: Passwords are hashed with bcrypt. Auth uses JWTs. SQLAlchemy ORM protects against SQL injection.
• Capacity: SQLite is suitable for low traffic; can be migrated to PostgreSQL for scaling.
• Compatibility: Backend requires Python 3.8+. Frontend requires a modern browser (ES6).
• Reliability: Designed for 24/7 availability. Primary failure point is the host server.
• Performance: AI response times are critical and benchmarked for each difficulty level.
• Usability: The interface is designed to be simple and intuitive.

4. Tests

The project includes a testing suite using Python's pytest framework to ensure functionality and correctness. Tests are isolated using a separate, in-memory SQLite database.

General Test Scenarios Covered:

• User registration and login.
• Making a valid game move as a guest and as a logged-in user.
• API endpoint responses for both valid and invalid requests.
• Correct data persistence in the test database.
• Functionality of core game logic and AI move generation.

Appendix A: References