Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
flext-ldap is an enterprise-grade LDAP operations library designed for the FLEXT framework. It provides a high-level, type-safe abstraction over LDAP protocols, supporting diverse server types including OpenLDAP, Oracle Unified Directory (OUD), and Microsoft Active Directory. The architecture follows Clean Architecture and Domain-Driven Design (DDD) principles, utilizing structural typing and formal protocols to decouple domain logic from underlying infrastructure like the ldap3 library.
Sources: README.md:5-7, examples/README.md:15-20, pyproject.toml:31-38
Core Architectural Layers
The system is organized into distinct layers to ensure separation of concerns and maintainability. It uses a facade pattern where api.py (exposed as ldap) serves as the primary entry point for all operations.
Layer Hierarchy
| Layer | Responsibility | Key Components |
|---|---|---|
| Facade/API | Primary interface for consumers | api.py, ldap |
| Services | Business logic and orchestration | sync.py, authentication.py, search.py |
| Adapters | Infrastructure-specific implementations | adapters/, ldap3_adapter_helpers.py |
| Domain | Core interfaces and data models | protocols.py, _models/ldap.py |
Sources: examples/README.md:18-20, src/flext_ldap/protocols.py:34-42
Component Relationships
The following diagram illustrates the relationship between the public API, the internal service layer, and the structural adapters that interface with LDAP servers.
The architecture relies heavily on Structural Typing (Protocols) to break circular imports and allow services to depend on abstractions rather than concrete implementations. This is specifically seen in the LdapClient and LdapAdapter protocols.
Sources: src/flext_ldap/protocols.py:20-25, src/flext_ldap/protocols.py:126-140
Data Models and Configuration
Data integrity is maintained through Pydantic models that validate LDAP configurations and operation parameters. These models are namespaced within FlextLdapModelsLdap.
Key Connection Settings
The ConnectionConfig model defines the parameters required to establish and secure an LDAP session.
| Parameter | Type | Default | Description |
|---|---|---|---|
host | str | localhost | LDAP server hostname |
port | int | 389 | LDAP server port |
use_ssl | bool | False | Enable SSL (LDAPS) |
use_tls | bool | False | Enable StartTLS |
bind_dn | str | None | None | Bind DN for authentication |
timeout | int | 10 | Connection timeout in seconds |
Sources: src/flext_ldap/_models/ldap.py:20-40
Search and Operation Logic
Search operations are driven by the SearchOptions model, which supports base, one-level, and subtree scopes.
Adapter and Wrapper Pattern
The library implements a wrapper pattern to sanitize interaction with the ldap3 library. The FlextLdapLdap3Wrappers class provides static methods that normalize input/output for common LDAP operations like add, modify, and delete.
Operation Execution Flow
- Input Normalization: Converters transform domain objects (e.g.,
m.Ldif.Entry) into formats expected byldap3. - Execution: Wrappers execute the command on the
ldap3.Connection. - Result Parsing:
ResultConvertertransforms raw LDAP responses into immutable domain models likeOperationResult.
Sources: tests/unit/test_ldap3_adapter_helpers.py:265-285, src/flext_ldap/_models/ldap.py:220-235
Sync and Batch Operations
For enterprise workloads, the system provides advanced synchronization capabilities through the specification pattern.
- Phase Synchronization: Supports multi-phase sync (e.g., Users phase followed by Groups phase).
- Batch Statistics: Tracks successful, failed, and skipped entries via the
LdapBatchStatsmodel. - Progress Callbacks: Supports real-time monitoring of batch operations.
Sources: src/flext_ldap/_models/ldap.py:165-175, src/flext_ldap/_models/ldap.py:270-285, examples/README.md:210-220
Conclusion
The flext-ldap architecture provides a robust, protocol-first approach to LDAP integration. By abstracting the complexities of different server implementations and the underlying ldap3 library into a cohesive set of Pydantic models and structural protocols, it enables developers to perform complex directory operations with high type safety and minimal infrastructure coupling.