# go-to-k/cls3 architecture

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

- Interactive diagram: https://gitdiagram.com/go-to-k/cls3
- Repository: https://github.com/go-to-k/cls3

## Overview

##### Project Identification
- Project Type: This is a Go-based CLI tool designed to delete or empty Amazon S3 buckets (including handling versioned buckets) and associated S3 Tables. It is a command‐line utility with interactive and non‑interactive modes.
- Purpose: cls3 supports bucket searching, mass deletion, concurrency support, and integration with CI/CD tools (e.g., GitHub Actions). It wraps AWS S3 APIs and provides additional logic (like retries on 503 errors) to ensure robustness.

##### Analyzing the File Structure and Its Implications
- Top-Level Components:
- cmd/cls3: Contains the main entry point (main.go). This module is where the CLI is initialized and command line arguments are parsed.
- internal/app: Encapsulates the core business logic. Here you have modules for bucket processing (bucket_processor.go), bucket selection (bucket_selector.go), state management (clearing_state.go), and display management (display_manager.go). This “application layer” orchestrates the overall bucket deletion workflow.
- internal/io: Manages input, logging, UI interactions, and writing output. It clearly separates the data I/O layer from the business logic.
- internal/wrapper: Provides abstraction over AWS S3 services with specific wrappers. This includes different wrappers for S3 buckets versus S3 tables, allowing the tool to differentiate behavior based on the mode.
- pkg/client: Contains the AWS client implementations and utility functions (like retryer logic and error handling) to interact with the underlying AWS S3 APIs.
- Additional directories (like internal/version and testdata) support versioning and CI/deployment testing respectively. There are also GitHub actions settings and CI workflows which indicate automated testing/integration.

- Architecture Implications:
- The separation between cmd, internal/app, internal/io, and pkg/client reflects a modular layering similar to separating the user interface, business logic, and external integrations.
- The presence of dedicated wrappers for AWS services (internal/wrapper) indicates use of the Adapter/Facade pattern to simplify and consolidate external service calls.
- The code is organized to allow for testability, with mock implementations provided in several “internal” subdirectories.

a. Main Components to Include:
- CLI / Entry Point (cmd/cls3): Mark this as the starting point of the application.
- Application Layer (internal/app): This should include subcomponents such as:
- Bucket Processor
- Bucket Selector
- Clearing State Manager
- Manager
- I/O Layer (internal/io): For input management, UI rendering, and logging.
- AWS Client Layer (pkg/client): Encompassing functions to access S3 and S3 Tables; include the retry logic and error handling.
- Wrapper/Adapter Layer (internal/wrapper): Abstracts details of S3 operations and provides compatibility with different S3 modes (regular S3 buckets, directory buckets for one zone, table buckets).
- Version Module (internal/version): To handle versioning information and tests.

b. Relationships & Interactions:
- Bucket Selector (which processes names provided either via interactive mode or command-line options) to the Bucket Processor.
- Bucket Processor leading to the Clearing State Manager (for keeping track of progress and retrying deletion).
- Manager connected back to CLI/I-O to show progress and logs.
- Incorporate the I/O Layer as both receiving user input and providing live feedback back to the user interface.

