Comparisons

Choosing the right architectural pattern directly impacts the maintainability and velocity of your engineering team. ZCore is not designed to be a universal winner; it is a composable, opt-in layer designed for specific scaling patterns.

This page provides an objective, technical comparison to help you determine which paradigm fits your system architecture.

ZCore vs. Plain FastAPI

ZCore does not replace FastAPI; it runs alongside it to address common boilerplate patterns.

When to choose plain FastAPI

• Your application has a small domain model (1–3 tables) with simple, unique queries.
• You prefer explicit, inline code and want to avoid introducing any class-level abstractions.
• You have no requirements for complex, role-based data masking or dynamic schema generation.
• You are prototyping and want zero architectural layers between your database sessions and routes.

When ZCore adds value

• Your application is expanding, and you are writing identical CRUD and bulk mutation operations for multiple models.
• You need to dynamically prune sensitive attributes (like email, salary, or internal_notes) from responses based on active scopes, without maintaining multiple duplicate Pydantic models.
• You must coordinate multiple database writes atomically while ensuring that side-effect events only publish once the database commit succeeds.
• You want clean, type-hinted constructor dependency injection without nested Depends() parameter lists.

# You can mix both paradigms seamlessly in the same file
from fastapi import APIRouter
from zcore import BaseRepository, Inject, SessionDep
from .models import Task

class TaskRepo(BaseRepository[Task]):
    pass  # This route layer uses ZCore's BaseRepository

router = APIRouter()

# This route remains a standard, native FastAPI controller
# SessionDep is ZCore's Annotated[AsyncSession, Depends(get_db)]
@router.get("/health")
async def health_check(db: SessionDep):
    return {"status": "healthy"}

ZCore vs. Django / Django REST Framework

These frameworks solve fundamentally different architectural problems. Django is a batteries-included monolith, whereas ZCore is a composable architectural extension for FastAPI.

When Django is the optimal choice

• You are building a standard, monolithic web application (API + admin portal + server-rendered HTML templates).
• Your project requires a fully-featured, out-of-the-box admin dashboard immediately.
• Your team is highly productive within the Django ecosystem and prefers built-in, non-negotiable standards.
• You do not require high-performance, fully asynchronous execution across the entire transaction lifecycle.

When ZCore is the optimal choice

• You are building an API-first service optimized for high-throughput, async operation.
• You want to leverage SQLAlchemy 2.0's advanced query capabilities directly without ORM-level lock-in.
• You prefer composing your own modular abstractions over inheriting a monolithic framework.
• You want to avoid class-based views in favor of explicit, lightweight FastAPI endpoints with automated schema projection.

ZCore vs. FastAPI-Users

FastAPI-Users is a dedicated library for comprehensive user authentication, while ZCore's BaseAuth is an abstract helper designed to bind authentication state to the active context.

When FastAPI-Users is better

• You need a complete, turn-key authentication system, including email verification, password reset, and registration endpoints, with minimal manual coding.
• You do not want to design or write user database structures.

When ZCore's BaseAuth is better

• You already have an established user model and database strategy and simply need to integrate JWT claims with your request pipeline.
• You want to seamlessly bind user permissions to ZContext.restricted_fields to drive ZCore's automated Zchema field-pruning serialization.
• You prefer custom, lightweight authentication callbacks over relying on a third-party user-management engine.

ZCore vs. Standalone SQLAlchemy 2.0

ZCore does not replace SQLAlchemy; it builds on top of it. However, it is important to understand the level of abstraction introduced by BaseRepository and SearchEngine.

Where ZCore Introduces Trade-offs

A balanced architecture means acknowledging that every abstraction carries a cost: