# e2b-dev/infra architecture

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

- Interactive diagram: https://gitdiagram.com/e2b-dev/infra
- Repository: https://github.com/e2b-dev/infra

## Overview

##### Main Components

- API Service – Located under packages/api, this service contains the core logic (handlers, middlewares, authentication, cache, analytics) and is responsible for providing the infrastructure’s API endpoints.

- Client & Reverse Proxy – The packages/client-proxy and packages/docker-reverse-proxy indicate that a client-side proxy layer and a reverse proxy exist. They help route requests and manage inbound traffic.

- Environment & Template Management – With components like packages/envd and packages/template-manager, the system supports managing execution environments and build templates, allowing customization and deployment of “sandboxes.”

- Orchestration – The packages/orchestrator contains logic for sandbox creation, instance lifecycle management, and overall orchestration of compute resources. It interacts with lower-level modules such as nodes, DNS, and caching.

- Database Services – The packages/db area includes migrations, queries, and client code for handling persistent data (e.g., user profiles, team configuration, sandbox metadata).

- Cloud & Cluster Provisioning – The directories under packages/cluster, packages/buckets, and Terraform configurations (e.g., main.tf at the repo’s root; terraform/*) show that Terraform is used to manage and deploy the underlying cloud infrastructure (GCP, AWS, etc.) for clusters, networking, security, and more.

- Firecracker Kernel & Versions – components located in packages/fc-kernels and packages/fc-versions imply that the system uses Firecracker micro-VMs, with dedicated modules for managing kernel versions and VM configuration.

- Shared Libraries – The packages/shared directory provides common utilities, model definitions, logging, telemetry (OpenTelemetry in the middleware), gRPC connections, etc., which support cross-service consistency, especially for communication and monitoring.

##### Relationships and Data Flows

- Incoming requests typically hit the reverse proxy first. This reverse proxy then directs traffic to the API server and possibly the orchestrator, ensuring security, authentication, and load balancing.

- The API service is the central hub; it processes requests (with middleware layers for tracing and metrics), communicates with the database for persistent data, and coordinates with the orchestrator for resource management.

- The orchestrator and EnvD modules interact to manage the lifecycle of sandboxes and compute instances (which may be implemented via Firecracker). They also interact with client-proxy components to enable low-latency service delivery.

- Template Manager services provide container and environment templates. They coordinate with the API and orchestrator to trigger builds and updates.

- The infrastructure is provisioned and managed through Terraform scripts located in packages/cluster, packages/init, and the terraform/ directories. These scripts establish the network, compute resources, buckets, and security configurations across different cloud providers.

- Shared libraries (for logging, db, grpc, models, telemetry, etc.) support all these components, ensuring that standards are consistently applied across services.

##### Architectural Patterns

- Microservices: Each major component (API, orchestrator, client proxy, env management, template manager) is grouped into its own package, allowing independent development and deployment.

- Infrastructure-as-Code: The presence of Terraform configurations and various “*.tf” files shows that provisioning and cloud resource management follow declarative patterns.

- Middleware and Observability: OpenTelemetry is integrated across API services and orchestrator modules, indicating a focus on distributed tracing and metrics.

- Modular Design: The partitioning into packages (shared, orchestrator, db, etc.) provides a clear separation of concerns.

##### Final Assembly

– Start with an external layer: Users or agents send requests to the Reverse Proxy.
– Show the reverse proxy directing traffic to the API service.
- The Database (persistent storage and migrations)
- The Orchestrator (which further manages sandboxes and instances)
- The Template Manager and EnvD (for environment configuration)
– Include connections from the Orchestrator to components like Client Proxy and Firecracker interfaces.

Happy diagramming!

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Layer
    User["External User/Agent"]:::external
    RP["Reverse Proxy"]:::infrastructure

    %% Application Services Layer
    subgraph "Application Services"
        API["API Service (Go)"]:::service
        DB["Database Services"]:::infrastructure
        ORCH["Orchestration Service"]:::service
        TM["Template Manager"]:::service
        ENVD["Environment Management (EnvD)"]:::service
        CP["Client Proxy"]:::service
        FCK["Firecracker Kernel Management"]:::service
        FCV["Firecracker Version Management"]:::service
        SHARED["Shared Libraries"]:::shared
    end

    %% Infrastructure Provisioning Layer
    subgraph "Infrastructure Provisioning"
        INF_CLUSTER["Cluster Provisioning"]:::infrastructure
        INF_BUCKETS["Buckets Provisioning"]:::infrastructure
        INF_TERRAFORM["Terraform Configurations"]:::infrastructure
    end

    %% Data Flow Connections
    User -->|"sendsRequest"| RP
    RP -->|"routesTo"| API
    API -->|"queries"| DB
    API -->|"orchestrates"| ORCH
    API -->|"coordinatesWith"| TM
    API -->|"manages"| ENVD
    API -->|"utilizes"| SHARED

    TM -->|"uses"| SHARED
    ENVD -->|"uses"| SHARED
    ORCH -->|"uses"| SHARED
    ORCH -->|"triggers"| CP
    ORCH -->|"invokes"| FCK
    ORCH -->|"invokes"| FCV

    %% Infrastructure Provisioning arrows (provisioning the core system via API)
    INF_CLUSTER -->|"provisions"| API
    INF_BUCKETS -->|"provisions"| API
    INF_TERRAFORM -->|"provisions"| API

    %% Styles
    classDef service fill:#cce5ff,stroke:#333,stroke-width:2px;
    classDef infrastructure fill:#d4edda,stroke:#333,stroke-width:2px;
    classDef shared fill:#fff3cd,stroke:#333,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#333,stroke-width:2px;

    %% Click Events
    click API "https://github.com/e2b-dev/infra/tree/main/packages/api"
    click CP "https://github.com/e2b-dev/infra/tree/main/packages/client-proxy"
    click RP "https://github.com/e2b-dev/infra/tree/main/packages/docker-reverse-proxy"
    click ENVD "https://github.com/e2b-dev/infra/tree/main/packages/envd"
    click TM "https://github.com/e2b-dev/infra/tree/main/packages/template-manager"
    click ORCH "https://github.com/e2b-dev/infra/tree/main/packages/orchestrator"
    click DB "https://github.com/e2b-dev/infra/tree/main/packages/db"
    click INF_CLUSTER "https://github.com/e2b-dev/infra/tree/main/packages/cluster"
    click INF_BUCKETS "https://github.com/e2b-dev/infra/tree/main/packages/buckets"
    click INF_TERRAFORM "https://github.com/e2b-dev/infra/tree/main/terraform/"
    click FCK "https://github.com/e2b-dev/infra/tree/main/packages/fc-kernels"
    click FCV "https://github.com/e2b-dev/infra/tree/main/packages/fc-versions"
    click SHARED "https://github.com/e2b-dev/infra/tree/main/packages/shared"
```
