# plattar/workflows architecture

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

- Interactive diagram: https://gitdiagram.com/plattar/workflows
- Repository: https://github.com/plattar/workflows

## Overview

##### Project type and purpose
- This repository is an open-source **library of reusable GitHub Actions workflows** whose sole purpose is to **build and deploy applications to Cloudflare Pages** with multi-environment support.

##### File structure analysis
- Top-level directories/files:
- .github/workflows/cloudflare-pages-deploy.yml  ← the reusable workflow
- LICENSE
- README.md
- No frontend/backend separation here—this is strictly a **CI/CD pipeline definition**.

##### README insights
- Describes how to call the workflow from any consumer repo.
- Lists required inputs (tag, environment, project-name, build-directory, etc.) and secrets (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID).
- Defines tag conventions (1.0.0, 1.0.0-staging, etc.).

a. Main components
1. Developer (or automated process)
2. Caller Repository (your app’s codebase)
3. GitHub Actions Runner
4. Shared Workflows Repository (this project)
5. Build Environment (Node.js container on the runner)
6. Secrets Store (GitHub Actions secrets)
7. Cloudflare Pages Service (external API)
b. Relationships and interactions
- Developer pushes a tag or dispatches a workflow →
- GitHub Actions event triggers on the **Caller Repository** →
- Runner clones Caller Repo, then **imports** the `cloudflare-pages-deploy.yml` workflow from the **Shared Workflows Repo** →
- Runner fetches secrets from the **Secrets Store** →
- Runner spins up a Node.js container, runs `npm run build` (or custom build-command) →
- Artifacts are collected (output-directory) →
- Runner calls the **Cloudflare Pages API** (using CLOUDFLARE_API_TOKEN & CLOUDFLARE_ACCOUNT_ID) to deploy to the specified environment →
- Cloudflare Pages returns deployment status → job completes.
c. Architectural patterns & principles
- **CI/CD pipeline** using reusable/composite workflows
- **Single source of truth** for deployment logic
- **Separation of concerns**: build and deploy steps are encapsulated in the shared workflow
- **Inputs & secrets** model to parameterize environments and keep credentials secure
d. Key technologies & frameworks
- GitHub Actions (reusable/composite workflows)
- Node.js / npm
- Cloudflare Pages REST API

##### Detail level
- Step in the CI/CD pipeline (trigger, checkout, setup, build, deploy).
- Where inputs enter the flow and where secrets are pulled.
- Don’t omit the reusable-workflow import action—this is the core of the library.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Developer["Developer/Automated<br/>Push Tag or Dispatch"]:::external
    subgraph "Caller Repository"
        CR["Caller Repo (Your App)"]:::codeRepos
    end
    subgraph "Shared Workflows Repository"
        SW["Shared Workflows Repo"]:::codeRepos
        RW["Reusable Workflow<br/>(cloudflare-pages-deploy.yml)"]:::codeRepos
        DOC["Documentation<br/>README.md"]:::codeRepos
        LIC["License<br/>LICENSE"]:::codeRepos
    end
    Runner["GitHub Actions Runner"]:::runner
    Secrets["Secrets Store"]:::secrets
    BuildEnv["Node.js Container<br/>Build Step"]:::runner
    Artifacts["Artifacts"]:::runner
    CFAPI["Cloudflare Pages API"]:::external

    Developer -->|push tag/dispatch| CR
    CR -->|trigger workflow| Runner
    Runner -->|checkout code| CR
    Runner -->|import workflow| RW
    Runner -->|fetch inputs & secrets| Secrets
    Runner -->|setup build environment| BuildEnv
    BuildEnv -->|run build| Artifacts
    Artifacts -->|call API| CFAPI

    click SW "https://github.com/plattar/workflows/tree/main//"
    click RW "https://github.com/plattar/workflows/blob/main/.github/workflows/cloudflare-pages-deploy.yml"
    click DOC "https://github.com/plattar/workflows/blob/main/README.md"
    click LIC "https://github.com/plattar/workflows/tree/main/LICENSE"

    classDef codeRepos fill:#D6EAF8,stroke:#3498DB,color:#154360,stroke-width:2px;
    classDef runner fill:#D5F5E3,stroke:#27AE60,color:#1E8449,stroke-width:2px,stroke-dasharray: 5 5;
    classDef secrets fill:#FCF3CF,stroke:#F1C40F,color:#7D6608,stroke-width:2px;
    classDef external fill:#EBDEF0,stroke:#8E44AD,color:#4A235A,stroke-width:2px;
```
