fastapi-zcore-framework 0.1.0rc3

An architectural chassis for building modular applications on top of FastAPI.
Structuring transactional boundaries, constructor dependency injection, and field-level access controls while preserving native FastAPI semantics.

🧭 Overview

FastAPI provides an efficient, ergonomic foundation for HTTP handling, asynchronous I/O, and data validation using Pydantic. However, as codebases grow beyond simple APIs into larger services or modular monoliths, engineering teams frequently face common structural challenges:

• Session Lifetime & Leaks: Database sessions can inadvertently leak across concurrent coroutines or terminate prematurely during background tasks.
• Transaction Coordination: Workflows that update multiple repositories often lack a unified, atomic transaction boundary, risking partial writes when a middle step fails.
• Schema Proliferation: Writing and maintaining separate Pydantic models (UserPublic, UserInternal, UserAdminResponse) solely to conceal specific fields across user roles introduces repetitive boilerplate.
• Module Coupling: Large domain modules frequently develop tangled dependency graphs and circular imports when interacting with shared databases.

Full-stack monolithic frameworks solve these issues by introducing comprehensive conventions, coupled ORMs, and centralized registries. While effective, this approach can reduce architectural flexibility.

ZCore is designed as an intermediate layer. It does not hide FastAPI or replace its router. Instead, it provides a set of decoupled architectural primitives—such as a re-entrant Unit of Work, constructor-based Inversion of Control (IoC), context-aware schema filtering (Zchema), and lifecycle plugins—built on top of standard FastAPI, SQLAlchemy 2.0 (Async), and Pydantic V2.

You can adopt individual components where they solve concrete architectural needs or use the structured chassis as a cohesive pattern for modular application design.

🛍️ Reference Implementation: ZShop

To examine how these architectural patterns interact in an end-to-end codebase, refer to ZShop, a modular monolith reference application:

• Context & Security Inspection: Demonstrates active correlation IDs (x-request-id), execution profiling, and role-based data projection.
• Role-Based Schema Pruning: Displays how confidential attributes (such as supplier costs) are dynamically excluded based on the authenticated context via Zchema.
• Atomic Rollback Demonstration: Validates multi-repository rollback guarantees by simulating invariant violations during order checkout.
• Contract-Driven Decoupling: Demonstrates cross-domain communication via Python Protocols (ProductContract) rather than direct database model imports.

👉 Explore the ZShop Reference Codebase

⚖️ Architectural Comparison

🚀 Quick Start

1. Installation

pip install "fastapi-zcore-framework[all]"

2. Initialize a Project

The interactive zc CLI configures your workspace, sets up a virtual environment (uv or pip), and bootstraps the appropriate asynchronous database driver:

# Interactive setup
zc init core_api && cd core_api

# Scaffold a domain module
zc startapp tasks

3. Define Your Domain Model

In tasks/models.py (standard SQLAlchemy 2.0):

import uuid
from sqlalchemy.orm import Mapped, mapped_column
from zcore import Base, SoftDeleteMixin

class Task(Base, SoftDeleteMixin):
    __tablename__ = "tasks"
    
    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
    title: Mapped[str] = mapped_column(index=True)
    is_completed: Mapped[bool] = mapped_column(default=False)

4. Run the Development Server

zc run

The application starts at http://127.0.0.1:8000 with 8 standard endpoints managed by BaseRouter:

• POST /tasks/ — Entity creation
• GET /tasks/{id} — Single-record retrieval with primary key inspection
• GET /tasks/ — List retrieval supporting offset or keyset cursor pagination
• POST /tasks/search — Dynamic nested JSON filtering and sorting
• POST /tasks/lookup — Lightweight, column-projected endpoint for relational references
• PUT /tasks/{id} & PATCH /tasks/{id} — Complete and partial updates
• DELETE /tasks/{id} — Soft delete (or physical purge via ?force=true)
• GET /tasks/_schema — Role-aware schema introspection (all actions or filtered via ?action=create|update|view|lookup)

🏛️ Core Architectural Components

import uuid
from decimal import Decimal
from zcore import Zchema

