How janstuemmel/aws-role-switch works
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.