# imshakil/pacli architecture

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

- Interactive diagram: https://gitdiagram.com/imshakil/pacli
- Repository: https://github.com/imshakil/pacli

## Overview

##### Project Type and Purpose
- pacli is a command-line tool (CLI) for securely storing and managing secrets locally.
- It provides subcommands for secrets CRUD, SSH connection management, URL shortening, clipboard integration, and exporting data.

##### File Structure
Top-level directories & files:
- pacli/
– cli.py (entry point)
– commands/ (admin, secrets, ssh, utils)
– store.py (data persistence & encryption)
– linklyhq.py (LinklyHQ API integration)
– ssh_utils.py (SSH connection)
– helpers.py, decorators.py, log.py (utility modules)
- tests/ (unit tests)
- GitHub workflows (.github/workflows/*.yml)
- pyproject.toml, requirements.txt (build & dependencies)

Architectural patterns:
- CLI-driven command dispatcher (likely uses click or argparse)
- Modular commands implementing Single Responsibility
- Local encrypted storage (file-based database via store.py)
- External integrations: LinklyHQ API, system clipboard, SSH client

##### Key Insights from README
- Master password encryption for the local store
- Environment variables for master password and LinklyHQ credentials
- Commands to add/get/update/delete secrets, manage SSH, shorten URLs, copy to clipboard, and export data

##### Main Components & Interactions
a. User Shell & CLI Frontend
– Component: Terminal / shell
– Tech: Python CLI (click/argparse) in pacli/cli.py
b. Command Dispatcher
– Routes subcommands (init, add, get, ssh, short, cc, export)
– Located in pacli/commands/*.py
c. Core Logic Modules
– pacli/store.py
- Handles encrypted file storage, master password, CRUD operations
– pacli/ssh_utils.py
- Wraps SSH client calls
– pacli/linklyhq.py
- HTTP client for LinklyHQ API
– pacli/helpers.py, decorators.py, log.py
- Shared utilities, logging, CLI prompts
d. External Services & OS Integrations
– File System (encrypted data file in user’s home)
– System Clipboard (via pyperclip or similar)
– External API (LinklyHQ REST endpoint)
– SSH Daemon (remote servers)
e. Environment & Configuration
– Environment Variables (PACLI_MASTER_PASSWORD, PACLI_LINKLYHQ_KEY/WID)
– Configuration files (none; uses env + prompts)

##### Architectural Patterns & Design Principles
- Separation of Concerns: CLI entrypoint vs. command modules vs. helpers vs. store
- Single Responsibility: each command class handles one feature
- Inversion of Control: decorators manage cross-cutting concerns (e.g., error handling)
- Local-First Security: encrypted at rest, master password prompt/use of env var

- Notes on technologies (e.g., Python, file-based encryption, HTTP REST)
- Modules with file paths (e.g., pacli/store.py) for clarity

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layer 1: User Interaction
    Terminal["Terminal"]:::ui
    CLI["pacli CLI\n(cli.py)"]:::internal
    Terminal --> CLI
    click CLI "https://github.com/imshakil/pacli/blob/main/pacli/cli.py"

    %% Layer 2: Command Dispatcher
    subgraph "Command Dispatcher"
        AdminCmd["Admin Commands\n(admin.py)"]:::internal
        SecretsCmd["Secrets CRUD Commands\n(secrets.py)"]:::internal
        SSHCmd["SSH Management Commands\n(ssh.py)"]:::internal
        UtilsCmd["Utility Commands\n(utils.py)"]:::internal
    end
    CLI --> AdminCmd
    CLI --> SecretsCmd
    CLI --> SSHCmd
    CLI --> UtilsCmd

    click AdminCmd "https://github.com/imshakil/pacli/blob/main/pacli/commands/admin.py"
    click SecretsCmd "https://github.com/imshakil/pacli/blob/main/pacli/commands/secrets.py"
    click SSHCmd "https://github.com/imshakil/pacli/blob/main/pacli/commands/ssh.py"
    click UtilsCmd "https://github.com/imshakil/pacli/blob/main/pacli/commands/utils.py"

    %% Layer 3: Core Services & Utilities
    subgraph "Core Services & Utilities"
        Storage["Storage Service\n(store.py)"]:::internal
        SSHService["SSH Service\n(ssh_utils.py)"]:::internal
        Linkly["URL Shortener Service\n(linklyhq.py)"]:::internal
        Helpers["Helpers\n(helpers.py)"]:::internal
        Decorators["Decorators\n(decorators.py)"]:::internal
        Log["Logging Module\n(log.py)"]:::internal
    end

    AdminCmd --> Storage
    SecretsCmd --> Storage
    UtilsCmd --> Storage
    SSHCmd --> SSHService
    UtilsCmd --> Helpers
    UtilsCmd --> Linkly

    AdminCmd --> Decorators
    SecretsCmd --> Decorators
    SSHCmd --> Decorators
    UtilsCmd --> Decorators

    AdminCmd --> Log
    SecretsCmd --> Log
    SSHCmd --> Log
    UtilsCmd --> Log

    click Storage "https://github.com/imshakil/pacli/blob/main/pacli/store.py"
    click SSHService "https://github.com/imshakil/pacli/blob/main/pacli/ssh_utils.py"
    click Linkly "https://github.com/imshakil/pacli/blob/main/pacli/linklyhq.py"
    click Helpers "https://github.com/imshakil/pacli/blob/main/pacli/helpers.py"
    click Decorators "https://github.com/imshakil/pacli/blob/main/pacli/decorators.py"
    click Log "https://github.com/imshakil/pacli/blob/main/pacli/log.py"

    %% Layer 4: External & OS Integrations
    subgraph "External & OS Integrations"
        FileSys["Encrypted File Store (File System)"]:::local
        Clipboard["OS Clipboard API"]:::local
        Env["Env Vars\n(PACLI_MASTER_PASSWORD,\nPACLI_LINKLYHQ_KEY)"]:::config
        SSHServer["SSH Servers"]:::external
        LinklyAPI["LinklyHQ API"]:::external
    end

    Storage <--> FileSys
    Helpers <--> Clipboard
    CLI --> Env
    Storage --> Env
    Linkly --> Env
    SSHService --> SSHServer
    Linkly --> LinklyAPI

    %% Styling
    classDef internal fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef local fill:#DFFFD0,stroke:#333,stroke-width:1px
    classDef external fill:#FFD0A0,stroke:#333,stroke-width:1px
    classDef ui fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#333,stroke-width:1px
```
