# fhpythonutils/pylottie architecture

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

- Interactive diagram: https://gitdiagram.com/fhpythonutils/pylottie
- Repository: https://github.com/fhpythonutils/pylottie

## Overview

##### Main Components
- Library Core – The conversion logic. Look at the “pylottie” directory where the __init__.py and lottie.html reside. This is the heart of the conversion functionality.
- External Dependencies – The project uses Playwright as noted in the README to drive the conversion and references Pillow for image processing. Create nodes for these external services.
- Test Suite – The “tests” directory contains unit and integration tests (e.g., test_main.py, simpletest.py). Represent testing as an independent component that validates system functionality.
- CI/CD & Build Automation – The presence of GitHub workflows (.github/workflows) and build-related scripts (pyproject.toml, fhmake instructions in the README) indicates an automated pipeline for testing, building, and documentation generation.
- Documentation – The “documentation” directory and “readme-assets” indicate that there is a structured reference and assets for understanding the API and usage.
- Packaging & Dependency Management – files like requirements.txt and pyproject.toml signal that dependency management and packaging (possibly using Poetry) play an important role.

##### Relationships and Data Flow
- Internal Processing – Show interactions between the core library functions and external libraries (Playwright, Pillow, etc.). The conversion functions call on these dependencies to perform file format transformations.
- Testing – Represent the tests directory as “Quality Assurance” which interacts with the core library to verify outputs.
- Build & Deployment – Illustrate the CI/CD pipelines (GitHub workflows) that automatically run tests, lint, package the library, and even mirror to Codeberg.
- Documentation – Connect the library components to the documentation files to indicate how API reference material is generated and maintained through tools like “handsdown”.

##### Architectural Patterns and Design Principles
- Modularity – The clear separation between core library functions, tests, and documentation indicates a modular design. Each layer (conversion logic, tests, CI/CD) has its own independent responsibility.
- Reusability – With well-defined functions and testing frameworks, the project is built for reuse in various environments (as indicated by the support for multiple OS architectures).
- Build Automation – Emphasize the importance of the build pipeline (driven by GitHub workflows and fhmake) as a backbone for continuous integration and deployment.

##### Final Advice
As many modules as you see fit without oversimplifying. Since the project is relatively small and modular, it is best to break it into the core components (main conversion engine, testing, CI/CD, documentation, build/deployment). Ensure that the principal components and their interactions are clearly highlighted to provide a complete high-level view of the entire system.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Input Layer
    subgraph "Input"
        I["User Input (.tgs/.lottie files)"]:::input
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        subgraph "Library Core"
            LC1["__init__.py"]:::library
            LC2["lottie.html"]:::library
        end
        CF["Conversion Functions Module"]:::module
    end

    %% External Dependencies Layer
    subgraph "External Dependencies"
        PW["Playwright\n(Render animations)"]:::external
        PL["Pillow\n(Image processing)"]:::external
    end

    %% Quality Assurance Layer
    subgraph "Quality Assurance"
        QA["Test Suite"]:::testing
    end

    %% Build & Deployment Layer
    subgraph "Build & Deployment"
        CICD["CI/CD & Build Automation"]:::cicd
        PKG["Packaging & Dependency Management"]:::packaging
    end

    %% Documentation Layer
    subgraph "Documentation"
        DOC["Documentation & Assets"]:::documentation
    end

    %% Connections
    I -->|"providesInput"| LC1
    I -->|"providesInput"| LC2
    LC1 -->|"invokes"| CF
    LC2 -->|"supports"| CF
    CF -->|"callsRender"| PW
    CF -->|"callsImageProc"| PL
    CF -->|"validatedBy"| QA
    QA -->|"feedbackTo"| CICD
    CICD -->|"triggersBuilds"| PKG
    LC1 -->|"documentedIn"| DOC
    LC2 -->|"documentedIn"| DOC
    CF -->|"documentedIn"| DOC

    %% Click Events
    click LC1 "https://github.com/fhpythonutils/pylottie/blob/master/pylottie/__init__.py"
    click LC2 "https://github.com/fhpythonutils/pylottie/blob/master/pylottie/lottie.html"
    click CF "https://github.com/fhpythonutils/pylottie/tree/master/pylottie"
    click QA "https://github.com/fhpythonutils/pylottie/tree/master/tests"
    click QA "https://github.com/fhpythonutils/pylottie/blob/master/tests/test_main.py"
    click QA "https://github.com/fhpythonutils/pylottie/blob/master/tests/simpletest.py"
    click CICD "https://github.com/fhpythonutils/pylottie/tree/master/.github/workflows"
    click CICD "https://github.com/fhpythonutils/pylottie/blob/master/pyproject.toml"
    click DOC "https://github.com/fhpythonutils/pylottie/tree/master/documentation"
    click DOC "https://github.com/fhpythonutils/pylottie/tree/master/readme-assets"
    click PKG "https://github.com/fhpythonutils/pylottie/blob/master/pyproject.toml"
    click PKG "https://github.com/fhpythonutils/pylottie/blob/master/requirements.txt"

    %% Styles
    classDef input fill:#f9c,stroke:#333,stroke-width:2px;
    classDef library fill:#bbf,stroke:#333,stroke-width:2px;
    classDef module fill:#ccf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
    classDef testing fill:#fcf,stroke:#333,stroke-width:2px;
    classDef cicd fill:#ff9,stroke:#333,stroke-width:2px;
    classDef packaging fill:#9ff,stroke:#333,stroke-width:2px;
    classDef documentation fill:#f99,stroke:#333,stroke-width:2px;
```
