# landing-ai/landingai-python architecture

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

- Interactive diagram: https://gitdiagram.com/landing-ai/landingai-python
- Repository: https://github.com/landing-ai/landingai-python

## Overview

##### Main Components
- Core Library Modules:
– Data Management (in landingai/data_management): Handles datasets, labels, metadata, and media handling.
– Pipeline (in landingai/pipeline): Manages the flow of image frames (using framesets, image sources, and postprocessing functions).
– Predict Module (in landingai/predict): Contains submodules for cloud, edge, OCR, and other inference methods that send images to deployed models.
– Storage (in landingai/storage): Abstracts storage details and integrates with solutions like Snowflake.

- Image Acquisition:
– Modules like image_source_ops.py and the various examples show how different sources (webcam, image files, RTSP streams, etc.) are used to acquire images.

- Client/Example Applications:
– The examples directory includes full applications (e.g., “ocr”, “license-plate-ocr”, “object-tracking”) and notebooks that demonstrate various use cases.

- Infrastructure & CI/CD:
– Directories such as .github/workflows and _infra indicate configuration scripts for automated testing, documentation, and deployment (including Docker builds and Kubernetes deployment scripts).

##### Relationships and Interactions
- The client application (or example app) interacts with the image acquisition modules to obtain raw data (images/frames).
- The acquired images pass to the Pipeline components, where initial processing (resizing, conversion, etc.) occurs.
- The processed images are then forwarded to the Predict module. This module interacts with external LandingLens endpoints (using an API key and endpoint ID) to run inference.
- Results from inference may undergo postprocessing: for example, overlaying predictions on images and further transformation via the postprocessing and visualization modules.
- Data Management and Storage components handle dataset registrations, media management, and even integration with external storage (e.g., Snowflake) for logging or caching.
- Telemetry and utility modules support monitoring, logging, and diagnostic functions throughout the flow.
- CI/CD pipelines, tests, and docs guarantee that the various components work cohesively and are well-integrated.

##### Architectural Patterns and Design Principles
- Modular and Layered Architecture: Each directory/module addresses a specific concern (e.g., separate modules for pipeline, prediction, storage, etc.), making the system loosely coupled.
- Extensibility: The examples, notebooks, and clear separation (e.g., between image acquisition and inference) indicate that the design allows for easy swapping or extension of components.
- Integration Emphasis: The library design encapsulates interactions with an external service (LandingLens) via well‑defined API interfaces within the Predict module.
- Reliability and Testing: The presence of both unit and integration tests suggests a design that encourages testability and resiliency.

##### Core Technologies, Frameworks, and Tools
- Python as the language and the standard packaging (pyproject.toml, poetry, etc.).
- Integration with cloud services via REST APIs (for model inference).
- Docker and Kubernetes (as seen in the _infra/deploy directory) for containerized deployments of demo applications.
- CI/CD pipelines using GitHub Actions.
- Documentation tools like MkDocs (mkdocs.yml) and PDoc for generating developer and user guides.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Example Applications
    CEA["Client/Example Applications"]:::internal

    %% Image Acquisition
    IA["Image Acquisition"]:::internal

    %% Core Library Modules
    subgraph "Core Library Modules"
        DM["Data Management"]:::internal
        PL["Pipeline"]:::internal
        PM["Predict Module"]:::internal
        ST["Storage"]:::internal
        subgraph "Utility Modules"
            UT1["Telemetry"]:::internal
            UT2["Timer"]:::internal
            UT3["Transform"]:::internal
            UT4["Visualize"]:::internal
            UT5["Notebook Utils"]:::internal
            UT6["Exceptions"]:::internal
            UT7["ST Utils"]:::internal
        end
    end

    %% External Integration
    External["LandingLens API"]:::external

    %% Infrastructure & CI/CD
    subgraph "Infrastructure & CI/CD"
        GH["GitHub Workflows"]:::ci
        DI["Deploy Infra"]:::ci
    end

    %% Data flow arrows
    CEA -->|"initiates"| IA
    IA -->|"provides images"| PL
    PL -->|"forward frames"| PM
    PM -->|"inference"| External
    PL -->|"register-data"| DM
    PL -->|"cache-media"| ST
    PL -->|"visualize"| UT4

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef external fill:#FDEBD0,stroke:#F39C12,stroke-width:2px;
    classDef ci fill:#d5f5e3,stroke:#27AE60,stroke-width:2px;

    %% Click Events
    click CEA "https://github.com/landing-ai/landingai-python/tree/main/examples/apps"
    click IA "https://github.com/landing-ai/landingai-python/blob/main/landingai/image_source_ops.py"
    click DM "https://github.com/landing-ai/landingai-python/tree/main/landingai/data_management"
    click PL "https://github.com/landing-ai/landingai-python/tree/main/landingai/pipeline"
    click PM "https://github.com/landing-ai/landingai-python/tree/main/landingai/predict"
    click ST "https://github.com/landing-ai/landingai-python/tree/main/landingai/storage"
    click UT1 "https://github.com/landing-ai/landingai-python/blob/main/landingai/telemetry.py"
    click UT2 "https://github.com/landing-ai/landingai-python/blob/main/landingai/timer.py"
    click UT3 "https://github.com/landing-ai/landingai-python/blob/main/landingai/transform.py"
    click UT4 "https://github.com/landing-ai/landingai-python/blob/main/landingai/visualize.py"
    click UT5 "https://github.com/landing-ai/landingai-python/blob/main/landingai/notebook_utils.py"
    click UT6 "https://github.com/landing-ai/landingai-python/blob/main/landingai/exceptions.py"
    click UT7 "https://github.com/landing-ai/landingai-python/blob/main/landingai/st_utils.py"
    click GH "https://github.com/landing-ai/landingai-python/tree/main/.github/workflows"
    click DI "https://github.com/landing-ai/landingai-python/tree/main/_infra/deploy"
```
