# siemens/snap-to-bucket architecture

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

- Interactive diagram: https://gitdiagram.com/siemens/snap-to-bucket
- Repository: https://github.com/siemens/snap-to-bucket

## Overview

##### Project type and purpose
- This is a Python‐based CLI tool (open‐source utility) that runs on an EC2 instance.
- Its goal is to migrate AWS EBS snapshots into an S3 bucket (and optionally restore them).

##### File structure
- `src/snap_to_bucket/run.py` provides the CLI entrypoint.
- `src/snap_to_bucket/runner/snap_handler.py` encapsulates the overall workflow.
- `src/snap_to_bucket/handlers/` holds three handler classes:
- `ec_2_handler.py` – uses boto3 to list/attach/detach EBS volumes & snapshots.
- `fs_handler.py` – handles mounting, partitioning, tar/gzip, splitting.
- `s3_handler.py` – uses boto3 to upload/download objects from S3.
- Configuration/deployment info is in Pipfile, setup.py, pyproject.toml.

##### README for additional insights
- The tool runs on an EC2 instance with an IAM role permitting EC2 and S3 operations.
- CLI flags control tag selection, S3 bucket, volume type, gzip, splitting, delete-on-transfer, restore mode.

A. CLI Layer
- snap2bucket command (entrypoint)
B. Orchestration Layer
- `SnapHandler` runner
C. Handler Components
1. EC2Handler – calls AWS EC2 APIs via boto3
2. FSHandler – local OS calls for mount/umount, tar, gzip, split
3. S3Handler – S3 API calls via boto3
D. External Services
- AWS EC2 snapshot & volume service
- AWS S3 (bucket)
E. Local Environment
- Linux file system (e.g., `/mnt/snaps`) on the EC2 instance

##### Relationships & data flows
- CLI → SnapHandler: parses options
- SnapHandler → EC2Handler:
- Snapshots by tag
- Create volume from snapshot
- Attach volume
- EC2Handler → FSHandler:
- Mount the attached device
- Tar (± gzip) and split into chunks
- FSHandler → S3Handler:
- Upload chunk(s) to S3
- Optionally delete snapshots via EC2Handler
- For restore mode, reverse: S3Handler → FSHandler → EC2Handler

##### Architectural patterns and principles
- Separation of concerns: each handler has a single responsibility.
- Plugin‐style extensibility: adding a new handler for e.g., another cloud provider.
- CLI orchestration + dependency injection: runner invokes handlers in a defined sequence.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["Snap2Bucket CLI"]:::local
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        SnapHandler["SnapHandler"]:::local
    end

    %% Handlers Layer
    subgraph "Handlers"
        EC2H["EC2Handler"]:::local
        FSH["FSHandler"]:::local
        S3H["S3Handler"]:::local
    end

    %% Local OS / File System
    subgraph "Local OS & File System"
        OS["Linux File System (/mnt/snaps)"]:::os
    end

    %% AWS Services
    subgraph "AWS Services"
        EC2["AWS EC2"]:::aws
        S3["AWS S3 Bucket"]:::aws
    end

    %% Configuration & Deployment
    subgraph "Config & Deployment"
        Pipfile["Pipfile"]:::config
        Setup["setup.py"]:::config
        Pyproject["pyproject.toml"]:::config
    end

    %% Documentation
    subgraph "Documentation"
        DocRun["doc-sources/snap_to_bucket.run.rst"]:::docs
        DocSnap["doc-sources/snap_to_bucket.snap_handler.rst"]:::docs
        DocEC2["doc-sources/snap_to_bucket.ec_2_handler.rst"]:::docs
        DocFS["doc-sources/snap_to_bucket.fs_handler.rst"]:::docs
        DocS3["doc-sources/snap_to_bucket.s3_handler.rst"]:::docs
    end

    %% Connections
    CLI -->|"parses options"| SnapHandler
    SnapHandler -->|"listSnapshots / createVolume / attachVolume"| EC2H
    EC2H -->|"mountDevice"| FSH
    FSH -->|"tar+gzip & split"| OS
    FSH -->|"uploadChunk(s)"| S3H
    S3H -->|"putObject|getObject"| S3
    EC2H -->|"deleteSnapshot"| EC2

    %% Restore Flow
    S3 -->|"downloadChunk(s)"| S3H
    S3H -->|"untar & restore"| FSH
    FSH -->|"attachVolume / createSnapshot"| EC2H

    %% Click Events
    click CLI "https://github.com/siemens/snap-to-bucket/blob/master/src/snap_to_bucket/run.py"
    click SnapHandler "https://github.com/siemens/snap-to-bucket/blob/master/src/snap_to_bucket/runner/snap_handler.py"
    click EC2H "https://github.com/siemens/snap-to-bucket/blob/master/src/snap_to_bucket/handlers/ec_2_handler.py"
    click FSH "https://github.com/siemens/snap-to-bucket/blob/master/src/snap_to_bucket/handlers/fs_handler.py"
    click S3H "https://github.com/siemens/snap-to-bucket/blob/master/src/snap_to_bucket/handlers/s3_handler.py"
    click DocRun "https://github.com/siemens/snap-to-bucket/blob/master/doc-sources/snap_to_bucket.run.rst"
    click DocSnap "https://github.com/siemens/snap-to-bucket/blob/master/doc-sources/snap_to_bucket.snap_handler.rst"
    click DocEC2 "https://github.com/siemens/snap-to-bucket/blob/master/doc-sources/snap_to_bucket.ec_2_handler.rst"
    click DocFS "https://github.com/siemens/snap-to-bucket/blob/master/doc-sources/snap_to_bucket.fs_handler.rst"
    click DocS3 "https://github.com/siemens/snap-to-bucket/blob/master/doc-sources/snap_to_bucket.s3_handler.rst"

    %% Styles
    classDef local fill:#b2f2bb,stroke:#2f6627,color:#2f6627
    classDef aws fill:#ffe5b4,stroke:#bf5700,color:#bf5700
    classDef os fill:#cce5ff,stroke:#0066cc,color:#0066cc
    classDef config fill:#e0e0e0,stroke:#888888,color:#444444
    classDef docs fill:#fff2cc,stroke:#cca300,color:#cca300
```
