# aashmitmckenzie/secure-vault architecture

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

- Interactive diagram: https://gitdiagram.com/aashmitmckenzie/secure-vault
- Repository: https://github.com/aashmitmckenzie/secure-vault

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Secret Vault 2.0”) whose purpose is to securely store, retrieve, and audit user credentials.
- It uses a FastAPI backend (Python) exposing a RESTful API, a static HTML/CSS/JS frontend, an embedded SQLite database, and optional integration with HashiCorp Vault, Google OAuth, and an email/SMS service for notifications.

##### File Structure
Top-level directories and files reveal:
- main.py (entry point, mounts routes & static‐file serving)
- auth.py, crud.py, notify.py, encryption.py, vault_client.py, database.py, models.py (core modules implementing API controllers, business logic, data access, encryption & KMS integration)
- frontend/ (static assets: HTML pages, CSS, JS served by FastAPI at /app/)
- scripts (add_demo_credentials.py, setup_admin.py, create_dummy_user.py, backup.py, check_db.py, check_audit.py, quick_test.py) for CLI tasks, seeding, health checks
- config.py, security.py (configuration loader, security utilities)
- email_service.py, verify_email.py, notifications.py (outbound email/SMS)
- logger.py, server.log, secret_vault.log (audit & system logging)
- requirements.txt, encryption_key.key or environment‐backed KMS

##### README for Additional Insights
- Features: AES-256 (Fernet) encryption of stored passwords, bcrypt for user‐passwords, multi-authentication (email/password + Google OAuth), audit logging, expiration tracking, search/filter.
- SQLite database with two tables: credentials & audit_logs.
- Optional HashiCorp Vault for storing the master Fernet key.
- External email provider & Google OAuth as third-party dependencies.
- Docker/Docker-Compose support for containerized deploy.

##### Main Components and Their Interactions
a. Frontend (User’s Browser)
- HTML/CSS/JS pages under frontend/ accessed at /app/
- Communicates with backend over REST (AJAX/fetch)
b. Backend API (FastAPI)
- main.py initializes FastAPI, mounts routers from auth.py, crud.py, audit modules, system health, and static file handlers.
- Controllers handle HTTP requests, invoke Services & Data modules.
c. Services / Business Logic
- auth.py: user authentication (bcrypt, JWT/HTTPBasic), Google OAuth handshake.
- crud.py: credential CRUD operations, integrates encryption.py.
- encryption.py: Fernet key management, encrypt/decrypt payloads via local key or vault_client.py.
- vault_client.py: optional HashiCorp Vault integration for KMS.
- email_service.py & verify_email.py: send email verifications and notifications.
- notifications.py: in-app or outbound notifications.
- check_db.py / check_audit.py: internal health checks.
d. Data Layer
- database.py: SQLAlchemy session & connection to SQLite file (secret_vault.db)
- models.py: ORM & Pydantic schemas for credentials & audit_logs tables
e. External Services
- HashiCorp Vault (KV store)
- Google OAuth provider
- SMTP/Third-party email API
f. Logging & Auditing
- logger.py writes to secret_vault.log & server.log
- audit tables store user actions
g. CLI & Utilities
- Scripts (add_demo_credentials.py, add_test_users.py, create_dummy_user.py, setup_admin.py) for seeding/test data
- backup.py dumps DB, quick_test.py for smoke testing

