# ynput/ayon-python-api architecture

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

- Interactive diagram: https://gitdiagram.com/ynput/ayon-python-api
- Repository: https://github.com/ynput/ayon-python-api

## Overview

##### Project type and purpose
- This is an open-source Python client library (“ayon-python-api”) for communicating with an AYON connection server over REST and GraphQL.
- It provides both “raw” HTTP methods and higher-level entity-oriented operations (CRUD for entities, events, etc.).

##### File structure
- Top-level files:
- setup.py, pyproject.toml, LICENSE, README.md – packaging and metadata
- automated_api.py – glue for auto-generating API calls
- Core package “ayon_api/”:
- _api.py – low-level HTTP/GraphQL request logic (uses requests)
- server_api.py, constants.py, utils.py, exceptions.py – connection management, configuration, error handling
- graphql.py, graphql_queries.py – GraphQL client and query definitions
- operations.py – CRUD operations on AYON entities (folders, tasks, etc.)
- entity_hub.py – high-level façade that groups entity operations into domain objects
- typing.py, version.py – type stubs and version info
- docs/ – Sphinx documentation source, Makefiles, CI workflow for docs publishing
- .github/workflows – linting, publishing to PyPI, docs deployment
- tests/ – unit tests for each module, fixtures in tests/resources

##### README for additional insights
- Explains singleton vs. multiple‐connection model (ServerAPI vs. ServerAPIBase).
- References REST and GraphQL communications, environment variables (AYON_SERVER_URL, AYON_API_KEY).
- TODOs point toward splitting ServerAPI (currently monolithic ~4k LOC).

##### Components
a. Main components:
- Client Application (user’s Python code)
- AYON-Python-API Library
– Connection Manager (ServerAPIBase / singleton wrapper)
– HTTP Transport Layer (_api.py)
– REST Adapters & GraphQL Client (graphql.py + graphql_queries.py)
– CRUD Operations Module (operations.py)
– Entity Hub (entity_hub.py)
– Utilities/Config (constants.py, utils.py, exceptions.py, typing.py)
- AYON Server (external service exposing REST & GraphQL endpoints)
- CI/CD Pipeline (GitHub Actions for lint/docs/publish)
- Package Repository (PyPI)
b. Relationships & interactions:
– Developer code → imports → Connection Manager → Transport Layer
– Operations & GraphQL modules invoke Transport Layer → AYON Server
– Entity Hub aggregates Operations → returns domain objects to developer
– CI/CD pushes new versions to PyPI; docs hosted via GitHub Pages
c. Architectural patterns & principles:
– Layered architecture (EntityHub → Operations → ServerAPI → HTTP)
– Singleton pattern for default connection; factory pattern via ServerAPIBase for multiple servers
– Separation of concerns: raw API vs. prepared entity API
– Extensibility points: automated_api for code generation, placeholder for future WebSockets
d. Key technologies & libraries:
– Python requests for HTTP/GraphQL transport
– Sphinx for docs
– pytest for testing
– GitHub Actions for CI/CD
– setuptools / wheel for packaging

##### Detailed but focused
- Every major module and its role.

## Diagram (Mermaid)

