# bhatti/plexpass architecture

> Architecture diagram of the GitHub repository bhatti/plexpass, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhatti/plexpass
- Repository: https://github.com/bhatti/plexpass

## Overview

##### High-Level Architecture Components

a) Client Layer:
- Web UI (Browser-based interface)
- CLI Interface
- REST API Clients

b) Application Layer:
- HTTP/TLS Server (Port 8443)
- Authentication & Authorization
- Controllers (API and UI)
- Domain Services
- Command Handlers

c) Data Layer:
- Repositories
- Database (SQLite)
- HSM Storage
- File System Storage

##### Key Architectural Patterns to Highlight

a) Security Components:
- End-to-End Encryption
- Multi-Factor Authentication
- PKI Infrastructure
- Envelope Encryption
- Zero-Knowledge Architecture

b) Service Layer:
- Core services with their relationships:
- AuthenticationService
- UserService
- VaultService
- AccountService
- EncryptionService
- PasswordService
- ShareVaultAccountService
- AuditLogService

##### Data Flow Representation

- User authentication flow
- Vault and account creation/management flow
- Password analysis and sharing workflows
- Encryption/decryption processes
- Import/export operations

##### Specific Implementation Details

- Rust as the implementation language
- Diesel ORM for database operations
- Askama for templating
- WebAuthn/FIDO support
- HIBP integration

##### Key Interactions

Important interactions:
- Master password and pepper key combination
- Envelope encryption process
- Multi-factor authentication flow
- Vault sharing mechanism
- Password analysis workflow

##### External Dependencies

Connections to:
- Have I Been Pwned API
- Hardware Security Modules
- Local file system
- Browser security features

##### Deployment Context

How the system operates in:
- Local environment
- Docker container
- Multi-device setup

##### Cross-Cutting Concerns

- Logging and Audit
- Metrics (Prometheus)
- Internationalization
- Error handling

Remember to include notes about the encryption schemes (AES-256-GCM, ECC) and how they're applied at different levels of the system. This will help viewers understand the security measures in place throughout the application.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        WUI["Web UI Interface"]:::ui
        CLI["CLI Interface"]:::ui
        API["REST API Clients"]:::ui
    end

    subgraph Security
        E2E["End-to-End Encryption"]:::security
        MFA["Multi-Factor Authentication"]:::security
        PKI["PKI Infrastructure"]:::security
        EE["Envelope Encryption"]:::security
        ZKA["Zero-Knowledge Architecture"]:::security
        CRYPTO["Encryption Module"]:::security
    end

    subgraph "Application Layer"
        HTTPS["HTTP/TLS Server (8443)"]:::server
        AUTH["Authentication & Authorization"]:::auth
        CTRL["API Controllers"]:::controller
        
        subgraph "Core Services"
            direction TB
            AS["Authentication Service"]:::service
            US["User Service"]:::service
            VS["Vault Service"]:::service
            ACS["Account Service"]:::service
            ES["Encryption Service"]:::service
            PS["Password Service"]:::service
            SVS["Share Vault Account Service"]:::service
            ALS["Audit Log Service"]:::service
        end
        
        CMD["Command Handlers"]:::handler
    end

    subgraph "Data Layer"
        REPO["Repositories"]:::data
        DB[(SQLite Database)]:::database
        HSM["HSM Storage"]:::storage
        FS["File System Storage"]:::storage
    end

    subgraph "External Systems"
        HIBP["Have I Been Pwned"]:::external
        PROM["Prometheus Metrics"]:::external
    end

    %% Client Layer Connections
    WUI --> HTTPS
    CLI --> HTTPS
    API --> HTTPS

    %% Security Layer Connections
    HTTPS --> AUTH
    AUTH --> E2E
    AUTH --> MFA
    AUTH --> PKI
    
    %% Application Layer Connections
    HTTPS --> CTRL
    CTRL --> CMD
    CMD --> AS
    CMD --> US
    CMD --> VS
    CMD --> ACS
    CMD --> ES
    CMD --> PS
    CMD --> SVS
    CMD --> ALS

    %% Data Layer Connections
    AS --> REPO
    US --> REPO
    VS --> REPO
    ACS --> REPO
    ES --> REPO
    PS --> REPO
    SVS --> REPO
    ALS --> REPO
    REPO --> DB
    REPO --> HSM
    REPO --> FS

    %% External Connections
    PS --> HIBP
    ALS --> PROM

    %% Click Events
    click WUI "https://github.com/bhatti/PlexPass/tree/main/templates/"
    click CTRL "https://github.com/bhatti/PlexPass/blob/main/src/controller/*_api_controller.rs"
    click AUTH "https://github.com/bhatti/PlexPass/tree/main/src/auth/"
    click CRYPTO "https://github.com/bhatti/PlexPass/blob/main/src/crypto.rs"
    click AS "https://github.com/bhatti/PlexPass/blob/main/src/service/authentication_service_impl.rs"
    click US "https://github.com/bhatti/PlexPass/blob/main/src/service/user_service_impl.rs"
    click VS "https://github.com/bhatti/PlexPass/blob/main/src/service/vault_service_impl.rs"
    click ACS "https://github.com/bhatti/PlexPass/blob/main/src/service/account_service_impl.rs"
    click ES "https://github.com/bhatti/PlexPass/blob/main/src/service/encryption_service_impl.rs"
    click PS "https://github.com/bhatti/PlexPass/blob/main/src/service/password_service_impl.rs"
    click SVS "https://github.com/bhatti/PlexPass/blob/main/src/service/share_vault_account_service_impl.rs"
    click ALS "https://github.com/bhatti/PlexPass/blob/main/src/service/audit_service_impl.rs"
    click REPO "https://github.com/bhatti/PlexPass/tree/main/src/dao/"
    click DB "https://github.com/bhatti/PlexPass/tree/main/migrations/"
    click CMD "https://github.com/bhatti/PlexPass/tree/main/src/command/"
    click HIBP "https://github.com/bhatti/PlexPass/blob/main/src/hibp.rs"
    click HSM "https://github.com/bhatti/PlexPass/blob/main/src/store/hsm_store_file.rs"
    click PROM "https://github.com/bhatti/PlexPass/blob/main/src/utils/metrics.rs"

    %% Styling
    classDef ui fill:#9370DB,stroke:#333,stroke-width:2px
    classDef security fill:#FF6B6B,stroke:#333,stroke-width:2px
    classDef server fill:#4A90E2,stroke:#333,stroke-width:2px
    classDef auth fill:#FF9F40,stroke:#333,stroke-width:2px
    classDef controller fill:#4A90E2,stroke:#333,stroke-width:2px
    classDef service fill:#4A90E2,stroke:#333,stroke-width:2px
    classDef handler fill:#4A90E2,stroke:#333,stroke-width:2px
    classDef data fill:#2ECC71,stroke:#333,stroke-width:2px
    classDef database fill:#2ECC71,stroke:#333,stroke-width:2px
    classDef storage fill:#2ECC71,stroke:#333,stroke-width:2px
    classDef external fill:#F39C12,stroke:#333,stroke-width:2px
```
