# thunderskull7/secure-password-manager-cpp architecture

> Architecture diagram of the GitHub repository thunderskull7/secure-password-manager-cpp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thunderskull7/secure-password-manager-cpp
- Repository: https://github.com/thunderskull7/secure-password-manager-cpp

## Overview

Secure Password Manager is an offline C++ CLI for managing credentials in an authenticated, encrypted local vault. The user enters through the interactive application: create or unlock a vault, manage and search credentials, optionally generate passwords, then save or lock the session. Its domain stages are credential handling, cryptography, serialization, and atomic persistence. The graph also shows secure-memory support and terminal echo control. CLI implementation details were not sampled; workflow links from it follow the README, while internal storage and cryptography links are supported by the excerpts and source index.

Main entry points: [`src/cli/PasswordManagerApp.cpp`](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/cli/PasswordManagerApp.cpp) (Interactive app), [`src/core/VaultStorage.cpp`](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/VaultStorage.cpp) (Vault storage), [`src/core/Vault.cpp`](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/Vault.cpp) (Credential vault), [`src/core/CryptoService.cpp`](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/CryptoService.cpp) (Crypto service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI experience"]
  node_app["Interactive app"]
  node_console["Console I/O<br/>[Console.cpp]"]
  node_banner["Startup banner<br/>[Banner.cpp]"]
end

subgraph group_domain["Credential domain"]
  node_generator["Password generator"]
  node_credential["Credential model<br/>[Credential.cpp]"]
  node_validator["Credential validation"]
  node_vault["Credential vault<br/>[Vault.cpp]"]
  node_timestamp["Timestamp service<br/>[Timestamp.cpp]"]
end

subgraph group_security["Security services"]
  node_crypto["Crypto service<br/>[CryptoService.cpp]"]
  node_sodium["Sodium initialization"]
  node_securekey["Secure key<br/>[SecureKey.cpp]"]
  node_securebuffer["Secure buffer<br/>[SecureBuffer.cpp]"]
end

subgraph group_persistence["Vault persistence"]
  node_storage["Vault storage<br/>[VaultStorage.cpp]"]
  node_format["Binary file format"]
  node_serializer["Vault serializer"]
end

node_user(("User"))
node_filesystem[("Local filesystem")]

node_user -->|"uses"| node_app
node_app -->|"reads and prints"| node_console
node_app -->|"shows"| node_banner
node_app -->|"manages credentials"| node_vault
node_app -->|"loads and saves"| node_storage
node_app -->|"requests passwords"| node_generator
node_vault -->|"validates inputs"| node_validator
node_vault -.->|"stores records"| node_credential
node_vault -.->|"timestamps changes"| node_timestamp
node_storage -->|"derives and encrypts"| node_crypto
node_storage -->|"serializes credentials"| node_serializer
node_storage -->|"validates header"| node_format
node_storage -->|"reads and writes"| node_filesystem
node_crypto -->|"initializes library"| node_sodium
node_crypto -.->|"returns derived key"| node_securekey
node_crypto -.->|"returns plaintext buffer"| node_securebuffer
node_serializer -->|"uses protected buffer"| node_securebuffer

click node_app "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/cli/PasswordManagerApp.cpp"
click node_console "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/cli/Console.cpp"
click node_banner "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/ui/Banner.cpp"
click node_generator "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/PasswordGenerator.cpp"
click node_credential "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/models/Credential.cpp"
click node_validator "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/CredentialValidator.cpp"
click node_vault "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/Vault.cpp"
click node_timestamp "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/Timestamp.cpp"
click node_crypto "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/CryptoService.cpp"
click node_sodium "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/SodiumInitializer.cpp"
click node_securekey "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/SecureKey.cpp"
click node_securebuffer "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/SecureBuffer.cpp"
click node_storage "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/VaultStorage.cpp"
click node_format "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/include/core/VaultFileFormat.hpp"
click node_serializer "https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/VaultSerializer.cpp"

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_app,node_console,node_banner,node_user toneBlue
class node_generator,node_credential,node_validator,node_vault,node_timestamp,node_filesystem toneAmber
class node_crypto,node_sodium,node_securekey,node_securebuffer toneMint
class node_storage,node_format,node_serializer toneRose
```

## Components

### CLI experience

- [Interactive app](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/cli/PasswordManagerApp.cpp): `src/cli/PasswordManagerApp.cpp`
- [Console I/O](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/cli/Console.cpp): `src/cli/Console.cpp`
- [Startup banner](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/ui/Banner.cpp): `src/ui/Banner.cpp`

### Credential domain

- [Password generator](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/PasswordGenerator.cpp): `src/core/PasswordGenerator.cpp`
- [Credential model](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/models/Credential.cpp): `src/models/Credential.cpp`
- [Credential validation](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/CredentialValidator.cpp): `src/core/CredentialValidator.cpp`
- [Credential vault](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/Vault.cpp): `src/core/Vault.cpp`
- [Timestamp service](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/Timestamp.cpp): `src/core/Timestamp.cpp`

### Security services

- [Crypto service](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/CryptoService.cpp): `src/core/CryptoService.cpp`
- [Sodium initialization](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/SodiumInitializer.cpp): `src/core/SodiumInitializer.cpp`
- [Secure key](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/SecureKey.cpp): `src/core/SecureKey.cpp`
- [Secure buffer](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/SecureBuffer.cpp): `src/core/SecureBuffer.cpp`

### Vault persistence

- [Vault storage](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/VaultStorage.cpp): `src/core/VaultStorage.cpp`
- [Binary file format](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/include/core/VaultFileFormat.hpp): `include/core/VaultFileFormat.hpp`
- [Vault serializer](https://github.com/thunderskull7/secure-password-manager-cpp/blob/main/src/core/VaultSerializer.cpp): `src/core/VaultSerializer.cpp`

### Other components

- **User**
- **Local filesystem**

## Connections

- User → Interactive app: uses (evidence: `README.md`)
- Interactive app → Console I/O: reads and prints (evidence: `README.md`)
- Interactive app → Startup banner: shows (evidence: `README.md`)
- Interactive app → Credential vault: manages credentials (evidence: `README.md`)
- Interactive app → Vault storage: loads and saves (evidence: `README.md`)
- Interactive app → Password generator: requests passwords (evidence: `README.md`)
- Credential vault → Credential validation: validates inputs (evidence: `src/core/Vault.cpp`)
- Credential vault → Credential model: stores records
- Credential vault → Timestamp service: timestamps changes
- Vault storage → Crypto service: derives and encrypts (evidence: `src/core/VaultStorage.cpp`)
- Vault storage → Vault serializer: serializes credentials (evidence: `src/core/VaultStorage.cpp`)
- Vault storage → Binary file format: validates header (evidence: `src/core/VaultStorage.cpp`)
- Vault storage → Local filesystem: reads and writes (evidence: `src/core/VaultStorage.cpp`)
- Crypto service → Sodium initialization: initializes library (evidence: `src/core/CryptoService.cpp`)
- Crypto service → Secure key: returns derived key
- Crypto service → Secure buffer: returns plaintext buffer
- Vault serializer → Secure buffer: uses protected buffer
