# wakeful/veil architecture

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

- Interactive diagram: https://gitdiagram.com/wakeful/veil
- Repository: https://github.com/wakeful/veil

## Overview

##### Project type and purpose
- This is a standalone command‐line tool (written in Go) that queries AWS IAM to expose trust relationships (who can assume which roles) and emits a JSON report.
- There is no frontend or persistent datastore—its sole job is to call AWS APIs, process the results, and print JSON to stdout.

##### File structure
- Top‐level Go module (go.mod, go.sum) with source files:
- main.go        → CLI entrypoint and flag parsing
- types.go       → domain types for principals, roles, trust graphs
- utils.go       → core logic: AWS SDK calls + data transformation
- utils_test.go  → unit tests for utility functions
- tools/ directory → secondary Go module, likely for build tools or optional subcommands
- CI/CD and release artifacts:
- .github/workflows/release.yml → GitHub Actions for build/test/release
- goreleaser.yml → automated binary packaging
- golangci.yaml, .pre-commit-config.yaml → linting & pre-commit checks

##### README for additional insights
- Uses the AWS Go SDK under the hood
- Outputs a map from “principal” → list of “roles they can assume”
- Designed for quick auditing via CLI, pipelines, or piping to jq

##### Main components
a. CLI Layer
- Flag parser (region, verbose, version)
- Invocation by user or CI/CD
b. AWS Communication Layer
- AWS SDK IAM client
- Authentication/credentials resolution (env vars, static creds, EC2/assume-role)
- API calls: ListRoles, ListPolicies, GetRolePolicy, etc.
c. Data Processing Layer
- Graph builder that maps “who trusts whom”
- Filtering/aggregation logic
d. Output Layer
- JSON marshalling
- Stdout writer, exit codes
e. DevOps/CI Pipeline (external)
- GitHub Actions (lint, test, release)
- GoReleaser produces cross-platform binaries
- Optional tools/ subproject

##### Relationships and data flow
- User invokes `veil` → CLI Layer parses flags → AWS SDK client fetches IAM data → passes raw data to the Data Processing Layer → builds trust graph → JSON Formatter serializes graph → CLI writes to stdout.
- CI/CD pipeline invokes tests & linters against the same codebase and triggers GoReleaser on tagged commits.

##### Architectural patterns and design principles
- Single‐binary micro‐CLI: minimal external dependencies
- Clear separation of concerns:
- main.go only handles I/O and flag parsing
- utils.go + types.go encapsulate business logic and domain models
- utils_test.go ensures core logic correctness
- Infrastructure as Code for releases (Goreleaser) and CI (GitHub Actions)

##### Relevant technologies and frameworks
- Go (modules, standard library)
- AWS Go SDK (IAM service client)
- GoReleaser for releases
- golangci-lint, pre-commit hooks

- Use clear labels on each component (e.g., “Flag Parser”, “IAM Client”, “Graph Builder”)
- Input flow (User → CLI)
- API calls (CLI → AWS IAM)
- Data flow (IAM → Processor → JSON Output)
- Blue rectangles for runtime modules
- Orange documents for artifacts (JSON output)

##### Final advice
- Be exhaustive in naming each functionally distinct piece: entrypoint, credential resolution, API interaction, processing, output.
- Dev tooling (linters, tests) as part of the architecture—this shows how quality is enforced.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Execution Layer
    subgraph "Runtime Execution"
        CLI["Flag Parser & Entrypoint"]:::runtime
        Cred["Credential Resolver"]:::runtime
        IAMClient["IAM Client & API Calls"]:::runtime
        Graph["Graph Builder & Aggregation Logic"]:::runtime
        JSONFmt["JSON Formatter"]:::runtime
        Stdout["Stdout Writer"]:::runtime
    end

    %% External Service
    AWS["AWS IAM Service"]:::external

    %% Output Artifact
    JSONOut["JSON Output"]:::artifact

    %% DevOps Pipeline
    subgraph "DevOps Pipeline"
        GHAction["GitHub Actions"]:::devops
        Lint["golangci-lint"]:::devops
        PreCommit["Pre-commit Hooks"]:::devops
        UnitTests["Unit Tests (utils_test.go)"]:::devops
        GoRel["GoReleaser"]:::devops
        Tools["Tools Submodule"]:::devops
    end

    %% Runtime Flow
    User["User/CI Invocation"]:::external -->|invokes| CLI
    CLI -->|resolves creds| Cred
    Cred -->|uses SDK| IAMClient
    IAMClient -->|ListRoles,GetRolePolicy| AWS
    AWS -->|returns IAM Data| IAMClient
    IAMClient -->|raw data| Graph
    Graph -->|trust graph| JSONFmt
    JSONFmt -->|serialized JSON| Stdout
    Stdout -->|writes| JSONOut

    %% DevOps Flow
    GHAction -->|runs| Lint
    GHAction -->|runs| UnitTests
    GHAction -->|triggers| GoRel
    GHAction -->|validates| PreCommit
    Tools -->|provides| GHAction

    %% Click Events
    click CLI "https://github.com/wakeful/veil/blob/main/main.go"
    click DM "https://github.com/wakeful/veil/blob/main/types.go"
    click IAMClient "https://github.com/wakeful/veil/blob/main/utils.go"
    click Graph "https://github.com/wakeful/veil/blob/main/utils.go"
    click JSONFmt "https://github.com/wakeful/veil/blob/main/utils.go"
    click UnitTests "https://github.com/wakeful/veil/blob/main/utils_test.go"
    click Tools "https://github.com/wakeful/veil/tree/main/tools/"
    click GHAction "https://github.com/wakeful/veil/blob/main/.github/workflows/release.yml"
    click GoRel "https://github.com/wakeful/veil/blob/main/.goreleaser.yml"
    click Lint "https://github.com/wakeful/veil/blob/main/.golangci.yaml"
    click PreCommit "https://github.com/wakeful/veil/blob/main/.pre-commit-config.yaml"

    %% Styles
    classDef runtime fill:#bbdefb,stroke:#000,stroke-width:1px
    classDef external fill:#c8e6c9,stroke:#000,stroke-width:1px
    classDef artifact fill:#ffecb3,stroke:#000,stroke-width:1px
    classDef devops fill:#e0e0e0,stroke:#000,stroke-width:1px
```
