# 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**](/core-concepts/devbox.md) **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

<img src="/files/BRxw90F3elofD1dYvvkq" alt="" class="gitbook-drawing">

### 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**](/core-concepts/preview-url.md) **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](/core-concepts/app-catalog.md)
* **Creates dev** [**environments**](/core-concepts/environment.md) - 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](/core-concepts/architecture/branch-environment-architecture.md), computes routing tables and distributes them to sidecars (sidecars enforce routing; see [Traffic Routing Architecture](/core-concepts/architecture/traffic-routing-architecture.md))
* **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](/core-concepts/devbox.md) | [Local Development with Devbox](/how-to-guides/local-development-with-devbox.md)

### Learn More

**Specialized Architecture Documentation:**

* [Traffic Routing Architecture](/core-concepts/architecture/traffic-routing-architecture.md) - How Lapdev routes traffic between components
* [Branch Environment Architecture](/core-concepts/architecture/branch-environment-architecture.md) - Cost-effective environment model details

**Core Concepts:**

* [Cluster](/core-concepts/cluster.md) - How clusters connect to Lapdev
* [App Catalog](/core-concepts/app-catalog.md) - Blueprint for your application
* [Environment](/core-concepts/environment.md) - Running instances of your app
* [Preview URL](/core-concepts/preview-url.md) - HTTPS access to your services

**Getting Started:**

* [Connect Your Kubernetes Cluster](/how-to-guides/connect-your-kubernetes-cluster.md)
* [Create an App Catalog](/how-to-guides/create-an-app-catalog.md)
* [Create Lapdev Environment](/how-to-guides/create-lapdev-environment.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lap.dev/core-concepts/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.