# lunarway/shuttle architecture

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

- Interactive diagram: https://gitdiagram.com/lunarway/shuttle
- Repository: https://github.com/lunarway/shuttle

## Overview

##### Main Components

a. Core Components:
- CLI Interface Layer
- Plan Management System
- Execution Engine
- Template Engine
- Telemetry System

b. External Components:
- Git Repositories (Plan Sources)
- Project Directories
- Docker Runtime
- Go Runtime

**┌─────────────────────────────────────────────────────────┐**
- CLI Interface                        │
- ┤
- Core Services                        │
- ┬───────────────┬────────────┬───────────┤
- Plan Manager  │ Executor      │ Template   │ Telemetry │
- Framework      │ Engine     │ System    │
- ┴───────────────┴────────────┴───────────┤
- Executors                           │
- ┬───────────────┬────────────────────────┤
- Shell         │ Docker        │ Golang                 │
- Executor      │ Executor      │ Executor               │
- ┴───────────────┴────────────────────────┘

##### Component Details

a. CLI Interface:
- Command handlers (run, plan, get, has, etc.)
- Configuration parsing
- User interaction components

b. Plan Manager:
- Plan loading and caching
- Git integration
- Plan validation
- Variable management

c. Executor Framework:
- Task execution pipeline
- Script handling
- Action coordination

d. Template Engine:
- Template processing
- Function registry
- Variable substitution

e. Telemetry System:
- Logging
- Metrics collection
- Upload mechanism

##### External Interactions

Connections to:
- Git repositories (for plan fetching)
- Local filesystem (for project files)
- Docker daemon (for container operations)
- Go runtime (for action execution)

##### Important Implementation Details

Highlight:
- Plan inheritance and overriding
- Script execution paths
- Template processing pipeline
- Golang action compilation and execution
- Telemetry data flow

##### Notes

Annotations for:
- Caching mechanisms
- Security boundaries
- Configuration points
- Extension points

- The modular executor system
- Plan management flexibility
- Template processing capabilities
- Integration with external tools

Keep the abstraction level focused on the architectural components while showing enough detail to understand the system's operation and extension points.

This design captures Shuttle's core functionality as a build and deploy tool orchestrator while showing its flexibility in handling different project types and execution environments.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph CLI
        CLI_MAIN["CLI Interface"]:::cli
        CMD_RUN["Run Command"]:::cli
        CMD_PLAN["Plan Command"]:::cli
        CMD_GET["Get Command"]:::cli
        CMD_HAS["Has Command"]:::cli
        CMD_CONFIG["Config Handler"]:::cli
        
        CLI_MAIN --> CMD_RUN
        CLI_MAIN --> CMD_PLAN
        CLI_MAIN --> CMD_GET
        CLI_MAIN --> CMD_HAS
        CLI_MAIN --> CMD_CONFIG
    end

    subgraph Core
        PLAN_MGR["Plan Manager"]:::core
        EXEC_FW["Executor Framework"]:::core
        TMPL_ENG["Template Engine"]:::core
        TEL_SYS["Telemetry System"]:::core

        PLAN_MGR --> EXEC_FW
        EXEC_FW --> TMPL_ENG
        EXEC_FW --> TEL_SYS
    end

    subgraph Executors
        SHELL_EXEC["Shell Executor"]:::executor
        DOCKER_EXEC["Docker Executor"]:::executor
        GO_EXEC["Golang Executor"]:::executor

        EXEC_FW --> SHELL_EXEC
        EXEC_FW --> DOCKER_EXEC
        EXEC_FW --> GO_EXEC
    end

    subgraph External
        GIT["Git Repository"]:::external
        DOCKER["Docker Runtime"]:::external
        GO["Go Runtime"]:::external
        FS["File System"]:::external
    end

    CMD_RUN --> PLAN_MGR
    CMD_PLAN --> PLAN_MGR
    CMD_GET --> PLAN_MGR
    CMD_HAS --> PLAN_MGR

    PLAN_MGR -.-> GIT
    DOCKER_EXEC -.-> DOCKER
    GO_EXEC -.-> GO
    PLAN_MGR -.-> FS

    %% Click Events
    click CLI_MAIN "https://github.com/lunarway/shuttle/tree/master/cmd"
    click CMD_RUN "https://github.com/lunarway/shuttle/blob/master/cmd/run.go"
    click CMD_PLAN "https://github.com/lunarway/shuttle/blob/master/cmd/plan.go"
    click CMD_GET "https://github.com/lunarway/shuttle/blob/master/cmd/get.go"
    click CMD_HAS "https://github.com/lunarway/shuttle/blob/master/cmd/has.go"
    click CMD_CONFIG "https://github.com/lunarway/shuttle/blob/master/cmd/config.go"
    click PLAN_MGR "https://github.com/lunarway/shuttle/tree/master/pkg/config"
    click EXEC_FW "https://github.com/lunarway/shuttle/blob/master/pkg/executors/executor.go"
    click TMPL_ENG "https://github.com/lunarway/shuttle/tree/master/pkg/templates"
    click TEL_SYS "https://github.com/lunarway/shuttle/blob/master/pkg/telemetry/telemetry.go"
    click SHELL_EXEC "https://github.com/lunarway/shuttle/blob/master/pkg/executors/shell.go"
    click DOCKER_EXEC "https://github.com/lunarway/shuttle/blob/master/pkg/executors/docker.go"
    click GO_EXEC "https://github.com/lunarway/shuttle/blob/master/pkg/executors/golang/executer/executer.go"

    %% Styles
    classDef cli fill:#2374ab
    classDef core fill:#048ba8
    classDef executor fill:#16db93
    classDef external fill:#888888
    
    %% Legend
    subgraph Legend
        L1["CLI Components"]:::cli
        L2["Core Services"]:::core
        L3["Executors"]:::executor
        L4["External Systems"]:::external
    end
```
