Fastro FastAPI Boilerplate

Fastro is a production-ready FastAPI boilerplate designed with vertical-slice modules and swappable infrastructure. Key features include:

• Core: Fully async FastAPI, SQLAlchemy 2.0, and Pydantic v2.
• Auth: Server-side sessions, CSRF, OAuth (Google), and API keys via crudauth.
• Database & CRUD: PostgreSQL with Alembic migrations and FastCRUD for efficient generics and pagination.
• Background Tasks: Taskiq workers using Redis or RabbitMQ.
• Caching: Decorator-based caching (@cache) supporting Redis or Memcached.
• Rate Limiting: Per-tier and per-path rules.
• Admin: Optional SQLAdmin-based admin panel (toggled via environment variables).
• CLI: The bp tool for deployment scaffolding, environment auditing, and plugin management.

Fastro is built on a modern, async-first Python stack designed for high performance and scalability:

• FastAPI: Web framework for building APIs.
• Pydantic V2: High-speed data validation (Rust-based).
• SQLAlchemy 2.0: SQL toolkit and ORM.
• PostgreSQL: Relational database.
• Redis: In-memory store for caching and message brokering.
• Taskiq: Async-first task queue.
• Docker: Containerization for deployment.

When using the @cache decorator on endpoints that return user-specific data, you must ensure the cache key includes the user's identity. If you only key by a resource ID, multiple users may receive the same cached data belonging to the first user who triggered the cache.

To fix this, include the user identifier in the key_prefix using placeholders. Alternatively, if the data is highly personalized and frequently accessed, consider not caching it at all to avoid the latency of Redis hits.

# WRONG — every user gets user 1's data
@router.get("/me/dashboard")
@cache(key_prefix="dashboard", resource_id_name="user_id")
async def my_dashboard(request: Request, user_id: int, ...):
    ...

# CORRECT — Include user in the prefix
@cache(key_prefix="dashboard_for_user_{user_id}", resource_id_name="user_id")
# → dashboard_for_user_5:5  ← key includes user

To maintain data integrity and performance, avoid these common caching mistakes:

• Caching mutation responses: The decorator only caches GET requests. If you need to cache a POST or PATCH response, cache the GET endpoint that provides that data instead.
• Caching non-derived state: Only cache data that can be reconstructed from the database. If losing the cache results in actual data loss, that data belongs in a database row, not a cache.
• Inconsistent TTLs in pagination: Avoid having different TTLs for different pages of the same resource (e.g., widgets:page_1 expiring before widgets:page_2). Use a consistent TTL across the entire prefix family to prevent inconsistent pagination.
• Frequent pattern invalidation: Using pattern scans to wipe many keys at once can become expensive at scale. Use them only when absolutely necessary.

The boilerplate uses SQLAlchemy relationship() with lazy="selectin" to prevent N+1 query problems.

Best Practices:

1. Avoid Circular Imports: Use TYPE_CHECKING for imports and string literals for class names in the relationship() function.
2. Skip Unnecessary Relationships: If a relationship is only one-way (e.g., an APIKey knows its user_id but User doesn't need a list of keys), only define the ForeignKey column and skip the relationship() call. You can still perform joins via FastCRUD.
3. Dataclass Ergonomics: Use init=False for relationship attributes so they are excluded from the model's constructor.

from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from ..tier.models import Tier

class User(Base, ...):
    tier: Mapped["Tier | None"] = relationship(
        "Tier", back_populates="users", lazy="selectin", init=False
    )

Login Lockout

The POST /api/v1/auth/login endpoint is automatically throttled by crudauth. It uses an escalating per-IP and per-identifier lockout mechanism. When throttled, the server returns a 429 status code with a Retry-After header. There are no environment variables to tune this behavior.

Error Messages

To prevent user enumeration, the login endpoint returns a generic "Incorrect username or password" message regardless of whether the username or the password was incorrect.

Account Deletion

By default, DELETE /api/v1/users/{username} performs a soft delete. Hard deletion (which involves anonymization to preserve foreign key integrity) is reserved for specific GDPR-style requests.

The boilerplate follows a layered architecture to separate concerns. This allows for easier testing (mocking layers) and maintenance.

Request Flow:

1. HTTP Request arrives.
2. APIRouter (modules/<feature>/routes.py): Handles HTTP concerns like status codes, schemas, and dependencies.
3. Service (modules/<feature>/service.py): Orchestrates business rules, validation, and permission checks.
4. FastCRUD (modules/<feature>/crud.py): Manages data access logic.
5. SQLAlchemy Model (modules/<feature>/models.py): Defines the database schema.
6. PostgreSQL: The persistent data store.