# 7836246/aws-builder-id architecture

> Architecture diagram of the GitHub repository 7836246/aws-builder-id, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/7836246/aws-builder-id
- Repository: https://github.com/7836246/aws-builder-id

## Overview

1. This repository is a Python 3.10+ automation tool for registering AWS Builder ID accounts. The architecture centers on a Selenium-based browser automation flow, with supporting modules for environment simulation, email verification, and proxy/IP control.

2. The top-level execution boundary is under `src/runners/`. These entrypoints orchestrate the full lifecycle: start a browser session, prepare the target locale/device/proxy environment, complete the signup flow, wait for verification, and persist the resulting account record. The presence of `main.py`, `single_outlook_run.py`, `batch_run.py`, and `smart_run.py` suggests multiple orchestration modes rather than multiple business domains.

3. Browser interaction is abstracted in `src/pages/`. `base_page.py` is the likely shared layer for Selenium page actions and synchronization, while the actual AWS Builder ID signup steps are driven from the runner/service side. This creates a clear separation between page mechanics and workflow orchestration.

4. The external account verification path is handled in `src/services/`. `email_service.py` is the abstraction for receiving verification codes, with the README indicating integration with a Cloudflare Worker-based temporary email service. `outlook_service.py` and `outlook_accounts.py` indicate an alternative email backend centered on Outlook/IMAP account handling.

5. Persistence of successful registrations appears to be handled as structured local output, likely via a JSONL account store. The README explicitly mentions `accounts.jsonl`, and the `services/outlook_accounts.py` file suggests account metadata management is part of the service layer rather than embedded in the runners.

6. Environment simulation is split into helper modules under `src/helpers/`. `fingerprint.py` covers browser fingerprint shaping such as CPU, memory, and WebGL characteristics. `multilang.py` and the `config/languages.yaml` file support locale-specific text handling. `ip_location.py` likely maps or validates the current IP geolocation against the target region. `utils.py` is the shared utility boundary for cross-cutting tasks.

7. Proxy control is isolated in `src/managers/`. `proxy_manager.py` handles static proxy and dynamic proxy API modes described in the README, while `whitelist_manager.py` suggests support for allowlisting or brokered access setup. This manager layer sits between runner logic and network configuration, keeping IP concerns separate from signup workflow code.

8. The configuration boundary is explicit in `config/config.yaml` and `config/languages.yaml`, and loaded through `src/config.py`. The main configuration controls email backend, region, device type, proxy mode, and wait timeouts. Language configuration gives the automation layer localized strings for region-specific flows.

9. Region and device selection are first-class concerns in the architecture. The project supports USA, Germany, and Japan environments, and desktop/mobile device profiles. That means the system is not just registering accounts; it is also simulating a plausible client environment that matches the target locale.

10. The scripts under `scripts/` are operational utilities around the core automation pipeline. They do not appear to be primary business logic; instead they validate or mutate environment state: checking fingerprints, testing proxies, switching regions or devices, debugging runs, probing email flow, and verifying Outlook login. This indicates the repo is designed for interactive operations and troubleshooting, not only unattended batch execution.

11. The main data flow is: configuration and region/device selection feed into proxy and fingerprint setup, the runner launches a hardened browser session, the signup form is completed, a verification code is retrieved from the configured email service, and successful account details are written locally. The browser, proxy, and email systems are therefore the three main external boundaries.

12. The project’s infrastructure dependencies are important to the architecture: Chrome/ChromeDriver for browser execution, Selenium for automation, and an anti-detection browser setup noted in the README. The temporary email service is externalized rather than embedded, which keeps inbox ingestion outside the core repo.

13. The documentation split under `docs/` mirrors the major subsystems: region management, mobile mode, fingerprinting, proxy setup, and overall usage. That reflects the design of the codebase itself: a small orchestration core surrounded by specialized support modules for environment realism and verification.

