# bryan-13-ty/gestor-de-contrasenas architecture

> Architecture diagram of the GitHub repository bryan-13-ty/gestor-de-contrasenas, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bryan-13-ty/gestor-de-contrasenas
- Repository: https://github.com/bryan-13-ty/gestor-de-contrasenas

## Overview

1. **Overall shape**
   - This is a small Python password-manager project, centered on a local “vault” concept.
   - The architecture is layered: an entry point calls application services, which orchestrate domain models, cryptography, and storage.

2. **Entry point**
   - `main.py` is the top-level executable path for the application.
   - It likely wires together the service layer and user-facing flow, but the repo does not show any web framework or external API layer.

3. **Domain models**
   - `models/credential.py` and `models/vault.py` define the core data structures.
   - `Credential` is the atomic secret record, while `Vault` is the aggregate/container that groups credentials and represents the protected dataset.

4. **Service layer**
   - `services/vault_service.py` is the main orchestration boundary.
   - This is where vault operations likely happen: create/open/update credential data, call encryption/decryption, and coordinate persistence.

5. **Cryptography subsystem**
   - `crypto/encryption.py` and `crypto/key_derivation.py` isolate security-sensitive logic.
   - One module appears responsible for encrypting/decrypting vault content, while the other derives keys from user input or a master secret.
   - This separation is important because it keeps cryptographic primitives out of business logic and storage code.

6. **Persistence layer**
   - `storage/vault_storage.py` is the repository’s storage adapter.
   - It likely serializes the vault to local storage and reads it back, acting as the boundary between in-memory objects and durable data.
   - The presence of a dedicated storage package suggests the app is designed to keep encrypted vault data at rest.

7. **Utilities**
   - `utils/utils.py` contains shared helper functions that don’t belong in the domain, crypto, or storage layers.
   - In a project like this, such helpers usually support formatting, validation, or general-purpose transformations.

8. **Data flow**
   - Typical flow is: user interacts with `main.py` → `vault_service` loads or mutates a `Vault` → crypto derives a key and encrypts/decrypts credential data → `vault_storage` persists the result.
   - The reverse flow occurs when opening the vault: storage reads encrypted data, crypto decrypts it, and the service returns usable models.

9. **Boundary separation**
   - The key architectural boundary is between plaintext domain objects and encrypted persisted state.
   - Models represent business data, services coordinate behavior, crypto owns secret-handling, and storage owns file I/O or serialization concerns.

10. **Testing**
   - `tests/test_crypto.py` shows explicit coverage for the cryptography layer.
   - That indicates crypto is treated as a critical subsystem with dedicated verification, which is appropriate for a password manager.

11. **Tooling and packaging**
   - `requirements.txt` indicates a standard Python runtime with external dependencies.
   - `Makefile` suggests scripted developer tasks such as test execution or setup, but the repo does not show heavier build or deployment infrastructure.

12. **What is not present**
   - There is no evidence of a database server, background worker, message queue, or HTTP service.
   - The architecture appears intentionally local and self-contained: application logic plus encrypted storage, with cryptography as a first-class module.

