# i-had-a-bad-idea/pv architecture

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

- Interactive diagram: https://gitdiagram.com/i-had-a-bad-idea/pv
- Repository: https://github.com/i-had-a-bad-idea/pv

## Overview

##### Project type and purpose
- PV is a standalone CLI-based password manager written in Python.
- It uses AES-GCM encryption via the `cryptography` library, stores encrypted secrets in local files, and provides add/remove/list commands.
- Purpose: local, no-cloud password vault, extendable as a DIY project.

##### File structure
- Top-level:
- `.github/ISSUE_TEMPLATE` – templates for bug/feature issues
- `Documentation.md` – detailed CLI command docs
- `PV/` – the Python package containing `project.py` (the entry point)
- `Test_data/` – sample data for versions (not part of runtime)
- `setup.py` – packaging/install script
- PV module:
- `__init__.py`
- `project.py` – main CLI logic, command parser, orchestrates encryption & storage
- No separate frontend/backend; it’s a monolithic CLI with sub-components.

##### README for additional insights
- Technical stack: Python 3.7+, `cryptography`, `pyperclip`, `idna`
- Behavior: on first run, prompts for master key → derives encryption key → reads/writes two files:
- `PV_passwords` (encrypted vault)
- `PV_configs` (stores file paths/settings)
- Commands: add, passwords (list), password (retrieve), remove, export/import, cleanup.

a. Main components
- User (Terminal)
- CLI Interface (project.py)
- Command Dispatcher / Parser
- Vault Service
- Key Derivation & Crypto Engine (AES-GCM)
- Clipboard Integration (`pyperclip`)
- Storage Service
- File I/O for `PV_passwords` & `PV_configs`
- External Libraries
- cryptography, pyperclip, idna
b. Relationships & interactions
- User → types command in Terminal
- Terminal → CLI Interface → Command Dispatcher
- Dispatcher → Vault Service
- Key Derivation → Crypto Engine
- Crypto Engine ↔ Storage Service (read/write encrypted vault)
- On “password” command → vault decrypts → `pyperclip` copies to clipboard
- Storage Service → filesystem (e.g., `C:\ProgramData\PV`)
c. Architectural patterns & design principles
- Single-process monolith with clear separation:
- Presentation (CLI)
- Business logic (Vault Service)
- Infrastructure (Storage, Crypto libs)
- Dependency injection: core logic depends on abstracted Storage/Encryption modules
- Extensibility: new commands plug into the dispatcher
d. Relevant technologies
- Python runtime 3.7+
- cryptography (AES-GCM, key derivation)
- pyperclip (clipboard)
- idna (helper library)
- Standard libs: `os`, `base64`, `threading` (if used)

- Title: “PV CLI Password Vault – High-Level Architecture”
- CLI Interface (`PV.project.py`)
- VaultService / CryptoEngine
- StorageService / FileManager
- External Libraries
- User input → CLI
- CLI → CommandDispatcher
- Dispatcher → VaultService
- VaultService → CryptoEngine
- CryptoEngine ↔ StorageService → Filesystem
- VaultService → Clipboard integration

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User (Terminal)"]:::frontend
    CLI["CLI Interface\n(PV/project.py)"]:::frontend
    Dispatcher["Command Dispatcher\n(Parser)"]:::core
    Vault["Vault Service"]:::core
    Crypto["Crypto Engine\n(AES-GCM)"]:::core
    Storage["Storage Service\n(File Manager)"]:::infra
    Filesystem["Filesystem\n(ProgramData)"]:::infra
    Clipboard["Clipboard Integration\n(pyperclip)"]:::external
    ExtLib["External Libraries\n(cryptography, idna)"]:::external
    Init["Package Init\n(PV/__init__.py)"]:::core
    Doc["Project Documentation\n(Documentation.md)"]:::infra
    Setup["Packaging Script\n(setup.py)"]:::infra
    Issues["Issue Templates\n(.github/ISSUE_TEMPLATE/)"]:::external
    TestData["Sample Test Data\n(Test_data/)"]:::external
    Readme["README Overview\n(README.md)"]:::external
    License["License Information\n(LICENSE)"]:::external

    User -->|"types command"| CLI
    CLI -->|"parse() / dispatch"| Dispatcher
    Dispatcher -->|"invoke(command)"| Vault
    Vault -->|"derive_key()"| Crypto
    Vault -->|"encrypt()/decrypt()"| Crypto
    Crypto -.->|"read/write encrypted vault"| Storage
    Storage -->|"filesystem I/O"| Filesystem
    Vault -->|"copy_to_clipboard()"| Clipboard
    Crypto -.-> ExtLib
    Clipboard -.-> ExtLib

    %% Mapped component click events
    click CLI "https://github.com/i-had-a-bad-idea/pv/blob/main/PV/project.py"
    click Init "https://github.com/i-had-a-bad-idea/pv/blob/main/PV/__init__.py"
    click Doc "https://github.com/i-had-a-bad-idea/pv/blob/main/Documentation.md"
    click Setup "https://github.com/i-had-a-bad-idea/pv/blob/main/setup.py"
    click Issues "https://github.com/i-had-a-bad-idea/pv/tree/main/.github/ISSUE_TEMPLATE/"
    click TestData "https://github.com/i-had-a-bad-idea/pv/tree/main/Test_data/"
    click Readme "https://github.com/i-had-a-bad-idea/pv/blob/main/README.md"
    click License "https://github.com/i-had-a-bad-idea/pv/tree/main/LICENSE"

    classDef frontend fill:#9f6,stroke:#333,stroke-width:1px
    classDef core fill:#6cf,stroke:#333,stroke-width:1px
    classDef infra fill:#f90,stroke:#333,stroke-width:1px
    classDef external fill:#ccc,stroke:#333,stroke-width:1px
```
