# eric050828/n8n-sdk-python architecture

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

- Interactive diagram: https://gitdiagram.com/eric050828/n8n-sdk-python
- Repository: https://github.com/eric050828/n8n-sdk-python

## Overview

##### Project type and purpose
- This repository is an open-source Python SDK (client library) for interacting with the n8n workflow automation platform’s REST API.
- Its purpose is to provide Python‐native wrappers (“clients”) for each n8n resource (workflows, credentials, executions, etc.), plus data models and utility helpers, so that other Python applications can programmatically manage n8n.

##### File structure
- Top-level packaging and metadata:
- setup.py, pyproject.toml, LICENSE, CHANGELOG.md
- .github/workflows/publish-to-pypi.yml – CI/CD for publishing releases
- .env.example – sample environment variables
- Core library under n8n_sdk_python/:
- client/ – per-resource API wrapper modules (audit.py, workflows.py, …)
- models/ – Pydantic-style classes representing request/response payloads
- utils/ – shared helpers (errors.py, logger.py)
- Entry points & examples:
- examples/simple_case.py – shows typical usage
- tests/ – unit tests targeting each client/model
- Documentation: docs/README_TW.md and main README.md describe setup, usage, and environment configuration.

##### README for additional insights
- SDK is asynchronous (users call await client.method(...))
- Configuration is driven by environment variables (N8N_BASE_URL, N8N_API_KEY) or explicit parameters
- Emphasis on Python 3.8+, virtual environments, python-dotenv for .env loading

##### Elements
- Application → Client (method calls)
- Client → HTTP Client → n8n API (HTTP request/response)
- HTTP Client → Model Layer (data parsing)
- Tests → Client/Models (validation)
- CI/CD → Repository → PyPI (publish)

