# distilleryvfx/cdl_convert architecture

> Architecture diagram of the GitHub repository distilleryvfx/cdl_convert, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/distilleryvfx/cdl_convert
- Repository: https://github.com/distilleryvfx/cdl_convert

## Overview

##### File Structure
- Top-level files include configuration files (.gitignore, .travis.yml, setup.py, etc.) and documentation (docs directory) along with tests, which shows the project is well-organized following common best practices.
- The main program logic is contained within the “cdl_convert” directory. Notice the separation into several modules:
- __init__.py: Initializes the package.
- base.py: Likely contains base classes used across the module.
- cdl_convert.py: This is the main script functionality.
- config.py: Manages configuration values (e.g., global settings like HALT_ON_ERROR).
- decision.py: Defines decision-related classes (e.g., combining a correction and media reference).
- parse.py: Contains all the input parsing functions for different file formats.
- utils.py: Provides utility functions like sanity checks.
- write.py: Contains the export or writing functionality for various output formats.
- The tests directory includes unit tests for most of these components, which implies heavy reliance on modular design and separation of concerns.

##### Additional Insights from the README
- The README explains both the purpose and usage of the tool.
- It describes the different file formats handled, the available command-line options (e.g., flags like --check, --halt), and the role of each module (as detailed in the Python Structure Refactoring section).
- The documentation also clarifies that the project was originally a script that evolved into a modular Python package.

a. Main Components:
- Command-line Interface (CLI): Represented by the main script (cdl_convert.py at the project root level) which handles user input.
- Parser Module (parse.py): Reads and interprets the various CDL formats, converting them into an internal structure.
- Domain Model: Consisting of:
- Base Classes (base.py): Fundamental building blocks.
- Decision Components (decision.py): Represents decisions or references linking corrections.
- Writer Module (write.py): Converts the internal data structures back into the desired output file formats.
- Configuration (config.py): Centralized settings and flags guiding behavior (e.g., error handling).
- Utility Functions (utils.py): Contains miscellaneous support functions like sanity checks.
- Tests and Docs: Although not part of the runtime architecture, include tests (in the tests folder) and documentation (docs folder) as supporting elements during development and CI processes.

b. Relationships and Interactions:
- The CLI initiates the conversion process, reading in one or more input files.
- Input files are passed to the Parser, where functions in parse.py read data and create instances of the domain model (e.g., ColorCorrection, ColorCollection).
- The domain model objects flow into the Writer module, which then outputs file(s) in the specified format.
- Throughout, the configuration module sets runtime behavior (for error handling, destination directories, etc.) and utility functions assist in validation (sanity_check).

c. Architectural Patterns and Design Principles:
- Modular Separation: Each functionality (parsing, modeling, writing) has its own dedicated module.
- Separation of Concerns: The conversion process is divided into distinct phases (input parsing, internal processing, output writing).
- Command-Line Driven Execution: The main script orchestrates the overall process.
- Extensibility: The clear separation into parser, model, and writer components makes it easier to add support for additional formats in the future.

d. Technologies and Frameworks:
- Python is the core language, supporting diverse versions (Python 2.6 through 3.5, including PyPy).
- Testing is performed via standard Python libraries or frameworks as inferred by the tests directory.
- Continuous integration tools (Travis CI, Coveralls) and code quality services (landscape.io) are integrated, which might be indicated in an "infrastructure" block if desired.

##### Elements
- Clear, descriptive labels for each component (CLI, Parser, Domain Model, Writer, Config, and Utils).
– From CLI to Parser.
– From Parser to Domain Model (illustrate how input becomes internal data).
– From Domain Model to Writer.
– Rectangles for major modules.

Be sure as a principal software engineer to capture every essential detail:
- Layer and component with its associated responsibilities and interactions.
- How the modular design supports extensibility and testing.
- That both the conversion process and error-checking flows (e.g., use of --halt and sanity_check) are clearly depicted.

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["Command-line Interface (CLI)"]:::cli
    end

    %% Parsing Layer
    subgraph "Parsing Layer"
        Parser["Parser Module"]:::parser
    end

    %% Domain Model Layer
    subgraph "Domain Model"
        Base["Base Classes"]:::domain
        Correction["Color Correction Entities"]:::domain
        Collection["Collection"]:::domain
        Decision["Decision Components"]:::domain
    end

    %% Writing Layer
    subgraph "Writing Layer"
        Writer["Writer Module"]:::writer
    end

    %% Configuration & Utilities
    subgraph "Configuration & Utilities"
        Config["Configuration"]:::config
        Utils["Utility Functions"]:::utils
    end

    %% Supporting Elements
    subgraph "Supporting Elements"
        Tests["Supporting Tests"]:::support
        Docs["Documentation"]:::support
    end

    %% Main Flow
    CLI -->|"initiates"| Parser
    Parser -->|"creates"| Base
    Parser -->|"creates"| Correction
    Parser -->|"creates"| Collection
    Parser -->|"creates"| Decision

    Correction -->|"feeds"| Writer
    Collection -->|"feeds"| Writer
    Decision -->|"feeds"| Writer

    %% Configuration influence
    Config -->|"configures"| Parser
    Config -->|"configures"| Correction
    Config -->|"configures"| Collection
    Config -->|"configures"| Decision
    Config -->|"configures"| Writer

    %% Utility assistance (dashed lines)
    Utils -.->|"assists"| Parser
    Utils -.->|"assists"| Correction
    Utils -.->|"assists"| Writer

    %% Supporting elements connections (dashed lines)
    Tests -.->|"validates"| CLI
    Tests -.->|"validates"| Parser
    Tests -.->|"validates"| Writer

    Docs -.->|"documents"| CLI
    Docs -.->|"documents"| Parser
    Docs -.->|"documents"| Base
    Docs -.->|"documents"| Correction
    Docs -.->|"documents"| Collection
    Docs -.->|"documents"| Decision
    Docs -.->|"documents"| Writer
    Docs -.->|"documents"| Config
    Docs -.->|"documents"| Utils

    %% Styles
    classDef cli fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef parser fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef domain fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef writer fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef config fill:#a3e4d7,stroke:#333,stroke-width:2px;
    classDef utils fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef support fill:#d5dbdb,stroke:#333,stroke-width:2px,stroke-dasharray: 5, 5;

    %% Click Events
    click CLI "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert.py"
    click Parser "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert/parse.py"
    click Base "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert/base.py"
    click Correction "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert/correction.py"
    click Collection "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert/collection.py"
    click Decision "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert/decision.py"
    click Writer "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert/write.py"
    click Config "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert/config.py"
    click Utils "https://github.com/distilleryvfx/cdl_convert/blob/master/cdl_convert/utils.py"
    click Tests "https://github.com/distilleryvfx/cdl_convert/tree/master/tests"
    click Docs "https://github.com/distilleryvfx/cdl_convert/tree/master/docs"
```
