# ndavd/agevault architecture

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

- Interactive diagram: https://gitdiagram.com/ndavd/agevault
- Repository: https://github.com/ndavd/agevault

## Overview

##### Project Type and Purpose
- The project is a command-line directory encryption tool that uses age encryption.
- Its primary functions include generating an encrypted identity (keygen), locking a directory (encrypting its content), and unlocking it (decryption).
- It leverages the “age” encryption approach to ensure a secure and straightforward workflow.

##### Analyzing the File Structure
- The top-level files (main.go, go.mod, go.sum) indicate this is a Go-based CLI application.
- There’s an "internal" folder that houses the core functionality, organized into submodules:
– internal/archive: Contains tar.go and zip.go, suggesting that it handles archiving (e.g., compressing directories to single archive files) as a precursor to encryption.
– internal/crypt: Contains crypt.go, which likely manages the encryption and decryption routines using age.
– internal/shredder: Contains shredder.go, hinting at secure deletion or cleaning of sensitive data.
– internal/utils: Provides helper functions that support the other modules.
- The .github directory with GitHub Actions workflows (CI.yaml and release.yaml) addresses continuous integration and deployment, but these are not directly part of the runtime architecture.

##### Extracting Key Insights from the README
- The README describes the simple usage patterns: key generation, lock, and unlock commands.
- It emphasizes a no-frills, secure flow over extensive configuration.
- This security-focused operational flow indicates clear separations for key management, encryption, archiving, and file shredding.

a. Command-line Interface (CLI):
– Represented by main.go, it is the entry point that interprets user commands (e.g., lock, unlock, keygen).
b. Archive Module:
– Comprising tar.go and zip.go under internal/archive, this module handles packaging directories.
– Show its interaction with the CLI: after a command is issued, the appropriate archiving method is invoked.
c. Crypt Module:
– Containing crypt.go under internal/crypt, this module performs the encryption/decryption using age.
– Indicate that this module may depend on external libraries or follow similar patterns as the upstream age tool.
d. Shredder Module:
– Under internal/shredder, the shredder module securely deletes data after processing.
– Connect this module to the flow after encryption operations when needed.
e. Utilities:
– Located in internal/utils, these functions support common operations across the main modules.
f. Continuous Integration/Deployment:
– Optionally, include a CI/CD component (GitHub Workflows) that automates testing and releases, distinct from runtime architecture.

##### Relationships and Data Flow
– The CLI layer dispatches commands to the Archive, Crypt, and Shredder modules.
– For instance, the "lock" command triggers an archive process (if necessary), then passes data to the Crypt module to encrypt the archive, followed by optional secure deletion via the Shredder.
– Similarly, the "unlock" command invokes decryption first, then extraction via the Archive module.
- Utility functions being called by each module by linking the Utils layer.

##### Architectural Patterns and Design Principles
- Modularity & Separation of Concerns: Each internal package (archive, crypt, shredder, utils) is a self-contained module responsible for a specific part of the encryption workflow.
- Clear CLI Routing: The main.go file acts as a central controller, coordinating between the modules.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Layer"
        CLI["CLI (main.go)"]:::cli
    end

    subgraph "Internal Modules"
        Archive["Archive Module (tar & zip)"]:::module
        Crypt["Crypt Module (crypt.go)"]:::module
        Shredder["Shredder Module (shredder.go)"]:::module
        Utilities["Utilities (utils.go)"]:::utility
    end

    subgraph "CI/CD"
        CICD["GitHub Workflows (.github/workflows)"]:::external
    end

    %% Command flows for lock command
    CLI -->|"lock_cmd"| Archive
    Archive -->|"pack_dir"| Crypt
    Crypt -->|"encrypt_data"| Shredder

    %% Command flows for unlock command
    CLI -->|"unlock_cmd"| Crypt
    Crypt -->|"extract_data"| Archive

    %% Key generation command flow
    CLI -->|"keygen_cmd"| Crypt

    %% Utilities support
    Archive -->|"supports"| Utilities
    Crypt -->|"supports"| Utilities
    Shredder -->|"supports"| Utilities

    %% CI/CD interactions (for automation, testing, and deployment)
    CICD -.->|"automated_tests"| CLI
    CICD -.->|"deploys_to"| Crypt

    %% Click Events
    click CLI "https://github.com/ndavd/agevault/blob/main/main.go"
    click Archive "https://github.com/ndavd/agevault/tree/main/internal/archive"
    click Crypt "https://github.com/ndavd/agevault/blob/main/internal/crypt/crypt.go"
    click Shredder "https://github.com/ndavd/agevault/blob/main/internal/shredder/shredder.go"
    click Utilities "https://github.com/ndavd/agevault/blob/main/internal/utils/utils.go"
    click CICD "https://github.com/ndavd/agevault/tree/main/.github/workflows"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:2px;
    classDef module fill:#bbf,stroke:#333,stroke-width:2px;
    classDef utility fill:#ff9,stroke:#333,stroke-width:2px;
    classDef external fill:#f99,stroke:#333,stroke-width:2px;
```
