# nsiow/yams architecture

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

- Interactive diagram: https://gitdiagram.com/nsiow/yams
- Repository: https://github.com/nsiow/yams

## Overview

##### Project type and purpose
- This is a Go-based simulation tool (“yams”) for AWS IAM, exposing both a CLI (multiple subcommands) and an HTTP API/server.
- Its purpose is to load IAM configuration (from AWS Config dumps, JSON files, etc.), build an in-memory model (“universe”) of AWS IAM entities, and run permission simulations.

##### File structure
- Top-level “cmd/yams” directory holds entrypoints for subcommands:
- cli/… implements the interactive CLI, flag parsing, logging, ASCII art, and invoking each command
- dump, inventory, sim, status, server subdirectories contain subcommand drivers
- “pkg/…” holds reusable packages:
- pkg/server – HTTP routing, handlers, API v1 endpoints, healthchecks
- pkg/sim – the simulation engine, decision logic, tracing, gates
- pkg/loaders – AWS Config loader adapter
- pkg/policy, pkg/entities, pkg/aws – domain model for IAM policy, entities, AWS types
- “internal/…” holds implementation details not exposed as part of public API:
- internal/assets – embedded policy/managed-policy JSON
- internal/smartrw – I/O abstractions for gzip, S3, stdout
- internal/log, internal/common, internal/testlib – support libs and tests
- “misc/…” contains cloudformation templates and helper scripts.
- Configuration and orchestration: Makefile, CI workflows, go.mod, testdata for unit and integration tests.

##### Additional README insights
- Confirms it is a simulation tool for AWS IAM.

a. Main components (group into logical layers):
1. Presentation Layer
- CLI Frontend (cmd/yams/cli + subcommands: dump, inventory, sim, status)
- REST API Server (cmd/yams/server → pkg/server)
2. Application Core
- Simulation Engine (pkg/sim)
- Universe Builder (pkg/entities + loaders)
- Policy Evaluator (pkg/policy)
3. Infrastructure & Adapters
- AWS Config Loader adapter (pkg/loaders/awsconfig)
- I/O adapters: S3 Reader/Writer, gzip, stdout (internal/smartrw)
- Embedded asset provider (internal/assets)
- Logging (internal/log), common utilities (internal/common)
4. Data & External Services
- AWS Config files (JSON, JSONL, gzipped)
- AWS APIs (for live data, optional)
- CloudFormation templates (misc/cf-templates)

b. Relationships & interactions
- CLI/Server → calls into Application Core
- Simulation Engine uses:
- Universe Builder to load and construct IAM entity graph
- Policy Evaluator to run decision logic on that graph
- Adapters supply data:
- AWS Config Loader reads JSON/JSONL → Entities
- smartrw abstracts reading from file/S3/gzip
- internal/assets supplies bundled policies
- Server handlers wrap the same core logic to serve HTTP requests (list, get, sim, search).

c. Architectural patterns & design principles
- Layered (onion/hexagonal) architecture: core logic isolated from I/O & UI
- Dependency inversion: core depends on interfaces (loaders, readers), implementations live in adapters
- Single binary delivering CLI + HTTP server
- Reuse of packages: “pkg/…” for public APIs, “internal/…” for private helpers

d. Key technologies/frameworks
- Go modules, standard net/http for the server
- Cobra or custom flag parsing in cli/flags.go
- gzip, AWS SDK abstractions for config ingestion
- Go’s embed-style asset bundling (internal/assets)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interfaces Layer
    subgraph "User Interfaces"
        CLI["CLI Frontend"]:::ui
        Dump["dump"]:::ui
        Inventory["inventory"]:::ui
        SimCmd["sim"]:::ui
        Status["status"]:::ui
        CLI -->|invokes| Dump
        CLI -->|invokes| Inventory
        CLI -->|invokes| SimCmd
        CLI -->|invokes| Status

        HTTPServer["HTTP API Server"]:::ui
    end

    %% Application Core Layer
    subgraph "Application Core"
        UB["Universe Builder"]:::core
        SE["Simulation Engine"]:::core
        PE["Policy Evaluator"]:::core
        UB -->|provides entity graph| SE
        PE -->|evaluates policies| SE
    end

    %% Infrastructure & Adapters Layer
    subgraph "Infrastructure & Adapters"
        AWSLoader["AWS Config Loader"]:::infra
        IOAdapters["I/O Adapters"]:::infra
        Assets["Embedded Policy Assets"]:::infra
        Logging["Logging Library"]:::infra
        Common["Common Utilities"]:::infra

        IOAdapters -->|reads gz/jsonl| AWSLoader
        AWSLoader -->|loads entities| UB
        Assets -->|bundles policies| UB
    end

    %% Data & External Services Layer
    subgraph "Data & External Services"
        ConfigFiles["AWS Config Files"]:::data
        AWSAPI["AWS APIs (optional)"]:::data
        CFTemplates["CloudFormation Templates"]:::data
        ConfigFiles -->|source data| AWSLoader
        AWSAPI -->|live data| AWSLoader
    end

    %% Cross-layer interactions
    Dump -->|CLI call| SE
    Inventory -->|CLI call| UB
    SimCmd -->|CLI call| SE
    Status -->|CLI call| UB
    HTTPServer -->|HTTP requests| SE

    %% Shared dependencies
    Logging --> CLI
    Logging --> HTTPServer
    Logging --> SE
    Common --> CLI
    Common --> HTTPServer
    Common --> SE

    %% Click Events
    click CLI "https://github.com/nsiow/yams/tree/main/cmd/yams/cli"
    click Dump "https://github.com/nsiow/yams/tree/main/cmd/yams/dump"
    click Inventory "https://github.com/nsiow/yams/tree/main/cmd/yams/inventory"
    click SimCmd "https://github.com/nsiow/yams/tree/main/cmd/yams/sim"
    click Status "https://github.com/nsiow/yams/tree/main/cmd/yams/status"
    click HTTPServer "https://github.com/nsiow/yams/blob/main/cmd/yams/server/server.go"
    click AWSLoader "https://github.com/nsiow/yams/tree/main/pkg/loaders/awsconfig"
    click IOAdapters "https://github.com/nsiow/yams/tree/main/internal/smartrw"
    click Assets "https://github.com/nsiow/yams/tree/main/internal/assets"
    click Logging "https://github.com/nsiow/yams/tree/main/internal/log"
    click Common "https://github.com/nsiow/yams/tree/main/internal/common"
    click UB "https://github.com/nsiow/yams/blob/main/pkg/entities/universe_builder.go"
    click SE "https://github.com/nsiow/yams/tree/main/pkg/sim"
    click PE "https://github.com/nsiow/yams/tree/main/pkg/policy"
    click CFTemplates "https://github.com/nsiow/yams/tree/main/misc/cf-templates"
    click ConfigFiles "https://github.com/nsiow/yams/tree/main/pkg/server/api/v1"
    click ConfigFiles "https://github.com/nsiow/yams/blob/main/pkg/server/route.go"
    click ConfigFiles "https://github.com/nsiow/yams/blob/main/pkg/server/server.go"
    click ConfigFiles "https://github.com/nsiow/yams/blob/main/pkg/server/healthcheck.go"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000
    classDef core fill:#90EE90,stroke:#000
    classDef infra fill:#FFA500,stroke:#000
    classDef data fill:#D3D3D3,stroke:#000
```
