# kcp-dev/kcp architecture

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

- Interactive diagram: https://gitdiagram.com/kcp-dev/kcp
- Repository: https://github.com/kcp-dev/kcp
- Video tour (about a minute): https://gitdiagram.com/kcp-dev/kcp/video

## Overview

##### Main Components

a. Core Components:
- API Server Layer
- Virtual Workspaces
- API Export/Import System
- Authentication/Authorization
- Workspace Management
- Cache Server
- Front Proxy
- Storage (etcd)

b. Key Subsystems:
- Admission Controllers
- Reconcilers
- Virtual API Framework
- Client SDK

**┌─ External Clients/Users ─────────────────────┐**

- Front Layer ────────────────────────────────┤
- kcp-front-proxy                           │
- Authentication/Authorization               │

- Core Services Layer ────────────────────────┤
- ┌─ Workspace Management ─┐ ┌─ API Services ─┐│
- Workspace Controller │ │ - APIExports   ││
- Workspace Types     │ │ - APIBindings  ││
- ┘ └───────────────┘ │

- Virtual Framework Layer ───────────────────┤
- Dynamic API Registration                   │
- API Resource Management                    │

- Storage Layer ──────────────────────────────┤
- etcd                                      │
- Cache Server                              │
- ┘

##### Connection Types

- Double lines: High-bandwidth data paths

##### Key Elements to Highlight

a. Workspace Isolation:
- How workspaces are isolated from each other
- Workspace type inheritance
- Resource boundaries

b. API Management:
- APIExport flow
- APIBinding relationships
- Schema management

c. Authentication Flow:
- User authentication path
- Authorization decisions
- RBAC integration

##### Additional Details

Annotations for:
- Key configuration points
- Scaling components
- High availability pairs
- Security boundaries
- API version management

##### Implementation Notes

- Relationship between `/pkg/virtual` and API management
- How `/pkg/reconciler` components maintain system state
- Demonstrate how `/pkg/admission` controls access and validation
- Cache server's role from `/pkg/cache`

##### Security Boundaries

Clearly mark:
- Trust boundaries
- Authentication checkpoints
- Authorization enforcement points
- Isolation mechanisms

Remember to maintain consistency with the project's actual implementation as shown in the file structure, particularly the core components in `/pkg` and the API definitions in `/sdk/apis`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph External["External Clients/Users"]
        Clients(["External Clients"]):::client
        SDK["Client SDK"]:::client
    end

    subgraph FrontLayer["Front Layer"]
        FrontProxy["Front Proxy"]:::proxy
        Auth["Authentication/Authorization"]:::auth
    end

    subgraph CoreLayer["Core Services Layer"]
        subgraph WS["Workspace Management"]
            WSController["Workspace Controller"]:::core
            WSTypes["Workspace Types"]:::core
        end
        
        subgraph API["API Services"]
            APIExports["API Exports"]:::api
            APIBindings["API Bindings"]:::api
        end
        
        AdmissionCtrl["Admission Controllers"]:::core
        Reconcilers["Reconcilers"]:::core
    end

    subgraph VirtualLayer["Virtual Framework Layer"]
        VWorkspaces["Virtual Workspaces"]:::virtual
        VAPIFramework["Virtual API Framework"]:::virtual
        CoreAPIs["Core APIs"]:::virtual
    end

    subgraph StorageLayer["Storage Layer"]
        ETCD[(ETCD)]:::storage
        Cache["Cache Server"]:::storage
    end

    %% Connections
    Clients --> FrontProxy
    SDK --> FrontProxy
    FrontProxy --> Auth
    Auth --> VWorkspaces
    Auth --> AdmissionCtrl
    
    VWorkspaces --> APIExports
    VWorkspaces --> APIBindings
    VWorkspaces --> WSController
    
    WSController --> WSTypes
    WSTypes --> Reconcilers
    
    APIExports --> VAPIFramework
    APIBindings --> VAPIFramework
    VAPIFramework --> CoreAPIs
    
    AdmissionCtrl --> Reconcilers
    Reconcilers --> ETCD
    
    VWorkspaces --> Cache
    Cache --> ETCD

    %% Click Events
    click VWorkspaces "https://github.com/kcp-dev/kcp/tree/main/pkg/virtual/"
    click APIExports "https://github.com/kcp-dev/kcp/tree/main/pkg/virtual/apiexport/"
    click Auth "https://github.com/kcp-dev/kcp/tree/main/pkg/authorization/"
    click WSController "https://github.com/kcp-dev/kcp/tree/main/pkg/reconciler/tenancy/workspace/"
    click Cache "https://github.com/kcp-dev/kcp/tree/main/pkg/cache/"
    click FrontProxy "https://github.com/kcp-dev/kcp/tree/main/pkg/proxy/"
    click VAPIFramework "https://github.com/kcp-dev/kcp/tree/main/pkg/virtual/framework/"
    click AdmissionCtrl "https://github.com/kcp-dev/kcp/tree/main/pkg/admission/"
    click Reconcilers "https://github.com/kcp-dev/kcp/tree/main/pkg/reconciler/"
    click ETCD "https://github.com/kcp-dev/kcp/tree/main/pkg/embeddedetcd/"
    click APIBindings "https://github.com/kcp-dev/kcp/tree/main/pkg/reconciler/apis/apibinding/"
    click CoreAPIs "https://github.com/kcp-dev/kcp/tree/main/sdk/apis/core/"
    click SDK "https://github.com/kcp-dev/kcp/tree/main/sdk/client/"
    click WSTypes "https://github.com/kcp-dev/kcp/tree/main/pkg/reconciler/tenancy/workspacetype/"

    %% Styling
    classDef client fill:#FF9900,stroke:#333,stroke-width:2px
    classDef proxy fill:#6699FF,stroke:#333,stroke-width:2px
    classDef auth fill:#FFFF00,stroke:#333,stroke-width:2px
    classDef core fill:#3366CC,stroke:#333,stroke-width:2px,color:#fff
    classDef api fill:#33CC33,stroke:#333,stroke-width:2px
    classDef virtual fill:#9933CC,stroke:#333,stroke-width:2px,color:#fff
    classDef storage fill:#666666,stroke:#333,stroke-width:2px,color:#fff

    %% Legend
    subgraph Legend
        Client[Client Components]:::client
        Proxy[Proxy Components]:::proxy
        AuthComp[Auth Components]:::auth
        CoreComp[Core Components]:::core
        ApiComp[API Components]:::api
        VirtualComp[Virtual Components]:::virtual
        StorageComp[Storage Components]:::storage
    end
```
