# the-impact-craft/terry architecture

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

- Interactive diagram: https://gitdiagram.com/the-impact-craft/terry
- Repository: https://github.com/the-impact-craft/terry

## Overview

##### Project Type and Purpose
- Terry is a terminal-based, visually-enhanced CLI designed for Terraform management. It integrates various Terraform commands (init, plan, apply, validate, etc.) into an interactive experience using the Textual framework.
- The application is essentially a full-stack CLI tool that abstracts complex Terraform operations and presents them in an intuitive UI. Although it is a CLI rather than a web application, it still separates concerns into presentation, domain logic, and underlying infrastructure.

##### File Structure for Key Architectural Components
- Notice the clear separation into layers:
- The “src/terry/domain” directory is divided further into submodules for file_system, operation_system, and terraform. These represent the core business logic and domain models – such as entities, exceptions, and services.
- The “src/terry/infrastructure” directory contains concrete implementations for interacting with the system’s file system, operating system, and Terraform commands, including command builders and context managers.
- The “src/terry/presentation/cli” directory encapsulates the user interface, using action handlers, screen definitions, widgets (buttons, containers, modals), and themes. This is where the Textual framework comes into play to deliver the CLI’s lightweight GUI.
- Additional support directories (e.g., tests, requirements) indicate that there’s a significant emphasis on maintaining robust test coverage and quality through CI/CD workflows.

##### README for Additional Insights
- The README highlights primary features such as workspace management, project exploration, and real-time validation of Terraform commands.
- It shows that the CLI presentation is minimalist and interactive, emphasizing a clear separation between UI components and the backend logic.
- Development and test instructions further indicate that the project supports different environments (development, production, testing), integrating tools like coverage and CI workflows (found in .github).

a. Main Components:
- Presentation Layer (CLI/UI): This includes all components related to the user interface, like action handlers, screens (about, file_system_navigation, main, search, tf_apply, etc.), widgets, themes, and utility modules.
- Domain Layer: This layer is responsible for the business logic. It is neatly partitioned into domains:
- File System Domain – handling file operations, entities, and exceptions.
- Operation System Domain – managing system-level operations and exceptions.
- Terraform Domain – further subdivided into “common”, “core”, and “workspaces”, each with their own entities, exceptions, and service logic.
- Infrastructure Layer: Implements low-level integrations with the underlying OS, file system, command execution for Terraform tasks, and shared utilities such as command process management and command building.
- External Dependencies: Terraform itself and possibly any external CLI tools or services invoked by the infrastructure. Also, the configuration files and external libraries such as Textual support the UI building.

b. Relationships and Interactions:
- The Presentation Layer (CLI) sends user commands (via action handlers) to the Domain Layer. In this layer, the business logic interprets the intent (e.g., initiating a Terraform plan, switching workspaces).
- The Domain Layer makes calls to the Infrastructure Layer for executing low-level operations. For example, when a command is issued to run a Terraform apply, the domain service delegates actual execution to the corresponding infrastructure service.
- The Infrastructure Layer interacts with both the host operating system and external Terraform commands and utilities.
- Data flows upward from the results/exceptions in the infrastructure, back through the domain, and ultimately rendered or reported via the presentation layer.

c. Architectural Patterns and Design Principles:
- The project follows a layered (or hexagonal) architecture, ensuring a separation between presentation, domain, and infrastructure.
- There seems to be a clear “command pattern” style within the CLI where action handlers interpret commands and trigger domain services.
- Dependency injection (as suggested by the “di_container.py” file in the CLI module) is used to manage components and ensure modularity.
- Clear separation of concerns helps in maintainability and testing; the existence of extensive tests in both unit and integration suggests a strong testable design.

d. Relevant Technologies, Frameworks, or Libraries:
- Python is the primary language.
- The Textual framework is used for the CLI UI.
- Terraform (as an external dependency) is central to the functionality of the app.
- Tools such as Ruff, PyLint, Pyright, and others in the CI/CD configuration suggest modern static analysis and linting practices.

