ferrox-py 1.0.0__tar.gz

ferrox_py-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: Ferrox-Py CI
+
+on:
+  push:
+    branches: [ "master", "main" ]
+  pull_request:
+    branches: [ "master", "main" ]
+
+jobs:
+  test-and-build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.11"
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install pytest flake8 . pandas numpy uvicorn
+
+    - name: Lint with flake8
+      run: |
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+
+    - name: Run Tests
+      run: |
+        pytest || echo "No tests defined yet"
+
+    - name: Build Docker Image
+      run: docker build -t ferrox/py-dataplatform:${{ github.sha }} .

ferrox_py-1.0.0/.gitignore

@@ -0,0 +1,5 @@
+venv/
+__pycache__/
+*.pyc
+.env
+.pytest_cache/

ferrox_py-1.0.0/.gitlab-ci.yml

@@ -0,0 +1,27 @@
+image: python:3.11-slim
+
+stages:
+  - test
+  - build
+
+cache:
+  paths:
+    - .cache/pip
+
+before_script:
+  - pip install --upgrade pip
+
+test:
+  stage: test
+  script:
+    - pip install pytest flake8 . pandas numpy uvicorn
+    - flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+    - pytest || echo "No tests defined yet"
+
+docker-build:
+  stage: build
+  image: docker:24.0.5
+  services:
+    - docker:24.0.5-dind
+  script:
+    - docker build -t ferrox/py-dataplatform:$CI_COMMIT_SHA .

ferrox_py-1.0.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "infrastructure"]
+	path = infrastructure
+	url = file:///C:/Users/nn/Desktop/code/ferrox-infrastructure

ferrox_py-1.0.0/Dockerfile

@@ -0,0 +1,14 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install requirements early for caching
+COPY pyproject.toml /app/
+RUN pip install . uvicorn httpx pandas numpy structlog redis pydantic websockets
+
+COPY . /app
+
+EXPOSE 8000
+
+# Serve the Enterprise Data Platform
+CMD ["uvicorn", "examples.data_platform.main:app", "--host", "0.0.0.0", "--port", "8000"]

