Core Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
FLEXT-LDIF is an enterprise-grade LDIF (LDAP Data Interchange Format) processing library designed with Clean Architecture and Domain-Driven Design (DDD) principles. It provides a robust framework for parsing, validating, transforming, and writing LDIF data while maintaining strict type safety and cross-server compatibility. The system is built to support complex enterprise workflows, including migrations between different LDAP implementations like Oracle Internet Directory (OID), Oracle Unified Directory (OUD), and OpenLDAP.
Sources: src/README.md:37-45, src/README.md:65-72
The architecture prioritizes separation of concerns, ensuring that business logic is isolated from technical infrastructure and user interfaces. This modular approach allows for high maintainability, extensive test coverage (targeting 90%+), and seamless integration with the broader FLEXT ecosystem.
Sources: src/README.md:47-63, src/README.md:83-88
Architectural Layers
FLEXT-LDIF is organized into four distinct architectural layers, following the Clean Architecture pattern. This structure ensures that the core business rules are independent of external tools and frameworks.
Sources: src/README.md:47-63
Layer Definitions
| Layer | Responsibility | Key Modules |
|---|---|---|
| Domain Layer | Pure business logic, entities, and value objects. | models.py, exceptions.py |
| Application Layer | Use case orchestration and main service API. | api.py |
| Infrastructure Layer | Technical implementations (parsing, settings, services). | core.py, settings.py, services.py, modernized_ldif.py |
| Interface Layer | External interfaces (CLI, public API exports). | cli.py, __init__.py |
| Sources: src/README.md:49-63 |
The following diagram illustrates the dependency flow between these layers, where dependencies point inward toward the Domain Layer.
The diagram shows the Clean Architecture dependency inversion where technical infrastructure and interfaces depend on the core domain models.
Sources: src/README.md:47-63, src/README.md:105-121
Server and Metadata Architecture
A critical component of the architecture is the server-specific processing logic, managed through a base server class and extensive metadata tracking. This allows the library to handle differences in LDAP implementations while preserving original data for round-trip operations.
Sources: src/flext_ldif/servers/_base/entry.py:22-35, src/flext_ldif/_models/domain_metadata.py:126-140
Base Entry Server
The FlextLdifServersBaseEntry class provides the foundation for all entry-related operations. It manages parsing, writing, and normalization hooks that can be overridden by specific server implementations (e.g., OID, OUD).
Sources: src/flext_ldif/servers/_base/entry.py:22-60
Metadata Management
The system uses a ServerMetadata container to store server-proprietary data, RFC violation logs, and conversion history. This ensures that during a migration from OID to OUD, for example, original attribute casing and boolean formats are tracked.
Sources: src/flext_ldif/_models/domain_metadata.py:126-170, src/flext_ldif/_utilities/metadata.py:539-556
The class diagram displays the relationship between the primary metadata container and its specialized components for data preservation.
Sources: src/flext_ldif/_models/domain_metadata.py:126-218
Data Processing Pipeline
The processing pipeline follows a "Railway Oriented Programming" pattern using a Result type (r) for error composition. This ensures early failure detection and clean error handling across complex transformation workflows.
Sources: src/flext_ldif/servers/_base/entry.py:86-100, examples/01_basic_usage.py:139-158
Typical Processing Flow
- Detection: Auto-detecting the effective server type (e.g., RFC, OID, AD) from LDIF content.
- Parsing: Transforming raw LDIF text into Domain
Entrymodels. - Validation: Checking entries against RFC 2849 rules and server-specific constraints.
- Transformation/Migration: Modifying entries based on target server requirements.
- Writing: Serializing models back to LDIF format with specific formatting options (line folding, attribute ordering).
Sources: examples/01_basic_usage.py:113-130, src/flext_ldif/servers/_base/entry.py:155-180
The sequence diagram illustrates the standard flow of data from ingestion through the API service to the final serialized output.
Sources: src/flext_ldif/servers/_base/entry.py:86-105, examples/01_basic_usage.py:139-158
Engineering Standards and Governance
The project adheres to "Universal Agent Law" and strict quality gates to maintain a high-integrity codebase.
Sources: AGENTS.md:144-180
- SSOT (Single Source of Truth): Config and settings are the sole authority for business rules.
- Zero-Debt Baseline: All failures found during tasks must be fixed at the root.
- Type Safety: MyPy strict mode is enforced, targeting 95%+ coverage.
- Testing: 90%+ target across all modules, utilizing unit, integration, and E2E tests.
Sources: AGENTS.md:146-155, src/README.md:83-88
Summary
The core architecture of FLEXT-LDIF provides a structured, multi-layered environment for managing LDAP data. By combining Clean Architecture with robust metadata tracking and a railway-oriented processing model, the library achieves enterprise-level reliability and flexibility. This design specifically addresses the complexities of multi-vendor LDAP environments, ensuring data integrity and RFC compliance throughout the lifecycle of LDIF processing.
Sources: src/README.md:37-63, src/flext_ldif/_models/domain_metadata.py:126-135