##### Detail
- Sub-package (client, models, utils) as its own component.
- Flow of environment variables into the client constructor.
- Test suite as part of the architecture (mocking, test coverage).
- Packaging and distribution (setup.py, PyPI).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Consumer Application
    subgraph "Consumer Application" 
        style Consumer fill:#9f6,stroke:#333,stroke-width:1px
        Consumer["Example Script"] 
    end
    click Consumer "https://github.com/eric050828/n8n-sdk-python/blob/main/examples/simple_case.py"

    %% Environment Configuration
    EnvConfig["Environment Variables"]:::env

    Consumer -->|"imports & config"| EnvConfig
    EnvConfig -->|"injects into"| ClientLayer

    %% SDK Library Layers
    subgraph "n8n-sdk-python Library"
        direction TB
        subgraph "Client Layer" 
            style ClientLayer fill:#bbf,stroke:#333,stroke-width:1px
            CL_base["base.py"]
            CL_audit["audit.py"]
            CL_connections["connections.py"]
            CL_credentials["credentials.py"]
            CL_executions["executions.py"]
            CL_nodes["nodes.py"]
            CL_projects["projects.py"]
            CL_source["source_control.py"]
            CL_tags["tags.py"]
            CL_users["users.py"]
            CL_variables["variables.py"]
            CL_workflows["workflows.py"]
        end
        click CL_base "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/base.py"
        click CL_audit "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/audit.py"
        click CL_connections "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/connections.py"
        click CL_credentials "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/credentials.py"
        click CL_executions "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/executions.py"
        click CL_nodes "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/nodes.py"
        click CL_projects "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/projects.py"
        click CL_source "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/source_control.py"
        click CL_tags "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/tags.py"
        click CL_users "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/users.py"
        click CL_variables "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/variables.py"
        click CL_workflows "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/workflows.py"

        subgraph "Model Layer"
            style ModelLayer fill:#bbf,stroke:#333,stroke-width:1px
            ML_base["base.py"]
            ML_audit["audit.py"]
            ML_credentials["credentials.py"]
            ML_executions["executions.py"]
            ML_nodes["nodes.py"]
            ML_projects["projects.py"]
            ML_source["source_control.py"]
            ML_users["users.py"]
            ML_variables["variables.py"]
            ML_workflows["workflows.py"]
        end
        click ML_base "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/base.py"
        click ML_audit "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/audit.py"
        click ML_credentials "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/credentials.py"
        click ML_executions "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/executions.py"
        click ML_nodes "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/nodes.py"
        click ML_projects "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/projects.py"
        click ML_source "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/source_control.py"
        click ML_users "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/users.py"
        click ML_variables "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/variables.py"
        click ML_workflows "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/models/workflows.py"

        subgraph "Utilities"
            style Utils fill:#bbf,stroke:#333,stroke-width:1px
            U_errors["errors.py"]
            U_logger["logger.py"]
        end
        click U_errors "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/utils/errors.py"
        click U_logger "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/utils/logger.py"
    end

    %% HTTP Client & External Service
    subgraph "External Dependencies"
        style ExtDeps fill:#eef,stroke:#333,stroke-width:1px
        HTTPClient["Async HTTP Client"]
        Dotenv["python-dotenv"]
        Asyncio["asyncio"]
    end
    click HTTPClient "https://github.com/eric050828/n8n-sdk-python/blob/main/n8n_sdk_python/client/base.py"
    click Dotenv "https://github.com/eric050828/n8n-sdk-python/blob/main/.env.example"

    subgraph "External Service"
        style N8N fill:#f96,stroke:#333,stroke-width:1px
        N8NAPI["n8n Workflow API"]
    end

    ClientLayer -->|"builds requests"| HTTPClient
    HTTPClient -->|"sends HTTP"| N8NAPI
    HTTPClient -->|"parses JSON"| ModelLayer
    Utils -->|"logging & errors"| ClientLayer
    Utils -->|"validation & errors"| ModelLayer

    %% Tests
    subgraph "Tests"
        style Tests fill:#cff,stroke:#333,stroke-width:1px
        T_audit["test_audit.py"]
        T_connections["test_connections.py"]
        T_credentials["test_credentials.py"]
        T_executions["test_executions.py"]
        T_projects["test_projects.py"]
        T_source["test_source_control.py"]
        T_tags["test_tags.py"]
        T_users["test_users.py"]
        T_variables["test_variables.py"]
        T_workflow["test_workflow.py"]
    end
    click T_audit "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_audit.py"
    click T_connections "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_connections.py"
    click T_credentials "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_credentials.py"
    click T_executions "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_executions.py"
    click T_projects "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_projects.py"
    click T_source "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_source_control.py"
    click T_tags "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_tags.py"
    click T_users "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_users.py"
    click T_variables "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_variables.py"
    click T_workflow "https://github.com/eric050828/n8n-sdk-python/blob/main/tests/test_workflow.py"

    Tests -->|"invoke"| ClientLayer
    Tests -->|"validate"| ModelLayer

    %% Packaging & CI/CD
    subgraph "Repository & CI/CD"
        style Repo fill:#ddd,stroke:#333,stroke-width:1px
        Repo["Source Repository"]
        Setup["setup.py\npyproject.toml\nCHANGELOG.md\nLICENSE"]
        Docs["docs/README_TW.md\nREADME.md"]
        CI["GitHub Actions CI/CD"]
    end
    click Setup "https://github.com/eric050828/n8n-sdk-python/blob/main/setup.py"
    click CI "https://github.com/eric050828/n8n-sdk-python/blob/main/.github/workflows/publish-to-pypi.yml"
    click Docs "https://github.com/eric050828/n8n-sdk-python/blob/main/docs/README_TW.md"
    click Docs "https://github.com/eric050828/n8n-sdk-python/blob/main/README.md"

    Repo --> Setup
    Repo --> Docs
    Repo --> CI
    CI -->|"publish on tag"| PyPI["PyPI Registry"]

    %% Data Flows
    Consumer -->|"calls client methods"| CL_base
    Consumer -->|"await client.method()"| CL_workflows
    CLI[".env example"] -.-> Dotenv

    %% Classes
    classDef env stroke-dasharray: 5 5,fill:#fff,stroke:#999;
    class EnvConfig env
```