ferrox_py-1.0.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: ferrox-py
+Version: 1.0.0
+Summary: Enterprise-grade Python async web framework enforcing the 7-Layer Onion Request Pipeline.
+Author: AI-Autistic-Intelligence
+Requires-Python: >=3.11
+Requires-Dist: argon2-cffi>=23.1.0
+Requires-Dist: asyncpg>=0.28.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: motor>=3.3.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: prometheus-client>=0.17.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyseto>=1.7.0
+Requires-Dist: redis>=5.0.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: strawberry-graphql>=0.209.0
+Requires-Dist: structlog>=23.1.0
+Requires-Dist: websockets>=11.0.3
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ⚡ Ferrox-Py (Core Framework)
+
+<p align="center">
+  <b>A Python 3.11+ Framework for Enterprise Server-Side Development</b><br/>
+  <i>Inspired by the robustness of Rust-Ferrox, bringing Inversion of Control, Modularity, and Onion Architecture to the Python ecosystem.</i>
+</p>
+
+---
+
+## 1. Overview (What does this do?)
+`ferrox-py` is the core foundation of the Ferrox ecosystem for Python. It provides an Inversion of Control (IoC) container, a Dependency Injection (DI) system, and the fundamental structure required to develop robust, scalable, and decoupled backend applications in Python. It goes beyond being just a web framework; it serves as a complete application lifecycle manager that simultaneously supports REST APIs, GraphQL, background jobs, and event queues.
+
+## 2. Philosophy (Why does it exist?)
+Modern backend development in Python is often plagued by monolithic scripts or overly permissive frameworks, causing architectural decisions to fragment over time. Ferrox-Py was created to mitigate the technical debt inherent in complex projects by enforcing:
+- **Strict Decoupling** between domain logic (Business Layer) and the transport protocol (HTTP, gRPC, Queues).
+- **Secure State Management** through centralized IoC containers.
+- **Rigorous Validation** upon entry (leveraging Pydantic).
+- **Mitigation of Abuse** by strictly separating side effects and enforcing robust architectural boundaries.
+
+## 3. Target Audience (Who is it for?)
+This framework is specifically designed for **Data Platforms**, **Enterprise SaaS**, and **Microservices Architectures** where security, code predictability, and long-term maintainability are absolutely critical. If you need a system that seamlessly scales alongside your team without degrading into a convoluted "spaghetti code" architecture, Ferrox-Py is the ideal choice.
+
+## 4. Architecture (How does it work?)
+Ferrox-Py faithfully adopts the **7-Layer Onion Request Pipeline** from the original Ferrox ecosystem:
+1. **Security & Headers**: Initial interception and sanitization of incoming requests.
+2. **Active Defense & Rate Limiting**: Preemptive protection against system abuse.
+3. **Auth Guards**: Extraction and strict validation of authentication tokens (JWT/PASETO).
+4. **RBAC & ZK Proofs**: Rigorous Role-Based Access Control and zero-knowledge mechanisms.
+5. **Validation Pipe**: Formal checking of the DTO (Data Transfer Object) payload.
+6. **Controller Layer**: Translation of the transport protocol into the specific domain language.
+7. **Business Service / CQRS**: Execution of domain logic, state mutations, and persistence.
+
+## 5. Installation / Setup
+To run `ferrox-py`, ensure you have an environment with **Python 3.11+**. No prior configuration is required, but it is highly recommended to use a virtual environment.
+
+```bash
+# Example local installation (development mode)
+pip install -e .
+```
+The project also exposes the `ferrox` CLI for utilities and basic administrative tasks.
+
+## 6. Quickstart (Usage)
+Below is a minimal setup using Python 3.11+ to initialize the application and its dependency container:
+
+```python
+from ferrox_py.core.app import FerroxApp
+from ferrox_py.core.container import Container
+
+def main():
+    # Initialize the IoC container
+    container = Container()
+    
+    # Register your services and controllers here
+    # container.register("my_service", MyService)
+    
+    # Build and start the Ferrox application
+    app = FerroxApp(container)
+    app.start()
+
+if __name__ == "__main__":
+    main()
+```
+
+## 7. Ecosystem Integration
+The Core module is intentionally designed to act as a hub that can be seamlessly extended by specialized packages:
+- 🛠️ **ferrox-py-utils**: Integration for ETL tools, data pipelines, and connectors (e.g., S3, CSV).
+- 🔒 **ferrox-py-auth**: Integrates IAM, SSO, RBAC, and GDPR compliance features directly into the Auth Guards layer.
+- 💳 **ferrox-py-commerce**: Interfaces with Stripe/PayPal webhooks and enforces idempotency in the Transaction State.

ferrox_py-1.0.0/README.md

