# bbacker/taglightswitch architecture

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

- Interactive diagram: https://gitdiagram.com/bbacker/taglightswitch
- Repository: https://github.com/bbacker/taglightswitch

## Overview

##### Project type and purpose
- This is a standalone CLI‐based Python tool (“taglightswitch”) that inspects EC2 instance tags, computes a desired on/off schedule, and then optionally powers instances on or off via AWS APIs. It is not a web or full-stack app, but an open-source utility focused on cost control for EC2 instances.

a. CLI entrypoint
- Script: check_lightswitches.py
- Parses command-line arguments (advise vs correct, target time/day, dry-run)
b. Tag-parsing layer (module: controltags.py)
- Reads AWS “lightswitch:*” tags to extract offhours/offdays/offmode
c. Schedule engine (module: lightswitch.py)
- Applies the tag data to the current (or target) time/day to decide desired state
d. Instance abstraction (module: switchableitem.py)
- Wraps an EC2 instance’s metadata, current state, and provides “power_on” / “power_off” methods
e. AWS integration layer
- Boto3 client calls: describe_instances, start_instances, stop_instances
f. External scheduler
- Cron, Jenkins, or Lambda that triggers the CLI on a fixed schedule

##### Relationships and data flow
- External scheduler triggers the CLI entrypoint
→ CLI parses options & invokes tag-parsing layer
→ Tag layer calls AWS EC2 describe_instances (filtered by lightswitch tag)
→ Controltags creates SwitchableItem objects
→ Schedule engine determines desired state for each item
→ For “advise” mode: builds a report
→ For “correct” mode: calls start_instances/stop_instances via AWS integration
→ AWS EC2 service receives power on/off API calls

##### Important architectural patterns / principles
- Single codebase, pluggable modules for tag parsing, scheduling logic, and AWS calls
- No separate data store: schedules are stored in EC2 tags
- Dependency inversion: business logic (lightswitch.py) is decoupled from AWS calls (boto3), enabling dry-run or test mocks
- Test layer sits outside in “tests/” to validate each component

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Scheduler Trigger
    subgraph "External Scheduler" 
        direction TB
        SchedulerTrigger("Cron/Lambda/Jenkins"):::extScheduler
    end

    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI["check_lightswitches.py"]:::internal
    end

    %% Ingestion Layer
    subgraph "Ingestion Layer"
        direction TB
        TagParser["controltags.py"]:::internal
        SwitchableItem["switchableitem.py"]:::internal
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        SchedulerEngine["lightswitch.py"]:::internal
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        AWSClient["AWS Integration (boto3 calls)"]:::awsClient
    end

    %% AWS Service
    AWS["AWS EC2 Service"]:::awsService

    %% Test Suite
    subgraph "Test Suite" 
        direction TB
        Tests["tests/"]:::tests
    end

    %% Data Flow
    SchedulerTrigger -->|"triggers CLI"| CLI
    CLI -->|"parse args & invoke"| TagParser
    TagParser -->|"create instances"| SwitchableItem
    SwitchableItem -->|"provide metadata"| SchedulerEngine
    TagParser -->|"describe_instances"| AWSClient
    AWSClient -->|"describe_instances API"| AWS
    SchedulerEngine -->|"compute desired state"| CLI
    CLI -->|"advise mode"| Reports["Report Output"]:::internal
    CLI -->|"correct mode"| AWSClient
    AWSClient -->|"start/stop API"| AWS

    %% Click Events
    click CLI "https://github.com/bbacker/taglightswitch/tree/master/taglightswitch/check_lightswitches"
    click TagParser "https://github.com/bbacker/taglightswitch/blob/master/taglightswitch/controltags.py"
    click SchedulerEngine "https://github.com/bbacker/taglightswitch/blob/master/taglightswitch/lightswitch.py"
    click SwitchableItem "https://github.com/bbacker/taglightswitch/blob/master/taglightswitch/switchableitem.py"
    click Tests "https://github.com/bbacker/taglightswitch/tree/master/tests/"

    %% Styles
    classDef internal fill:#AEDFF7,stroke:#005b96,color:#000;
    classDef extScheduler fill:#E2E2E2,stroke:#666,color:#000,stroke-dasharray: 5 5;
    classDef awsService fill:#FAD7A0,stroke:#d35400,color:#000,shape:cylinder;
    classDef awsClient fill:#F9E79F,stroke:#b7950b,color:#000,shape:hexagon;
    classDef tests fill:#D5F5E3,stroke:#229954,color:#000,stroke-dasharray: 2 2;
```
