Warning

This project is part of the “Multimedia Learning Environments” course offered by the Faculty of Business Education at the University of Bamberg. Due to the short development time available, certain features, such as sophisticated security, have not been implemented. This is merely a proof of concept for an educational game and the basis for a scientific thesis. Project will be tested on render.com.

CEOGame Backend API

A FastAPI-based backend for the CEOGame educational platform.
Manage users, school classes, and gamification scores with ease.

---

📖 About The Project

This repository contains the backend logic for CEOGame, an educational game designed to teach business concepts. The application is built using FastAPI and utilizes SQLModel for database interactions. It provides a RESTful API to handle user authentication, class management, and leaderboard tracking.

Key Features

• User Management: Registration and Login (JWT-style flow).
• Class System: Create school classes and assign students to them.
• Gamification: Track coins and generate rankings per class.
• Admin Seeding: Automatic initialization of admin accounts and classes.

---

🛠 Tech Stack

• Language: Python 3.12
• Framework: FastAPI
• Database: SQLite (via SQLModel/SQLAlchemy)
• Security: bcrypt (Password hashing), OAuth2PasswordBearer
• Package Manager: uv
• Containerization: Docker

---

🚀 Getting Started

To get a local copy up and running, follow these simple steps. This project supports both local Python environments using uv and containerized deployment using Docker.

Prerequisites

• Python 3.12+
• uv (An extremely fast Python package installer and resolver)
• Docker (Optional, for containerization)

Option 1: Running locally with uv

This project uses uv for dependency management.

1. Clone the repository

   git clone [https://github.com/VfBfoerst/test-fastapi.git](https://github.com/VfBfoerst/test-fastapi.git)
   cd test-fastapi

2. Install dependencies uv will handle the virtual environment creation and package installation.

   uv sync

3. Run the application Start the development server.

   uv run fastapi dev main.py

   The API will be available at http://127.0.0.1:8000.

Option 2: Running with Docker

1. Build the image

   docker build -t ceogame-backend .

2. Run the container

   docker run -p 8000:8000 ceogame-backend

---

📡 API Endpoints

Once the server is running, you can access the interactive API documentation at:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

Authentication & Users

Method	Endpoint	Description
POST	/register	Register a new user (Student).
POST	/token	Login to receive an access token.

Game Data & Scoring

Method	Endpoint	Description
GET	/score	Get a specific user's coin count.
POST	/score	Update the current user's score (Stub).

Class Management

Method	Endpoint	Description
POST	/create_class	Create a new School Class.
GET	/get_classes	List all available classes.
GET	/get_class_id	Find the Class ID for a specific user.
GET	/get_class_name	Get the name of a class by its ID.
GET	/get_class_ranking	Get the leaderboard (user/coins) for a specific class.

---

🗄️ Database Model

The application uses SQLModel to define the database schema.

• User: Stores credentials (username, hashed_password), current game currency (coins), and a foreign key to the SchoolClass.
• SchoolClass: Represents a group of students (id, name).

Note: On startup, the application checks for an admin user. If not found, it automatically creates an admin class and an admin user (Password: admin, Coins: 9999).

---

📂 Project Structure

.
├── database.py    # DB engine, session management, and admin seeding
├── Dockerfile     # Docker build instructions
├── main.py        # Application entry point and API routes
├── models.py      # SQLModel database tables (User, SchoolClass)
├── schemas.py     # Pydantic models for request bodies
├── security.py    # Password hashing and token verification logic
└── uv.lock        # Dependency lock file

⚠️ Security Note

[!CAUTION] As stated in the disclaimer, this is a Proof of Concept. The current implementation uses the username directly as the bearer token for simplicity. Production environments should implement proper JWT (JSON Web Token) generation and validation with expiration times.