# janstuemmel/aws-role-switch architecture

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

- Interactive diagram: https://gitdiagram.com/janstuemmel/aws-role-switch
- Repository: https://github.com/janstuemmel/aws-role-switch

## Overview

##### Main Components
- Browser Extension Shell: Represent the overall extension which ties all the pieces together.
- Content Scripts (src/content): Scripts injected into AWS web pages (e.g., aws-console.ts, aws-signin.ts). They handle direct interactions with the AWS pages (reading tokens/CSRF, modifying forms) and forward messages between the page and the extension.
- Background Scripts (src/background): These handle long-running tasks, message passing, and event listeners for configuration changes or browser events. They include separate handlers (e.g., getMappedConfig, redirectListener) for processing background events.
- Popup UI (src/popup): The user-facing component (defined in popup.tsx, its SCSS, and helper components like RoleItem and SectionList) that appears when the user triggers the shortcut (Ctrl+Shift+L). This module handles role selection and navigation.
- Options / Config Editor Page (src/options): Provides a UI (with editing and live preview in React/TSX) for editing the AWS role configuration in an INI-like syntax. It includes its own editor components and hooks.
- Common Modules (src/common): These contain shared logic, including:
- Config parsers and mappers for handling and validating the INI configuration file.
- Browser utilities for interacting with cookies, runtime, tabs, and storage.
- Reusable UI components (like AWSIcon) and hooks (for theme changes or key events).
- Build and Manifest Generation (src/build and manifest files): This area includes scripts and plugins that generate the final manifest files for both Chrome and Firefox (src/manifest.chrome.ts, src/manifest.firefox.ts) along with build plugins (like writeManifest.ts).

##### Relationships & Interactions
- The Options page and Popup are separate UI parts of the extension but share the same common modules (like configuration parsers and hooks for browser storage).
- The Background scripts act as a central message router and state manager, coordinating data (like configuration changes) between the content scripts, popup, and options page.
- Content scripts modify AWS pages and invoke the background handlers when a role switch event is triggered. They might also send messages to the popup.
- The build process combines all of these components and generates the appropriate extension bundles, ensuring that the manifest files are correctly configured based on the target browser.

##### Architectural Patterns & Design Principles
- Separation of Concerns: There is a clear division between background, content, popup, and options which aligns with a common browser extension pattern.
- Reuse & Modularity: The "common" directory houses all shared utilities, components, and hooks to promote reuse and reduce redundancy.
- Event-Driven Architecture: The extension uses events and messaging (from keyboard shortcuts in the popup and message passing in the background) to trigger role switching.
- Build Abstraction: The build scripts and manifest configuration abstractions indicate that the project is designed to support multiple targets (Chrome, Firefox) with minimal repeated configuration.

- At the top level, show the Browser (target platform) and within it, the extension container encapsulating all runtime components.
- Under the extension container, list:
- The Background Process as the central orchestrator.
- The Popup UI as the overlay for user interactions.
- The Options Page for configuration modification.
- The Content Scripts injected into AWS pages.

## Diagram (Mermaid)

```mermaid
graph TD
    User("User"):::user

    BrowserShell("Browser Extension Shell"):::shell

    Background("Background Scripts"):::runtime
    Content("Content Scripts"):::runtime
    Popup("Popup UI"):::ui
    Options("Options / Config Editor"):::ui
    Common("Common Modules"):::common
    Build("Build & Manifest Generation"):::build

    %% User Interaction
    User -->|"triggers"| Popup

    %% UI to Background communication
    Popup -->|"sendsMessage"| Background
    Options -->|"updatesConfig"| Background

    %% Background initiates role switching on AWS page
    Background -->|"roleSwitch"| Content

    %% Common Modules shared across components (bidirectional)
    Common <--> Background
    Common <--> Popup
    Common <--> Options
    Common <--> Content

    %% Browser Extension Shell encapsulates runtime components
    BrowserShell --> Background
    BrowserShell --> Popup
    BrowserShell --> Options
    BrowserShell --> Content
    BrowserShell --> Common

    %% Build process produces the final extension bundle
    Build -->|"builds"| BrowserShell

    %% Click Events
    click BrowserShell "https://github.com/janstuemmel/aws-role-switch/tree/master/src"
    click Content "https://github.com/janstuemmel/aws-role-switch/tree/master/src/content"
    click Background "https://github.com/janstuemmel/aws-role-switch/tree/master/src/background"
    click Popup "https://github.com/janstuemmel/aws-role-switch/tree/master/src/popup"
    click Options "https://github.com/janstuemmel/aws-role-switch/tree/master/src/options"
    click Common "https://github.com/janstuemmel/aws-role-switch/tree/master/src/common"
    click Build "https://github.com/janstuemmel/aws-role-switch/tree/master/src/build"

    %% Styles
    classDef ui fill:#FFDDC1,stroke:#F66,stroke-width:2px;
    classDef runtime fill:#C1E1FF,stroke:#036,stroke-width:2px;
    classDef common fill:#C1FFC1,stroke:#0A0,stroke-width:2px;
    classDef build fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
    classDef shell fill:#E6E6FA,stroke:#800080,stroke-width:2px;
    classDef user fill:#FFB6C1,stroke:#FF1493,stroke-width:2px;
```
