Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT Auth is an enterprise-grade authentication and authorization service designed with a clean, refactored architecture. It provides robust identity management, session handling, and token validation capabilities. The system is built on Python 3.13+ and leverages strict typing and Pydantic 2 patterns to ensure security and reliability in enterprise environments.
The architecture follows a layered approach, separating domain constants, core logic, and infrastructure services. This design enables seamless integration with the broader FLEXT ecosystem while maintaining clear abstraction boundaries for authentication workflows.
Sources: README.md:8-10, examples/refactored_system_showcase_04.py:12-25, src/flext_auth/history.json:23-45
System Components
The FLEXT Auth system is composed of several specialized services coordinated through the primary FlextAuth facade. This structure ensures that specific responsibilities—such as token generation or session management—are isolated within dedicated modules.
Core Service Architecture
The high-level relationship between the main facade and its internal services is illustrated below:
The diagram shows how the FlextAuth class acts as the central entry point, delegating operations to specialized identity, session, and token services.
Sources: examples/comprehensive_demo_03.py:38-51, examples/refactored_system_showcase_04.py:30-35
Key Classes and Responsibilities
| Component | Responsibility | Relevant Methods |
|---|---|---|
FlextAuth | Primary API facade for consumers. | register_user, authenticate_user, quick_start |
IdentityService | Manages user data and persistent identities. | get_user_by_username, get_user |
SessionService | Handles active session lifecycles and lookups. | get_active_sessions, end_session_by_id |
TokenService | Manages JWT generation and validation. | validate_token, create_token |
FlextAuthSettings | Configuration and environment management. | N/A (ConfigDict based) |
Sources: examples/comprehensive_demo_03.py:40-105, examples/refactored_system_showcase_04.py:30-45, README.md:23-28
Domain Logic and Constants
FLEXT Auth utilizes a centralized constant registry (FlextAuthConstants) that extends the core FLEXT infrastructure. This registry uses StrEnum for type-safe enumerations, ensuring that all authentication methods, roles, and status codes are validated at the data model level.
Authentication Workflow
The following sequence diagram represents a typical user authentication flow:
This diagram illustrates the internal delegation from the FlextAuth facade to the underlying services to complete a secure login.
Sources: examples/comprehensive_demo_03.py:38-55, src/flext_auth/history.json:52-80
Security Constraints
The system enforces strict security boundaries through predefined constants:
- Token Security: Supports multiple algorithms including HS256, RS256, and ES256.
- Credential Limits: Minimum password length is 8 characters; maximum username length is 255.
- Lockout Policy: Implements account locking after 5 failed attempts for a duration of 30 minutes.
Sources: src/flext_auth/history.json:100-145, examples/comprehensive_demo_03.py:100-105
Data Models and Validation
The project uses Pydantic 2 for model definition and validation. Models are organized within the m.Auth namespace and handle the conversion of raw request data into typed identity objects.
Model Definitions
| Model | Description | Primary Fields |
|---|---|---|
AuthIdentityRequest | Used for user registration and identity creation. | name, contact, credential, roles |
AuthIdentity | Represents an authenticated user session. | name, token, session_id, roles |
UserStatus | Enum for account states. | ACTIVE, INACTIVE, LOCKED, PENDING |
Sources: examples/comprehensive_demo_03.py:65-72, src/flext_auth/history.json:150-180
Testing Architecture
FLEXT Auth employs a comprehensive testing pyramid to ensure 95% minimum coverage. The suite is divided into unit, integration, and end-to-end (E2E) tests, with a focus on fast execution and component isolation.
Testing Strategy
The diagram outlines the testing tiers and their corresponding execution speed targets.
Sources: tests/README.md:25-50, tests/unit/README.md:15-30
Coverage Gates
The project enforces strict quality gates:
- Minimum Coverage: 95% for all source code.
- Branch Coverage: 90% for conditional logic.
- Reliability: 0% flaky tests allowed in CI/CD pipelines.
Sources: tests/README.md:85-95, pyproject.toml:90-95
Conclusion
The architecture of FLEXT Auth is designed for scalability and security, utilizing a facade pattern to simplify complex authentication and authorization operations. By integrating strict typing, comprehensive validation through Pydantic 2, and a rigorous testing framework, it provides a stable foundation for enterprise identity management within the FLEXT platform.