# quantumleap-us/beamable-auto-claim architecture

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

- Interactive diagram: https://gitdiagram.com/quantumleap-us/beamable-auto-claim
- Repository: https://github.com/quantumleap-us/beamable-auto-claim

## Overview

##### Main Components
- Auto Claim Controller (auto_claim.py): The core script that triggers claim operations immediately and schedules subsequent claims.
- Configuration Management: The .env file (copied from .env.example) holds the BEAMABLE_COOKIE, which is critical for authenticated requests.
- HTTP Client Module: Uses Python HTTP requests (likely the “requests” library) to fetch webpage content and parse the countdown information.
- Scheduler Module: Contains logic to compute and schedule the next claim time (defaulting to 12 hours or based on parsed countdown).
- Logging Module: Implements detailed logging (both to the console and an “auto_claim.log” file) with UTC timestamps.
- Startup Script: “start.bat” provides a Windows-friendly mechanism to launch the auto_claim.py script.

##### Relationships and Interactions
- The Configuration Management component loads environment variables (BEAMABLE_COOKIE) at startup.
- The HTTP Client communicates with the Beamable Network website to retrieve live countdown data.
- The Auto Claim Controller integrates countdown parsing and claim triggering, then passes scheduling information to the Scheduler.
- The Scheduler directs when the next HTTP re-check and claim operation should occur.
- The Logging Module captures all key events and errors, and both console and file outputs are updated accordingly.

##### Architectural Patterns and Principles
- Fallback mechanism: In case the countdown can’t be parsed, a default interval (12 hours) is applied – this is an example of graceful handling of unexpected data.
- Time-centric design: The use of UTC across logging, scheduling, and operational logic ensures synchronization with the Beamable Network's countdown.

##### Relevant Technologies & Libraries
- Python 3.7+ as the programming language and runtime.
- External libraries from “requirements.txt” (e.g., requests or any scheduling libraries).
- Environment variable management (with the .env configuration).
- Logging frameworks (likely Python’s built-in logging) for both file and console outputs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Internal Modules"
        Config["Configuration Loader"]:::config
        Controller["Claim Operation Controller"]:::controller
        HTTP["HTTP Request Handler"]:::http
        Scheduler["Scheduler"]:::scheduler
        Logger["Logging System"]:::logger
    end

    subgraph "External Services"
        BNW["Beamable Network Website"]:::external
    end

    subgraph "External Libraries"
        Dependencies["Dependencies"]:::dependencies
    end

    Startup["Startup Script"]:::startup

    Startup -->|"Launches"| Controller
    Config -->|"Loads config"| Controller
    HTTP -->|"Returns countdown"| Controller
    Controller -->|"Schedules next claim"| Scheduler
    Controller -->|"Logs event"| Logger
    HTTP -->|"HTTP GET"| BNW
    Dependencies -->|"Provides libraries"| Controller

    click Controller "https://github.com/quantumleap-us/beamable-auto-claim/blob/main/auto_claim.py"
    click Config "https://github.com/quantumleap-us/beamable-auto-claim/blob/main/.env.example"
    click Startup "https://github.com/quantumleap-us/beamable-auto-claim/blob/main/start.bat"
    click Dependencies "https://github.com/quantumleap-us/beamable-auto-claim/blob/main/requirements.txt"

    classDef config fill:#add8e6,stroke:#333,stroke-width:2px
    classDef controller fill:#90ee90,stroke:#333,stroke-width:2px
    classDef http fill:#ffd700,stroke:#333,stroke-width:2px
    classDef scheduler fill:#ffa500,stroke:#333,stroke-width:2px
    classDef logger fill:#d3d3d3,stroke:#333,stroke-width:2px
    classDef external fill:#ffb6c1,stroke:#333,stroke-width:2px
    classDef startup fill:#dda0dd,stroke:#333,stroke-width:2px
    classDef dependencies fill:#e6e6fa,stroke:#333,stroke-width:2px
```
