# common-fate/granted architecture

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

- Interactive diagram: https://gitdiagram.com/common-fate/granted
- Repository: https://github.com/common-fate/granted

## Overview

Based on our analysis of the file tree and the README, it’s clear that Granted is a Go-based CLI tool whose primary purpose is to simplify cloud access—primarily for AWS—by managing role assumption, credential caching, and even launching multiple cloud accounts simultaneously in the browser. In addition to its CLI capabilities, the project includes a modular layout with packages dedicated to browser integration, secure storage, cloud API interactions, and configuration.

##### Main Components
- CLI/Entry Points: Represent the command entry files under the “cmd” directory. There are at least two main entry points:
– The core “granted” CLI (cmd/granted) and
– Testing and auxiliary commands (cmd/testing).
- Core Business Logic and Libraries: Represent the many sub-packages in “pkg” (e.g., pkg/assume, pkg/granted, pkg/browser, pkg/cfaws, pkg/securestorage). These encapsulate the various functionalities such as:
– Role assumption and SSO logic (pkg/assume, pkg/granted/sso.go)
– AWS integration (pkg/cfaws)
– Browser integration for multi-account access (pkg/browser)
– Secure storage operations (pkg/securestorage)
– Caching and configuration (pkg/cache, pkg/config, pkg/cfcfg)
- Build and Versioning: The “internal/build” package handles version and configuration details that can be shown as part of the build process.
- Testing/Utilities: Acknowledge that there are helper scripts (in the “scripts” folder) and a “cmd/testing” directory for integration or system testing.
- External Dependencies and CI/CD: Include GitHub Actions workflows (from the “.github/workflows” directory) as an external process for continuous integration and testing.

##### Relationships and Data Flow
- The CLI layer (cmd directories) receives user input and then calls into the core libraries (pkg/*) for business logic.
- For role assumption and credential management, the CLI routes commands to modules in pkg/assume and pkg/granted, which further communicate with the AWS integration modules in pkg/cfaws.
- Browser interactions, to open multiple cloud roles simultaneously, are handled in pkg/browser and are triggered by commands from cmd.
- Secure storage for credentials and SSO tokens (in pkg/securestorage) works hand-in-hand with the authentication and caching modules.
- The caching system (pkg/cache) captures temporary state that might be used by both the CLI and the auto-sync mechanisms (pkg/autosync).

##### Architectural Patterns
- Separation of Concerns: Notice the clear separation between command-line interface logic, business logic, and platform-dependent integration.
- Modular Design: Each pkg sub-directory encapsulates a distinct domain (e.g., AWS API integration, browser detection, credential management) so that changes in one module do not directly affect the others.
- Extensibility: The project’s modular structure and the presence of hooks (e.g., pkg/hook/accessrequesthook) suggest that it’s designed for future extension and integration with additional cloud providers or additional features.

##### Incorporate Relevant Technology and Tools
- GitHub Actions: Represent CI/CD pipelines and workflows from the “.github” directory.
- Build Tools: Makefile and the “internal/build” package denote the build/version control process.
- Configuration Management: Include the configuration components (from pkg/config, pkg/cfcfg) as they are crucial for aligning different system parts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        A["Granted CLI (cmd/granted)"]
        B["Testing & Aux Commands (cmd/testing)"]
    end

    %% Business Logic
    subgraph "Business Logic"
        C["Role Assumption & SSO (pkg/assume)"]
        D["AWS Integration (pkg/cfaws)"]
        E["Secure Storage (pkg/securestorage)"]
        F["Credential Caching & Config (pkg/cache, pkg/config, pkg/cfcfg)"]
    end

    %% Browser & Platform Integration
    subgraph "Browser & Platform Integration"
        G["Browser Integration (pkg/browser)"]
    end

    %% Build/CI & Testing
    subgraph "Build/CI & Testing"
        H["Build & Versioning (internal/build)"]
        I["CI/CD Pipelines (.github/workflows)"]
        J["Testing & Utilities (scripts & cmd/testing)"]
    end

    %% Connections: CLI Layer to Business Logic and Browser
    A -->|"executes"| C
    A -->|"executes"| F
    A -->|"triggers"| G

    %% Business Logic interactions
    C -->|"invokes"| D
    C -->|"stores tokens in"| E
    F -->|"interacts with"| E

    %% Testing relationship
    B -->|"triggers tests"| J

    %% Build info and CI/CD
    H -->|"builds"| A
    I -->|"runs"| J

    %% Styles for CLI Layer
    class A,B cli
    classDef cli fill:#AED6F1,stroke:#3498DB,stroke-width:2px;

    %% Styles for Business Logic
    class C,D,E,F business
    classDef business fill:#A9DFBF,stroke:#28B463,stroke-width:2px;

    %% Styles for Browser Integration
    class G browser
    classDef browser fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;

    %% Styles for Build/CI & Testing
    class H,I,J build
    classDef build fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;

    %% Click Events
    click A "https://github.com/common-fate/granted/blob/main/cmd/granted/main.go"
    click B "https://github.com/common-fate/granted/tree/main/cmd/testing/"
    click C "https://github.com/common-fate/granted/tree/main/pkg/assume/"
    click D "https://github.com/common-fate/granted/tree/main/pkg/cfaws/"
    click E "https://github.com/common-fate/granted/tree/main/pkg/securestorage/"
    click F "https://github.com/common-fate/granted/tree/main/pkg/cache/"
    click G "https://github.com/common-fate/granted/tree/main/pkg/browser/"
    click H "https://github.com/common-fate/granted/tree/main/internal/build/"
    click I "https://github.com/common-fate/granted/tree/main/.github/workflows/"
    click J "https://github.com/common-fate/granted/tree/main/scripts/"
```
