fastapi-zcore-framework 0.1.0rc2

A composable architectural foundation for building scalable applications on top of FastAPI.
Standardize your structure, manage atomic transactions, and protect sensitive data — without sacrificing FastAPI's flexibility.

🧭 Overview

FastAPI is an exceptional microframework for HTTP routing, request parsing, and asynchronous I/O.

However, as applications grow into medium and large systems, teams inevitably encounter an architectural gap:

• Database sessions leak across asynchronous tasks or background jobs.
• Business workflows spanning multiple repositories lack reliable, all-or-nothing transaction boundaries.
• Teams end up writing dozens of nearly identical DTO schemas just to hide internal fields (like profit margins, supplier terms, or sensitive IDs) from different user roles.
• Domain modules become tightly coupled through circular imports and tangled dependency trees.

Heavy enterprise frameworks solve these challenges by enforcing rigid conventions, proprietary ORMs, and heavy abstractions that eliminate your freedom.

ZCore is the middle ground: ZCore provides a structured, modular layer that sits directly on top of standard FastAPI, SQLAlchemy 2.0, and Pydantic V2. It introduces proven architectural patterns (Unit of Work, IoC Dependency Injection, Field-Level Security, and Domain Event Dispatching) as composable building blocks.

Your code remains 100% standard FastAPI. Adopt ZCore piece by piece where it solves real problems, or use the full architectural stack — with zero vendor lock-in.

🛍️ Reference Showcase: ZShop

To see ZCore's architectural concepts in action before writing a single line of code, explore ZShop — the official Modular Monolith e-commerce reference implementation:

• Interactive Live Inspector Dock: Monitor active request context, correlation IDs (x-request-id), execution latencies, and real-time SSE stream events.
• 1-Click RBAC Persona Switcher: Switch between SuperAdmin, Store Manager, Customer, and Guest to watch confidential data fields automatically vanish from responses via Zchema.
• Atomic Rollback Demonstration: An interactive deficit checkout button verifying that stock adjustments and order persistence roll back atomically when any invariant fails.
• Decoupled Architecture: Strict inter-module communication using Python Protocols (ProductContract) without cross-domain database coupling.

👉 Explore the ZShop Showcase Repository

⚖️ Why ZCore? (An Honest Comparison)

🚀 Quick Start (in Under 60 Seconds)

1. Installation

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

2. Scaffold a New Project

The interactive zc CLI configures your environment, sets up a virtual environment (uv or pip), and provisions your database driver:

# Interactive mode (recommended)
zc init core_api && cd core_api

# Generate your first domain module
zc startapp tasks

3. Define Your Domain Model

Open 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

Your API is running at http://127.0.0.1:8000 with 8 production-ready endpoints out of the box:

• POST /tasks/ — Create entity
• GET /tasks/{id} — Fetch single record (with automatic PK type inspection)
• GET /tasks/ — List records (with cursor or offset pagination)
• POST /tasks/search — Dynamic nested JSON filtering engine
• POST /tasks/lookup — Lightweight field-projected endpoint for dropdowns
• PUT /tasks/{id} & PATCH /tasks/{id} — Full and partial updates
• DELETE /tasks/{id} — Soft delete (or permanent purge via ?force=true)
• GET /tasks/?schema=true — Dynamic role-aware frontend form schema

🏛️ Core Architectural Patterns

import uuid
from decimal import Decimal
from pydantic import Field
from zcore import Zchema

class ProductResponse(Zchema):
    __model__ = "products"

    id: uuid.UUID
    name: str
    price: Decimal
    cost_price: Decimal | None = None      # 🔒 Sensitive business margin
    supplier_notes: str | None = None  # 🔒 Internal agreement details

from zcore import UnitOfWork

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

    # 3. Buffer domain event
    # If the transaction rolls back, this event is discarded immediately!
    uow.register_event("order.created", {"order_id": str(new_order.id)})

# contracts/catalog.py (No database imports!)
from typing import Protocol, runtime_checkable

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

# apps/orders/services.py
from contracts.catalog import ProductContract

class OrderService(BaseService[Orders]):
    # Pure Python constructor: Auto-wired by ZCore's IoC container!
    def __init__(self, repository: OrderRepository, inventory: ProductContract):
        super().__init__(model=Orders, repository=repository)
        self.inventory = inventory

from zcore import background_task

@background_task
async def generate_invoice_task(
    order_id: uuid.UUID,
    order_repo: OrderRepository,  # Automatically injected with an isolated session!
) -> None:
    order = await order_repo.get(id=order_id)
    # Safely executes without relying on completed HTTP request lifecycles

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="customer-uuid",
        scopes=["orders:create", "products:view"]
    ) as client:
        response = await client.post("/checkout/orders/", json={...})
        assert response.status_code == 201
    # Database is automatically rolled back to its exact pre-test state!

🛠️ Interactive Developer Tooling (zc CLI)

ZCore includes an interactive terminal user interface (TUI) powered by Questionary and Rich:

$ zc

⚡ ZCore Framework v0.1.0-rc.2 • 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

CLI Command Summary

📢 Community Testing & Feedback (Release Candidate rc.2)

We are currently validating v0.1.0-rc.2 before tagging the official v1.0.0 stable release.

We built ZCore to solve architectural pain points we faced in production. Before declaring the API stable, we need your critical engineering feedback:

• Try the Showcase: Clone ZShop, run the seed script, and test the endpoints.
• Test the Edge Cases: Push the boundaries of UnitOfWork, test complex nested queries with SearchEngine, or inspect field pruning with Zchema.
• Break It & Report: If an abstraction feels awkward, if a type hint breaks, or if an async session leaks, please open an issue!

👉 Submit Issues & Architectural Feedback on GitHub

📚 Documentation Index

Comprehensive guides, architectural deep-dives, and complete API references are available at our official documentation portal:

• Quick Start Tutorial — From zero to a working API in 60 seconds.
• 10-Step Quick Learn — Systematic layer-by-layer walkthrough.
• Architectural Comparisons — Honest comparisons with plain FastAPI, Django, and other frameworks.
• How-To Guides — Practical recipes for Multi-tenancy, Keyset Pagination, File Uploads, and Caching.
• Core Concepts — Deep dives into DI auto-wiring, Unit of Work, Kernel DAG, and Context shielding.
• API Reference — Detailed signatures and class specifications.

📄 License

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

_{Developed with architectural rigor and care by Ali Alf Ostovar / Baseryn.}