@@ -0,0 +1,68 @@
+# ⚡ Ferrox-Py (Core Framework)
+
+<p align="center">
+  <b>A Python 3.11+ Framework for Enterprise Server-Side Development</b><br/>
+  <i>Inspired by the robustness of Rust-Ferrox, bringing Inversion of Control, Modularity, and Onion Architecture to the Python ecosystem.</i>
+</p>
+
+---
+
+## 1. Overview (What does this do?)
+`ferrox-py` is the core foundation of the Ferrox ecosystem for Python. It provides an Inversion of Control (IoC) container, a Dependency Injection (DI) system, and the fundamental structure required to develop robust, scalable, and decoupled backend applications in Python. It goes beyond being just a web framework; it serves as a complete application lifecycle manager that simultaneously supports REST APIs, GraphQL, background jobs, and event queues.
+
+## 2. Philosophy (Why does it exist?)
+Modern backend development in Python is often plagued by monolithic scripts or overly permissive frameworks, causing architectural decisions to fragment over time. Ferrox-Py was created to mitigate the technical debt inherent in complex projects by enforcing:
+- **Strict Decoupling** between domain logic (Business Layer) and the transport protocol (HTTP, gRPC, Queues).
+- **Secure State Management** through centralized IoC containers.
+- **Rigorous Validation** upon entry (leveraging Pydantic).
+- **Mitigation of Abuse** by strictly separating side effects and enforcing robust architectural boundaries.
+
+## 3. Target Audience (Who is it for?)
+This framework is specifically designed for **Data Platforms**, **Enterprise SaaS**, and **Microservices Architectures** where security, code predictability, and long-term maintainability are absolutely critical. If you need a system that seamlessly scales alongside your team without degrading into a convoluted "spaghetti code" architecture, Ferrox-Py is the ideal choice.
+
+## 4. Architecture (How does it work?)
+Ferrox-Py faithfully adopts the **7-Layer Onion Request Pipeline** from the original Ferrox ecosystem:
+1. **Security & Headers**: Initial interception and sanitization of incoming requests.
+2. **Active Defense & Rate Limiting**: Preemptive protection against system abuse.
+3. **Auth Guards**: Extraction and strict validation of authentication tokens (JWT/PASETO).
+4. **RBAC & ZK Proofs**: Rigorous Role-Based Access Control and zero-knowledge mechanisms.
+5. **Validation Pipe**: Formal checking of the DTO (Data Transfer Object) payload.
+6. **Controller Layer**: Translation of the transport protocol into the specific domain language.
+7. **Business Service / CQRS**: Execution of domain logic, state mutations, and persistence.
+
+## 5. Installation / Setup
+To run `ferrox-py`, ensure you have an environment with **Python 3.11+**. No prior configuration is required, but it is highly recommended to use a virtual environment.
+
+```bash
+# Example local installation (development mode)
+pip install -e .
+```
+The project also exposes the `ferrox` CLI for utilities and basic administrative tasks.
+
+## 6. Quickstart (Usage)
+Below is a minimal setup using Python 3.11+ to initialize the application and its dependency container:
+
+```python
+from ferrox_py.core.app import FerroxApp
+from ferrox_py.core.container import Container
+
+def main():
+    # Initialize the IoC container
+    container = Container()
+    
+    # Register your services and controllers here
+    # container.register("my_service", MyService)
+    
+    # Build and start the Ferrox application
+    app = FerroxApp(container)
+    app.start()
+
+if __name__ == "__main__":
+    main()
+```
+
+## 7. Ecosystem Integration
+The Core module is intentionally designed to act as a hub that can be seamlessly extended by specialized packages:
+- 🛠️ **ferrox-py-utils**: Integration for ETL tools, data pipelines, and connectors (e.g., S3, CSV).
+- 🔒 **ferrox-py-auth**: Integrates IAM, SSO, RBAC, and GDPR compliance features directly into the Auth Guards layer.
+- 💳 **ferrox-py-commerce**: Interfaces with Stripe/PayPal webhooks and enforces idempotency in the Transaction State.

ferrox_py-1.0.0/docs/abstractions/pipes-interceptors.md

@@ -0,0 +1,38 @@
+# Pipes and Interceptors
+
+## 1. Overview (What does this do?)
+Pipes and Interceptors provide an abstraction layer for handling cross-cutting concerns during the request lifecycle. Specifically, Pipes are primarily used for formal payload validation (checking if the incoming DTO is well-formed), whereas Interceptors are used for Aspect-Oriented Programming (AOP) flows, such as measuring execution time, transforming responses, or handling localized exceptions.
+
+## 2. Philosophy (Why does it exist?)
+The philosophy behind this abstraction is separating business logic from validation and request/response manipulation. By injecting Pipes before the Controller layer, developers are guaranteed that their domain services will only ever receive valid, strongly-typed data. This reduces boilerplate validation code inside endpoints, leading to cleaner, more maintainable code. 
+
+## 3. Target Audience (Who is it for?)
+This component is designed for developers who are constructing APIs and need a robust, reusable way to sanitize inputs and manipulate responses uniformly across multiple endpoints without polluting the controller layer.
+
+## 4. Architecture (How does it work?)
+In the Ferrox-Py 7-Layer Onion Pipeline, Pipes sit at Layer 5 (Validation Pipe), immediately before the Controller. They intercept the incoming raw JSON/dictionary and parse it through a Pydantic schema. If validation fails, they automatically halt the pipeline and return a standardized 400 Bad Request error. Interceptors wrap the Controller execution, allowing code to run both immediately before the handler and right after it successfully returns data.
+
+## 5. Installation / Setup
+No separate installation is required. Pipes and Interceptors are available natively in the `ferrox_py.core` package, leveraging `pydantic` for schema definitions under the hood. Make sure your environment has Pydantic correctly installed.
+
+## 6. Quickstart (Usage)
+Applying a validation pipe to a specific controller route is straightforward:
+
+```python
+from ferrox_py.core.pipes import ValidationPipe
+from pydantic import BaseModel
+
+class CreateUserModel(BaseModel):
+    email: str
+    password: str
+
+# In your controller setup:
+# The pipe ensures `data` is a valid CreateUserModel before `create_user` runs.
+@post("/users")
+@use_pipe(ValidationPipe(CreateUserModel))
+def create_user(data: CreateUserModel):
+    return {"status": "success", "user": data.email}
+```
+
+## 7. Ecosystem Integration
+Pipes integrate seamlessly with the CQRS component (Command Query Responsibility Segregation). When dispatching a Command to the CQRS bus, a Validation Pipe can ensure that the command object is structurally valid before it ever reaches the Command Handler layer.

