# viasat/alohomora architecture

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

- Interactive diagram: https://gitdiagram.com/viasat/alohomora
- Repository: https://github.com/viasat/alohomora

## Overview

##### Project Type and Purpose
- The project is a CLI utility written in Python.
- Its purpose is to help SAML-federated users obtain AWS API keys by authenticating with an Identity Provider and optionally using MFA (e.g., Duo Security or WebAuthN).
- The README outlines several usage patterns, configuration options, and even integration scenarios (like custom configuration profiles and AWS partition selection), indicating a focus on both security and flexibility.

##### File Structure and Key Components
- The top-level directories/files indicate:
- The main application code under the "alohomora" directory, including the primary entry point (main.py) and modules for handling SAML (saml.py), AWS key generation (keys.py), and request flow (req.py).
- Build and packaging support through setup.py and setup.cfg.
- Specs in the “specs” directory, representing package metadata or distribution requirements.
- CI/CD configuration in the ".github/workflows" directory, hinting that automated testing and package publishing are in place.
- This structure reinforces that the project is highly modular, with distinct responsibilities spread across multiple modules.

##### Key Components
a. Main Application Flow:
- CLI Entry: Represented by alohomora/main.py (where command-line input is handled).
- Configuration Loader: Loads user config from ~/.alohomora and/or parses CLI parameters.
- SAML Authentication: Implemented using alohomora/saml.py, responsible for handling the SAML authentication flow.
- MFA Integration: For additional security through Duo and optional WebAuthN (this may branch out from SAML when MFA is required).
- Request Handling: Managed by alohomora/req.py to process SAML responses and determine the roles/accounts.
- AWS Credentials: Finally, handled through alohomora/keys.py to store the AWS API keys in the appropriate location.

b. Build & Integration Block:
- Packaging: Reflect the role of setup.py and setup.cfg in assembling and publishing the software.
- Specs: Represented by the “specs” directory, which may contain distribution or spec files.
- CI/CD Integration: Illustrated by the presence of GitHub Actions workflows (python-publish.yml) that automate tests and deployment processes.

##### Relationships and Interactions
- The user initiates the process via the CLI which then goes through a series of steps:
- User → CLI Entry Point (main.py)
- Main.py loads configurations and calls SAML authentication.
- In the SAML module, if multi-factor authentication is required, the flow branches to the MFA module (Duo/WebAuthN) which then returns control.
- SAML then calls the request handler, and based on the response, the keys module manages AWS credential processing.
- On the “build & integration” side, packaging components and CI/CD tools ensure quality and smooth deployment flows.

##### Incorporating the Provided Flowchart

Flowchart Breakdown:
- Flow from the User to the CLI Entry Point (alohomora/main.py) with a label such as “invokes”.
- From the CLI, illustrate the two parallel flows: one to load configuration (from ~/.alohomora and CLI parameters) and the other to initiate SAML.
- From the SAML component, if MFA is triggered, show the branch to “MFA Integration (Duo/WebAuthN)” and back.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external
    CLI["CLI Entry Point (alohomora/main.py)"]:::cli
    Config["Config Loader (~/.alohomora & CLI Params)"]:::config
    SAML["SAML Authentication (alohomora/saml.py)"]:::auth
    MFA["MFA Integration (Duo/WebAuthN)"]:::mfa
    Req["Request Handling (alohomora/req.py)"]:::req
    AWS["AWS Credentials (alohomora/keys.py)"]:::aws

    User -->|"invokes"| CLI
    CLI -->|"loads"| Config
    CLI -->|"initiates"| SAML
    SAML -->|"ifMFA"| MFA
    MFA -->|"returns"| SAML
    SAML -->|"calls"| Req
    Req -->|"processes"| AWS

    subgraph "Build & Integration"
        Pack["Packaging (setup.py, setup.cfg)"]:::pack
        Specs["Specs (specs/)"]:::pack
        CI["CI/CD Integration (.github/workflows/python-publish.yml)"]:::ci
        Pack --> Specs
    end

    click CLI "https://github.com/viasat/alohomora/blob/master/alohomora/main.py"
    click SAML "https://github.com/viasat/alohomora/blob/master/alohomora/saml.py"
    click Req "https://github.com/viasat/alohomora/blob/master/alohomora/req.py"
    click AWS "https://github.com/viasat/alohomora/blob/master/alohomora/keys.py"
    click Pack "https://github.com/viasat/alohomora/blob/master/setup.py"
    click Specs "https://github.com/viasat/alohomora/tree/master/specs/"
    click CI "https://github.com/viasat/alohomora/blob/master/.github/workflows/python-publish.yml"

    classDef external fill:#ffd1dc,stroke:#cc3366,stroke-width:2px;
    classDef cli fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef config fill:#d6e9c6,stroke:#3c763d,stroke-width:2px;
    classDef auth fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef mfa fill:#fef2cc,stroke:#8a6d3b,stroke-width:2px;
    classDef req fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef aws fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef pack fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef ci fill:#d1c4e9,stroke:#4a148c,stroke-width:2px;
```
