# keyshade-xyz/keyshade architecture

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

- Interactive diagram: https://gitdiagram.com/keyshade-xyz/keyshade
- Repository: https://github.com/keyshade-xyz/keyshade

## Overview

##### Main Components
- API Server (Backend): Located under apps/api, this service is written using NestJS and is responsible for handling requests related to secrets, environments, projects, and user management. It includes controllers (for API key, auth, environment, event, integration, secret, user, workspace, etc.), modules for core functionality, Prisma integration for database migrations, caching (with Redis), and external providers (like Minio and Redis).
- CLI Application: Found under apps/cli, this command‐line tool offers commands to manage environments, projects, secrets, variables, workspaces, and roles. It interacts with the backend API to perform many administrative and operational tasks.
- Platform (Dashboard): Under apps/platform, this Next.js-based frontend serves as the user dashboard. It offers features such as secret creation, secret revision screens, environment management views, and integration with the API backend.
- Web Application: Under apps/web, likely the marketing or informational website of keyshade, built also using Next.js with separate pages to describe the product, pricing, about, and other public assets.
- API Client Package: Found in packages/api-client, this Node.js client package provides a programmatic way for users to interact with keyshade’s API directly from their own applications.
- Additional Packages: Other packages like packages/schema (defining TypeScript types and schemas) and packages/secret-scan (which detects secrets in code) further extend the tool’s functionality and developer integrations.

##### Relationships and Data Flow
- The API Server acts as the central hub. It receives requests from the Platform (dashboard), the CLI, and the API Client as well as possibly from other integrated external services.
- The API server interacts with the database (managed via Prisma migrations) for persistent secret storage, project and workspace configuration, and history (revisioning) of secrets.
- Caching mechanisms (using Redis) are leveraged to improve performance on repeat queries.
- The secrets and variables are encrypted using public key encryption; the frontend dashboard and API server must be architected to safely handle encryption and decryption while ensuring the private key is never exposed.
- The CLI and API Client packages provide different interfaces to access the same functionality offered by the API server.
- The Web (marketing) application is largely read-only and informational and may also provide links or authentication routing to the Platform.
- External integrations (e.g., Slack, Discord, GitHub, GitLab, Google for OAuth) connect to the API server to allow operations such as authentication and notification.

##### Architectural Patterns and Design Principles
- Modularity: The backend is organized into separate modules corresponding to functional domains (e.g., secret management, project management, authentication, role management).
- Microservices-as-Packages: Although contained in a monorepo, the packages (api-client, schema, secret-scan) might be used independently or integrated into other systems.
- Secure Data Flow: Emphasize that secrets are encrypted end-to-end (both at rest and in transit) and that live updates propagate changes in real time to the runtime environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        DB["Database (Prisma)"]:::database
        Cache["Cache (Redis)"]:::cache
        Storage["File Storage (Minio)"]:::storage
    end

    %% External Integrations
    subgraph "External Integrations"
        ExtOAuth["OAuth_Providers_(GitHub,GitLab,Google)"]:::integration
        ExtNotify["Notifications_(Slack,Discord)"]:::integration
    end

    %% Application Layer
    subgraph "Applications"
        APIServer["API Server (NestJS)"]:::backend
        CLIApp["CLI Application"]:::utility
        Dashboard["Dashboard (Platform - Next.js)"]:::frontend
        WebApp["Marketing Web App (Next.js)"]:::frontend
        APIClient["API Client Package (Node.js)"]:::utility
    end

    %% Packages & Tools
    subgraph "Packages & Tools"
        SchemaPkg["Schema Package (Type definitions)"]:::package
        SecretScan["Secret Scan Package (Code secret scanning)"]:::package
    end

    %% API Server Internal Components
    subgraph "API Server Components"
        Auth["Auth_Module"]:::backend
        SecretM["Secret_Management"]:::backend
        EnvProj["Environment_&_Project_Management"]:::backend
        CacheModule["Caching_(Redis)"]:::backend
        ExtProvider["External_Providers_(Minio,Redis)"]:::backend
    end

    %% Connections from external clients to API Server
    Dashboard -->|"API_call"| APIServer
    CLIApp -->|"HTTPS_API"| APIServer
    APIClient -->|"API_call"| APIServer

    %% API Server internal module relationships
    APIServer --> Auth
    APIServer --> SecretM
    APIServer --> EnvProj
    APIServer --> CacheModule
    APIServer --> ExtProvider

    %% API Server interactions with Data Layer
    APIServer -->|"DB_query"| DB
    APIServer -->|"Cache_access"| Cache
    APIServer -->|"File_ops"| Storage

    %% External Integrations connecting to API Server
    ExtOAuth -->|"OAuth_flow"| APIServer
    ExtNotify -->|"Notify_trigger"| APIServer

    %% Package relationships with API Client Package
    APIClient ---|"Uses"| SchemaPkg
    APIClient ---|"Utilizes"| SecretScan

    %% Styles
    classDef backend fill:#ffb3b3,stroke:#cc0000,stroke-width:2px;
    classDef frontend fill:#b3ffb3,stroke:#009900,stroke-width:2px;
    classDef utility fill:#b3d9ff,stroke:#0066cc,stroke-width:2px;
    classDef package fill:#e6e6e6,stroke:#808080,stroke-width:2px;
    classDef database fill:#fff0b3,stroke:#cc9900,stroke-width:2px,stroke-dasharray: 5,5;
    classDef cache fill:#ffe6cc,stroke:#ff9900,stroke-width:2px,stroke-dasharray: 5,5;
    classDef storage fill:#f2ccff,stroke:#9900cc,stroke-width:2px,stroke-dasharray: 5,5;
    classDef integration fill:#ffd1cc,stroke:#ff3300,stroke-width:2px;

    %% Click Events
    click APIServer "https://github.com/keyshade-xyz/keyshade/tree/develop/apps/api"
    click CLIApp "https://github.com/keyshade-xyz/keyshade/tree/develop/apps/cli"
    click Dashboard "https://github.com/keyshade-xyz/keyshade/tree/develop/apps/platform"
    click WebApp "https://github.com/keyshade-xyz/keyshade/tree/develop/apps/web"
    click APIClient "https://github.com/keyshade-xyz/keyshade/tree/develop/packages/api-client"
    click SchemaPkg "https://github.com/keyshade-xyz/keyshade/tree/develop/packages/schema"
    click SecretScan "https://github.com/keyshade-xyz/keyshade/tree/develop/packages/secret-scan"
```