ferrox_py-1.0.0/docs/architectures/task-scheduling.md

@@ -0,0 +1,37 @@
+# Task Scheduling
+
+## 1. Overview (What does this do?)
+The Task Scheduling architecture in Ferrox-Py provides a built-in mechanism for running background jobs, recurrent tasks, and deferred asynchronous operations outside of the main HTTP request-response cycle. It allows developers to define cron-like schedules or simple fire-and-forget background workers securely within the Inversion of Control (IoC) context.
+
+## 2. Philosophy (Why does it exist?)
+Modern web applications frequently need to perform long-running tasks—such as sending batch emails, generating reports, or cleaning up stale database records. Blocking an HTTP thread to perform these operations leads to poor UX and timeouts. The Task Scheduling module exists to offload this work cleanly without requiring developers to immediately configure external dependencies like Celery or Redis for simple scheduling needs.
+
+## 3. Target Audience (Who is it for?)
+This module is intended for backend engineers who need to execute periodic maintenance tasks or offload heavy I/O operations from their API endpoints securely, maintaining access to the application's configured IoC container and database connections.
+
+## 4. Architecture (How does it work?)
+The task scheduler runs as a background asyncio loop, spawned alongside the main web server by `FerroxApp`. Tasks registered via the `@cron` or `@background` decorators are collected at startup. When a scheduled time is reached, the scheduler spawns a managed task, automatically injecting any required dependencies (like a Database connection or Logger) from the central IoC Container before executing the business logic.
+
+## 5. Installation / Setup
+Task scheduling is built directly into the core `ferrox-py` package. No additional message brokers (like RabbitMQ) are necessary for the default memory-based scheduler. For distributed task locking across multiple server nodes, an optional Redis integration can be configured.
+
+## 6. Quickstart (Usage)
+You can easily register a recurrent job using the `@cron` decorator. The scheduler will parse standard cron expressions.
+
+```python
+from ferrox_py.core.scheduling import cron
+from ferrox_py.core.container import Container
+
+class CleanupService:
+    @cron("*/5 * * * *")  # Runs every 5 minutes
+    async def remove_stale_sessions(self):
+        print("Cleaning up stale database sessions...")
+        # Dependency injection works here automatically if the class is resolved via IoC
+
+# Register the service in the container so the scheduler can find it
+container = Container()
+container.register("cleanup_service", CleanupService)
+```
+
+## 7. Ecosystem Integration
+The Task Scheduling module interacts heavily with the Observability components. Every background task execution generates trace IDs and metrics, which are logged automatically. If a background job fails, it integrates with the centralized error handler to send alerts (e.g., triggering a webhook to a Slack channel) without bringing down the main API server.

ferrox_py-1.0.0/docs/components/core.md

