# boltops-tools/ufo architecture

> Architecture diagram of the GitHub repository boltops-tools/ufo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/boltops-tools/ufo
- Repository: https://github.com/boltops-tools/ufo

## Overview

UFO is a Heroku-like command-line tool for working with AWS ECS. Its broad workflow is to configure an application, prepare a task definition and container image, and manage deployment and runtime operations. The tree also shows CloudFormation infrastructure generation, rollback, scaling, logs, hooks, and project setup. Sampled code confirms task-definition context loading, ECS service resource construction, and ECR authentication; most command-to-subsystem wiring was not shown, so those relationships are dashed and unverified.

Main entry points: [`lib/ufo/cli.rb`](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli.rb) (UFO commands), [`lib/ufo/docker/builder.rb`](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/docker/builder.rb) (Image build), [`lib/ufo/cfn/stack/builder/resources/ecs_service.rb`](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cfn/stack/builder/resources/ecs_service.rb) (Stack resources), [`lib/ufo/task_definition/context.rb`](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/task_definition/context.rb) (Task context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["CLI workflows"]
  node_cli["UFO commands<br/>[cli.rb]"]
  node_scaffold["Project setup<br/>[sequence.rb]"]
end

subgraph group_app["Application setup"]
  node_config["Configuration<br/>[config.rb]"]
  node_layers["Config layering<br/>[layer.rb]"]
  node_task_context["Task context<br/>[context.rb]"]
  node_task_build["Task definitions<br/>[builder.rb]"]
  node_hooks["Deployment hooks<br/>[runner.rb]"]
end

subgraph group_deploy["Image and deployment"]
  node_docker_build["Image build<br/>[builder.rb]"]
  node_docker_push["Image push<br/>[pusher.rb]"]
  node_docker_state[("Build state<br/>[s3.rb]")]
  node_ecr_auth["ECR login<br/>[auth.rb]"]
  node_cfn_deploy["Stack deployment<br/>[deploy.rb]"]
  node_stack_build["Stack resources<br/>[ecs_service.rb]"]
end

subgraph group_runtime["ECS operations"]
  node_ecs["ECS service<br/>[service.rb]"]
  node_runtime_cli["Runtime commands<br/>[ps.rb]"]
  node_logs["Service logs<br/>[logs.rb]"]
  node_scaling["Service scaling<br/>[scale.rb]"]
  node_rollback["Rollback<br/>[rollback.rb]"]
end

subgraph group_aws["AWS integrations"]
  node_iam["IAM roles<br/>[builder.rb]"]
  node_aws_clients["AWS clients<br/>[aws_services.rb]"]
end

node_operator(("Operator"))
node_aws["AWS services"]

node_operator -.->|"invokes"| node_cli
node_cli -.->|"creates projects"| node_scaffold
node_cli -.->|"uses settings"| node_config
node_task_context -->|"loads layers"| node_layers
node_task_context -.->|"provides context"| node_task_build
node_cli -.->|"builds definitions"| node_task_build
node_cli -.->|"builds images"| node_docker_build
node_docker_build -.->|"pushes image"| node_docker_push
node_docker_build -.->|"stores state"| node_docker_state
node_docker_push -.->|"authenticates"| node_ecr_auth
node_ecr_auth -->|"gets ECR token"| node_aws_clients
node_aws_clients -->|"creates clients"| node_aws
node_cli -.->|"deploys stack"| node_cfn_deploy
node_cfn_deploy -.->|"uses resources"| node_stack_build
node_stack_build -->|"defines service"| node_ecs
node_stack_build -.->|"defines roles"| node_iam
node_cli -.->|"runs operations"| node_runtime_cli
node_cli -.->|"fetches logs"| node_logs
node_cli -.->|"scales service"| node_scaling
node_cli -.->|"rolls back"| node_rollback
node_cli -.->|"runs hooks"| node_hooks

click node_cli "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli.rb"
click node_scaffold "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli/new/sequence.rb"
click node_config "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/config.rb"
click node_layers "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/layering/layer.rb"
click node_task_context "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/task_definition/context.rb"
click node_task_build "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/task_definition/builder.rb"
click node_docker_build "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/docker/builder.rb"
click node_docker_push "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/docker/pusher.rb"
click node_docker_state "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/docker/state/s3.rb"
click node_ecr_auth "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/ecr/auth.rb"
click node_cfn_deploy "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cfn/deploy.rb"
click node_stack_build "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cfn/stack/builder/resources/ecs_service.rb"
click node_ecs "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/ecs/service.rb"
click node_runtime_cli "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli/ps.rb"
click node_logs "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli/logs.rb"
click node_scaling "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli/scale.rb"
click node_rollback "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/s3/rollback.rb"
click node_hooks "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/hooks/runner.rb"
click node_iam "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/iam_role/builder.rb"
click node_aws_clients "https://github.com/boltops-tools/ufo/blob/main/lib/ufo/aws_services.rb"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_scaffold toneBlue
class node_config,node_layers,node_task_context,node_task_build,node_hooks toneAmber
class node_docker_build,node_docker_push,node_docker_state,node_ecr_auth,node_cfn_deploy,node_stack_build toneMint
class node_ecs,node_runtime_cli,node_logs,node_scaling,node_rollback toneRose
class node_iam,node_aws_clients,node_operator,node_aws toneIndigo
```

## Components

### CLI workflows

- [UFO commands](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli.rb): `lib/ufo/cli.rb`
- [Project setup](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli/new/sequence.rb): `lib/ufo/cli/new/sequence.rb`

### Application setup

- [Configuration](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/config.rb): `lib/ufo/config.rb`
- [Config layering](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/layering/layer.rb): `lib/ufo/layering/layer.rb`
- [Task context](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/task_definition/context.rb): `lib/ufo/task_definition/context.rb`
- [Task definitions](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/task_definition/builder.rb): `lib/ufo/task_definition/builder.rb`
- [Deployment hooks](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/hooks/runner.rb): `lib/ufo/hooks/runner.rb`

### Image and deployment

- [Image build](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/docker/builder.rb): `lib/ufo/docker/builder.rb`
- [Image push](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/docker/pusher.rb): `lib/ufo/docker/pusher.rb`
- [Build state](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/docker/state/s3.rb): `lib/ufo/docker/state/s3.rb`
- [ECR login](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/ecr/auth.rb): `lib/ufo/ecr/auth.rb`
- [Stack deployment](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cfn/deploy.rb): `lib/ufo/cfn/deploy.rb`
- [Stack resources](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cfn/stack/builder/resources/ecs_service.rb): `lib/ufo/cfn/stack/builder/resources/ecs_service.rb`

### ECS operations

- [ECS service](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/ecs/service.rb): `lib/ufo/ecs/service.rb`
- [Runtime commands](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli/ps.rb): `lib/ufo/cli/ps.rb`
- [Service logs](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli/logs.rb): `lib/ufo/cli/logs.rb`
- [Service scaling](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/cli/scale.rb): `lib/ufo/cli/scale.rb`
- [Rollback](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/s3/rollback.rb): `lib/ufo/s3/rollback.rb`

### AWS integrations

- [IAM roles](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/iam_role/builder.rb): `lib/ufo/iam_role/builder.rb`
- [AWS clients](https://github.com/boltops-tools/ufo/blob/main/lib/ufo/aws_services.rb): `lib/ufo/aws_services.rb`

### Other components

- **Operator**
- **AWS services**

## Connections

- Operator → UFO commands: invokes
- UFO commands → Project setup: creates projects
- UFO commands → Configuration: uses settings
- Task context → Config layering: loads layers (evidence: `lib/ufo/task_definition/context.rb`)
- Task context → Task definitions: provides context
- UFO commands → Task definitions: builds definitions
- UFO commands → Image build: builds images
- Image build → Image push: pushes image
- Image build → Build state: stores state
- Image push → ECR login: authenticates
- ECR login → AWS clients: gets ECR token (evidence: `lib/ufo/ecr/auth.rb`)
- AWS clients → AWS services: creates clients (evidence: `lib/ufo/aws_services.rb`)
- UFO commands → Stack deployment: deploys stack
- Stack deployment → Stack resources: uses resources
- Stack resources → ECS service: defines service (evidence: `lib/ufo/cfn/stack/builder/resources/ecs_service.rb`)
- Stack resources → IAM roles: defines roles
- UFO commands → Runtime commands: runs operations
- UFO commands → Service logs: fetches logs
- UFO commands → Service scaling: scales service
- UFO commands → Rollback: rolls back
- UFO commands → Deployment hooks: runs hooks
