# devevandro/coolify-app-deploy architecture

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

- Interactive diagram: https://gitdiagram.com/devevandro/coolify-app-deploy
- Repository: https://github.com/devevandro/coolify-app-deploy

## Overview

##### Project Type and Purpose
- **Type:** Open-source integration tool in the form of a GitHub Action.
- **Purpose:** When a Git push (or manual dispatch) to a branch occurs, this Action runs on a GitHub Actions runner, reads inputs/secret values, and invokes the Coolify REST API to deploy an app and update its environment variables.

##### File Structure
- **Top-level files:**
- `.github/workflows/deploy.yml` – CI pipeline (build & publish Action, optional).
- `action.yml` – Action metadata (inputs, outputs, entrypoint).
- `README.md` – User guide.
- `package.json` / `tsconfig.json` – Node/TypeScript config.
- **Source & build dirs:**
- `src/index.ts` – Main logic entrypoint.
- `src/utils/index.ts` – Payload/build helpers.
- `dist/index.js` – Compiled JS used at runtime.
- **Lock file & ignore:** typical Node modules.

##### README for Additional Insights
- **Features:**
- `coolify_url`, `coolify_token`, `coolify_app_uuid` as required inputs.
- Optional `secrets` JSON blob and `secrets_to_exclude`.
- Secure auth via Bearer token.
- Plug-and-play in any workflow YAML.
- **Usage snippet:** shows how it is invoked in a standard GH Actions workflow.

##### Main Components & Relationships
a. **GitHub Actor (Developer / Push event)**
→ triggers the workflow on GitHub.com
b. **GitHub Actions Runner**
– Checks out the repo (standard `actions/checkout`)
– Reads `action.yml` metadata
– Installs dependencies / Node runtime
– Executes `dist/index.js` with provided inputs
c. **Action Logic (Node.js / TypeScript)**
– Validates inputs, merges optional `secrets`, applies `secrets_to_exclude` filter
– Makes HTTP calls (e.g., via `fetch` or `axios`) to:
- `POST {coolify_url}/api/applications/{appUuid}/deploy`
- `PUT {coolify_url}/api/applications/{appUuid}/env`
– Handles HTTP responses / errors, logs status
d. **Coolify Instance (Self-hosted)**
– API Gateway / Auth layer (verifies `coolify_token`)
– Application service (updates DB, writes env vars)
– Deployment orchestrator (builds containers, updates pods)
e. **External Systems**
– (Optional) Secrets store: GitHub Secrets
– (Optional) Coolify’s backing DB / container registry

##### Architectural Patterns & Principles
- **Adapter/Integration Pattern:** wraps Coolify’s REST API in a simple Action interface.
- **Single Responsibility:** one Action for deploy + env management.
- **Immutability:** uses fresh runner each invocation.
- **Configuration as Code:** all inputs are declared in `action.yml` & workflow YAML.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% GitHub.com Layer
    subgraph "GitHub.com"
        GH_TRIGGER["GitHub.com / Workflow Trigger"]:::github
        GH_SECRET["Secrets Store (GitHub Secrets)"]:::external
    end

    %% Runner Layer
    subgraph "GitHub Actions Runner"
        CI["Checkout & Setup"]:::github
        WORKFLOW[".github/workflows/deploy.yml"]:::action
        ACTION_META["action.yml"]:::action
        README_DOC["README.md"]:::external
        PACKAGE_JSON["package.json"]:::action
        TSCONFIG["tsconfig.json"]:::action
        LOCK_FILE["package-lock.json"]:::action
        SRC_INDEX["src/index.ts"]:::action
        UTILS["src/utils/index.ts"]:::action
        BUILD["Compile TS → JS"]:::action
        DIST_JS["dist/index.js"]:::action
    end

    %% Coolify Layer
    subgraph "Coolify Instance"
        API_GATEWAY["Coolify API Gateway"]:::coolify
        APP_SERVICE["Application Service"]:::coolify
        BACKEND_DB["Back-End DB / Container Registry"]:::coolify
    end

    %% Flows
    GH_TRIGGER --> CI
    CI --> WORKFLOW
    CI --> ACTION_META
    CI --> README_DOC
    CI --> PACKAGE_JSON
    CI --> TSCONFIG
    CI --> LOCK_FILE
    CI --> BUILD
    BUILD --> DIST_JS
    BUILD --> SRC_INDEX
    BUILD --> UTILS
    GH_SECRET -.-> DIST_JS
    DIST_JS -->|"HTTP Requests"| API_GATEWAY
    API_GATEWAY --> APP_SERVICE
    APP_SERVICE --> BACKEND_DB

    %% Click Events
    click WORKFLOW "https://github.com/devevandro/coolify-app-deploy/blob/main/.github/workflows/deploy.yml"
    click ACTION_META "https://github.com/devevandro/coolify-app-deploy/blob/main/action.yml"
    click README_DOC "https://github.com/devevandro/coolify-app-deploy/blob/main/README.md"
    click PACKAGE_JSON "https://github.com/devevandro/coolify-app-deploy/blob/main/package.json"
    click TSCONFIG "https://github.com/devevandro/coolify-app-deploy/blob/main/tsconfig.json"
    click LOCK_FILE "https://github.com/devevandro/coolify-app-deploy/blob/main/package-lock.json"
    click SRC_INDEX "https://github.com/devevandro/coolify-app-deploy/blob/main/src/index.ts"
    click UTILS "https://github.com/devevandro/coolify-app-deploy/blob/main/src/utils/index.ts"
    click DIST_JS "https://github.com/devevandro/coolify-app-deploy/blob/main/dist/index.js"

    %% Styles
    classDef github fill:#cce5ff,stroke:#1a73e8
    classDef action fill:#d4edda,stroke:#28a745
    classDef coolify fill:#ffe5b4,stroke:#ff9800
    classDef external fill:#f8f9fa,stroke:#6c757d,stroke-dasharray:5 5
```
