# internetarchive/cicd architecture

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

- Interactive diagram: https://gitdiagram.com/internetarchive/cicd
- Repository: https://github.com/internetarchive/cicd

## Overview

##### Project type and purpose
- This is an open-source GitHub Actions “reusable workflow” repository. Its purpose is to provide a standardized CI/CD pipeline (build, test, and deploy) for any Docker-based project, deploying into HashiCorp Nomad clusters (dev and optional prod).
- Key indicators: only a single workflow file under `.github/workflows/cicd.yml`, README describes how to “use” this workflow from other repositories.

##### File structure
- Top-level directories:
- `.github/workflows` – contains the reusable CI/CD pipeline definition (`cicd.yml`).
- Root files: `LICENSE`, `README.md`, `_config.yml` (for GitHub Pages or docs).
- No application code here: this is purely configuration for GitHub Actions.
- No build scripts beyond the workflow itself; the workflow drives Docker builds and Nomad deployments.

##### README for additional insights
- The README documents:
- How to reference this workflow from other repos.
- Required GitHub secrets (`NOMAD_TOKEN`, optional `NOMAD_TOKEN_PROD`).
- Optional inputs (`BASE_DOMAIN`, `NOMAD_ADDR`, `PLATFORMS`, `NOMAD_VAR_*`).
- Flow: on `push` or manual dispatch → build & test → deploy to dev or prod Nomad cluster.
- External integrations: GitHub Container Registry, Nomad API, GitHub Secrets store.

a. Main components
- Consumer GitHub Repository (“Your App Repo”)
- GitHub Actions Runner (hosted)
- Reusable Workflow Definition (`internetarchive/cicd/.github/workflows/cicd.yml`)
- Docker Build & Test steps
- GitHub Container Registry
- HashiCorp Nomad Dev Cluster
- HashiCorp Nomad Prod Cluster (optional)
- GitHub Secrets (NOMAD_TOKEN*, BASE_DOMAIN, NOMAD_ADDR)
b. Relationships & interactions
1. Developer pushes code to “Your App Repo”
2. GitHub Actions Runner loads the reusable workflow from `internetarchive/cicd`
3. Runner executes `build` job:
- Builds Docker image using repo’s Dockerfile
- (Optional) Runs tests inside container
4. Runner pushes Docker image to GitHub Container Registry
5. Runner invokes Nomad API (using `NOMAD_TOKEN` secret) to deploy to Dev Cluster
6. On `production` branch (and `NOMAD_TOKEN_PROD`), deploy to Prod Cluster
c. Architectural patterns / principles
- Reusable Workflows: DRY pipelines across many repos
- Infrastructure as Code: declarative GitHub Actions YAML
- Secrets management: GitHub Secrets for API tokens
- Environment Segregation: separate Dev vs Prod deployments via branch rules
d. Technologies / frameworks
- GitHub Actions (reusable workflow syntax)
- Docker
- GitHub Container Registry (ghcr.io)
- HashiCorp Nomad
- GitHub Secrets

##### Final advice
- Every element: entrypoint (`.github/workflows/`), the “uses:” link to internetarchive/cicd, build/test steps, registry, Nomad deploys, secrets, optional prod path.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Repository Structure"
        README["README.md"]:::github
        License["LICENSE"]:::github
        Config["_config.yml"]:::github
        WorkflowsDir[".github/workflows"]:::github
    end

    Developer["Developer"]:::external
    Developer -->|"push code / dispatch"| YourRepo["Your App Repo"]:::github
    YourRepo -->|"triggers"| Runner["GitHub Actions Runner"]:::github
    Runner -->|"uses internetarchive/cicd/.github/workflows/cicd.yml"| ReusableWorkflow["Reusable Workflow Definition"]:::github
    ReusableWorkflow -->|"defines jobs"| Runner
    Runner -->|"executes build & test"| Docker["Docker Build & Test"]:::process
    Docker -->|"push image"| Registry["GitHub Container Registry"]:::registry
    Runner -->|"deploy (NOMAD_TOKEN)"| Dev["Nomad Dev Cluster"]:::registry
    Runner -.->|"deploy (NOMAD_TOKEN_PROD)"| Prod["Nomad Prod Cluster"]:::registry
    Secrets["GitHub Secrets"]:::github
    Secrets -->|"NOMAD_TOKEN, BASE_DOMAIN, NOMAD_ADDR, PLATFORMS, NOMAD_VAR_*"| Runner

    click ReusableWorkflow "https://github.com/internetarchive/cicd/blob/main/.github/workflows/cicd.yml"
    click README "https://github.com/internetarchive/cicd/blob/main/README.md"
    click License "https://github.com/internetarchive/cicd/tree/main/LICENSE"
    click Config "https://github.com/internetarchive/cicd/blob/main/_config.yml"
    click WorkflowsDir "https://github.com/internetarchive/cicd/tree/main/.github/workflows"

    classDef github fill:#cceeff,stroke:#339,stroke-width:1px
    classDef registry fill:#ccffcc,stroke:#393,stroke-width:1px
    classDef process fill:#eef5ff,stroke:#559,stroke-width:1px
    classDef external fill:#ffd8b1,stroke:#e65c00,stroke-width:1px
```
