# azure/bicep-deploy architecture

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

- Interactive diagram: https://gitdiagram.com/azure/bicep-deploy
- Repository: https://github.com/azure/bicep-deploy

## Overview

##### Project Type and Purpose
- This is an open-source GitHub Action for managing Azure infrastructure deployments via ARM Templates or Bicep files.
- It acts as a wrapper around Azure Resource Manager (ARM) deployments, offering “create,” “validate,” “what-if,” and “delete” operations at various scopes (tenant, subscription, resource group, etc.).
- It is not a full-stack web app; rather, it’s a CI/CD integration tool that plugs into GitHub workflows and talks to Azure APIs.

##### File Structure Analysis
- Top-level:
- action.yml → Action metadata, inputs/outputs
- src/ → TypeScript source: entry points and helpers
- dist/ → Compiled JavaScript shipped to npm
- examples/ → Usage examples in GitHub YAML
- scripts/ → CI / release scripts
- test-live/ & test/ → Live integration and unit tests
- Key source modules in src/:
- index.ts & main.ts → orchestration
- handler.ts → GitHub Actions toolkit integration
- config.ts & helpers/input.ts → parse and validate user inputs
- helpers/file.ts → read ARM/Bicep files
- helpers/azure.ts → call Azure REST/SDK for deployments
- helpers/whatif.ts → preview change sets
- helpers/logging.ts → structured logs

##### README Insights
- Describes inputs (type, operation, scope, template-file, parameters-file, what-if options, unmanaged-resource actions, deny settings).
- Shows the action is invoked in a GitHub workflow and depends on azure/login and actions/checkout.
- Explains outputs are captured and exported back to later steps.

##### Main Components & Interactions
a. GitHub Actions Runner
- Reads action.yml, checks out code, authenticates using azure/login.
- Loads the compiled action (dist/index.js).
b. Action Entrypoint
- handler.ts invokes main.ts via GitHub Actions toolkit.
- config.ts reads and validates inputs from action.yml context.
c. Core Engine
- file.ts loads the template and parameter files from the workspace.
- whatif.ts optionally runs a “What-If” API call to ARM.
- azure.ts performs the create/validate/delete operations via Azure REST or SDK.
d. Outputs & Logging
- logging.ts standardizes console output.
- After deployment, outputs (resource IDs, endpoints, etc.) are captured and set as step outputs.
e. External Dependencies
- Azure Resource Manager (ARM) REST API or Azure SDK
- GitHub Actions toolkit (actions/core)
- Node.js runtime on the runner

##### Architectural Patterns & Principles
- Layered structure:
- Ingress layer: ﹣action.yml + handler.ts (reads inputs).
- Application layer: ﹣main orchestration (main.ts).
- Service layer: ﹣azure.ts, whatif.ts (calls external Azure APIs).
- Utility layer: ﹣file.ts, input.ts, logging.ts.
- Modularity: helpers grouped by concern (file, azure, what-if, logging, input).
- Single Responsibility: each module does one thing (parse, read, call, log).

- Clear labels on each component (module name + responsibility).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    Runner["GitHub Actions Runner"]:::external
    Toolkit["GitHub Actions toolkit\n(actions/core)"]:::external
    ARMAPI["Azure Resource Manager API"]:::external

    %% Packaged Action
    PackagedJS["Packaged JavaScript\n(dist/)"]:::external
    click PackagedJS "https://github.com/azure/bicep-deploy/tree/main/dist/"

    %% Azure Deployment Action Container
    subgraph "Azure Deployment Action"
        direction TB
        EntryProxy["Action Entry Proxy\n(src/index.ts)"]:::ingress
        Handler["Entrypoint Handler\n(src/handler.ts)"]:::ingress
        Main["Main Orchestration Engine\n(src/main.ts)"]:::core
        Config["Inputs Parser\n(src/config.ts)"]:::ingress
        InputHelper["Inputs Helper\n(src/helpers/input.ts)"]:::ingress
        FileLoader["File Loader\n(src/helpers/file.ts)"]:::core
        WhatIf["What-If Engine\n(src/helpers/whatif.ts)"]:::core
        DeployEngine["Deployment Engine\n(src/helpers/azure.ts)"]:::core
        Logger["Logging Utility\n(src/helpers/logging.ts)"]:::util
    end

    %% Examples and Tests (outside flow)
    Examples["Usage Examples\n(examples/)"]:::doc
    UnitTests["Unit Tests\n(test/)"]:::doc
    LiveTests["Live Integration Tests\n(test-live/)"]:::doc

    %% Relationships
    Runner --> PackagedJS
    PackagedJS --> Toolkit
    Toolkit --> EntryProxy
    EntryProxy --> Handler
    Handler --> Config --> InputHelper
    Handler --> Main
    Main --> FileLoader -->|"reads templates"| FileLoader
    Main --> WhatIf -->|"calls What-If API"| ARMAPI
    Main --> DeployEngine -->|"calls ARM REST/SDK"| ARMAPI
    Main --> Logger -->|"writes logs"| Runner
    DeployEngine -->|"returns outputs"| Handler

    %% Click Events
    click Runner "https://github.com/azure/bicep-deploy/blob/main/action.yml"
    click Toolkit "https://github.com/azure/bicep-deploy/tree/main/node_modules/actions-core"
    click EntryProxy "https://github.com/azure/bicep-deploy/blob/main/src/index.ts"
    click Handler "https://github.com/azure/bicep-deploy/blob/main/src/handler.ts"
    click Main "https://github.com/azure/bicep-deploy/blob/main/src/main.ts"
    click Config "https://github.com/azure/bicep-deploy/blob/main/src/config.ts"
    click InputHelper "https://github.com/azure/bicep-deploy/blob/main/src/helpers/input.ts"
    click FileLoader "https://github.com/azure/bicep-deploy/blob/main/src/helpers/file.ts"
    click WhatIf "https://github.com/azure/bicep-deploy/blob/main/src/helpers/whatif.ts"
    click DeployEngine "https://github.com/azure/bicep-deploy/blob/main/src/helpers/azure.ts"
    click Logger "https://github.com/azure/bicep-deploy/blob/main/src/helpers/logging.ts"
    click Examples "https://github.com/azure/bicep-deploy/tree/main/examples/"
    click UnitTests "https://github.com/azure/bicep-deploy/tree/main/test/"
    click LiveTests "https://github.com/azure/bicep-deploy/tree/main/test-live/"

    %% Styles
    classDef ingress fill:#cce5ff,stroke:#000,stroke-width:1px;
    classDef core fill:#d4edda,stroke:#000,stroke-width:1px;
    classDef util fill:#e2e3e5,stroke:#000,stroke-width:1px;
    classDef external fill:#ffe5b4,stroke:#000,stroke-width:1px;
    classDef doc fill:#f8d7da,stroke:#000,stroke-width:1px;
```
