# tellerops/teller architecture

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

- Interactive diagram: https://gitdiagram.com/tellerops/teller
- Repository: https://github.com/tellerops/teller

## Overview

##### Project Type & Purpose
- The project is an open-source command-line tool (CLI) that acts as a universal secret manager.
- It is used to securely fetch, scan, redact, and sync secrets between various cloud providers and local configuration files.
- The README emphasizes operations such as “run” (to launch processes with secrets loaded), “scan” (to detect leaked secrets in code), “redact” (to filter out secrets from outputs), and “template” (to render configuration files).

##### Analyzing the File Structure
- Top-level directories include:
- teller-cli: Contains the user-facing CLI code and command implementations (e.g., commands within src/cli.rs, src/wizard.rs, etc.)
- teller-core: Houses the business logic, configuration processing, scanning, redacting, and templating functions.
- teller-providers: Includes integration modules for various secret providers (e.g., AWS, Google, dotenv, etc.). It provides adapters to connect the Teller logic to external systems.
- xtask: Likely used for automation tasks (e.g., custom build scripts or tooling).
- In addition, there are associated configuration files such as Cargo.toml, rust-toolchain.toml, and continuous integration workflows (in .github) – which show that there is an emphasis on quality, testing, and CI/CD.

a. Main Components:
- CLI Layer (teller-cli): The primary entry point that accepts user input (commands like “run”, “scan”, “redact”, “copy”, “put”, “delete”, “export”).
- Core Logic (teller-core): The core functional layer that processes configurations, conducts secret operations, scans for secret sprawl, and handles templating.
- Provider Integrations (teller-providers): Provides connections and abstractions to multiple secret providers (e.g., Hashicorp Vault, AWS Secrets Manager, Google Secret Manager, etc.), encapsulating provider-specific logic.
- Configuration Management: The YAML configuration (.teller.yml) which defines providers, maps, keys, and templating instructions.
- Testing & CI: Though not part of runtime architecture, the project includes robust testing (unit tests, integration tests, snapshots) and CI workflows that ensure each component behaves as expected.

b. Relationships and Interactions:
- The CLI layer receives input from the user and then routes the command to the core library.
- The core logic reads the configuration (from .teller.yml and related fixture files) and, based on the command, either manipulates environment variables, scans files, or triggers templating.
- When external data is needed, the core logic calls upon the providers layer, which in turn interacts with external secret managers (via their respective APIs, SDKs, or file integrations).
- There is a clear separation of concerns, where the CLI deals with user interaction, the core encapsulates business logic, and the providers encapsulate external integrations.

c. Architectural Patterns or Design Principles:
- Layered/MVC-like separation: User-interface (CLI) → Business Logic (Core) → Service Adapters (Providers).
- Modular design with clear separation: Each crate (teller-cli, teller-core, and teller-providers) strictly manages its domain responsibility.
- Dependency injection-like strategy: The core delegates provider-specific operations to the providers crate, allowing for extensibility to new secret sources.

d. Relevant Technologies & Frameworks:
- Rust is the primary language, with Cargo as the build and dependency management tool.
- Tera templating engine (as noted in the README) for template rendering.
- The project uses GitHub Actions for CI/CD (with workflows specified in .github/workflows).
- Testing frameworks in Rust with snapshot tests to ensure consistent behavior.

## Diagram (Mermaid)

```mermaid
graph TB
    U["User Request"]:::user
    CLI["CLI Interface (teller-cli)"]:::cli
    CORE["Core Logic (teller-core)"]:::core
    PROVIDER["Provider Integrations (teller-providers)"]:::provider
    CONFIG["Configuration (.teller.yml)"]:::config
    CI["CI/CD Workflows (.github)"]:::ci

    U -->|"input"| CLI
    CLI -->|"processCommand"| CORE
    CONFIG -->|"readsConfig"| CORE
    CORE -->|"secretOps"| PROVIDER
    PROVIDER -->|"response"| CORE
    CORE -->|"returnsOutput"| CLI
    CORE -->|"triggerTests"| CI

    click CLI "https://github.com/tellerops/teller/blob/master/teller-cli/src/cli.rs"
    click CORE "https://github.com/tellerops/teller/blob/master/teller-core/src/config.rs"
    click PROVIDER "https://github.com/tellerops/teller/tree/master/teller-providers/src/providers"
    click CONFIG "https://github.com/tellerops/teller/blob/master/teller-cli/fixtures/config.yml"
    click CI "https://github.com/tellerops/teller/tree/master/.github/workflows"

    classDef user fill:#ffe6e6,stroke:#b30000,stroke-width:2px;
    classDef cli fill:#f9e79f,stroke:#b7950b,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef provider fill:#a9dfbf,stroke:#1e8449,stroke-width:2px;
    classDef config fill:#f5cba7,stroke:#d35400,stroke-width:2px;
    classDef ci fill:#d2b4de,stroke:#8e44ad,stroke-width:2px;
```
