# frerich/auto_updater architecture

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

- Interactive diagram: https://gitdiagram.com/frerich/auto_updater
- Repository: https://github.com/frerich/auto_updater

## Overview

##### Project type and purpose
- This is an Elixir library (Mix application) named AutoUpdater.
- Its purpose is to automatically fetch and deploy new Mix releases (tarballs) on Linux or macOS.
- It provides an OTP application that watches for new releases and secrets, downloads updates from different storage backends, and installs/deploys them.

##### File structure
- Top-level files:
- mix.exs, mix.lock: Elixir project configuration and dependencies.
- lib/auto_updater: main application code.
- test/: unit tests for each module and storage adapter.
- lib/auto_updater/application.ex: defines the OTP supervision tree.
- lib/auto_updater/release_watcher.ex & secrets_watcher.ex: GenServers monitoring for new releases or secret changes.
- lib/auto_updater/storage/*.ex: behaviour and adapters (GitHub, S3, local).
- lib/auto_updater/secrets/*.ex: behaviour and adapters (encrypted JSON, local, AWS Secrets Manager).
- lib/auto_updater/deploy.ex & installation.ex: modules handling unpacking tarballs and performing the actual update on disk.
- Configuration and extensibility points: storage and secrets behaviours with multiple implementations.

##### README for additional insights
- Key detail: distribution as tar.gz Mix releases.
- Focus of the library: periodic polling or event-based watching of external storage, secure retrieval of secrets, controlled installation and deployment of updated software.

a. Main components
- OTP Application (Supervisor)
- ReleaseWatcher (GenServer)
- SecretsWatcher (GenServer)
- Storage Behaviour + Adapters
- Secrets Behaviour + Adapters
- Installation module
- Deploy module
- External Systems: GitHub, S3, Local FS, Secrets Manager
- Local disk (where new release tarballs and extracted files live)
b. Relationships and interactions
1. Supervisor starts watchers and core modules.
2. ReleaseWatcher polls or subscribes to Storage Adapter → asks for versions or tarball URLs.
3. Storage Adapter communicates with external storage (GitHub API, AWS S3 API, or local directory).
4. SecretsWatcher polls or subscribes to Secrets Adapter → fetches decryption keys or credentials.
5. On detection of new release:
– ReleaseWatcher emits an “update available” event.
– Installation module downloads the tarball via Storage Adapter, passes through Secrets module if encrypted.
– Installation module extracts the Mix release to a staging directory.
– Deploy module switches symlinks or moves directories to activate the new release.
6. Optional: Secrets module decrypts configuration, writes local secret files for the application.
c. Architectural patterns and principles
- OTP Supervision Tree for fault tolerance.
- Behaviour + Adapter pattern for pluggable storages and secrets backends.
- Event-driven watchers (polling or push) decoupled from installation/deployment.
- Single Responsibility: each module focuses on one concern (watching, storage, secrets, deployment).
d. Relevant technologies and frameworks
- Elixir/OTP (GenServer, Supervisor)
- Mix releases (tar.gz)
- HTTP/HTTPS APIs for GitHub and AWS S3
- JSON parsing and encryption libraries (for encrypted_json_file)
- File system operations

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Watchers and Supervisor
    subgraph "AutoUpdater OTP Application"
        Application["OTP Application (Supervisor)"]:::otp
        MainEntry["AutoUpdater Main Entry"]:::otp
        Application -->|starts| ReleaseWatcher
        Application -->|starts| SecretsWatcher
        MainEntry --> Application
    end

    ReleaseWatcher["ReleaseWatcher GenServer"]:::otp
    SecretsWatcher["SecretsWatcher GenServer"]:::otp

    %% Adapters Layer
    subgraph "Storage Adapters"
        StorageBehaviour["Storage Behaviour"]:::adapter
        GitHubAdapter["GitHub Storage Adapter"]:::adapter
        S3Adapter["S3 Storage Adapter"]:::adapter
        LocalStorage["Local Storage Adapter"]:::adapter
        StorageBehaviour -->|implemented by| GitHubAdapter
        StorageBehaviour -->|implemented by| S3Adapter
        StorageBehaviour -->|implemented by| LocalStorage
    end

    subgraph "Secrets Adapters"
        SecretsBehaviour["Secrets Behaviour"]:::adapter
        EncryptedJsonAdapter["Encrypted JSON File Adapter"]:::adapter
        LocalSecretsAdapter["Local Secrets Adapter"]:::adapter
        AWSSecretsManager["AWS Secrets Manager Adapter"]:::adapter
        SecretsBehaviour -->|implemented by| EncryptedJsonAdapter
        SecretsBehaviour -->|implemented by| LocalSecretsAdapter
        SecretsBehaviour -->|implemented by| AWSSecretsManager
    end

    %% Core Logic
    subgraph "Core Logic"
        Installation["Installation Module"]:::core
        Deploy["Deploy Module"]:::core
        TempHelper["Temporary File Helper"]:::core
        Installation -->|uses| TempHelper
        Installation -->|triggers| Deploy
    end

    %% External Systems
    subgraph "External Systems"
        GitHub["GitHub API"]:::external
        S3["AWS S3 API"]:::external
        LocalFS["Local File System"]:::external
        SecretsManager["AWS Secrets Manager"]:::external
        LocalDisk["Local Disk & Staging"]:::external
    end

    %% Flow Arrows
    ReleaseWatcher -->|polls| StorageBehaviour
    SecretsWatcher -->|polls| SecretsBehaviour
    GitHubAdapter -->|fetch tarball| GitHub
    S3Adapter -->|fetch tarball| S3
    LocalStorage -->|fetch tarball| LocalFS
    EncryptedJsonAdapter -->|fetch secrets| LocalFS
    LocalSecretsAdapter -->|fetch secrets| LocalFS
    AWSSecretsManager -->|fetch secrets| SecretsManager
    ReleaseWatcher -->|update event| Installation
    SecretsWatcher -->|secret event| Installation
    Installation -->|extract to| LocalDisk
    Deploy -->|switch release in| LocalDisk

    %% Click Events
    click Application "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/application.ex"
    click MainEntry "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater.ex"
    click ReleaseWatcher "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/release_watcher.ex"
    click SecretsWatcher "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/secrets_watcher.ex"
    click StorageBehaviour "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/storage.ex"
    click GitHubAdapter "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/storage/github.ex"
    click S3Adapter "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/storage/s3.ex"
    click LocalStorage "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/storage/local.ex"
    click SecretsBehaviour "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/secrets.ex"
    click EncryptedJsonAdapter "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/secrets/encrypted_json_file.ex"
    click LocalSecretsAdapter "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/secrets/local.ex"
    click AWSSecretsManager "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/secrets/secrets_manager.ex"
    click Installation "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/installation.ex"
    click Deploy "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/deploy.ex"
    click TempHelper "https://github.com/frerich/auto_updater/blob/main/lib/auto_updater/temp.ex"

    %% Styles
    classDef otp fill:#D6EAF8,stroke:#2980B9,stroke-width:1px
    classDef adapter fill:#E8DAEF,stroke:#8E44AD,stroke-width:1px
    classDef core fill:#D5F5E3,stroke:#27AE60,stroke-width:1px
    classDef external fill:#FADBD8,stroke:#C0392B,stroke-width:1px
```