```mermaid
flowchart TD
    classDef library fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef external fill:#E6FFEA,stroke:#28A745,color:#28A745
    classDef cicd fill:#FFF5D0,stroke:#D69E00,color:#D69E00

    User["Client Application\n(User Code)"]:::external

    subgraph "AYON-Python-API Library"
        direction TB
        DC1["Constants\n(constants.py)"]:::library
        Utils["Utils\n(utils.py)"]:::library
        Exc["Exceptions\n(exceptions.py)"]:::library
        Typ["Typing\n(typing.py)"]:::library
        Ver["Version\n(version.py)"]:::library

        subgraph "Connection Manager"
            SA["ServerAPI / Base\n(server_api.py)"]:::library
        end

        subgraph "Transport Layer"
            API["_api.py\n(HTTP/GraphQL Transport)"]:::library
        end

        subgraph "GraphQL Client"
            GQL["graphql.py"]:::library
            GQLQ["graphql_queries.py"]:::library
        end

        subgraph "Operations Layer"
            OP["operations.py\n(CRUD Operations)"]:::library
        end

        EH["EntityHub\n(entity_hub.py)"]:::library
        AA["Automated API Generator\n(automated_api.py)"]:::library
    end

    User -->|calls| EH
    EH -->|aggregates| OP
    OP -->|invokes| API
    SA -->|uses| API
    OP -->|builds queries| GQLQ
    OP -->|uses| GQL
    GQL -->|transport| API
    API -->|"HTTP/GraphQL"| AYONServer

    subgraph "External Systems"
        AYONServer["AYON Server\n(REST & GraphQL)"]:::external
    end

    subgraph "CI/CD & Docs" 
        direction TB
        Lint["Linting / PR Checks\n(.github/workflows/pr_linting.yml)"]:::cicd
        DPub["Docs Publish\n(.github/workflows/docs-publish.yml)"]:::cicd
        Pypub["PyPI Publish\n(.github/workflows/python-publish.yml)"]:::cicd
        DocsRoot["Docs Source\n(docs/)"]:::cicd
        Conf["Sphinx Conf\n(docs/source/conf.py)"]:::cicd
        APIrst["API RST\n(docs/source/ayon_api.rst)"]:::cicd
        Setup["setup.py"]:::library
        PyProj["pyproject.toml"]:::library
        Lic["LICENSE"]:::library
        Readme["README.md"]:::library
    end

    subgraph "Tests Suite"
        direction TB
        TEH["test_entity_hub.py"]:::external
        TGE["test_get_events.py"]:::external
        TGQ["test_graphql_queries.py"]:::external
        TS["test_server.py"]:::external
    end

    CI[CI/CD Triggers]:::cicd -->|publishes| Pypub
    CI -->|deploys docs| DPub
    Pypub --> PyPI["PyPI Repository"]:::external
    DPub --> GHPages["GitHub Pages"]:::external
    Tests["Tests Suite"] -->|validates| AA

    click SA "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/server_api.py"
    click API "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/_api.py"
    click GQL "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/graphql.py"
    click GQLQ "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/graphql_queries.py"
    click OP "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/operations.py"
    click EH "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/entity_hub.py"
    click DC1 "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/constants.py"
    click Utils "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/utils.py"
    click Exc "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/exceptions.py"
    click Typ "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/typing.py"
    click Ver "https://github.com/ynput/ayon-python-api/blob/develop/ayon_api/version.py"
    click AA "https://github.com/ynput/ayon-python-api/blob/develop/automated_api.py"
    click Lint "https://github.com/ynput/ayon-python-api/blob/develop/.github/workflows/pr_linting.yml"
    click DPub "https://github.com/ynput/ayon-python-api/blob/develop/.github/workflows/docs-publish.yml"
    click Pypub "https://github.com/ynput/ayon-python-api/blob/develop/.github/workflows/python-publish.yml"
    click DocsRoot "https://github.com/ynput/ayon-python-api/tree/develop/docs/"
    click Conf "https://github.com/ynput/ayon-python-api/blob/develop/docs/source/conf.py"
    click APIrst "https://github.com/ynput/ayon-python-api/blob/develop/docs/source/ayon_api.rst"
    click Setup "https://github.com/ynput/ayon-python-api/blob/develop/setup.py"
    click PyProj "https://github.com/ynput/ayon-python-api/blob/develop/pyproject.toml"
    click Lic "https://github.com/ynput/ayon-python-api/tree/develop/LICENSE"
    click Readme "https://github.com/ynput/ayon-python-api/blob/develop/README.md"
    click TEH "https://github.com/ynput/ayon-python-api/blob/develop/tests/test_entity_hub.py"
    click TGE "https://github.com/ynput/ayon-python-api/blob/develop/tests/test_get_events.py"
    click TGQ "https://github.com/ynput/ayon-python-api/blob/develop/tests/test_graphql_queries.py"
    click TS "https://github.com/ynput/ayon-python-api/blob/develop/tests/test_server.py"
```
