Protocols & Base Classes
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The flext-dbt-ldif project utilizes a structured hierarchy of protocols and base classes to manage the transformation of LDIF (LDAP Data Interchange Format) data into dbt (data build tool) models. This architecture relies on structural typing (Protocols) to define contracts for dbt execution, LDIF parsing, and validation, ensuring that different service implementations can be interchanged while maintaining strict type safety and architectural consistency.
The system follows the Dependency Inversion Principle (DIP), where high-level business logic depends on abstractions rather than concrete implementations. This is primarily facilitated through the FlextDbtLdifProtocols namespace and various service mixins that provide core functionality for model generation and data analytics.
Sources: src/flext_dbt_ldif/protocols.py:1-20, AGENTS.md:120-130
Protocol Definitions
Protocols in this module define the interface for interacting with dbt and LDIF data processing. The primary namespace FlextDbtLdifProtocols inherits from flext_meltano and flext_ldif protocols, creating a unified contract for the integration layer.
Dbt Protocol
The Dbt protocol defines the required methods for any service or client responsible for executing dbt models and tests.
| Method | Parameters | Return Type | Description |
|---|---|---|---|
run_dbt_models | models: t.StrSequence | None | p.Result[m.DbtLdif.DbtTransformationResult] | Executes the specified dbt models and returns a result payload. |
test_dbt_models | models: t.StrSequence | None | p.Result[m.DbtLdif.DbtTransformationResult] | Runs dbt tests for the specified models and returns status. |
Sources: src/flext_dbt_ldif/protocols.py:19-35
Protocol Hierarchy
The project uses a nested protocol structure to organize capabilities.
The diagram shows how FlextDbtLdifProtocols aggregates functionality from both base LDIF and Meltano integration layers.
Sources: src/flext_dbt_ldif/protocols.py:15-18, tests/protocols.py:17-25
Core Service Architecture
The business logic is organized into "Core" classes and "Service" mixins. This separation allows for modular composition of functionality such as model generation, analytics, and workflow orchestration.
Model Generator
The ModelGenerator is a core component responsible for defining the structure of dbt staging and analytics models based on LDIF source data.
- Initialization: Defaults to the current working directory but accepts a custom
project_dir. - Staging Generation: Produces a list of models typically prefixed with
stg_ldif_. - Analytics Generation: Produces downstream models like
analytics_ldif_insights.
Sources: tests/unit/test_core.py:19-50, tests/unit/test_dbt_models.py:34-70
Analytics Component
The Analytics class within FlextDbtLdifCore provides logic for evaluating LDIF data patterns. It calculates metrics such as total entry counts and unique Distinguished Names (DNs) to inform model generation.
Sources: tests/unit/test_core.py:53-83
Unified Service Implementation
The UnifiedService acts as a concrete implementation that combines settings, project configurations, and core logic. It provides a high-level API for model generation and execution.
The flow shows how the Unified Service utilizes internal core components to generate different layers of dbt models.
Sources: src/flext_dbt_ldif/services/unified_service.py:1-25, tests/unit/test_dbt_models.py:18-32
Service Workflow Execution
The workflow typically follows a sequence of parsing, validation, and model generation as demonstrated in the service mixin tests.
This diagram illustrates the internal delegation within the service layer to process raw LDIF into dbt-ready structures.
Sources: tests/unit/test_services.py:130-175, tests/unit/test_services_and_api.py:30-55
Code Structure Patterns
The implementation adheres to the following engineering principles:
- Single Source of Truth (SSOT): Configurations and identities are referenced from a single authority.
- Dependency Injection (DI): Collaborators are injected into services to avoid hard-wired construction.
- Strict Typing: Use of
runtime_checkableprotocols andTYPE_CHECKINGblocks to ensure robust static analysis.
Sources: AGENTS.md:100-115, src/flext_dbt_ldif/protocols.py:7-13
Summary
The "Protocols & Base Classes" in flext-dbt-ldif establish the foundational framework for dbt-driven LDAP transformations. By leveraging Python Protocols, the system maintains a decoupled architecture where core logic (like the ModelGenerator) and orchestration services (like the UnifiedService) interact through well-defined, type-safe interfaces. This structure supports the project's goal of transforming LDIF data into structured dbt environments with consistent validation and materialization strategies.