Skip to main content

Ferrox-Py Overview

1. Overview (What does this do?)​

The Ferrox-Py ecosystem provides a robust backend development framework, centered around the 7-Layer Onion Request Pipeline. It adapts the stringent, enterprise-grade conventions established by the original Ferrox ecosystem specifically for Python 3.11+. The overview encapsulates how various modular components—ranging from routing to security—come together to form a highly resilient application core.

2. Philosophy (Why does it exist?)​

The overarching philosophy of the Ferrox-Py framework is zero-trust security and maximum decoupling. It exists to solve the common issue of unmaintainable, tightly coupled backend monoliths. By enforcing the 7-layer pipeline, it prevents developers from taking shortcuts that would compromise the system architecture (such as bypassing validation or security measures) and effectively prevents cache stampedes in highly concurrent environments.

3. Target Audience (Who is it for?)​

This overview and the framework it describes are intended for backend engineers, system architects, and technical leads who are building large-scale Enterprise SaaS applications, Data Platforms, or intricate microservice ecosystems. It is meant for teams that prioritize long-term maintainability, strict typing, and robust security policies over "quick-and-dirty" prototyping.

4. Architecture (How does it work?)​

The system relies on FastAPI acting as the underlying ASGI container, upon which Ferrox-specific security modules are seamlessly layered as middleware and dependencies. The complete 7-Layer Onion Request Pipeline consists of:

  1. Security Header Enforcer Middleware
  2. Polymorphic Route Token (MTD)
  3. Sentinel Threat Engine
  4. Auth Guards (PASETO v4)
  5. Validation Pipe (Pydantic)
  6. Controller Route Handler (FastAPI)
  7. Business Service (Singleflight / CQRS)

5. Installation / Setup​

To get started with the concepts outlined in this overview, you need the base Ferrox-Py package installed in a Python 3.11+ environment.

pip install ferrox-py

Ensure that no custom Starlette middlewares are globally configured in a way that bypasses the built-in Ferrox 7-layer pipeline.

6. Quickstart (Usage)​

Initializing the foundational application structure is straightforward:

from ferrox_py.core.app import FerroxApp
from ferrox_py.core.container import Container

# Initialize the IoC Container and Application
container = Container()
app = FerroxApp(container)

# The app is now ready to serve the 7-layer pipeline

7. Ecosystem Integration​

The concepts described in this architectural overview integrate closely with every other component in the ferrox-py ecosystem. For instance, the Business Service layer (Layer 7) integrates seamlessly with the Singleflight and CQRS components, ensuring I/O bounds are strictly optimized and preventing database overloading, while the Webhooks integration automatically links with the Sentinel Threat Engine (Layer 3).