# garfield-u/vaultshield architecture

> Architecture diagram of the GitHub repository garfield-u/vaultshield, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/garfield-u/vaultshield
- Repository: https://github.com/garfield-u/vaultshield

## Overview

VaultShield is a local password manager with a command-line workflow and a Tkinter dashboard. In the CLI, the user authenticates, then adds, views, searches, or deletes entries; the entry point delegates authentication, storage, and password encoding/decoding to separate modules. The GUI provides a broader dashboard, including password management, settings, and security features. GUI code is a single large module, so its responsibilities are shown separately but share that path. GUI storage details are based on the sampled excerpts; documented capabilities are included where implementation was not sampled.

Main entry points: [`gui.py`](https://github.com/garfield-u/vaultshield/blob/main/gui.py) (Tkinter Dashboard), [`main.py`](https://github.com/garfield-u/vaultshield/blob/main/main.py) (CLI Workflow), [`auth.py`](https://github.com/garfield-u/vaultshield/blob/main/auth.py) (Master Login), [`storage.py`](https://github.com/garfield-u/vaultshield/blob/main/storage.py) (Vault Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Command Line"]
  node_cli_app["CLI Workflow<br/>[main.py]"]
end

subgraph group_gui["Desktop Dashboard"]
  node_dashboard["Tkinter Dashboard<br/>[gui.py]"]
  node_entry_management["Entry Management<br/>[gui.py]"]
  node_password_view["Reveal And Copy<br/>[gui.py]"]
  node_preferences["Settings And Lock<br/>[gui.py]"]
end

subgraph group_security["Authentication And Security"]
  node_auth["Master Login<br/>[auth.py]"]
  node_encoding["Password Encoding<br/>[utils.py]"]
  node_security_tools["Security Checks<br/>[gui.py]"]
end

subgraph group_local["Local Data"]
  node_storage_ops["Vault Operations<br/>[storage.py]"]
  node_vault[("Password Vault")]
  node_master_store[("Master Hash")]
  node_settings_store[("Settings Data")]
end

node_user(("User"))
node_clipboard["System Clipboard"]

node_user -->|"chooses actions"| node_cli_app
node_cli_app -->|"authenticates"| node_auth
node_cli_app -->|"manages entries"| node_storage_ops
node_cli_app -->|"encodes and decodes"| node_encoding
node_storage_ops -->|"reads and writes"| node_vault
node_auth -->|"reads and writes hash"| node_master_store
node_user -->|"uses dashboard"| node_dashboard
node_dashboard -->|"offers management"| node_entry_management
node_dashboard -->|"offers reveal and copy"| node_password_view
node_entry_management -->|"reads and writes"| node_vault
node_password_view -.->|"reads entries"| node_vault
node_password_view -->|"copies password"| node_clipboard
node_dashboard -->|"offers settings"| node_preferences
node_preferences -->|"loads settings"| node_settings_store
node_preferences -.->|"locks on inactivity"| node_dashboard
node_dashboard -->|"offers security checks"| node_security_tools
node_security_tools -->|"checks master hash"| node_master_store
node_security_tools -->|"resets vault"| node_vault

click node_cli_app "https://github.com/garfield-u/vaultshield/blob/main/main.py"
click node_auth "https://github.com/garfield-u/vaultshield/blob/main/auth.py"
click node_encoding "https://github.com/garfield-u/vaultshield/blob/main/utils.py"
click node_storage_ops "https://github.com/garfield-u/vaultshield/blob/main/storage.py"
click node_dashboard "https://github.com/garfield-u/vaultshield/blob/main/gui.py"
click node_entry_management "https://github.com/garfield-u/vaultshield/blob/main/gui.py"
click node_password_view "https://github.com/garfield-u/vaultshield/blob/main/gui.py"
click node_preferences "https://github.com/garfield-u/vaultshield/blob/main/gui.py"
click node_security_tools "https://github.com/garfield-u/vaultshield/blob/main/gui.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_app,node_user toneBlue
class node_dashboard,node_entry_management,node_password_view,node_preferences toneAmber
class node_auth,node_encoding,node_security_tools toneMint
class node_storage_ops,node_vault,node_master_store,node_settings_store toneRose
class node_clipboard toneIndigo
```

## Components

### Command Line

- [CLI Workflow](https://github.com/garfield-u/vaultshield/blob/main/main.py): `main.py`

### Desktop Dashboard

- [Tkinter Dashboard](https://github.com/garfield-u/vaultshield/blob/main/gui.py): `gui.py`
- [Entry Management](https://github.com/garfield-u/vaultshield/blob/main/gui.py): `gui.py`
- [Reveal And Copy](https://github.com/garfield-u/vaultshield/blob/main/gui.py): `gui.py`
- [Settings And Lock](https://github.com/garfield-u/vaultshield/blob/main/gui.py): `gui.py`

### Authentication And Security

- [Master Login](https://github.com/garfield-u/vaultshield/blob/main/auth.py): `auth.py`
- [Password Encoding](https://github.com/garfield-u/vaultshield/blob/main/utils.py): `utils.py`
- [Security Checks](https://github.com/garfield-u/vaultshield/blob/main/gui.py): `gui.py`

### Local Data

- [Vault Operations](https://github.com/garfield-u/vaultshield/blob/main/storage.py): `storage.py`
- **Password Vault**
- **Master Hash**
- **Settings Data**

### Other components

- **User**
- **System Clipboard**

## Connections

- User → CLI Workflow: chooses actions (evidence: `main.py`)
- CLI Workflow → Master Login: authenticates (evidence: `main.py`)
- CLI Workflow → Vault Operations: manages entries (evidence: `main.py`)
- CLI Workflow → Password Encoding: encodes and decodes (evidence: `main.py`)
- Vault Operations → Password Vault: reads and writes (evidence: `storage.py`)
- Master Login → Master Hash: reads and writes hash (evidence: `auth.py`)
- User → Tkinter Dashboard: uses dashboard (evidence: `README.md`)
- Tkinter Dashboard → Entry Management: offers management (evidence: `README.md`)
- Tkinter Dashboard → Reveal And Copy: offers reveal and copy (evidence: `README.md`)
- Entry Management → Password Vault: reads and writes (evidence: `gui.py`)
- Reveal And Copy → Password Vault: reads entries
- Reveal And Copy → System Clipboard: copies password (evidence: `gui.py`)
- Tkinter Dashboard → Settings And Lock: offers settings (evidence: `gui.py`)
- Settings And Lock → Settings Data: loads settings (evidence: `gui.py`)
- Settings And Lock → Tkinter Dashboard: locks on inactivity (evidence: `README.md`)
- Tkinter Dashboard → Security Checks: offers security checks (evidence: `README.md`)
- Security Checks → Master Hash: checks master hash (evidence: `gui.py`)
- Security Checks → Password Vault: resets vault (evidence: `gui.py`)
