# taxel/plextraktsync architecture

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

- Interactive diagram: https://gitdiagram.com/taxel/plextraktsync
- Repository: https://github.com/taxel/plextraktsync

## Overview

##### Main Components

- Command-Line Interface (CLI) Frontend:
- The entry point is in plextraktsync/__main__.py which routes to subcommands.
- Commands are implemented under plextraktsync/commands (e.g., sync, login, inspect, etc.).

- Configuration Management:
- The project uses YAML configuration files (config.yml, servers.yml, config.default.yml).
- Configuration modules in plextraktsync/config (e.g., ConfigLoader.py, RunConfig.py) are responsible for reading and merging configuration data. This component determines sync options, which libraries to operate on, and per-server settings.

- External Service Integrations:
- Plex API Integration: Modules under plextraktsync/plex (including PlexApi.py, PlexServerConnection.py, etc.) deal with interfacing with Plex Media Server.
- Trakt API Integration: Modules under plextraktsync/trakt (e.g., TraktApi.py, TraktLookup.py, etc.) handle communication with trakt.tv.
- These components encapsulate the logic to authenticate, fetch, and update data from each service.

- Sync Engine:
- Located mainly within plextraktsync/sync and plextraktsync/commands/sync.py.
- This engine orchestrates the fetching of data from Plex and Trakt, performs comparisons, and triggers updates.
- It makes use of a plugin model (see plextraktsync/plugin and plextraktsync/sync/plugin) to allow extensibility for different sync operations (ratings, watched status, collections, etc.).

- Task Queuing / Background Processing:
- The queue module (plextraktsync/queue) contains background task handlers such as TraktBatchWorker and TraktScrobbleWorker.
- These can be depicted as a separate component that decouples the immediate sync logic from batch processing and scheduled tasks.

- Logging and Monitoring:
- The logger directory (plextraktsync/logger) manages logging and filtering.
- This component provides feedback (logs, progress bars) that is crucial for troubleshooting and operational visibility.

- Utility Components:
- The util folder contains shared helper functions (for paths, version info, parsing dates, etc.) that support both the sync engine and the CLI.
- Decorators in plextraktsync/decorators provide cross-cutting concerns such as rate limiting, retries, measuring execution time, etc.

- Deployment / External Interfaces:
- Docker-related files (Dockerfile, docker-compose.yml, various shell scripts) indicate that the system is often run in containerized environments.
- The README details how to run using Docker or systemd, showing that orchestration and service management are also important parts of the ecosystem.

##### Relationships and Interactions

- The CLI is the main entry point where user commands (sync, login, etc.) are received.
- It dispatches the request to command-specific modules.
- The configuration loader reads the YAML files and passes the settings to all components.
- The Plex and Trakt API components connect to external services using the settings (like credentials, API tokens) provided by the configuration.
- The sync engine orchestrates the overall workflow by calling the Plex API to gather media library data and then checking and comparing with Trakt data using the Trakt API.
- A background task queue can then either schedule or process tasks asynchronously (e.g., batch uploads to Trakt).
- Logging and utility functions provide cross-cutting functionality that is used by almost every module to ensure uniform behavior and error reporting.
- Deployment pieces (Docker/Docker Compose, systemd service files) wrap the entire application, with environment variables and volume mounts configuring persistent storage (config, logs, cache).

##### Architectural Patterns & Design Principles

- Modularization – The code is clearly separated into modules for configuration, API integration, commands, background processing, and utilities.
- Plugin and Extension – The existence of a plugin manager and separate commands for varied sync tasks indicates that the design supports pluggability and extensibility.
- Decoupling – The use of decorators, factories, and a task queue demonstrates a design that decouples cross-cutting concerns (like retry logic, factory-based object creation) from the core business logic.
- Service-Oriented – While not microservices distributed across different processes, the clear separation between services (Plex API, Trakt API, task handling, CLI) mirrors a service-oriented architecture.
- Containerization – Presence of Docker-related files means the system is designed to run in isolated containers using environment configurations.

##### Final Recommendations

- Notes about external environments (Docker, systemd, etc.) to show how the code is executed in production.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Components
    A["CLI Front-End (__main__.py)"]:::cli
    B["Command Handlers (sync, login, inspect, etc.)"]:::command
    C["Configuration Manager"]:::config
    D["YAML Config Files (config.yml, servers.yml, config.default.yml)"]:::config
    E["Plex API Integration"]:::api
    F["Trakt API Integration"]:::api
    G["Sync Engine & Plugins"]:::sync
    H["Sync Command (sync.py)"]:::sync
    I["Task Queue / Background Processing"]:::queue

    %% Support Components
    subgraph "Support Components"
        J["Logging & Monitoring"]:::support
        K["Helper Functions (Util)"]:::support
        L["Decorators"]:::support
    end

    %% Deployment & External Interfaces
    subgraph "Deployment & External Interfaces"
        M1["Dockerfile"]:::deploy
        M2["docker-compose.yml"]:::deploy
        M3["Shell Scripts (entrypoint.sh, plex-api.sh, plextraktsync.sh, plextraktsync.bat)"]:::deploy
    end

    %% Relationships
    A -->|"routes"| B
    A -->|"loads"| C
    C -->|"reads"| D
    C -->|"supplies config"| E
    C -->|"supplies config"| F
    B -->|"invokes"| H
    H -->|"orchestrates"| G
    E -->|"provides Plex data"| G
    F -->|"provides Trakt data"| G
    G -->|"queues tasks"| I
    M1 --- A
    M2 --- A
    M3 --- A

    %% Support dashed connections
    A -.-> J
    B -.-> J
    C -.-> J
    E -.-> J
    F -.-> J
    G -.-> J
    I -.-> J

    A -.-> K
    B -.-> K
    C -.-> K
    E -.-> K
    F -.-> K
    G -.-> K
    I -.-> K

    A -.-> L
    B -.-> L
    C -.-> L
    E -.-> L
    F -.-> L
    G -.-> L
    I -.-> L

    %% API integrations support
    G -->|"calls"| E
    G -->|"calls"| F

    %% Task Queue support from Sync Engine
    G -->|"schedules"| I

    %% Click Events
    click A "https://github.com/taxel/plextraktsync/blob/main/plextraktsync/__main__.py"
    click B "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/commands/"
    click C "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/config/"
    click D "https://github.com/taxel/plextraktsync/blob/main/plextraktsync/config.default.yml"
    click E "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/plex/"
    click F "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/trakt/"
    click G "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/sync/"
    click H "https://github.com/taxel/plextraktsync/blob/main/plextraktsync/commands/sync.py"
    click I "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/queue/"
    click J "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/logger/"
    click K "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/util/"
    click L "https://github.com/taxel/plextraktsync/tree/main/plextraktsync/decorators/"
    click M1 "https://github.com/taxel/plextraktsync/tree/main/Dockerfile"
    click M2 "https://github.com/taxel/plextraktsync/blob/main/docker-compose.yml"
    click M3 "https://github.com/taxel/plextraktsync/blob/main/entrypoint.sh"

    %% Styles
    classDef cli fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef command fill:#ffe6cc,stroke:#cc6600,stroke-width:2px;
    classDef config fill:#e6ffcc,stroke:#669900,stroke-width:2px;
    classDef api fill:#cce6ff,stroke:#003399,stroke-width:2px;
    classDef sync fill:#e6ccff,stroke:#6600cc,stroke-width:2px;
    classDef queue fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef support fill:#f2f2f2,stroke:#999999,stroke-width:2px;
    classDef deploy fill:#ffebcc,stroke:#cc7a00,stroke-width:2px;
```
