# keygen-sh/keygen-api architecture

> Architecture diagram of the GitHub repository keygen-sh/keygen-api, 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/keygen-sh/keygen-api
- Repository: https://github.com/keygen-sh/keygen-api

## Overview

##### Main System Components

a. API Layer
- REST API endpoints (under app/controllers/api/v1)
- Authentication & Authorization systems
- Rate limiting and request tracking
- Webhook handling

b. Core Services
- License Management
- Machine/Device Management
- User Management
- Product Management
- Release Management
- Analytics & Metrics
- Event Logging

c. Background Processing
- Sidekiq workers (under app/workers)
- Scheduled tasks
- Event broadcasting

d. Data Storage
- PostgreSQL database
- Redis for caching and Sidekiq
- S3/R2 for artifact storage

##### Architectural Patterns

a. Multi-tenancy Architecture
- Account isolation
- Environment separation
- Role-based access control

b. Event-Driven Architecture
- Webhook system
- Event logging
- Metrics collection

##### Integration Points

External service connections:
- Stripe for billing
- S3/R2 for storage
- SMTP for email delivery
- Package registry integrations (npm, RubyGems, PyPI)

##### Specific Design Elements

Use these visual elements:

- Blue: API endpoints
- Green: Core services
- Yellow: Background jobs
- Red: Security components
- Purple: External services
- Gray: Storage systems

b. Connection Types:

##### Component Relationships

Interactions:
- API Gateway → Authentication → Authorization → Controllers
- Controllers → Services → Models → Database
- Background Jobs → Services → External Services
- Event System → Webhooks → External Systems

##### Security Layer

Security components:
- Authentication mechanisms
- Authorization policies
- API key management
- Encryption systems
- Rate limiting

##### Scaling Components

Scalable components:
- Load balancers
- Database replication
- Worker pools
- Cache layers

##### Client Layer (Top)
- API clients
- Package managers
- Webhook consumers

##### Application Layer (Middle)
- API controllers
- Service objects
- Background workers

##### Data Layer (Bottom)
- Databases
- Caching
- File storage

- Component types
- Connection types
- Environment boundaries
- Security zones

This system design should reflect Keygen's nature as a robust, enterprise-grade licensing system with strong security, multi-tenancy, and extensibility features.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef api fill:#3498db,stroke:#2980b9,color:white
    classDef service fill:#2ecc71,stroke:#27ae60,color:white
    classDef worker fill:#f1c40f,stroke:#f39c12,color:black
    classDef security fill:#e74c3c,stroke:#c0392b,color:white
    classDef external fill:#9b59b6,stroke:#8e44ad,color:white
    classDef storage fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Client Layer
    subgraph ClientLayer[Client Layer]
        APIClients["API Clients"]
        PackageManagers["Package Managers"]
        WebhookConsumers["Webhook Consumers"]
    end

    %% Application Layer
    subgraph AppLayer[Application Layer]
        %% API Controllers
        subgraph APIControllers[API Controllers]
            LicenseCtrl["License Controller"]:::api
            MachineCtrl["Machine Controller"]:::api
            UserCtrl["User Controller"]:::api
            ProductCtrl["Product Controller"]:::api
            ReleaseCtrl["Release Controller"]:::api
            WebhookCtrl["Webhook Controller"]:::api
            MetricsCtrl["Metrics Controller"]:::api
        end

        %% Security
        subgraph Security[Security Layer]
            Auth["Authentication"]:::security
            AuthZ["Authorization"]:::security
            RateLimit["Rate Limiting"]:::security
            APIKeys["API Key Management"]:::security
        end

        %% Core Services
        subgraph CoreServices[Core Services]
            LicenseSvc["License Service"]:::service
            MachineSvc["Machine Service"]:::service
            UserSvc["User Service"]:::service
            ProductSvc["Product Service"]:::service
            ReleaseSvc["Release Service"]:::service
            AnalyticsSvc["Analytics Service"]:::service
            EventSvc["Event Service"]:::service
        end

        %% Background Workers
        subgraph Workers[Background Workers]
            EventWorker["Event Workers"]:::worker
            MachineWorker["Machine Workers"]:::worker
            LicenseWorker["License Workers"]:::worker
            WebhookWorker["Webhook Workers"]:::worker
        end
    end

    %% Data Layer
    subgraph DataLayer[Data Layer]
        Postgres[(PostgreSQL)]:::storage
        Redis[(Redis)]:::storage
        S3["S3/R2 Storage"]:::storage
    end

    %% External Services
    subgraph ExternalServices[External Services]
        Stripe["Stripe"]:::external
        SMTP["SMTP"]:::external
        PackageRegistries["Package Registries"]:::external
    end

    %% Relationships
    APIClients --> Auth
    Auth --> APIControllers
    AuthZ --> APIControllers
    RateLimit --> APIControllers

    APIControllers --> CoreServices
    CoreServices --> Postgres
    CoreServices --> Redis
    CoreServices --> S3

    CoreServices --> Workers
    Workers --> ExternalServices
    Workers --> Redis

    EventSvc --> WebhookWorker
    WebhookWorker --> WebhookConsumers

    CoreServices --> Stripe
    CoreServices --> SMTP
    ReleaseSvc --> PackageRegistries

    %% Click Events
    click Auth "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/concerns/authentication.rb"
    click AuthZ "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/concerns/authorization.rb"
    click RateLimit "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/concerns/rate_limiting.rb"
    click WebhookCtrl "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/api/v1/webhook_events_controller.rb"
    click LicenseCtrl "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/api/v1/licenses_controller.rb"
    click MachineCtrl "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/api/v1/machines_controller.rb"
    click UserCtrl "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/api/v1/users_controller.rb"
    click ProductCtrl "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/api/v1/products_controller.rb"
    click ReleaseCtrl "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/api/v1/releases_controller.rb"
    click MetricsCtrl "https://github.com/keygen-sh/keygen-api/blob/master/app/controllers/api/v1/metrics_controller.rb"
    click EventWorker "https://github.com/keygen-sh/keygen-api/blob/master/app/workers/event_log_worker.rb"
    click MachineWorker "https://github.com/keygen-sh/keygen-api/blob/master/app/workers/machine_heartbeat_worker.rb"
    click LicenseWorker "https://github.com/keygen-sh/keygen-api/blob/master/app/workers/license_expirations_worker.rb"
    click WebhookWorker "https://github.com/keygen-sh/keygen-api/blob/master/app/workers/webhook_worker.rb"
    click APIKeys "https://github.com/keygen-sh/keygen-api/blob/master/app/models/key.rb"

    %% Legend
    subgraph Legend
        API[API Component]:::api
        SVC[Service]:::service
        WRK[Worker]:::worker
        SEC[Security]:::security
        EXT[External]:::external
        STR[Storage]:::storage
    end
```
