# kayac/ecspresso architecture

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

- Interactive diagram: https://gitdiagram.com/kayac/ecspresso
- Repository: https://github.com/kayac/ecspresso

## Overview

Based on both the file tree and the README contents, “ecspresso” is a CLI deployment tool written in Go. It is designed to manage Amazon ECS services and Task Definitions, allowing users to perform operations such as deploy, diff, rollback, scale, run tasks, and integrate with AWS CodeDeploy for blue/green deployments. Moreover, it provides a robust plugin system for integrating with systems like Terraform state lookups, CloudFormation outputs, SSM Parameter Store, and Secrets Manager.

##### Main Components
- CLI Interface: At the center is the command-line interface (see “cli.go” and the “cmd/ecspresso” directory) that parses user input and invokes the proper command. This layer includes subcommands like deploy, diff, rollback, etc.
- Command Handlers / Core Modules:
– Separate modules (individual Go packages such as appspec, registry, secretsmanager, and others) are responsible for functionality like rendering configuration templates, handling AWS-specific logic, and interfacing with services.
– In particular, modules handling AWS deployments (e.g., deploy.go, register.go, scale.go) encapsulate calls to AWS ECS, CodeDeploy, and Auto Scaling.
- Configuration Management: A central configuration loader (supported formats include YAML, JSON, and Jsonnet) reads and interprets configuration files (like “ecspresso.yml”, “ecs-service-def.json”, “ecs-task-def.json”). This component also integrates template processing (utilizing “text/template” plus additional functions and plugins).
- Plugin Subsystem: A dedicated plugin module supports extensions – for instance, plugins for tfstate lookups, CloudFormation output fetching, SSM Parameter Store access, and resolving Secrets Manager ARNs.
- AWS Integration Layer: This layer represents the connection points for interacting with AWS services – ECS, CodeDeploy, Auto Scaling, ECR, CloudWatch logs, etc. The tool uses AWS SDK integrations and supports handling both Fargate and EC2 deployment scenarios.
- CI/CD Integrations: Although not part of the compiled code, documentation details integrations with Homebrew, asdf, aqua, GitHub Actions, and CircleCI (with provided YAML configurations); these external systems invoke ecspresso as part of the deployment pipeline.

##### Relationships and Data Flow
- User inputs a command via the CLI – e.g., “ecspresso deploy” – which is handled by the CLI module.
- The command handler loads the configuration (from files like ecspresso.yml), which may require template rendering. This rendering sometimes involves plugins (such as tfstate and cloudformation) to fetch dynamic values.
- The processed configuration instructs the AWS Integration Layer to invoke API calls to ECS and perhaps CodeDeploy to execute tasks such as registering a new task definition, updating a service, initiating rollbacks, or scaling services.
- For operations like “diff” or “verify”, the tool retrieves current remote state from AWS and compares it with the local configuration.
- CI/CD tools (GitHub Actions, CircleCI Orbs) call this CLI tool in automated pipelines, ensuring consistency across deployments.

