Code Sensei – Learn Your Codebase

Your first contribution starts with a map

Illustrative onboarding example adapted from the FastAPI demo bundled with Code Sensei. This is not a newly executed session against a live repository.

1. Understand one request before reading every file

This example is a FastAPI todo API. Its main flow separates HTTP handling, business rules, and database access:

Client request
      ↓
routes/          Parse the request and return a response
      ↓
services/        Apply business rules
      ↓
repositories/    Read and write records
      ↓
models/          Define the database entities
      ↓
PostgreSQL

config.py → application settings
schemas/  → API input and output shapes
main.py   → assembles the application

Why this helps: if your first task is “limit how many todos a user can create,” start with configuration and the service layer. You do not need to read every route first.

2. Know what to read next—and why

Start here: complete the short configuration lesson below. Then follow one setting into the service that uses it.

3. First lesson: config.py

Level: Beginner · Estimated study time: 5 minutes

Configuration keeps environment-specific values in one place, so the rest of the application can use settings without scattering defaults across modules.

Read the code

The following code is from the bundled illustrative example:

# config.py:1-22
from pydantic_settings import BaseSettings
from functools import lru_cache

class Settings(BaseSettings):
    # Database
    database_url: str = "postgresql://localhost/tododb"
    
    # API
    api_prefix: str = "/api/v1"
    debug: bool = False
    
    # Auth
    secret_key: str = "change-me-in-production"
    access_token_expire_minutes: int = 30
    
    class Config:
        env_file = ".env"        # ← Reads from .env file
        env_file_encoding = "utf-8"

@lru_cache()                     # ← Singleton: only created once
def get_settings() -> Settings:
    return Settings()

What to notice

• Defaults are visible: the database URL, API prefix, and token lifetime are declared together.
• Environment configuration is centralized: the settings class is configured to read an .env file.

Settings are reused: get_settings() is cached so callers normally receive the same settings object within a process.

• The secret is a placeholder: “change-me-in-production” is illustrative, not a production credential.

Connect it to the app

4. Turn understanding into a small change

Easy — Explain: if DATABASE_URL is not set, which value does the example use?

Medium — Modify: add max_todos_per_user with a default of 100, then use it in the todo service to enforce a limit.

Hard — Design: how would you separate development, staging, and production settings without committing secrets?

A useful follow-up

You: “Where should I enforce the todo limit?”

Teaching hint: “Start in the service layer. Find where a todo is created and where the user's existing todos can be counted. What should happen when the count reaches the configured limit?”

5. Your next step

Trace one setting from its definition to its consumer, attempt the medium exercise, and ask for a hint if you get stuck. Continue with models and schemas once you can explain the configuration flow in your own words.