# pranavtej/unkey architecture

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

- Interactive diagram: https://gitdiagram.com/pranavtej/unkey
- Repository: https://github.com/pranavtej/unkey

## Overview

##### Main Components

a) API Layer (apps/api)
- HTTP endpoints for key management
- Authentication flows
- Authorization checks
- Rate limiting endpoints

b) Agent Service (apps/agent)
- Distributed rate limiting
- Key verification
- Encryption/decryption services
- Cluster management

c) Dashboard (apps/dashboard)
- User interface for key management
- Analytics and monitoring
- Settings and configuration

d) Core Services
- Semantic Cache
- Rate Limiting
- Audit Logging
- Billing/Usage Tracking

##### Data Stores and Infrastructure
Critical storage components:

a) Databases
- Primary database (likely PostgreSQL based on schema files)
- ClickHouse for analytics
- Redis for caching/rate limiting

b) External Services
- Tinybird for analytics
- Axiom for logging
- S3 for storage

##### Communication Flows

a) Internal Communication
- gRPC connections between services (shown in proto files)
- Event-based communication (gossip protocol)
- Cache invalidation flows

b) External Communication
- Client API requests
- Webhook deliveries
- Integration endpoints (Vercel, etc.)

##### Security Boundaries
Highlight:

- Encryption boundaries (vault service)
- Authentication checkpoints
- Rate limiting zones
- IP whitelisting boundaries

##### Deployment Architecture
Show:

- Load balancers
- Edge functions
- Regional deployments
- Clustering configuration

##### Specific Design Elements

Use these visual elements:
- Blue: Core services
- Green: Data stores
- Yellow: External services
- Red: Security boundaries

##### Legends
- Component types
- Communication protocols
- Security zones
- Deployment regions

##### Key Workflows to Highlight

a) Key Verification Flow:
**Client → API → Agent → Cache → Database**

b) Rate Limiting Flow:
**Request → Edge → Agent Cluster → Distributed Counter → Response**

c) Audit Trail Flow:
**Action → Event Router → ClickHouse → Analytics**

##### Implementation Details

Technical stack indicators:
- TypeScript/Node.js for API
- Go for Agent
- React for Dashboard
- Protocol Buffers for RPC
- WebSocket for real-time features

Remember to include version indicators and deployment environment boundaries (production/staging/development) if relevant to the specific implementation.

This system design should emphasize the distributed nature of the authentication and authorization services while showing how the various components work together to provide a secure and scalable API key management solution.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph API
        API[API Service]:::api
        Auth[Authentication]:::api
        RateLimit[Rate Limiting]:::api
        HTTPEndpoints[HTTP Endpoints]:::api
        
        API --> Auth
        API --> RateLimit
        API --> HTTPEndpoints
    end
    
    subgraph Agent
        AgentService[Agent Service]:::agent
        KeyVerif[Key Verification]:::agent
        Encrypt[Encryption]:::agent
        Cluster[Cluster Management]:::agent
        AgentRate[Rate Limiting]:::agent
        
        AgentService --> KeyVerif
        AgentService --> Encrypt
        AgentService --> Cluster
        AgentService --> AgentRate
    end
    
    subgraph Dashboard
        UI[Dashboard UI]:::dashboard
        KeyMgmt[Key Management]:::dashboard
        Analytics[Analytics]:::dashboard
        Settings[Settings]:::dashboard
        
        UI --> KeyMgmt
        UI --> Analytics
        UI --> Settings
    end
    
    subgraph CoreServices
        Cache[Semantic Cache]:::core
        AuditLog[Audit Logging]:::core
        Billing[Billing/Usage]:::core
        EventRouter[Event Router]:::core
        
        EventRouter --> AuditLog
        EventRouter --> Billing
    end
    
    subgraph DataStores
        DB[(PostgreSQL)]:::db
        ClickHouse[(ClickHouse)]:::db
        Redis[(Redis)]:::db
        S3[(S3)]:::db
    end
    
    subgraph ExternalServices
        Tinybird[Tinybird Analytics]:::external
        Axiom[Axiom Logging]:::external
        Vercel[Vercel Integration]:::external
    end
    
    API -.->|gRPC| AgentService
    AgentService -->|Cache| Redis
    AgentService -->|Analytics| ClickHouse
    API -->|Store| DB
    EventRouter -->|Analytics| Tinybird
    AuditLog -->|Logs| Axiom
    Cache -->|Query| DB
    UI -->|API Requests| API
    
    classDef api fill:#2374ab
    classDef agent fill:#048ba8
    classDef dashboard fill:#2a9d8f
    classDef core fill:#e9c46a
    classDef db fill:#264653,color:white
    classDef external fill:#e76f51
    
    %% Click events for component mapping
    click API "https://github.com/Pranavtej/unkey/tree/main/apps/api/"
    click Auth "https://github.com/Pranavtej/unkey/tree/main/apps/api/src/pkg/auth/"
    click RateLimit "https://github.com/Pranavtej/unkey/tree/main/apps/api/src/pkg/ratelimit/"
    click HTTPEndpoints "https://github.com/Pranavtej/unkey/tree/main/apps/api/src/routes/"
    click AgentService "https://github.com/Pranavtej/unkey/tree/main/apps/agent/"
    click KeyVerif "https://github.com/Pranavtej/unkey/tree/main/apps/agent/pkg/api/routes/"
    click Encrypt "https://github.com/Pranavtej/unkey/tree/main/apps/agent/services/vault/"
    click Cluster "https://github.com/Pranavtej/unkey/tree/main/apps/agent/pkg/cluster/"
    click AgentRate "https://github.com/Pranavtej/unkey/tree/main/apps/agent/services/ratelimit/"
    click UI "https://github.com/Pranavtej/unkey/tree/main/apps/dashboard/"
    click KeyMgmt "https://github.com/Pranavtej/unkey/tree/main/apps/dashboard/app/(app)/apis/"
    click Analytics "https://github.com/Pranavtej/unkey/tree/main/apps/dashboard/app/(app)/overview/"
    click Settings "https://github.com/Pranavtej/unkey/tree/main/apps/dashboard/app/(app)/settings/"
    click Cache "https://github.com/Pranavtej/unkey/tree/main/apps/semantic-cache/"
    click AuditLog "https://github.com/Pranavtej/unkey/tree/main/apps/agent/pkg/logging/"
    click Billing "https://github.com/Pranavtej/unkey/tree/main/apps/billing/"
    click ClickHouse "https://github.com/Pranavtej/unkey/tree/main/apps/agent/pkg/clickhouse/"
    click EventRouter "https://github.com/Pranavtej/unkey/tree/main/apps/agent/services/eventrouter/"
```
