Architecture Overview

Relevant source files

The following files were used as context for generating this wiki page:

• src/README.md
• README.md
• AGENTS.md
• src/flext_api/init.py
• examples/01_basic_usage.py
• src/flext_api/history.json
• tests/README.md

The flext-api library is a high-performance REST API framework built on top of FastAPI, designed for enterprise-grade Python 3.13+ environments. It utilizes a layered "Clean Architecture" approach, emphasizing strict typing, modularity, and a "Fix-Forward-Only" engineering philosophy. The system provides a unified surface for HTTP client operations, request/response normalization, and Pydantic-driven validation.

Sources: README.md:10-12, src/README.md:1-5, AGENTS.md:1-5

Layered Organization

The project is structured into distinct layers to separate domain logic from infrastructure concerns. This allows for easier testing and maintenance.

Layer	Responsibility	Key Files/Directories
Public API	Facades and public exports for consumer usage.	src/flext_api/__init__.py, api.py
Infrastructure	External concerns, configuration, and FastAPI application logic.	src/flext_api/infrastructure/, app.py, main.py
Domain	Core business logic, entities, and value objects.	src/flext_api/domain/, entities.py, value_objects.py
Data/Support	Builders, storage utilities, and type definitions.	builder.py, storage.py, types.py

Sources: src/README.md:16-52

Core Components

• FlextApiClient (api.py): The primary service class that composes the HTTP client and provides the main interface for API interaction.
• Client (client.py): A plugin-based HTTP client implementation.
• App Factory (app.py): The FastAPI application setup logic.
• Storage (storage.py): Utility for in-memory or persisted state management.

Sources: src/README.md:28-40

Operation Flow

The library follows a "Railway Oriented Programming" (ROP) pattern for handling operations, primarily using the Result type to explicitly manage success and failure states without relying on uncontrolled exceptions.

The following diagram illustrates the typical request/response flow when using the FlextApi facade:

The diagram shows how u.Api.RequestUtils handles normalization before the FlextApi facade executes the operation and wraps the outcome in a p.Result.
Sources: examples/01_basic_usage.py:20-130, examples/README.md:40-50

Type System and Constants

The architecture relies heavily on strict, most-restrictive typing and centralized constant definitions to ensure consistency across the platform.

Domain Constants

Constants are organized into nested classes within FlextApiConstants (aliased as c). This includes HTTP methods, status codes, and protocol-specific values for WebSockets and SSE.

class FlextApiConstants(FlextConstants):
    class Api:
        class Method(StrEnum):
            GET = "GET"
            POST = "POST"
            # ...
        class Status(StrEnum):
            IDLE = "idle"
            SUCCESS = "success"
            # ...

Sources: src/flext_api/history.json:constants.py:35-150

Type Aliases

The t namespace (defined in typings.py) provides unified type definitions, including:

• WebHeaders: Mapping for HTTP headers.
• RouteData: Structure for route registration.
• RequestBody/ResponseBody: Union types for supported data formats.

Sources: src/flext_api/history.json:typings.py:35-80

Governance and Quality Gates

The development of the library is governed by the "Universal Agent Law," which mandates:

• Zero-Tolerance: Root cause fixes only; no "dead code" or "TODOs".
• Strict Typing: Use of the most restrictive types possible (avoiding Any).
• SSOT: One authoritative source per fact (e.g., constants, configurations).

Sources: AGENTS.md:15-120

Testing Strategy

The test suite is divided into four main categories to ensure broad coverage:

1. Unit Tests: Isolated tests with mocks (tests/unit/).
2. Integration Tests: Interaction with real external services (tests/integration/).
3. E2E Tests: Full workflow validation (tests/e2e/).
4. Benchmarks: Performance and memory usage profiling (tests/benchmarks/).

Sources: tests/README.md:15-50

Conclusion

The flext-api architecture provides a robust, type-safe foundation for building high-performance APIs. By enforcing clean separation of concerns and a forward-only development model, it ensures that the system remains maintainable and scalable while minimizing technical debt.

Sources: README.md:10-20, AGENTS.md:1-10