# pig-dot-dev/pig-python architecture

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

- Interactive diagram: https://gitdiagram.com/pig-dot-dev/pig-python
- Repository: https://github.com/pig-dot-dev/pig-python

## Overview

##### Main Components
- SDK Client Library (located under src/pig): This encapsulates the core functionality including API client classes, CLI interface, and various modules (e.g., connection_session, connections, machines, sync_wrapper). These components handle the connection logic and the orchestration of commands.
- Command Line Interface (CLI): Found in src/pig/cli.py, this component exposes command line tools (e.g., pig ls) that allow users to interact with the system.
- Connection & Workflow Manager: The connection_session, connections, and sync_wrapper modules work together to abstract the process of establishing connections and sending workflows (keyboard, mouse, and screen actions) either locally or remotely.
- Examples: The examples directory (particularly examples/chat) shows how the SDK is integrated within an AI agent context. It demonstrates a practical use-case of the SDK by launching a “chat agent” that might interface with the automation API.
- Testing Suite: The tests directory contains unit, end-to-end, load, and local tests verifying the functionality. Although not part of the runtime architecture, it reinforces the design by verifying the connections and session handling.
- External Component – Piglet: While not part of the repository itself, the README makes it clear that a separate process called “Piglet” is a key part of the system. This process runs on Windows and listens on a port (default localhost:3000) for automation requests. It’s the component that executes the actual actions (keystrokes, mouse events, etc.).

##### Relationships and Interactions
- Connection Lifecycle: Illustrate how a machine (local or remote) is selected and how a connection is established, used (by sending commands as a workflow), and then closed – highlighting usage of the context manager pattern.

##### Architectural Patterns
- Modular Design: The project is organized into clearly separated modules for API communication, session management, and CLI handling.
- Abstraction via API Clients: The use of client classes abstracts the details of the underlying network or inter-process communication (with Piglet) from the user.
- Context Manager Pattern: Emphasize that all connection operations use Python’s with-statement for safe and predictable connection management.
- Test Driven Validation: The tests directory suggests a design that supports continuous integration and extensive automated testing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interaction
    User["User"]:::user

    %% CLI Component
    CLI["Command Line Interface (CLI)"]:::internal

    %% SDK Client Library Cluster
    subgraph "SDK Client Library"
        API["API Client & Modules"]:::internal
        subgraph "Connection Manager"
            CS["Connection Session"]:::internal
            CON["Connections"]:::internal
            SW["Sync Wrapper"]:::internal
        end
    end

    %% External Piglet Server
    Piglet["Piglet Server (External Process)"]:::external

    %% Examples Cluster
    Example["Chat Agent Example"]:::internal

    %% Testing Suite
    Test["Testing Suite"]:::testing

    %% Data Flow
    User -->|"triggers"| CLI
    CLI -->|"invokes commands"| API
    API -->|"uses"| CS
    API -->|"uses"| CON
    API -->|"uses"| SW
    CS -->|"sends requests"| Piglet
    CON -->|"sends requests"| Piglet
    SW -->|"sends requests"| Piglet

    Example -->|"uses SDK for automation"| API

    Test -.->|"validates"| API
    Test -.->|"validates"| CS

    %% Click Events
    click API "https://github.com/pig-dot-dev/pig-python/tree/main/src/pig/"
    click CLI "https://github.com/pig-dot-dev/pig-python/blob/main/src/pig/cli.py"
    click CS "https://github.com/pig-dot-dev/pig-python/blob/main/src/pig/connection_session.py"
    click CON "https://github.com/pig-dot-dev/pig-python/blob/main/src/pig/connections.py"
    click SW "https://github.com/pig-dot-dev/pig-python/blob/main/src/pig/sync_wrapper.py"
    click Example "https://github.com/pig-dot-dev/pig-python/tree/main/examples/chat/"
    click Test "https://github.com/pig-dot-dev/pig-python/tree/main/tests/"

    %% Styles
    classDef internal fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#faa,stroke:#333,stroke-width:2px;
    classDef testing fill:#afa,stroke:#333,stroke-width:2px;
    classDef user fill:#ffa,stroke:#333,stroke-width:2px;
```