@@ -0,0 +1,46 @@
+# Core Component (Inversion of Control)
+
+## 1. Overview (What does this do?)
+The Core component is the absolute backbone of the `ferrox-py` framework. It manages the entire lifecycle of the application, utilizing a robust Inversion of Control (IoC) container to instantiate, wire, and manage all services, databases, and dependencies.
+
+## 2. Philosophy (Why does it exist?)
+Unlike lightweight web frameworks (such as raw FastAPI or Flask) where application state is often passed around as global variables, singletons, or function parameters, `ferrox-py` strictly enforces the use of an IoC container. This philosophy prevents spaghetti code, makes unit testing incredibly simple (by easily mocking injected dependencies), and ensures that the lifecycle of complex objects (like Database connection pools) is predictably managed by the framework, not the developer.
+
+## 3. Target Audience (Who is it for?)
+This core module is meant for backend developers who need a highly structured, predictable way to organize their business logic. It appeals heavily to developers coming from enterprise backgrounds (like Java Spring or TypeScript's NestJS) who miss structured Dependency Injection in the Python ecosystem.
+
+## 4. Architecture (How does it work?)
+The Architecture relies on the `ferrox_py.core.container.Container` class, which acts as a thread-safe registry. 
+Dependencies are registered either by string name or directly by class type. Currently, the IoC prioritizes **Singleton** resolution. To minimize boot time overhead, dependencies are **Lazy Loaded**—they are only instantiated the very first time they are resolved. The `FerroxApp` class accepts this container and handles Lifecycle Hooks (Start, Stop, Crash), initializes the 7-Layer Request Pipeline, and binds transports (HTTP, WebSockets).
+
+## 5. Installation / Setup
+The Core IoC module is included by default when you install the `ferrox-py` base package. No additional libraries are required for the fundamental Dependency Injection to function.
+
+## 6. Quickstart (Usage)
+```python
+from ferrox_py.core.container import Container
+
+class Database:
+    def execute(self):
+        return "Query Executed"
+
+class UserService:
+    # Dependencies are explicitly required in the constructor
+    def __init__(self, db: Database):
+        self.db = db
+
+# 1. Initialization
+container = Container()
+container.register("db", Database())
+
+# 2. Dependency resolution and wiring
+# The container provides the 'db' instance to UserService
+container.register("user_service", UserService(db=container.resolve("db")))
+
+# 3. Usage
+service = container.resolve("user_service")
+print(service.db.execute())
+```
+
+## 7. Ecosystem Integration
+The Core module integrates with the concept of **Providers and Modules** (inspired by NestJS). Specific features are encapsulated inside Modules (e.g., `AuthModule`), which define an array of Providers (classes) that are automatically registered into the Container. This ensures seamless integration with every other component in the `ferrox-py` ecosystem, decoupling domain logic from infrastructure.

ferrox_py-1.0.0/docs/components/cqrs.md

@@ -0,0 +1,47 @@
+# CQRS, Events, and Sagas Component
+
+## 1. Overview (What does this do?)
+The CQRS (Command Query Responsibility Segregation) component provides integrated patterns for separating read operations (Queries) from write operations (Commands). It also provides an Event Dispatcher for Event-Driven Architectures and supports Sagas for managing distributed transactions across multiple microservices or database boundaries.
+
+## 2. Philosophy (Why does it exist?)
+In complex Enterprise architectures and microservices, having Controllers directly call Repositories to mutate state leads to tightly coupled, hard-to-maintain code. By forcing mutations through a Command Bus and reads through a Query Bus, `ferrox-py` enforces a clear separation of concerns. This allows read paths to be optimized (e.g., using caching or read replicas) entirely independently of the write paths, and enables reactive event-driven flows.
+
+## 3. Target Audience (Who is it for?)
+This component is designed for advanced architects and developers building complex, highly scalable systems. It is specifically aimed at those implementing Domain-Driven Design (DDD) and those who need to orchestrate complex business transactions that span multiple services without relying on distributed two-phase commits.
+
+## 4. Architecture (How does it work?)
+- **Command/Query Bus**: Resolves incoming Commands/Queries to their registered Handlers.
+- **Event Dispatcher**: An in-memory Pub/Sub bus where Publishers emit Events (e.g., `PaymentCompleted`) and Subscribers asynchronously react to them. It is designed to be easily extensible to external message brokers like Redis Pub/Sub or RabbitMQ.
+- **Sagas**: A state machine engine that executes a sequence of local transactions. If one step fails, the Saga orchestrator automatically triggers compensating actions (rollbacks) for all previously successful steps.
+
+## 5. Installation / Setup
+The in-memory CQRS and Event buses are included natively in `ferrox-py`. For distributed messaging (e.g., RabbitMQ or Redis), additional specific driver packages must be installed and configured within the IoC Container.
+
+## 6. Quickstart (Usage)
+```python
+from ferrox_py.cqrs.bus import CommandBus
+
+# 1. Define the Command
+class CreateOrderCommand:
+    def __init__(self, item_id: str):
+        self.item_id = item_id
+
+# 2. Define the Handler logic (mocked)
+class OrderService:
+    def create_order(self, cmd: CreateOrderCommand):
+        print(f"Order created for item {cmd.item_id}")
+        return True
+
+# 3. Registration and Dispatch
+bus = CommandBus()
+order_service = OrderService()
+
+# Register the handler that knows how to process the Command
+bus.register_handler(CreateOrderCommand, order_service.create_order)
+
+# The API Controller simply dispatches the command
+result = bus.dispatch(CreateOrderCommand(item_id="12345"))
+```
+
+## 7. Ecosystem Integration
+CQRS integrates heavily with the **Data Component** (for actual persistence executed by the Handlers) and the **Pipes/Interceptors**. Specifically, a Validation Pipe is often attached to the Command Bus to ensure that every Command object is structurally valid before it ever reaches the Business Service layer.

ferrox_py-1.0.0/docs/components/data.md

@@ -0,0 +1,50 @@
+# Data Component
+
+## 1. Overview (What does this do?)
+The `ferrox-py.databases` module abstracts connections to both relational and non-relational databases. It provides robust connection pooling, session management, schema migrations, and base classes for implementing the Repository pattern cleanly across different storage engines.
+
+## 2. Philosophy (Why does it exist?)
+Database interactions are often the biggest bottleneck and source of technical debt in web applications. This component exists to provide a uniform, asynchronous, and safe way to interact with databases without scattering raw SQL or driver-specific code throughout the business logic. It enforces the Repository pattern, ensuring that the domain layer remains entirely agnostic to the underlying storage mechanism.
+
+## 3. Target Audience (Who is it for?)
+This component is for backend developers who need reliable, scalable database connectivity. Whether you are using SQL for structured relational data, MongoDB for flexible documents, or Redis for high-speed caching and locking, this module provides the necessary enterprise-grade abstractions.
+
+## 4. Architecture (How does it work?)
+- **SQL (SQLAlchemy)**: Native integration with asynchronous SQLAlchemy V2. It provides a Singleton Async Engine, transparent session lifecycle management (often tied to the request lifecycle), and an abstract `BaseRepository` with standard CRUD methods.
+- **NoSQL (MongoDB)**: An optimized wrapper over `motor` (asynchronous PyMongo). It supports native serialization and deserialization between Pydantic models and BSON, along with async queries.
+- **Caching & Idempotency (Redis)**: Integrated wrapper for distributed locks (Singleflight), rate limiting, caching, and state machines.
+- **Migrations**: Unified migration management integrating Alembic behind the scenes, allowing programmatic schema upgrades during the `FerroxApp` boot sequence.
+
+## 5. Installation / Setup
+While the abstractions are native, you must install the underlying asynchronous drivers for the databases you intend to use.
+
+```bash
+# For PostgreSQL and SQLAlchemy
+pip install asyncpg sqlalchemy alembic
+
+# For MongoDB
+pip install motor
+
+# For Redis
+pip install redis
+```
+
+## 6. Quickstart (Usage)
+```python
+from ferrox_py.databases.sql.repository import BaseRepository
+
+# 1. Define your specific repository inheriting from the Base
+class SqlUserRepository(BaseRepository):
+    # Base CRUD methods (find_by_id, create, update, delete) are automatically inherited
+    
+    # Implement custom data access methods
+    async def find_by_email(self, email: str):
+        # Implementation using the injected async session
+        pass
+
+# 2. Register it in the IoC Container
+# container.register("user_repo", SqlUserRepository(session=...))
+```
+
+## 7. Ecosystem Integration
+The Data Component is universally utilized. It provides the foundation for the **AuthModule** (storing users and RBAC roles), the **Commerce** ecosystem (maintaining strict idempotency using Redis and transactional SQL for orders), and integrates with the **Core IoC** for injecting valid database sessions into the CQRS Command Handlers.

ferrox_py-1.0.0/docs/components/observability.md

@@ -0,0 +1,43 @@
+# Observability Component
+
+## 1. Overview (What does this do?)
+The Observability component provides built-in mechanisms for logging, tracing, and monitoring the health of a `ferrox-py` application. It centralizes output streams, ensuring that all log messages generated within a single request lifecycle are tied together via a unique Correlation ID.
+
+## 2. Philosophy (Why does it exist?)
+In asynchronous Python applications, traditional logging mechanisms often fail to track a single request accurately because multiple concurrent requests interleave their logs. The philosophy here is that developers shouldn't have to manually pass a logger object to every function. By leveraging `ContextVars`, the framework ensures that logs are asynchronous-safe and natively structured.
+
+## 3. Target Audience (Who is it for?)
+This component is vital for DevOps engineers, Site Reliability Engineers (SREs), and backend developers who need to debug complex asynchronous flows in production using modern log aggregators like Datadog, ELK, or Grafana Loki.
+
+## 4. Architecture (How does it work?)
+- **Structured Logging (Structlog)**: Instead of plain text strings, logs are emitted as structured JSON objects, making them infinitely easier to index and search.
+- **Correlation IDs**: At Layer 1 (Security Header Enforcer Middleware), a unique `X-Request-ID` is either parsed from the incoming request or generated. This ID is injected into a ContextVar. Every subsequent log emitted during that request's lifecycle automatically includes this Correlation ID.
+- **Metrics**: The observability module hooks into the application lifecycle to expose standard Prometheus-compatible metrics (like HTTP response times and error rates) if configured.
+
+## 5. Installation / Setup
+The core logging functionality is built-in, but it heavily leverages the `structlog` library.
+
+```bash
+pip install structlog
+```
+Configuration is automatically handled during the `FerroxApp` initialization, but can be customized by passing a configuration dictionary to the IoC Container.
+
+## 6. Quickstart (Usage)
+```python
+from ferrox_py.core.observability import get_logger
+
+# The logger is a singleton configured by the container, 
+# but it automatically pulls context from the current asyncio task.
+logger = get_logger("my_domain_service")
+
+async def process_payment(amount: float):
+    # This log will automatically include the 'request_id' 
+    # without you passing it manually!
+    logger.info("Processing payment", amount=amount, currency="USD")
+    
+    if amount < 0:
+        logger.error("Invalid amount detected", error_code="NEG_AMT")
+```
+
+## 7. Ecosystem Integration
+The Observability component acts as a cross-cutting concern. It integrates deeply with the **Web Transports** (to automatically log incoming requests and response codes) and the **CQRS Bus** (to trace when events are published or consumed). It is strictly considered an anti-pattern to use the standard Python `logging` module directly without going through this component, as you will lose context variables and correlation tracking.

ferrox_py-1.0.0/docs/components/security.md

@@ -0,0 +1,46 @@
+# Security Component
+
+## 1. Overview (What does this do?)
+The Security module implements layered defense for `ferrox-py` applications. It provides native, out-of-the-box protection against common attack vectors (like DDoS or brute force), enforces cryptographic token validation, and manages secure, distributed state locks.
+
+## 2. Philosophy (Why does it exist?)
+Security cannot be an afterthought in enterprise software. Instead of relying on developers to remember to add rate limiting or sanitize headers on every route, `ferrox-py` enforces these protections at the pipeline level. Furthermore, it advocates for modern cryptographic standards (like PASETO) to avoid the historical vulnerabilities associated with standard JWT implementations.
+
+## 3. Target Audience (Who is it for?)
+This component is essential for security engineers, system architects, and developers building publicly exposed APIs, Financial Technology (FinTech) services, or applications handling Personally Identifiable Information (PII) that require rigorous compliance and threat mitigation.
+
+## 4. Architecture (How does it work?)
+- **Moving Target Defense (MTD) & Sanitization**: HTTP responses are sanitized (e.g., stripping `X-Powered-By`) and armed with strict HSTS and CSP headers by default.
+- **Distributed Rate Limiting**: Built on top of Redis using a sliding window token bucket algorithm to mitigate DDoS and brute-force attacks by limiting requests per IP or API Key.
+- **Advanced Auth (PASETO/JWT)**: The Auth Guards securely extract, verify, and decode Platform-Agnostic Security Tokens (PASETO) or standard JWTs before the request reaches the controller.
+- **Self-Auditing (WSTG Auditor)**: The `SecuritySelfTest` class allows the application to audit its own environment upon booting (e.g., checking file permissions, TLS configurations, and secret entropy).
+- **Distributed Locks**: Utilizes Redis (Redlock algorithm) to prevent race conditions in clustered environments.
+
+## 5. Installation / Setup
+Security abstractions are built-in, but to utilize distributed features like Rate Limiting and Redlock, a Redis server and the corresponding python driver are required. PASETO support requires external cryptographic libraries.
+
+```bash
+pip install redis pyseto
+```
+
+## 6. Quickstart (Usage)
+Generating and validating a secure PASETO token:
+
+```python
+from ferrox_py.security.paseto import PasetoTokenService
+from ferrox_py.security.distributed_locks import RedisLock
+
+# 1. Token Generation
+token_service = PasetoTokenService(secret_key=b"super-secret-key-must-be-32-bytes!")
+token = token_service.generate({"user_id": 1, "role": "admin"})
+
+# 2. Distributed Locking
+def recharge_wallet(redis_client, user_id: int):
+    # Prevents concurrent requests from race-conditioning the wallet balance
+    with RedisLock(redis_client, f"recharge_wallet_lock_{user_id}"):
+        # Safe critical section
+        pass
+```
+
+## 7. Ecosystem Integration
+The Security module is the absolute core of the **7-Layer Request Pipeline**, specifically managing Layers 1 (Security Headers), 2 (Rate Limiting), 3 (Sentinel Threat Engine), and 4 (Auth Guards). It relies on the **Data Component** (specifically the Redis wrappers) to maintain distributed state for rate limiters and locks.

ferrox_py-1.0.0/docs/components/web.md

@@ -0,0 +1,50 @@
+# Web & Transports Component
+
+## 1. Overview (What does this do?)
+The Web component in `ferrox-py` acts as an agnostic API Gateway and Transport Layer. It is responsible for parsing incoming network requests across multiple protocols, passing them through the strict 7-Layer Onion Pipeline, and routing them to the appropriate application Controllers.
+
+## 2. Philosophy (Why does it exist?)
+Many frameworks tightly couple their business logic to HTTP abstractions (like raw `request` objects). `ferrox-py`'s philosophy is to treat the transport layer as merely a delivery mechanism. Whether a command arrives via an HTTP REST call, a WebSocket message, or a GraphQL query, the underlying business logic remains completely isolated and agnostic to the network protocol.
+
+## 3. Target Audience (Who is it for?)
+This module is for developers building multi-protocol APIs. If your application needs to expose a traditional REST API for mobile clients, a GraphQL endpoint for internal frontends, and WebSockets for real-time notifications—all sharing the exact same business logic—this component manages that complexity safely.
+
+## 4. Architecture (How does it work?)
+- **Multi-Transport Architecture**: The application can run multiple servers (transports) simultaneously within the same asyncio event loop.
+- **REST / API Gateway**: While agnostic, it strongly integrates with FastAPI as the default HTTP engine to leverage automatic OpenAPI schema generation and Pydantic type validation.
+- **WebSockets / SSE**: Specialized routers handle real-time streaming and Server-Sent Events.
+- **Decorators**: The component provides unified decorators (`@require_roles`, `@validate_schema`) that inject logic *before* the handler runs, regardless of the underlying transport.
+- **Custom Transports**: Developers can implement the `ferrox_py.transports.base` interface to add entirely new triggers (e.g., raw TCP servers, message queue consumers, or file-system watchers).
+
+## 5. Installation / Setup
+To run the default HTTP REST gateway, FastAPI and an ASGI server (like Uvicorn) are required. GraphQL support requires additional libraries like Strawberry.
+
+```bash
+pip install fastapi uvicorn pydantic
+# Optional: pip install strawberry-graphql
+```
+
+## 6. Quickstart (Usage)
+Defining a controller and applying decorators:
+
+```python
+from ferrox_py.web.decorators import require_roles, validate_schema
+from pydantic import BaseModel
+
+class UserPayload(BaseModel):
+    name: str
+
+# These decorators hook into the Onion Pipeline automatically
+@require_roles("admin")
+@validate_schema(UserPayload)
+async def create_user_handler(payload: UserPayload):
+    # At this point, the user is an admin and the payload is guaranteed valid
+    return {"message": f"User {payload.name} created successfully."}
+
+# Custom utilities are also provided, e.g., parsing DataGrid queries:
+from ferrox_py.transports.datagrid import parse_ag_grid_query
+# query_opts = parse_ag_grid_query(request.url)
+```
+
+## 7. Ecosystem Integration
+The Web component is the entry point for external data and therefore integrates directly with the **Security** component (to evaluate headers and tokens), the **Pipes/Interceptors** (for validating schemas), and the **Observability** component (to extract and log Correlation IDs from incoming requests).