# wundergraph/cosmo architecture

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

- Interactive diagram: https://gitdiagram.com/wundergraph/cosmo
- Repository: https://github.com/wundergraph/cosmo

## Overview

##### Main Components
The system should be divided into these core components:

a. Control Plane (Management Layer):
- Schema Registry
- Composition Service
- Authentication/Authorization
- Analytics & Metrics Collection
- Configuration Management
- User Management

b. Data Plane (Runtime Layer):
- Router Service
- GraphQL Federation Engine
- Metrics Collection
- Tracing System

c. Storage Layer:
- PostgreSQL (for control plane data)
- ClickHouse (for analytics)
- Redis (for caching)
- MinIO/S3 (for blob storage)

d. Supporting Services:
- Keycloak (authentication)
- OTel Collector (telemetry)
- CDN Server
- Studio (Web UI)

##### Component Relationships

a. External Interactions:
- Clients → Router
- CI/CD Systems → Control Plane
- Developers → Studio UI

b. Internal Data Flow:
- Router → Control Plane (configuration updates)
- Router → OTel Collector (metrics/traces)
- Control Plane → Storage Layer
- Studio UI → Control Plane
- CDN Server ↔ Storage Layer

##### Key Architectural Patterns

Patterns:

- Event-driven architecture for real-time updates
- Microservices architecture for component isolation
- API Gateway pattern for the router
- Publisher/Subscriber pattern for events
- Cache-aside pattern for performance

##### Component Details

- Service name
- Primary function
- Key technologies used
- Critical dependencies

##### Security Boundaries

Indicate:

- Authentication boundaries
- Authorization checkpoints
- Network security zones
- Data encryption points

##### Scaling Points

Highlight:

- Horizontally scalable components
- Load balancing points
- Caching layers
- Database replication

##### Monitoring Points

Mark:

- Metrics collection points
- Trace aggregation
- Log collection
- Health check endpoints

##### Data Layer (bottom)

Remember to emphasize the federated nature of the system and how it handles GraphQL schema composition and request routing.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Styles and classes
    classDef client fill:#FFE5CC,stroke:#FF9933
    classDef edge fill:#CCE5FF,stroke:#3399FF
    classDef control fill:#E5CCFF,stroke:#9933FF
    classDef storage fill:#CCFFCC,stroke:#33FF33
    classDef security fill:#FFB3B3,stroke:#FF3333
    classDef monitoring fill:#F0F0F0,stroke:#666666

    %% Client Layer
    subgraph Clients
        C1[Clients/Apps]:::client
        DEV[Developers]:::client
        CICD[CI/CD Systems]:::client
    end

    %% Edge Layer
    subgraph Edge
        CDN["CDN Server"]:::edge
        ROUTER["Router Service"]:::edge
        FEDENG["Federation Engine"]:::edge
    end

    %% Control Plane Layer
    subgraph ControlPlane
        SCHEMAREG["Schema Registry"]:::control
        COMP["Composition Service"]:::control
        AUTH["Authentication"]:::control
        AUTHZ["Authorization"]:::control
        ANALYTICS["Analytics Service"]:::control
        CONFIG["Configuration Management"]:::control
        USERMGMT["User Management"]:::control
        STUDIO["Studio Web UI"]:::control
    end

    %% Data Layer
    subgraph Storage
        POSTGRES[(PostgreSQL)]:::storage
        CLICK[(ClickHouse)]:::storage
        REDIS[(Redis Cache)]:::storage
        S3[(MinIO/S3)]:::storage
    end

    %% Supporting Services
    subgraph Support
        KEYCLOAK["Keycloak"]:::security
        OTEL["OTel Collector"]:::monitoring
    end

    %% Connections
    C1 --> ROUTER
    DEV --> STUDIO
    CICD --> ControlPlane
    
    ROUTER --> FEDENG
    ROUTER --> OTEL
    ROUTER --> ControlPlane
    
    CDN <--> Storage
    
    ControlPlane --> Storage
    STUDIO --> ControlPlane
    
    KEYCLOAK --> AUTH
    OTEL --> CLICK

    %% Click Events
    click ROUTER "https://github.com/wundergraph/cosmo/tree/main/router/"
    click FEDENG "https://github.com/wundergraph/cosmo/tree/main/router/core/"
    click SCHEMAREG "https://github.com/wundergraph/cosmo/blob/main/controlplane/src/core/repositories/SchemaCheckRepository.ts"
    click COMP "https://github.com/wundergraph/cosmo/tree/main/composition/"
    click AUTH "https://github.com/wundergraph/cosmo/blob/main/controlplane/src/core/services/Authentication.ts"
    click AUTHZ "https://github.com/wundergraph/cosmo/blob/main/controlplane/src/core/services/Authorization.ts"
    click ANALYTICS "https://github.com/wundergraph/cosmo/tree/main/controlplane/src/core/repositories/analytics/"
    click POSTGRES "https://github.com/wundergraph/cosmo/tree/main/controlplane/migrations/"
    click CLICK "https://github.com/wundergraph/cosmo/tree/main/controlplane/clickhouse/"
    click S3 "https://github.com/wundergraph/cosmo/blob/main/controlplane/src/core/blobstorage/s3.ts"
    click KEYCLOAK "https://github.com/wundergraph/cosmo/tree/main/keycloak/"
    click OTEL "https://github.com/wundergraph/cosmo/tree/main/otelcollector/"
    click CDN "https://github.com/wundergraph/cosmo/tree/main/cdn-server/"
    click STUDIO "https://github.com/wundergraph/cosmo/tree/main/studio/"
    click CONFIG "https://github.com/wundergraph/cosmo/tree/main/router/pkg/config/"

    %% Legend
    subgraph Legend
        L1[Client Components]:::client
        L2[Edge Services]:::edge
        L3[Control Plane]:::control
        L4[Storage Systems]:::storage
        L5[Security]:::security
        L6[Monitoring]:::monitoring
    end
```