class ProductResponse(Zchema):
    __model__ = "products"

    id: uuid.UUID
    name: str
    price: Decimal
    cost_price: Decimal | None = None      # Internal margin
    supplier_notes: str | None = None      # Vendor agreement notes

from zcore import UnitOfWork

async with UnitOfWork(session=self.session, dispatcher=self.dispatcher) as uow:
    # 1. Update inventory
    await self.inventory_service.adjust_stock(product_id, -quantity)
    
    # 2. Persist order entity
    self.order_repo.add(new_order)
    await self.session.flush()

    # 3. Buffer domain event
    # If any error occurs before commit completes, this event is discarded.
    uow.register_event("order.created", {"order_id": str(new_order.id)})

# Pure Python contract (contracts/catalog.py)
from typing import Protocol, runtime_checkable

@runtime_checkable
class ProductContract(Protocol):
    async def adjust_stock(self, product_id: str, delta: int) -> None: ...

# Domain implementation (apps/orders/services.py)
from contracts.catalog import ProductContract

class OrderService(BaseService[Orders]):
    # Dependencies are resolved by constructor type hints
    def __init__(self, repository: OrderRepository, inventory: ProductContract):
        super().__init__(model=Orders, repository=repository)
        self.inventory = inventory

import uuid
from zcore import background_task

@background_task
async def generate_invoice_task(
    order_id: uuid.UUID,
    order_repo: OrderRepository,  # Injected with an independent session
) -> None:
    order = await order_repo.get(id=order_id)
    # Operates safely outside of the HTTP request lifecycle

import pytest
from zcore.testing import ZTestClient
from main import app

@pytest.mark.asyncio
async def test_order_placement_atomicity():
    async with ZTestClient(
        app,
        user_id="test-user-id",
        scopes=["orders:create", "products:view"]
    ) as client:
        response = await client.post("/checkout/orders/", json={...})
        assert response.status_code == 201
    # Transaction changes are rolled back automatically upon context exit

🛠️ Developer Tooling (zc CLI)

ZCore provides an interactive command-line interface powered by Questionary and Rich:

$ zc

⚡ ZCore Framework v0.1.0-rc.3 • Modern Modular Monolith
 FastAPI • SQLAlchemy 2.0 • Pydantic V2

? What framework task would you like to perform? 
  ❯ 🧩 startapp   — Scaffold a modular domain app / plugin
    ⚡ run        — Launch Uvicorn development server
    📋 genenv     — Generate template .env from Settings class
    🔑 gensecret  — Generate cryptographically secure SECRET_KEY
    📦 init       — Scaffold a new ZCore project
    🚪 exit       — Exit CLI

Command Reference

📢 Testing & Community Validation (Release Candidate rc.3)

We are currently evaluating v0.1.0-rc.3 across real-world workloads prior to finalizing the v1.0.0 stable release.

ZCore was created to address architectural friction points encountered in production environments. We welcome technical feedback, bug reports, and discussion on edge cases:

• Evaluate the Showcase: Review ZShop to observe how components interact in a concrete project.
• Test Architectural Boundaries: Evaluate UnitOfWork behavior under nested operations, verify complex queries with SearchEngine, or test composite key models.
• Report Issues: If an abstraction feels rigid, if a type hint fails strict static analysis, or if an edge case is unhandled, please open a detailed issue on GitHub.

👉 Submit Issues & Technical Feedback on GitHub

📚 Documentation

Detailed guides, design explanations, and API references are available at our documentation portal:

• Quick Start Tutorial — Basic project initialization and endpoint setup.
• Layer-by-Layer Guide — Walkthrough of model, repository, service, and router separation.
• Architectural Comparisons — Technical comparisons with plain FastAPI and Django.
• How-To Guides — Practical patterns for Keyset Pagination, File Storage, and Caching.
• Core Concepts — Deep dives into DI auto-wiring, Unit of Work, Kernel DAG, and Context shielding.
• API Reference — Method signatures and parameter details.

📄 License

ZCore Framework is open-source software licensed under the Apache License 2.0.
See the LICENSE file for details.

_{Maintained by Ali Alf Ostovar and the Baseryn open-source community.}