# flosell/iam-policy-json-to-terraform architecture

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

- Interactive diagram: https://gitdiagram.com/flosell/iam-policy-json-to-terraform
- Repository: https://github.com/flosell/iam-policy-json-to-terraform

## Overview

##### Project type and purpose
- This is a hybrid open-source tool combining:
– A command-line interface (CLI) utility (`iam-policy-json-to-terraform`) written in Go
– A static web frontend (HTML/JS/CSS) that uses the same conversion logic compiled to JavaScript
– A minimal Go HTTP server (`web/web.go`) to serve the web UI locally
- The core purpose is to convert AWS IAM Policy documents in JSON into Terraform `aws_iam_policy_document` blocks.

##### File structure
- Top-level files
– `iam-policy-json-to-terraform.go`: CLI entrypoint
– `converter/`: Go package containing `decode.go`, `convert.go`, `encode.go` + unit tests
– `web/`: static frontend assets (HTML, CSS, JavaScript), TestCafe e2e tests, and `web.go` server
– `scripts/`: deployment and release automation (GitHub Pages, releases, README sanity tests)
– `.github/workflows`: CI pipelines (build, test, security scans)
– `go` script and `go.mod`: central build/test tool
- Patterns
– Library-core (`converter`) is reused by both CLI and web
– Separation of concerns:
- Core conversion logic (Go package)
- CLI wrapper
- Web UI (static assets + compiled JS)
- Deployment artifacts
– CLI binary for multiple platforms (built via CI, released to GitHub)
– Static site published to GitHub Pages

##### Review README insights
- Describes both CLI usage (stdin/stdout) and web deployment
- Defines development workflow via `./go` commands for building, testing, linting, web build, and deploy
- Mentions TestCafe e2e tests in `web_test.js` and browser automation for visual regression

##### Elements
- CLI application
- Web UI (static assets + JS converter)
- Conversion library (`converter` package)
- Local HTTP server (`web/web.go`)
- CI/CD pipeline (GitHub Actions)
- Hosting (GitHub Pages, GitHub Releases)
- Data flow from user input → converter → output
- Build flow from source code → binaries/JS → deployment targets
- Test flows (unit tests, e2e tests)
- Core logic (e.g., blue)
- Interfaces (e.g., green)
- Infrastructure/CI (e.g., orange)
– Annotations for key scripts and workflows (e.g., `./go web-build`, `scripts/deploy-github-pages.sh`)

##### Detail
– Capture every layer: source code, build steps, interfaces, and deployments
– Reflect the reuse of the `converter` package in both CLI and web contexts
– Show how GitHub Actions automate testing and publishing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Interfaces
    Terminal["Terminal"]:::interface
    Browser["Web Browser"]:::interface

    subgraph "Source Code"
        CLIApp["CLI Application\n(iam-policy-json-to-terraform.go"]:::interface
        Converter["Core Conversion Library\n(converter/)"]:::core
        WebServer["Local HTTP Server\n(web/web.go)"]:::interface
        WebUI["Web UI Static Assets\n(index.html, app.css, app.js, img/)"]:::interface
        Tests["Tests\n(converter & web tests)"]:::infra
        Scripts["Release & Deploy Scripts\n(scripts/)"]:::infra
        CI["CI/CD Workflows\n(.github/workflows/)"]:::infra
        Tooling["Build Tool & Modules\n(go, go.mod)"]:::infra
    end

    subgraph "Build Process"
        BuildCLI["Build CLI Binary\n(`./go build`)"]:::infra
        BuildWebJS["Compile JS Module\n(`./go web-build`)"]:::infra
    end

    subgraph "Outputs"
        Binary["CLI Binary"]:::infra
        JSBundle["Web JS Bundle"]:::infra
    end

    subgraph "Hosting"
        Releases["GitHub Releases"]:::infra
        Pages["GitHub Pages"]:::infra
    end

    %% User interactions
    Terminal -->|runs| CLIApp
    Browser -->|visits| Pages
    Browser -->|visits| WebServer

    %% Source Code dependencies
    CLIApp -->|imports| Converter
    WebUI -->|bundles| Converter
    WebServer -->|serves| WebUI
    Tests -->|validate| Converter
    Tests -->|validate| WebServer
    CI -->|runs| Tooling
    CI -->|runs| Tests
    CI -->|runs| Scripts

    %% Build flows
    Tooling --> BuildCLI
    Tooling --> BuildWebJS
    Converter --> BuildCLI
    Converter --> BuildWebJS
    CLIApp --> BuildCLI
    WebUI --> BuildWebJS

    BuildCLI --> Binary
    BuildWebJS --> JSBundle

    %% Deployment
    Scripts --> Releases
    Scripts --> Pages

    %% Click Events
    click CLIApp "https://github.com/flosell/iam-policy-json-to-terraform/blob/master/iam-policy-json-to-terraform.go"
    click Converter "https://github.com/flosell/iam-policy-json-to-terraform/tree/master/converter/"
    click WebServer "https://github.com/flosell/iam-policy-json-to-terraform/blob/master/web/web.go"
    click WebUI "https://github.com/flosell/iam-policy-json-to-terraform/blob/master/web/index.html"
    click CI "https://github.com/flosell/iam-policy-json-to-terraform/blob/master/.github/workflows/main.yml"
    click Scripts "https://github.com/flosell/iam-policy-json-to-terraform/blob/master/scripts/deploy-github-pages.sh"
    click Tooling "https://github.com/flosell/iam-policy-json-to-terraform/blob/master/go.mod"

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff,stroke-width:2px;
    classDef interface fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef infra fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
```