##### Relationships & Data Flows (
- Browser → FastAPI (REST calls: /auth, /credentials, /audit, /system/*)
- FastAPI → CRUD layer → Database (SQLite)
- CRUD layer ↔ Encryption service (encrypt/decrypt)
- Encryption service ↔ Vault (optional KMS)
- FastAPI → Google OAuth endpoint (external)
- FastAPI → Email service (SMTP/API)
- FastAPI → logger/audit subsystem → log files & audit table
- CLI scripts → directly invoke API endpoints or Data layer for setup/maintenance

##### Architectural Patterns & Principles
- Layered architecture: Presentation (frontend), API/Controller, Service/Domain, Data/Repository
- Modular feature separation: auth, credentials, audit, system
- Single origin for static assets + API, simplifying CORS
- Optional KMS abstraction allowing local key fallback

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Frontend
    subgraph "User & Frontend"
        direction TB
        UI["User's Browser UI"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API" 
        direction TB
        Main["FastAPI Init\n(main.py)"]:::backend
        Controllers["Controllers"]:::backend
        Services["Services"]:::service
        Utils["Config & Security"]:::utils
    end

    %% Controllers Breakdown
    subgraph "Controllers"
        direction TB
        Auth["Auth Controller\n(auth.py)"]:::backend
        Crud["Credential CRUD\n(crud.py)"]:::backend
        Verify["Email Verification\n(verify_email.py)"]:::backend
        NotifyController["Notifications Ctrl\n(notifications.py)"]:::backend
    end

    %% Services Breakdown
    subgraph "Services"
        direction TB
        Encryption["Encryption Service\n(encryption.py)"]:::service
        VaultClient["Vault KMS Client\n(vault_client.py)"]:::service
        EmailSvc["Email Service\n(email_service.py)"]:::service
    end

    %% Utils Breakdown
    subgraph "Config & Security"
        direction TB
        Config["Config Loader\n(config.py)"]:::utils
        Security["Security Utils\n(security.py)"]:::utils
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DBConn["DB Connection\n(database.py)"]:::data
        Models["ORM & Schemas\n(models.py)"]:::data
        SQLite["SQLite DB\n(secret_vault.db)"]:::storage
    end

    %% External Services & Logs
    subgraph "External & Logs"
        direction TB
        OAuth["Google OAuth Provider"]:::external
        SMTP["Email/SMTP Service"]:::external
        Vault["HashiCorp Vault"]:::storage
        Logger["Logging Subsystem\n(logger.py)"]:::utils
        AuditLogs["Audit Table"]:::data
        SystemLogs["Log Files\n(secret_vault.log,\nserver.log)"]:::utils
    end

    %% CLI & Utilities
    subgraph "CLI & Utilities"
        direction TB
        CLI1["add_demo_credentials.py"]:::utility
        CLI2["add_test_users.py"]:::utility
        CLI3["create_dummy_user.py"]:::utility
        CLI4["setup_admin.py"]:::utility
        CLI5["backup.py"]:::utility
        CLI6["quick_test.py"]:::utility
        CheckDB["DB Health Check\n(check_db.py)"]:::utility
        CheckAudit["Audit Health Check\n(check_audit.py)"]:::utility
    end

    %% Connections
    UI -->|"HTTPS/JSON"| Main
    Main --> Auth
    Main --> Crud
    Main --> Verify
    Main --> NotifyController
    Main --> Config
    Main --> Security

    Auth -->|"JWT Issuance"| Security
    Auth --> OAuth
    Crud --> Encryption
    Crud --> DBConn
    Crud --> AuditLogs
    Verify --> EmailSvc
    NotifyController --> EmailSvc
    NotifyController --> SMTP

    Encryption --> VaultClient
    VaultClient --> Vault
    Encryption -->|"Encrypt/Decrypt"| DBConn

    DBConn --> Models
    DBConn --> SQLite
    Models --> SQLite

    Main --> Logger
    Logger --> SystemLogs
    Logger --> AuditLogs

    %% CLI Scripts
    CLI1 --> Crud
    CLI2 --> Auth
    CLI3 --> Auth
    CLI4 --> Auth
    CLI5 --> DBConn
    CLI6 --> Main
    CheckDB --> DBConn
    CheckAudit --> AuditLogs

    %% External Calls
    Auth -->|"OAuth Flow"| OAuth
    EmailSvc --> SMTP

    %% Click Events
    click UI "https://github.com/aashmitmckenzie/secure-vault/tree/main/frontend/"
    click Main "https://github.com/aashmitmckenzie/secure-vault/blob/main/main.py"
    click Auth "https://github.com/aashmitmckenzie/secure-vault/blob/main/auth.py"
    click Crud "https://github.com/aashmitmckenzie/secure-vault/blob/main/crud.py"
    click Encryption "https://github.com/aashmitmckenzie/secure-vault/blob/main/encryption.py"
    click VaultClient "https://github.com/aashmitmckenzie/secure-vault/blob/main/vault_client.py"
    click EmailSvc "https://github.com/aashmitmckenzie/secure-vault/blob/main/email_service.py"
    click Verify "https://github.com/aashmitmckenzie/secure-vault/blob/main/verify_email.py"
    click NotifyController "https://github.com/aashmitmckenzie/secure-vault/blob/main/notifications.py"
    click DBConn "https://github.com/aashmitmckenzie/secure-vault/blob/main/database.py"
    click Models "https://github.com/aashmitmckenzie/secure-vault/blob/main/models.py"
    click Config "https://github.com/aashmitmckenzie/secure-vault/blob/main/config.py"
    click Security "https://github.com/aashmitmckenzie/secure-vault/blob/main/security.py"
    click CheckDB "https://github.com/aashmitmckenzie/secure-vault/blob/main/check_db.py"
    click CheckAudit "https://github.com/aashmitmckenzie/secure-vault/blob/main/check_audit.py"
    click Logger "https://github.com/aashmitmckenzie/secure-vault/blob/main/logger.py"
    click CLI1 "https://github.com/aashmitmckenzie/secure-vault/blob/main/add_demo_credentials.py"
    click CLI2 "https://github.com/aashmitmckenzie/secure-vault/blob/main/add_test_users.py"
    click CLI3 "https://github.com/aashmitmckenzie/secure-vault/blob/main/create_dummy_user.py"
    click CLI4 "https://github.com/aashmitmckenzie/secure-vault/blob/main/setup_admin.py"
    click CLI5 "https://github.com/aashmitmckenzie/secure-vault/blob/main/backup.py"
    click CLI6 "https://github.com/aashmitmckenzie/secure-vault/blob/main/quick_test.py"

    %% Styles
    classDef frontend fill:#D6E9FE,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#E8F1FC,stroke:#1A73E8,color:#1A73E8;
    classDef service fill:#FEF4D6,stroke:#E8A700,color:#E8A700;
    classDef data fill:#E8FCF1,stroke:#00A152,color:#00A152;
    classDef storage fill:#DFF6FF,stroke:#0091EA,color:#0091EA;
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#FB8C00;
    classDef utils fill:#F5F5F5,stroke:#9E9E9E,color:#424242;
    classDef utility fill:#F3E5F5,stroke:#8E24AA,color:#8E24AA;
```