Main entry points: [`src/runners/main.py`](https://github.com/7836246/aws-builder-id/blob/main/src/runners/main.py) (Main run), [`src/config.py`](https://github.com/7836246/aws-builder-id/blob/main/src/config.py) (Config loader), [`src/runners/single_outlook_run.py`](https://github.com/7836246/aws-builder-id/blob/main/src/runners/single_outlook_run.py) (Outlook run), [`src/managers/proxy_manager.py`](https://github.com/7836246/aws-builder-id/blob/main/src/managers/proxy_manager.py) (Proxy manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_execution["Execution"]
  node_src_runners_main["Main run<br/>runner entrypoint<br/>[main.py]"]
  node_src_runners_smart_run["Smart run<br/>runner mode<br/>[smart_run.py]"]
  node_src_runners_batch_run["Batch run<br/>runner mode<br/>[batch_run.py]"]
  node_src_runners_single_outlook_run["Outlook run<br/>runner mode"]
end

subgraph group_support["Support"]
  node_src_pages_base_page["Base page<br/>selenium page base<br/>[base_page.py]"]
  node_src_managers_proxy_manager[("Proxy manager<br/>network control<br/>[proxy_manager.py]")]
  node_src_managers_whitelist_manager[("Whitelist mgr<br/>network setup")]
  node_src_helpers_fingerprint{{"Fingerprint<br/>browser env<br/>[fingerprint.py]"}}
  node_src_helpers_multilang["Multilang<br/>locale support<br/>[multilang.py]"]
  node_src_helpers_ip_location["IP location<br/>geo check<br/>[ip_location.py]"]
  node_src_helpers_utils["Utils<br/>shared helpers<br/>[utils.py]"]
end

subgraph group_verification["Verification"]
  node_src_services_email_service["Email service<br/>verification service<br/>[email_service.py]"]
  node_src_services_outlook_service["Outlook svc<br/>mail backend<br/>[outlook_service.py]"]
  node_src_services_outlook_accounts[("Account store<br/>mail account data")]
end

subgraph group_config["Config"]
  node_src_config["Config loader<br/>runtime config<br/>[config.py]"]
  node_config_config_yaml["Config file<br/>yaml settings<br/>[config.yaml]"]
  node_config_languages_yaml["Languages<br/>yaml locale map<br/>[languages.yaml]"]
end

node_src_config -->|"loads"| node_config_config_yaml
node_src_config -->|"loads"| node_config_languages_yaml
node_src_runners_main -->|"uses"| node_src_config
node_src_runners_smart_run -->|"uses"| node_src_config
node_src_runners_batch_run -->|"uses"| node_src_config
node_src_runners_single_outlook_run -->|"uses"| node_src_config
node_src_runners_main -->|"drives"| node_src_pages_base_page
node_src_runners_main -->|"prepares"| node_src_managers_proxy_manager
node_src_runners_main -->|"prepares"| node_src_helpers_fingerprint
node_src_runners_main -->|"localizes"| node_src_helpers_multilang
node_src_runners_main -->|"checks"| node_src_helpers_ip_location
node_src_runners_main -->|"verifies"| node_src_services_email_service
node_src_runners_single_outlook_run -->|"uses"| node_src_services_outlook_service
node_src_services_outlook_service -->|"manages"| node_src_services_outlook_accounts
node_src_managers_proxy_manager -->|"coordinates"| node_src_managers_whitelist_manager
node_src_helpers_multilang -->|"maps"| node_config_languages_yaml
node_src_runners_main -->|"shares"| node_src_helpers_utils

click node_src_runners_main "https://github.com/7836246/aws-builder-id/blob/main/src/runners/main.py"
click node_src_runners_smart_run "https://github.com/7836246/aws-builder-id/blob/main/src/runners/smart_run.py"
click node_src_runners_batch_run "https://github.com/7836246/aws-builder-id/blob/main/src/runners/batch_run.py"
click node_src_runners_single_outlook_run "https://github.com/7836246/aws-builder-id/blob/main/src/runners/single_outlook_run.py"
click node_src_pages_base_page "https://github.com/7836246/aws-builder-id/blob/main/src/pages/base_page.py"
click node_src_managers_proxy_manager "https://github.com/7836246/aws-builder-id/blob/main/src/managers/proxy_manager.py"
click node_src_managers_whitelist_manager "https://github.com/7836246/aws-builder-id/blob/main/src/managers/whitelist_manager.py"
click node_src_helpers_fingerprint "https://github.com/7836246/aws-builder-id/blob/main/src/helpers/fingerprint.py"
click node_src_helpers_multilang "https://github.com/7836246/aws-builder-id/blob/main/src/helpers/multilang.py"
click node_src_helpers_ip_location "https://github.com/7836246/aws-builder-id/blob/main/src/helpers/ip_location.py"
click node_src_helpers_utils "https://github.com/7836246/aws-builder-id/blob/main/src/helpers/utils.py"
click node_src_services_email_service "https://github.com/7836246/aws-builder-id/blob/main/src/services/email_service.py"
click node_src_services_outlook_service "https://github.com/7836246/aws-builder-id/blob/main/src/services/outlook_service.py"
click node_src_services_outlook_accounts "https://github.com/7836246/aws-builder-id/blob/main/src/services/outlook_accounts.py"
click node_src_config "https://github.com/7836246/aws-builder-id/blob/main/src/config.py"
click node_config_config_yaml "https://github.com/7836246/aws-builder-id/blob/main/config/config.yaml"
click node_config_languages_yaml "https://github.com/7836246/aws-builder-id/blob/main/config/languages.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_runners_main,node_src_runners_smart_run,node_src_runners_batch_run,node_src_runners_single_outlook_run toneBlue
class node_src_pages_base_page,node_src_managers_proxy_manager,node_src_managers_whitelist_manager,node_src_helpers_fingerprint,node_src_helpers_multilang,node_src_helpers_ip_location,node_src_helpers_utils toneAmber
class node_src_services_email_service,node_src_services_outlook_service,node_src_services_outlook_accounts toneMint
class node_src_config,node_config_config_yaml,node_config_languages_yaml toneRose
```

## Components

### Execution

Runner entrypoints that orchestrate the registration lifecycle.

- [Main run](https://github.com/7836246/aws-builder-id/blob/main/src/runners/main.py): runner entrypoint · Primary orchestration path for a full Builder ID registration flow. · `src/runners/main.py`
- [Smart run](https://github.com/7836246/aws-builder-id/blob/main/src/runners/smart_run.py): runner mode · Adaptive orchestration mode for choosing or adjusting the run path. · `src/runners/smart_run.py`
- [Batch run](https://github.com/7836246/aws-builder-id/blob/main/src/runners/batch_run.py): runner mode · Batch-oriented execution boundary for repeated registration attempts. · `src/runners/batch_run.py`
- [Outlook run](https://github.com/7836246/aws-builder-id/blob/main/src/runners/single_outlook_run.py): runner mode · Run mode specialized for Outlook-backed verification. · `src/runners/single_outlook_run.py`

### Support

Shared browser, environment, and network support layers.

- [Base page](https://github.com/7836246/aws-builder-id/blob/main/src/pages/base_page.py): selenium page base · Shared browser-page actions and synchronization for Selenium automation. · `src/pages/base_page.py`
- [Proxy manager](https://github.com/7836246/aws-builder-id/blob/main/src/managers/proxy_manager.py): network control · Handles proxy selection and proxy API/static proxy modes. · `src/managers/proxy_manager.py`
- [Whitelist mgr](https://github.com/7836246/aws-builder-id/blob/main/src/managers/whitelist_manager.py): network setup · Manages allowlisting or access setup needed for proxy/network use. · `src/managers/whitelist_manager.py`
- [Fingerprint](https://github.com/7836246/aws-builder-id/blob/main/src/helpers/fingerprint.py): browser env · Shapes browser fingerprint traits such as CPU, memory, and WebGL. · `src/helpers/fingerprint.py`
- [Multilang](https://github.com/7836246/aws-builder-id/blob/main/src/helpers/multilang.py): locale support · Provides localized text and language-aware flow support. · `src/helpers/multilang.py`
- [IP location](https://github.com/7836246/aws-builder-id/blob/main/src/helpers/ip_location.py): geo check · Maps or validates public IP geolocation against the target region. · `src/helpers/ip_location.py`
- [Utils](https://github.com/7836246/aws-builder-id/blob/main/src/helpers/utils.py): shared helpers · Cross-cutting utility functions used across the automation stack. · `src/helpers/utils.py`

### Verification

Email and account handling used to complete signup flows.

- [Email service](https://github.com/7836246/aws-builder-id/blob/main/src/services/email_service.py): verification service · Abstraction for receiving verification codes from the configured email backend. · `src/services/email_service.py`
- [Outlook svc](https://github.com/7836246/aws-builder-id/blob/main/src/services/outlook_service.py): mail backend · Outlook/IMAP-oriented backend for verification and inbox access. · `src/services/outlook_service.py`
- [Account store](https://github.com/7836246/aws-builder-id/blob/main/src/services/outlook_accounts.py): mail account data · Manages Outlook account metadata and related account records. · `src/services/outlook_accounts.py`

### Config

Static and loaded configuration for regions, languages, and runtime behavior.

- [Config loader](https://github.com/7836246/aws-builder-id/blob/main/src/config.py): runtime config · Loads and mediates repository configuration for runners and helpers. · `src/config.py`
- [Config file](https://github.com/7836246/aws-builder-id/blob/main/config/config.yaml): yaml settings · Main runtime settings for region, device, proxy mode, email backend, and timeouts. · `config/config.yaml`
- [Languages](https://github.com/7836246/aws-builder-id/blob/main/config/languages.yaml): yaml locale map · Localized strings and language mappings used by region-specific flows. · `config/languages.yaml`

## Connections

- Config loader → Config file: loads · Reads primary runtime settings.
- Config loader → Languages: loads · Reads locale and language mappings.
- Main run → Config loader: uses · Consumes runtime configuration before orchestration.
- Smart run → Config loader: uses · Adapts execution using configuration state.
- Batch run → Config loader: uses · Drives batch behavior from configuration.
- Outlook run → Config loader: uses · Selects Outlook-oriented flow from configuration.
- Main run → Base page: drives · Coordinates browser actions through the shared page layer.
- Main run → Proxy manager: prepares · Sets up network/proxy conditions for the session.
- Main run → Fingerprint: prepares · Shapes browser fingerprinting before signup.
- Main run → Multilang: localizes · Selects language-aware text for region flows.
- Main run → IP location: checks · Validates region/IP alignment during setup.
- Main run → Email service: verifies · Waits for and retrieves signup verification codes.
- Outlook run → Outlook svc: uses · Connects the Outlook-specific verification backend.
- Outlook svc → Account store: manages · Uses stored account metadata for mail access.
- Proxy manager → Whitelist mgr: coordinates · May require whitelist setup for proxy access.
- Multilang → Languages: maps · Resolves localized strings from language data.
- Main run → Utils: shares · Uses common utility helpers across the flow.