# juspay/hyperswitch-card-vault architecture

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

- Interactive diagram: https://gitdiagram.com/juspay/hyperswitch-card-vault
- Repository: https://github.com/juspay/hyperswitch-card-vault

## Overview

##### Project Type & Overview
- This project is a backend, Rust-based secure vault service. Its primary role is to offer encrypted storage services through RESTful APIs. Clients communicate with the system via a middleware using encrypted and signed requests (JWS/JWE algorithms).
- The README highlights key flows such as authentication, encryption signing, and key hierarchy (master key and custodian keys) which are essential parts of the system.

##### Analysis of the File Structure
- Top-Level Directories:
- “src”: Contains the core application logic. It’s organized into several submodules including API endpoints (routes folders for data, cards, tenant, etc.), cryptography (encryption, hash, key manager, secrets manager), storage, error handling, logging, and configuration.
- “config” and “config.example.toml”: Provide runtime and environment-specific configurations.
- “migrations”: Contains Diesel migrations for defining and evolving the underlying database schema.
- “benches” and “loadtest”: Contain performance and load testing scenarios, ensuring that the secure vault can handle high loads and verify cryptographic operations.
- “.github”: Holds CI/CD configurations (workflows for building, testing, releasing, and docker image creation), emphasizing automated deployment and integration.
- This structured organization reflects a modular design where each module (API, cryptography, storage, error handling, logging) serves a dedicated function in the overall architecture.

##### Key Components
a. Client / Middleware:
b. API Gateway / Endpoint Layer:
- Routes (e.g., /data, /cards, /tenant) that handle incoming REST API requests.
- Security middleware components as the first point of contact for verifying request authenticity.
c. Cryptography Module:
- Separate subcomponents:
- Encryption Manager: Implements JWE/JWS algorithms for request signing/encryption.
- Hash Manager: Handles internal hashing checks to prevent data duplication.
- Key Manager and Secrets Manager: Manage master key and custodian key operations as well as interactions with external systems (e.g., AWS KMS, HC Vault, etc.).
d. Storage & Database Layer:
- Database layer (utilizing Diesel, migrations, and table schemas) for persisting encrypted sensitive data.
- A caching subcomponent if relevant from the “storage/caching” modules.
e. Logging and Error Handling:
- Dedicated logging components (with configuration, formatting, and storage modules) and error management modules that ensure system-wide visibility.
f. External Services & Infrastructure:
- Load testing and monitoring components (from the "loadtest" folder) that integrate with Grafana or other monitoring tools.

##### Relationships & Data Flow
- From external clients/middleware to the API layer.
- API requests are authenticated and then processed through the cryptography modules.
- After processing, data is persisted into the secure database (managed via Diesel and migrations).
- Feedback loops for error reporting, logging, and monitoring.
- That encryption and key management precede data storage — capture the order of operations like how a master key is managed by custodian keys.
- Distinguish internal vs. external communications; for example, note that external communications use encrypted channels and require signature verification.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client / Middleware Layer
    subgraph "Client / Middleware Layer"
        A1["API Client Communication"]:::client
        A2["Request Middleware"]:::client
    end

    %% API Gateway / Endpoint Layer
    subgraph "API Gateway / Endpoint Layer"
        B["API Gateway / Routes"]:::api
    end

    %% Cryptography Module
    subgraph "Cryptography Module"
        C1["Encryption Manager (JWE/JWS)"]:::crypto
        C2["Hash Manager"]:::crypto
        C3["Key Manager"]:::crypto
        C4["Secrets Manager"]:::crypto
    end

    %% Storage & Database Layer
    subgraph "Storage & Database Layer"
        D1["Persistent Storage (Diesel ORM)"]:::database
        D2["Caching Module"]:::database
        H["Database Migrations"]:::database
    end

    %% Logging & Error Handling
    subgraph "Logging & Error Handling"
        E1["Logging Component"]:::log
        E2["Error Handling Module"]:::error
    end

    %% CI/CD & Deployment Pipeline
    subgraph "CI/CD & Deployment"
        F1["CI/CD Pipeline"]:::devops
        F2["Containerization (Docker)"]:::devops
    end

    %% External Services
    subgraph "External Services"
        G["Monitoring & Load Testing"]:::monitoring
    end

    %% Data Flow Relationships
    A1 -->|"sends request"| B
    A2 -->|"verifies request"| B

    B -->|"encrypt/sign"| C1
    B -->|"hash_check"| C2
    B -->|"key_ops"| C3
    B -->|"secret_fetch"| C4

    C1 -->|"encrypted_data"| D1
    C2 -->|"data_validation"| D1
    C3 -->|"key_metadata"| D1
    C4 -->|"secret_details"| D1
    D1 -->|"schema defined"| H
    D1 --- D2

    %% Logging and Error Reporting
    B -->|"logs activity"| E1
    C1 -->|"reports issues"| E2
    D1 -->|"auditing"| E1

    %% CI/CD and Monitoring Integration
    F1 -->|"deploys service"| B
    F2 -->|"containerizes"| B
    E1 -->|"provides metrics"| G
    F1 -->|"integrates monitoring"| G

    %% Class Styles
    classDef client fill:#a8d0e6,stroke:#07689f,stroke-width:2px;
    classDef api fill:#f8e9a1,stroke:#f7d794,stroke-width:2px;
    classDef crypto fill:#c3e88d,stroke:#89b0ae,stroke-width:2px;
    classDef database fill:#f9c0c0,stroke:#f28c8c,stroke-width:2px;
    classDef log fill:#d3bdf0,stroke:#9a7bb8,stroke-width:2px;
    classDef error fill:#f3b0c3,stroke:#d95d5d,stroke-width:2px;
    classDef devops fill:#ffe156,stroke:#ff9f1c,stroke-width:2px;
    classDef monitoring fill:#b2f7ef,stroke:#0d3b66,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/juspay/hyperswitch-card-vault/blob/main/src/api_client.rs"
    click A2 "https://github.com/juspay/hyperswitch-card-vault/blob/main/src/middleware.rs"
    click B "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/routes"
    click C1 "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/crypto/encryption_manager"
    click C2 "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/crypto/hash_manager"
    click C3 "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/crypto/keymanager"
    click C4 "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/crypto/secrets_manager"
    click D1 "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/storage"
    click D2 "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/storage/caching"
    click H "https://github.com/juspay/hyperswitch-card-vault/tree/main/migrations"
    click E1 "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/logger"
    click E2 "https://github.com/juspay/hyperswitch-card-vault/tree/main/src/error"
    click F1 "https://github.com/juspay/hyperswitch-card-vault/tree/main/.github/workflows"
    click F2 "https://github.com/juspay/hyperswitch-card-vault/tree/main/Dockerfile"
    click G "https://github.com/juspay/hyperswitch-card-vault/tree/main/loadtest"
```
