Python 508 FILES 8 FINDINGS

HOW SQLMODEL
ACTUALLY WORKS

SQL databases in Python, designed for simplicity and compatibility with FastAPI. Conventions, patterns, and architecture extracted from the fastapi/sqlmodel repository by sourcebook.

VIEW_REPO north_east

QUICK_REF:

Routing: FastAPI endpoints Testing: pytest.

WHAT_MATTERS

→
Uses FastAPI endpoints for routing — follow this pattern, don't add REST routes directly

KEY_FINDINGS

FastAPI project. Use Pydantic models for request/response schemas, not raw dicts.

HIGH

Uses SQLAlchemy/SQLModel for ORM. Database sessions must be properly closed (use dependency injection).

HIGH

Uses pytest. Test files should be named `test_*.py` or `*_test.py`.

HIGH

Tests live in a separate test/ directory, mirroring src/ structure. New tests go there, not next to source files.

HIGH

API endpoints use FastAPI endpoints. Follow this pattern for new routes.

HIGH

14 files use FastAPI endpoints

Tests use pytest.

HIGH

20 test files

Route definitions live in: docs_src/tutorial/fastapi, docs_src/tutorial/fastapi/update, docs_src/tutorial/fastapi/teams. Add new endpoints here.

HIGH

3 route directories

smart_toy USING_AI_TOOLS

→don't guess routing patterns — check first
→follow existing patterns listed in quick reference

CLAUDE.MD expand_more

# CLAUDE.md

This file provides guidance to Claude Code when working with this codebase.
Generated by [sourcebook](https://github.com/maroondlabs/sourcebook). Review and edit — the best context comes from human + machine together.

## Quick Reference

- **routing:** API endpoints use FastAPI endpoints
- **testing:** Tests use pytest.

## Critical Constraints

- **FastAPI:** Uses SQLAlchemy/SQLModel for ORM. Database sessions must be properly closed (use dependency injection).

## Stack

FastAPI

## Project Structure

- `tests/` — Tests
- `scripts/` — Build / utility scripts
- `docs/` — Documentation

## Conventions & Patterns

- **FastAPI:** FastAPI project. Use Pydantic models for request/response schemas, not raw dicts.
- **Testing:**
- Uses pytest. Test files should be named `test_*.py` or `*_test.py`.
- Tests live in a separate test/ directory, mirroring src/ structure. New tests go there, not next to source files.
- **Dominant patterns:**
- API endpoints use FastAPI endpoints. Follow this pattern for new routes.
- Tests use pytest.
- Route definitions live in: docs_src/tutorial/fastapi, docs_src/tutorial/fastapi/update, docs_src/tutorial/fastapi/teams. Add new endpoints here.

## Before Making Changes

- **Follow existing patterns.** This project has established conventions (listed above). Match them instead of introducing new approaches.
- **Respect constraints.** Review the Critical Constraints section before making structural changes.

If the sourcebook MCP server is available (`sourcebook serve`), verify before acting:
- `get_blast_radius` — check what breaks if you edit a hub file
- `query_conventions` — confirm the right pattern before adding new code
- `get_pressing_questions` — get a briefing before editing an unfamiliar file

## What to Add Manually

The most valuable context is what only you know. Add:

- Architectural decisions and why they were made
- Past incidents that shaped current conventions
- Deprecated patterns to avoid in new code
- Domain-specific rules or terminology
- Environment setup beyond what .env.example shows

GENERATED IN ~3 SECONDS WITH

npx sourcebook init

VIEW ON GITHUB star

FROM_THE_BLOG

Why AI agents fail on real codebases arrow_forward Why auto-generated context makes agents worse arrow_forward

RELATED_REPOS

FASTAPI PYDANTIC

HOW SQLMODELACTUALLY WORKS

WHAT_MATTERS

KEY_FINDINGS

npx sourcebook init

FROM_THE_BLOG

RELATED_REPOS

HOW SQLMODEL
ACTUALLY WORKS