# yammerjp/optruck architecture

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

- Interactive diagram: https://gitdiagram.com/yammerjp/optruck
- Repository: https://github.com/yammerjp/optruck

## Overview

##### Project Type and Purpose
- optruck is a command-line application that facilitates two main operations: uploading secrets (from a local or k8s data source) into 1Password and generating template files for secret restoration.
- Its major use case is integrating with 1Password via the 1Password CLI, along with optionally interacting with a Kubernetes environment.

##### Key Components
a. CLI Application Interface:
- Entry Point: main.go initializes the app and dispatches command handling.
- Command Package: Under cmd/optruck, you have files for handling the CLI commands, interactive prompts, versioning, help, and the build process.

b. Interactive Mode Module:
- Found in internal/interactive – modules for guiding the user through selecting the data source, target vault/account in 1Password, and template file paths.

c. Data Sources:
- pkg/datasources contains modules to load secrets:
- envfile (for local .env files)
- k8ssecret (for obtaining secrets from Kubernetes)
- These components are crucial in determining how the secret data is ingested.

d. 1Password Operations:
- pkg/op: Implements functions for listing, creating, editing, and uploading secrets from optruck to 1Password.
- This module communicates with the op (1Password CLI) command.

e. Output/Template Generation:
- pkg/output: Contains functions to render templates (like envtemplate and k8stemplate) for the restoration process.

f. Kubernetes Integration:
- pkg/kube: Encapsulates functionality for connecting to Kubernetes clusters to retrieve secrets when the user opts for Kubernetes as the data source.

g. Utility and Logging Functions:
- internal/util (and its submodule exec and logger): Provide wrappers for executing system commands and logging functionality that support the application’s operations.

##### Relationships and Interactions
- In interactive mode (triggered with the "-i" flag), control flows into the internal/interactive module, which works closely with the data source modules to gather necessary secrets.
- Depending on the selected data source, either pkg/datasources/envfile (for .env files) or pkg/datasources/k8ssecret (for Kubernetes) is triggered.
- Once secrets are retrieved, the pkg/op components process these secrets, orchestrating the correct operation to upload or modify the secrets in 1Password via the CLI command, and then hand-off processing to pkg/output for template generation.
- Utility modules (internal/util) aid tasks such as command execution and logging throughout the flow.

##### Key Architectural Patterns/Design Principles
- Separation of Concerns: Codebase is neatly segmented into CLI command handling (cmd), interactive workflows (internal/interactive), business logic (pkg/op, pkg/datasources), and utility libraries.
- Modularity: Different functionalities (data ingestion, secret actions, template generation) are isolated in separate packages, making the system easier to understand and maintain.
- Extensibility: New data sources or output formats can be added with minimal changes to existing modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI1["CLI Entry (main.go)"]:::cli
        CMD["Command Package (cmd/optruck)"]:::cli
    end

    subgraph "Interactive Layer"
        IM["Interactive Mode (internal/interactive)"]:::interactive
    end

    subgraph "Data Sources"
        ENV[".env Files (pkg/datasources/envfile)"]:::datasource
        K8S["Kubernetes Secrets (pkg/datasources/k8ssecret)"]:::datasource
    end

    subgraph "External Integrations"
        EXTP["1Password CLI (external)"]:::external
        EXTK["Kubernetes API (external)"]:::external
    end

    subgraph "Processing"
        OPS["1Password Operations (pkg/op)"]:::op
        OUT["Output/Template Generation (pkg/output)"]:::output
    end

    subgraph "Kubernetes Integration"
        KUBE["Kubernetes Integration (pkg/kube)"]:::kube
    end

    subgraph "Utilities"
        UTIL["Utilities (internal/util)"]:::util
    end

    CICD["CI/CD Configuration (Build/Deployment)"]:::cicd

    %% Relationships
    CLI1 -->|"init"| CMD
    CMD -->|"if-i-flag"| IM
    IM -->|"select-.env"| ENV
    IM -->|"select-k8s"| K8S
    K8S -->|"fetch-secrets"| KUBE
    KUBE -->|"return-secrets"| K8S
    ENV -->|"load-secrets"| OPS
    K8S -->|"provide-secrets"| OPS
    OPS -->|"upload_secret"| EXTP
    OPS -->|"generate_template"| OUT
    KUBE -->|"call_K8s_API"| EXTK

    %% Utilities support (dashed lines)
    CMD ---|"util_support"| UTIL
    IM ---|"util_support"| UTIL
    ENV ---|"util_support"| UTIL
    K8S ---|"util_support"| UTIL
    OPS ---|"util_support"| UTIL
    OUT ---|"util_support"| UTIL

    %% CI/CD integration
    CICD ---|"build&deploy"| CMD

    %% Click Events
    click CLI1 "https://github.com/yammerjp/optruck/blob/main/main.go"
    click CMD "https://github.com/yammerjp/optruck/tree/main/cmd/optruck"
    click IM "https://github.com/yammerjp/optruck/tree/main/internal/interactive"
    click ENV "https://github.com/yammerjp/optruck/blob/main/pkg/datasources/envfile.go"
    click K8S "https://github.com/yammerjp/optruck/blob/main/pkg/datasources/k8ssecret.go"
    click OPS "https://github.com/yammerjp/optruck/tree/main/pkg/op"
    click OUT "https://github.com/yammerjp/optruck/tree/main/pkg/output"
    click KUBE "https://github.com/yammerjp/optruck/tree/main/pkg/kube"
    click UTIL "https://github.com/yammerjp/optruck/tree/main/internal/util"

    %% Styles
    classDef cli fill:#f9c,stroke:#333,stroke-width:2px;
    classDef interactive fill:#bbf,stroke:#333,stroke-width:2px;
    classDef datasource fill:#efe,stroke:#333,stroke-width:2px;
    classDef op fill:#cfc,stroke:#333,stroke-width:2px;
    classDef output fill:#cff,stroke:#333,stroke-width:2px;
    classDef util fill:#ddd,stroke:#333,stroke-width:2px;
    classDef external fill:#fdd,stroke:#333,stroke-width:2px;
    classDef kube fill:#dfd,stroke:#333,stroke-width:2px;
    classDef cicd fill:#ffd,stroke:#333,stroke-width:2px;
```