c. Architectural Patterns & Design Principles:
- Layered Architecture: Clearly separate the CLI interface, business logic, and external API integrations.
- Adapter/Wrapper Pattern: Use the wrapper components to abstract over differences in API usage (for S3 buckets, S3 Tables, and Directory Buckets modes).
- Testability: Optionally indicate the presence of test code and mocks (visible in directories like internal/app/*_test.go and internal/io/mock_input.go) which aid in unit testing and integration tests.

d. Relevant Technologies/Frameworks:
- Go (as the programming language) – emphasize that the system is built with idiomatic Go practices.
- AWS SDK (wrapped within pkg/client and internal/wrapper).
- GitHub Actions for CI/CD (referenced in the GitHub workflows).
- CI/CD automation and testing frameworks, as implied by the Makefile, GitHub actions configuration, and testdata.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level CLI and Version
    CLI["CLI Entry (cmd/cls3)"]:::cli
    VER["Version Module (internal/version)"]:::version

    %% Application Layer Subgraph
    subgraph "Application Layer"
        BS["Bucket Selector (internal/app)"]:::app
        BP["Bucket Processor (internal/app)"]:::app
        CS["Clearing State Manager (internal/app)"]:::app
        DM["Display Manager (internal/app)"]:::app
    end

    %% I/O Layer Subgraph
    subgraph "I/O Layer"
        IO1["Input (internal/io)"]:::io
        IO2["Logger (internal/io)"]:::io
        IO3["UI (internal/io)"]:::io
        IO4["Writer (internal/io)"]:::io
    end

    %% AWS Client Layer Subgraph
    subgraph "AWS Client Layer"
        AC1["AWS Config (pkg/client)"]:::awsclient
        AC2["S3 Client (pkg/client)"]:::awsclient
        AC3["S3 Tables (pkg/client)"]:::awsclient
        AC4["Retryer (pkg/client)"]:::awsclient
    end

    %% AWS Wrapper/Adapter Layer Subgraph
    subgraph "AWS Wrapper Layer"
        AW1["S3 Wrapper (internal/wrapper)"]:::awswrapper
        AW2["S3 Tables Wrapper (internal/wrapper)"]:::awswrapper
        AW3["Generic Wrapper (internal/wrapper)"]:::awswrapper
    end

    %% Connections between components
    CLI -->|"initiates"| BS
    BS -->|"selects"| BP
    BP -->|"processes"| CS
    CS -->|"updates"| DM
    DM -->|"renders on"| IO3
    DM -->|"logs"| IO2
    IO1 -->|"provides input to"| BS

    %% Application Layer interactions with AWS layers
    BP -->|"invokes"| AC2
    BP -->|"invokes"| AW1

    %% Bidirectional arrow between AWS Client and Wrapper layers
    AC2 <-->|"refines calls"| AW1

    %% Additional interactions from Application Layer to other AWS Client components
    BP -->|"configures via"| AC1
    BP -->|"handles tables via"| AC3
    BP -->|"uses retry logic"| AC4

    %% Interaction within AWS Wrapper Layer
    AW1 -->|"collaborates with"| AW2
    AW2 -->|"cooperates with"| AW3

    %% CLI to Version Module (for version info)
    CLI -->|"checks"| VER

    %% Styles
    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef app fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef io fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef awsclient fill:#D6EAF8,stroke:#1B4F72,stroke-width:2px;
    classDef awswrapper fill:#FAD7A0,stroke:#B9770E,stroke-width:2px;
    classDef version fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;

    %% Click Events
    click CLI "https://github.com/go-to-k/cls3/blob/main/cmd/cls3/main.go"
    click BS "https://github.com/go-to-k/cls3/blob/main/internal/app/bucket_selector.go"
    click BP "https://github.com/go-to-k/cls3/blob/main/internal/app/bucket_processor.go"
    click CS "https://github.com/go-to-k/cls3/blob/main/internal/app/clearing_state.go"
    click DM "https://github.com/go-to-k/cls3/blob/main/internal/app/display_manager.go"
    click IO1 "https://github.com/go-to-k/cls3/blob/main/internal/io/input.go"
    click IO2 "https://github.com/go-to-k/cls3/blob/main/internal/io/logger.go"
    click IO3 "https://github.com/go-to-k/cls3/blob/main/internal/io/ui.go"
    click IO4 "https://github.com/go-to-k/cls3/blob/main/internal/io/writer.go"
    click AC1 "https://github.com/go-to-k/cls3/blob/main/pkg/client/aws_config.go"
    click AC2 "https://github.com/go-to-k/cls3/blob/main/pkg/client/s3.go"
    click AC3 "https://github.com/go-to-k/cls3/blob/main/pkg/client/s3_tables.go"
    click AC4 "https://github.com/go-to-k/cls3/blob/main/pkg/client/retryer.go"
    click AW1 "https://github.com/go-to-k/cls3/blob/main/internal/wrapper/s3_wrapper.go"
    click AW2 "https://github.com/go-to-k/cls3/blob/main/internal/wrapper/s3_tables_wrapper.go"
    click AW3 "https://github.com/go-to-k/cls3/blob/main/internal/wrapper/wrapper.go"
    click VER "https://github.com/go-to-k/cls3/blob/main/internal/version/version.go"
```