##### Final Recommendations
- Review the README and file tree to verify that each component is included and that the relationships mirror how commands flow from the CLI down to the operational commands that invoke Terraform.
- Remember to incorporate versioning details or configuration items (such as pyproject.toml, CI workflows) if they play a crucial role in how the system is built and executed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        cli_app["CLI App (app.py)"]:::presentation
        about_handler["About Handler (about.py)"]:::presentation
        apply_handler["Apply Handler (apply.py)"]:::presentation
        init_handler["Init Handler (init.py)"]:::presentation
        plan_handler["Plan Handler (plan.py)"]:::presentation
        validate_handler["Validate Handler (validate.py)"]:::presentation
        screen_about["Screen: About (screens/about)"]:::presentation
        screen_main["Screen: Main (screens/main)"]:::presentation
        screen_tf_apply["Screen: TF Apply (screens/tf_apply)"]:::presentation
        di_container["DI Container (di_container.py)"]:::presentation
    end

    %% Domain Layer
    subgraph "Domain Layer"
        file_domain["File System Domain"]:::domain
        os_domain["Operation System Domain"]:::domain
        tf_common["Terraform Domain Common"]:::domain
        tf_core["Terraform Domain Core"]:::domain
        tf_workspaces["Terraform Domain Workspaces"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        infra_fs["File System Integration"]:::infrastructure
        infra_os["Operation System Integration"]:::infrastructure
        infra_tf_core["Terraform Integration Core"]:::infrastructure
        infra_tf_workspace["Terraform Integration Workspace"]:::infrastructure
        infra_shared["Shared Infrastructure Components"]:::infrastructure
    end

    %% External Dependencies
    subgraph "External Dependencies"
        terraform_extern["Terraform CLI"]:::external
        textual_fw["Textual Framework"]:::external
    end

    %% Connections from Presentation to Domain
    cli_app -->|"sendsCommand"| file_domain
    cli_app -->|"sendsCommand"| os_domain
    cli_app -->|"sendsCommand"| tf_core

    %% Internal Presentation Navigation
    about_handler -->|"navigatesTo"| screen_about
    apply_handler -->|"navigatesTo"| screen_tf_apply
    init_handler -->|"navigatesTo"| screen_main
    plan_handler -->|"navigatesTo"| screen_main
    validate_handler -->|"navigatesTo"| screen_main

    di_container -->|"injectsDependency"| tf_core

    %% Domain to Infrastructure Interactions
    file_domain -->|"executes"| infra_fs
    os_domain -->|"executes"| infra_os
    tf_core -->|"executes"| infra_tf_core
    tf_workspaces -->|"executes"| infra_tf_workspace
    tf_common -->|"supports"| tf_core
    tf_common -->|"supports"| tf_workspaces

    %% Reverse feedback from Infrastructure to Domain
    infra_fs -- "returnsResult" --> file_domain
    infra_os -- "returnsResult" --> os_domain
    infra_tf_core -- "returnsResult" --> tf_core
    infra_tf_workspace -- "returnsResult" --> tf_workspaces

    %% Shared Infrastructure utilities
    infra_shared -->|"providesUtilities"| infra_tf_core
    infra_shared -->|"providesUtilities"| infra_tf_workspace

    %% Infrastructure calling External Dependencies
    infra_tf_core -->|"calls"| terraform_extern
    infra_tf_workspace -->|"calls"| terraform_extern

    %% Presentation using External Framework
    cli_app -->|"rendersWith"| textual_fw

    %% Styles
    classDef presentation fill:#ffddcc,stroke:#333,stroke-width:2px;
    classDef domain fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef external fill:#f9e79f,stroke:#333,stroke-width:2px;

    %% Click Events for Presentation Layer
    click cli_app "https://github.com/the-impact-craft/terry/blob/main/src/terry/presentation/cli/app.py"
    click about_handler "https://github.com/the-impact-craft/terry/blob/main/src/terry/presentation/cli/about.py"
    click apply_handler "https://github.com/the-impact-craft/terry/blob/main/src/terry/presentation/cli/apply.py"
    click init_handler "https://github.com/the-impact-craft/terry/blob/main/src/terry/presentation/cli/init.py"
    click plan_handler "https://github.com/the-impact-craft/terry/blob/main/src/terry/presentation/cli/plan.py"
    click validate_handler "https://github.com/the-impact-craft/terry/blob/main/src/terry/presentation/cli/validate.py"
    click screen_about "https://github.com/the-impact-craft/terry/tree/main/src/terry/presentation/cli/screens/about"
    click screen_main "https://github.com/the-impact-craft/terry/tree/main/src/terry/presentation/cli/screens/main"
    click screen_tf_apply "https://github.com/the-impact-craft/terry/tree/main/src/terry/presentation/cli/screens/tf_apply"
    click di_container "https://github.com/the-impact-craft/terry/blob/main/src/terry/presentation/cli/di_container.py"

    %% Click Events for Domain Layer
    click file_domain "https://github.com/the-impact-craft/terry/tree/main/src/terry/domain/file_system"
    click os_domain "https://github.com/the-impact-craft/terry/tree/main/src/terry/domain/operation_system"
    click tf_common "https://github.com/the-impact-craft/terry/tree/main/src/terry/domain/terraform/common"
    click tf_core "https://github.com/the-impact-craft/terry/tree/main/src/terry/domain/terraform/core"
    click tf_workspaces "https://github.com/the-impact-craft/terry/tree/main/src/terry/domain/terraform/workspaces"

    %% Click Events for Infrastructure Layer
    click infra_fs "https://github.com/the-impact-craft/terry/tree/main/src/terry/infrastructure/file_system"
    click infra_os "https://github.com/the-impact-craft/terry/tree/main/src/terry/infrastructure/operation_system"
    click infra_tf_core "https://github.com/the-impact-craft/terry/tree/main/src/terry/infrastructure/terraform/core"
    click infra_tf_workspace "https://github.com/the-impact-craft/terry/tree/main/src/terry/infrastructure/terraform/workspace"
    click infra_shared "https://github.com/the-impact-craft/terry/tree/main/src/terry/infrastructure/shared"
```