##### Architectural Patterns and Design Principles
- Modular Design: The codebase is structured into fine-grained packages (e.g., appspec, registry, secretsmanager) that encapsulate specific responsibilities.
- Template & Plugin Extension: It separates core functionality from rendering (via Go’s “text/template” and additional Jsonnet processing), making it easy to extend with plugins.
- Command Pattern: Each operation (init, deploy, diff, etc.) is implemented as a distinct command, which helps in maintaining separation of concerns.
- Integration with External Tools: The design explicitly supports external integrations (CI/CD workflows, cloud configuration files) and encourages defining clear boundaries between configuration rendering and AWS API execution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top-level External Nodes
    User["User Command"]:::external
    ExternCI["External CI/CD Integration"]:::external

    %% CLI Interface
    CLI["CLI Interface"]:::cli

    %% Command Handlers Subgraph
    subgraph "Command Handlers"
        Deploy["Deploy Command"]:::core
        Diff["Diff Command"]:::core
        Rollback["Rollback Command"]:::core
        Scale["Scale Command"]:::core
        Register["Register Command"]:::core
        Delete["Delete Command"]:::core
        Create["Create Command"]:::core
    end

    %% Configuration Loader & Template Renderer
    Config["Configuration & Template Engine"]:::config

    %% Plugin System
    Plugin["Plugin System"]:::plugin

    %% AWS Integration Layer
    AWS["AWS API Integration Layer"]:::aws
    AWSServices(("AWS Services (ECS,CodeDeploy,AutoScaling)")):::aws

    %% Flows
    User -->|"inputCommand"| CLI
    ExternCI -->|"triggerCLI"| CLI

    CLI -->|"invokeCommands"| Deploy
    CLI -->|"invokeCommands"| Diff
    CLI -->|"invokeCommands"| Rollback
    CLI -->|"invokeCommands"| Scale
    CLI -->|"invokeCommands"| Register
    CLI -->|"invokeCommands"| Delete
    CLI -->|"invokeCommands"| Create

    %% Representative flow from a command to configuration parsing
    Deploy -->|"loadConfig"| Config

    %% Flow from Configuration Engine to Plugin System for dynamic enhancements
    Config -->|"applyPlugins"| Plugin

    %% Flow from Configuration Engine (post-enhancement) to AWS API Integration
    Config -->|"awsCall"| AWS

    %% AWS API Layer calls external AWS services
    AWS -->|"executeAPI"| AWSServices

    %% Class Definitions (with colors)
    classDef cli fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef core fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef config fill:#577590,stroke:#000,stroke-width:2px, color:#fff;
    classDef plugin fill:#f94144,stroke:#000,stroke-width:2px, color:#fff;
    classDef aws fill:#43aa8b,stroke:#000,stroke-width:2px, color:#fff;
    classDef external fill:#277da1,stroke:#fff,stroke-width:2px, color:#fff;

    %% Click Events for CLI Interface
    click CLI "https://github.com/kayac/ecspresso/blob/v2/cli.go"
    click CLI "https://github.com/kayac/ecspresso/blob/v2/cmd/ecspresso/main.go"

    %% Click Events for Command Handlers / Core Modules
    click Deploy "https://github.com/kayac/ecspresso/blob/v2/deploy.go"
    click Diff "https://github.com/kayac/ecspresso/blob/v2/diff.go"
    click Rollback "https://github.com/kayac/ecspresso/blob/v2/rollback.go"
    click Scale "https://github.com/kayac/ecspresso/blob/v2/scale.go"
    click Register "https://github.com/kayac/ecspresso/blob/v2/register.go"
    click Delete "https://github.com/kayac/ecspresso/blob/v2/delete.go"
    click Create "https://github.com/kayac/ecspresso/blob/v2/create.go"

    %% Click Events for Configuration Loader & Template Renderer
    click Config "https://github.com/kayac/ecspresso/blob/v2/config.go"
    click Config "https://github.com/kayac/ecspresso/blob/v2/render.go"

    %% Click Events for Plugin System
    click Plugin "https://github.com/kayac/ecspresso/blob/v2/plugin.go"
    click Plugin "https://github.com/kayac/ecspresso/blob/v2/secretsmanager/funcs.go"
    click Plugin "https://github.com/kayac/ecspresso/blob/v2/jsonnet.go"

    %% Click Events for AWS Integration Layer
    click AWS "https://github.com/kayac/ecspresso/blob/v2/autoscaling.go"
    click AWS "https://github.com/kayac/ecspresso/blob/v2/appspec.go"

    %% Click Events for External CI/CD Integrations
    click ExternCI "https://github.com/kayac/ecspresso/blob/v2/.github"
    click ExternCI "https://github.com/kayac/ecspresso/blob/v2/orb.yml"
```
