# Architecture This document explains how Lapdev works and how its components interact to provide seamless Kubernetes development environments. ### Overview Lapdev consists of three main components: 1. **Lapdev API Server** (SaaS) - Manages users, authentication, and orchestrates environment creation 2. **Lapdev-Kube-Manager** (In your cluster) - Reads production manifests, manages dev environments, and pushes routing/intercept state to sidecars 3. [**Devbox**](https://docs.lap.dev/core-concepts/devbox) **CLI** (Developer's machine) - Enables local debugging with cluster connectivity * Plus an auto-injected **Sidecar Proxy** per pod that enforces routing and intercepts at runtime ### Architecture Diagram ### Component Details #### Lapdev API Server (SaaS) The Lapdev cloud service handles: * **User authentication and authorization** - GitHub/GitLab OAuth, team management * **Environment orchestration** - Receives environment creation requests from users * **Secure tunnel management** - Establishes websocket tunnels between your cluster and Lapdev * [**Preview URL**](https://docs.lap.dev/core-concepts/preview-url) **routing** - Routes traffic from automatically generated HTTPS URLs to your cluster **Security:** * Communicates with your cluster via secure websocket tunnels (TLS encrypted) * No direct access to your cluster's API server * Receives workload manifests (Deployments, StatefulSets, ConfigMaps, Secrets) from lapdev-kube-manager to build App Catalogs * You control which workloads Lapdev can access through App Catalog selection * No access to runtime application data (databases, logs, persistent volumes) #### Lapdev-Kube-Manager (In Your Cluster) Deployed as a single Kubernetes deployment in your cluster, `lapdev-kube-manager`: * **Reads production manifests** - Discovers Deployments, StatefulSets, ConfigMaps, Secrets, and Services from your production namespace to build [App Catalogs](https://docs.lap.dev/core-concepts/app-catalog) * **Creates dev** [**environments**](https://docs.lap.dev/core-concepts/environment) - Replicates selected workloads into isolated or shared namespaces * **Manages sync** - Monitors production manifests for changes and updates dev environments * **Publishes traffic routing** - For [branch environments](https://docs.lap.dev/core-concepts/architecture/branch-environment-architecture), computes routing tables and distributes them to sidecars (sidecars enforce routing; see [Traffic Routing Architecture](https://docs.lap.dev/core-concepts/architecture/traffic-routing-architecture)) * **Establishes secure tunnel** - Maintains websocket connection to Lapdev API Server for orchestration **Permissions:** * Read access to production namespace (to read manifests) * Full access to Lapdev-managed namespaces (to create/update environments) * No access to other cluster resources #### Devbox CLI (Developer Machine) The `lapdev devbox` command-line tool enables local development: * **Traffic interception** - Routes requests for specific services to `localhost` (controlled via Lapdev dashboard) * **Cluster connectivity** - Provides transparent access to in-cluster services (databases, APIs, caches) * **Secure tunnel** - Establishes encrypted connection to Lapdev API Server, which proxies to your cluster **How it works:** 1. Developer runs `lapdev devbox connect` and sets their active environment in the dashboard 2. Devbox establishes secure tunnel: `Developer → Lapdev API` * Lapdev-Kube-Manager stays in the control plane, pushing intercept metadata and (optional) direct-connect hints to sidecars, but is not on the data path. 3. Sidecar receives intercept config, opens its own tunnel to Lapdev API for that workload, and forwards intercepted pod traffic over the tunnel to the Devbox CLI 4. Developer's code processes requests on localhost; responses flow back through the same tunnel to the pod 5. Non-intercepted traffic continues to the in-cluster service transparently Learn more: [Devbox Concept](https://docs.lap.dev/core-concepts/devbox) | [Local Development with Devbox](https://docs.lap.dev/how-to-guides/local-development-with-devbox) ### Learn More **Specialized Architecture Documentation:** * [Traffic Routing Architecture](https://docs.lap.dev/core-concepts/architecture/traffic-routing-architecture) - How Lapdev routes traffic between components * [Branch Environment Architecture](https://docs.lap.dev/core-concepts/architecture/branch-environment-architecture) - Cost-effective environment model details **Core Concepts:** * [Cluster](https://docs.lap.dev/core-concepts/cluster) - How clusters connect to Lapdev * [App Catalog](https://docs.lap.dev/core-concepts/app-catalog) - Blueprint for your application * [Environment](https://docs.lap.dev/core-concepts/environment) - Running instances of your app * [Preview URL](https://docs.lap.dev/core-concepts/preview-url) - HTTPS access to your services **Getting Started:** * [Connect Your Kubernetes Cluster](https://docs.lap.dev/how-to-guides/connect-your-kubernetes-cluster) * [Create an App Catalog](https://docs.lap.dev/how-to-guides/create-an-app-catalog) * [Create Lapdev Environment](https://docs.lap.dev/how-to-guides/create-lapdev-environment)