Main entry points: [`services/vault_service.py`](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/services/vault_service.py) (Vault service), [`crypto/encryption.py`](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/crypto/encryption.py) (Encryption), [`storage/vault_storage.py`](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/storage/vault_storage.py) (Vault storage), [`tests/test_crypto.py`](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/tests/test_crypto.py) (Crypto tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application"]
  node_main_py["main.py<br/>entrypoint<br/>[main.py]"]
  node_vault_service["Vault service<br/>orchestrator<br/>[vault_service.py]"]
end

subgraph group_domain["Domain"]
  node_vault_model["Vault<br/>aggregate<br/>[vault.py]"]
  node_credential_model["Credential<br/>entity<br/>[credential.py]"]
end

subgraph group_security["Security"]
  node_encryption{{"Encryption<br/>crypto<br/>[encryption.py]"}}
  node_key_derivation{{"Key derivation<br/>crypto<br/>[key_derivation.py]"}}
end

subgraph group_persistence["Persistence"]
  node_vault_storage[("Vault storage<br/>adapter<br/>[vault_storage.py]")]
end

subgraph group_shared["Shared"]
  node_utils["Utils<br/>helpers<br/>[utils.py]"]
  node_test_crypto["Crypto tests<br/>[test_crypto.py]"]
  node_makefile["Makefile<br/>tooling"]
  node_requirements["Requirements<br/>dependencies<br/>[requirements.txt]"]
end

node_main_py -->|"starts"| node_vault_service
node_vault_service -->|"uses"| node_vault_model
node_vault_service -->|"manages"| node_credential_model
node_vault_service -->|"derives key"| node_key_derivation
node_vault_service -->|"encrypts"| node_encryption
node_vault_service -->|"persists"| node_vault_storage
node_vault_service -.->|"shares helpers"| node_utils
node_vault_model -->|"contains"| node_credential_model
node_key_derivation -->|"feeds key"| node_encryption
node_vault_storage -->|"serializes"| node_vault_model
node_vault_storage -->|"stores ciphertext"| node_encryption
node_test_crypto -.->|"covers"| node_key_derivation
node_test_crypto -.->|"covers"| node_encryption
node_makefile -.->|"runs"| node_test_crypto
node_requirements -.->|"supports"| node_main_py

click node_main_py "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/main.py"
click node_vault_service "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/services/vault_service.py"
click node_vault_model "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/models/vault.py"
click node_credential_model "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/models/credential.py"
click node_encryption "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/crypto/encryption.py"
click node_key_derivation "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/crypto/key_derivation.py"
click node_vault_storage "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/storage/vault_storage.py"
click node_utils "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/utils/utils.py"
click node_test_crypto "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/tests/test_crypto.py"
click node_makefile "https://github.com/bryan-13-ty/gestor-de-contrasenas/tree/main/Makefile"
click node_requirements "https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/requirements.txt"

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_main_py,node_vault_service toneBlue
class node_vault_model,node_credential_model toneAmber
class node_encryption,node_key_derivation toneMint
class node_vault_storage toneRose
class node_utils,node_test_crypto,node_makefile,node_requirements toneIndigo
```

## Components

### Application

Entry point and orchestration

- [main.py](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/main.py): entrypoint · Top-level executable path · `main.py`
- [Vault service](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/services/vault_service.py): orchestrator · Coordinates vault operations · `services/vault_service.py`

### Domain

Core vault data structures

- [Vault](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/models/vault.py): aggregate · Protected vault container · `models/vault.py`
- [Credential](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/models/credential.py): entity · Atomic secret record · `models/credential.py`

### Security

Key derivation and encryption

- [Encryption](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/crypto/encryption.py): crypto · Encrypts and decrypts vault data · `crypto/encryption.py`
- [Key derivation](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/crypto/key_derivation.py): crypto · Derives keys from master secret · `crypto/key_derivation.py`

### Persistence

Local vault storage

- [Vault storage](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/storage/vault_storage.py): adapter · Persists encrypted vault data · `storage/vault_storage.py`

### Shared

Common helpers and validation

- [Utils](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/utils/utils.py): helpers · Shared helper functions · `utils/utils.py`
- [Crypto tests](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/tests/test_crypto.py): test · Verifies crypto behavior · `tests/test_crypto.py`
- [Makefile](https://github.com/bryan-13-ty/gestor-de-contrasenas/tree/main/Makefile): tooling · Developer task entrypoint · `Makefile`
- [Requirements](https://github.com/bryan-13-ty/gestor-de-contrasenas/blob/main/requirements.txt): dependencies · Python package dependencies · `requirements.txt`

## Connections

- main.py → Vault service: starts · Bootstraps the application flow
- Vault service → Vault: uses · Loads and mutates vault state
- Vault service → Credential: manages · Creates and updates credential records
- Vault service → Key derivation: derives key · Obtains encryption material from secret input
- Vault service → Encryption: encrypts · Protects vault content before persistence
- Vault service → Vault storage: persists · Reads and writes the vault
- Vault service → Utils: shares helpers · Uses common utility functions
- Vault → Credential: contains · Vault aggregates credential entries
- Key derivation → Encryption: feeds key · Supplies derived key material
- Vault storage → Vault: serializes · Stores vault representation
- Vault storage → Encryption: stores ciphertext · Keeps data encrypted at rest
- Crypto tests → Key derivation: covers · Exercises derivation logic
- Crypto tests → Encryption: covers · Exercises encryption logic
- Makefile → Crypto tests: runs · Supports test execution tasks
- Requirements → main.py: supports · Declares runtime dependencies