Connecting Game Features

Welcome back! So far, you’ve learned how to score word guesses using semantic similarity and set up a leaderboard. Now, it’s time to connect all these features together so your game can interact with players through the web.

In this lesson, you’ll learn how to create the main routes (or endpoints) in FastAPI that allow your frontend to communicate with your backend. These routes will let players get the daily prompt, submit their guesses, and see the leaderboard. By the end of this lesson, you’ll understand how each route works and how they power your word prediction game.

Before we dive in, let’s quickly remind ourselves about FastAPI’s APIRouter and how it helps organize your project.

An APIRouter in FastAPI is a way to group related routes together, making your code modular and easier to manage as your application grows. In our project, we use an APIRouter to keep all the game-related routes in one place.

For example, you might see something like this in your project:

from fastapi import APIRouter

router = APIRouter()

This creates a router called router. All the routes for your game will be registered under this router, keeping things tidy and organized. Later, this router is included in your main FastAPI app using app.include_router(router).

Let’s start by creating the route that sends the daily game data to the frontend. This is the /game route.

First, we define a new route using our APIRouter. We want this route to respond to GET requests.

from app.game import get_daily_prompt
from app.llm import get_llm_response_words

@router.get("/game")
def game_data():
    # Function body will go here

Here, @router.get("/game") tells FastAPI to call the game_data function whenever someone visits /game with a GET request.

Inside the function, we need to get today’s prompt. This is usually a dictionary with the system prompt, user question, and the LLM model to use.

prompt = get_daily_prompt()

The get_daily_prompt() function (defined elsewhere in your project) returns the prompt for today’s game.

Next, we want to get the list of words that the LLM (Large Language Model) would generate in response to the prompt.

words = get_llm_response_words(
    system_prompt=prompt["system_prompt"],
    user_question=prompt["user_question"],
    model=prompt.get("llm", "gpt-5.4-nano")
)

Here, get_llm_response_words takes the system prompt, user question, and model name, and returns a list of words generated by the LLM.

Finally, we return all this information as a dictionary. FastAPI will automatically convert it to a JSON response.

return {
    "prompt": {
        "llm": prompt["llm"],
        "system_prompt": prompt["system_prompt"],
        "user_question": prompt["user_question"]
    },
    "words": words,
    "breakpoints": prompt.get("breakpoints", [])
}

• The response includes the prompt, the list of words, and any breakpoints (special markers for the game).

Example Output:

{
  "prompt": {
    "llm": "gpt-5.4-nano",
    "system_prompt": "You are a helpful assistant.",
    "user_question": "What is the capital of France?"
  },
  "words": ["The", "capital", "of", "France", "is", "Paris", "."],
  "breakpoints": []
}

This output gives the frontend everything it needs to display the game for today.

Now, let’s create the route that lets players submit their guesses and get a score.

We want this route to accept POST requests, since the player is sending data to the server. In FastAPI, we use a Pydantic model to define the expected request body.

First, define the schema:

from pydantic import BaseModel

class GuessPayload(BaseModel):
    guess: str
    correct: str

Then, define the route:

@router.post("/submit_guess")
def submit_guess(payload: GuessPayload):
    # Function body will go here

Here, payload will automatically contain the parsed data from the request body.

Now, we use the score_guess function to compare the guess to the correct word and calculate a similarity score.

score = score_guess(payload.guess, payload.correct)

This function returns a score (for example, between 0 and 100) based on how close the guess is to the correct answer.

Finally, we return the score as a dictionary. FastAPI will convert it to JSON.

return {"score": score}

Example Request:

{
  "guess": "London",
  "correct": "Paris"
}

Example Response:

{
  "score": 42
}

This allows the frontend to show the player how close their guess was.

Let’s finish by looking at how players submit their total score and how the leaderboard is displayed.

Players send their name and score to the server using the /submit_score route. We use a Pydantic model for the request body and dependency injection for the database session.

First, define the schema:

class ScorePayload(BaseModel):
    name: str
    score: int

When defining the model, you might wonder why we don’t include a date field for when the score was submitted. That’s because the backend automatically calculates and assigns the date when saving the score to the database.

Then, define the route:

from fastapi import Depends, HTTPException
from sqlalchemy.orm import Session
from app.db import get_db

@router.post("/submit_score")
def submit_total_score(payload: ScorePayload, db: Session = Depends(get_db)):
    if not payload.name or payload.score is None:
        raise HTTPException(status_code=400, detail="Missing name or score.")

    submit_score(db, name=payload.name, score=payload.score)
    return {"success": True}

• We use dependency injection to get the database session by including db: Session = Depends(get_db) in the route’s arguments. This tells FastAPI to provide a database session to the function automatically, so we can use it to fetch the leaderboard data.
• The function checks that both name and score are provided.
• If either is missing, it raises an HTTPException with a 400 status code.
• Otherwise, it saves the score using the submit_score function and returns a success message.

Example Request:

{
  "name": "Alice",
  "score": 85
}

Example Response:

{
  "success": true
}

The /leaderboard route lets anyone see the top scores for today. We use dependency injection to get the database session.

@router.get("/leaderboard")
def leaderboard(db: Session = Depends(get_db)):
    scores = get_leaderboard(db)
    return {"scores": scores}

• This function calls get_leaderboard(db) to get the list of top scores.
• It returns the scores as a dictionary, which FastAPI converts to JSON.

Example Output:

{
  "scores": [
    {"name": "Alice", "score": 85},
    {"name": "Bob", "score": 78}
  ]
}

This allows the frontend to display the current leaderboard to all players.

In this lesson, you learned how to create the main routes that connect your FastAPI backend to the game’s frontend. You saw how to:

• Send the daily prompt and LLM-generated words to the frontend with /game
• Receive and score player guesses with /submit_guess
• Submit player scores and display the leaderboard with /submit_score and /leaderboard

These routes are the backbone of your word prediction game, allowing players to interact with your app in real time. Up next, you’ll get hands-on practice building and testing these routes yourself. This will help you solidify your understanding and prepare you to add even more features to your game. Good luck!