# gefyrahq/gefyra architecture

> Architecture diagram of the GitHub repository gefyrahq/gefyra, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gefyrahq/gefyra
- Repository: https://github.com/gefyrahq/gefyra

## Overview

Gefyra connects a developer’s local containers to Kubernetes workloads for realistic local development: the user installs the cluster components, runs a local container, and bridges a selected workload to it. The CLI also manages clients, mounts, status, and cleanup. The operator reconciles client, bridge, and mount resources; the carrier handles proxy traffic, while the Stowaway connection supplies the WireGuard-based cluster link. README claims inform product capabilities; several subsystem links use documented behavior because their source was not sampled.

Main entry points: [`client/gefyra/cli/main.py`](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/cli/main.py) (CLI Commands), [`operator/main.py`](https://github.com/gefyrahq/gefyra/blob/main/operator/main.py) (Operator Startup), [`operator/gefyra/handler/clients.py`](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/handler/clients.py) (Client Reconciliation), [`operator/gefyra/clientstate.py`](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/clientstate.py) (Client State)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Developer CLI"]
  node_cli_entry["CLI Commands<br/>[main.py]"]
  node_bridge_api["Bridge API<br/>[bridge.py]"]
  node_run_api["Run API<br/>[run.py]"]
  node_client_api["Client API<br/>[clients.py]"]
  node_mount_api["Mount API<br/>[mount.py]"]
  node_install_api["Install API<br/>[install.py]"]
end

subgraph group_local["Local Runtime"]
  node_local_clients["Client Runtime<br/>[clients.py]"]
  node_local_cargo["Container Runtime<br/>[cargo.py]"]
  node_local_mount["Mount Runtime<br/>[mount.py]"]
  node_local_network["Local Networking<br/>[networking.py]"]
end

subgraph group_control["Operator Control Plane"]
  node_operator_entry["Operator Startup<br/>[main.py]"]
  node_client_handler["Client Reconciliation<br/>[clients.py]"]
  node_bridge_handler["Bridge Reconciliation<br/>[bridges.py]"]
  node_mount_handler["Mount Reconciliation<br/>[bridge_mounts.py]"]
  node_client_state["Client State<br/>[clientstate.py]"]
end

subgraph group_traffic["Traffic and Connection"]
  node_stowaway["Stowaway Link<br/>[handler.py]"]
  node_carrier["Traffic Proxy<br/>[main.rs]"]
  node_route_rules["Proxy Match Rules<br/>[lib.rs]"]
end

subgraph group_cluster["Cluster Resources"]
  node_cluster_resources["Cluster Resources<br/>[statefulsets.py]"]
  node_rbac["Client Permissions<br/>[serviceaccounts.py]"]
end

node_developer(("Developer"))
node_kubernetes[("Kubernetes API")]
node_docker[("Docker Engine")]

node_developer -->|"issues commands"| node_cli_entry
node_cli_entry -->|"dispatches bridge"| node_bridge_api
node_cli_entry -->|"dispatches run"| node_run_api
node_cli_entry -->|"manages clients"| node_client_api
node_cli_entry -->|"manages mounts"| node_mount_api
node_cli_entry -->|"installs components"| node_install_api
node_run_api -->|"starts container"| node_local_cargo
node_local_cargo -->|"creates container"| node_docker
node_bridge_api -->|"configures bridge"| node_kubernetes
node_client_api -->|"creates client"| node_local_clients
node_local_clients -->|"writes client resource"| node_kubernetes
node_mount_api -->|"configures mount"| node_local_mount
node_local_mount -->|"mounts files"| node_docker
node_install_api -->|"installs components"| node_kubernetes
node_operator_entry -->|"registers handler"| node_client_handler
node_operator_entry -->|"registers handler"| node_bridge_handler
node_operator_entry -->|"registers handler"| node_mount_handler
node_client_handler -->|"reconciles state"| node_client_state
node_client_handler -->|"watches client objects"| node_kubernetes
node_bridge_handler -->|"reconciles bridges"| node_kubernetes
node_mount_handler -->|"reconciles mounts"| node_kubernetes
node_client_state -->|"manages permissions"| node_rbac
node_client_state -->|"enables connection"| node_stowaway
node_stowaway -->|"updates routes"| node_kubernetes
node_cluster_resources -->|"creates link resources"| node_kubernetes
node_stowaway -.->|"connects proxy"| node_carrier
node_carrier -->|"evaluates matches"| node_route_rules

click node_cli_entry "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/cli/main.py"
click node_bridge_api "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/bridge.py"
click node_run_api "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/run.py"
click node_client_api "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/clients.py"
click node_mount_api "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/mount.py"
click node_install_api "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/install.py"
click node_local_clients "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/local/clients.py"
click node_local_cargo "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/local/cargo.py"
click node_local_mount "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/local/mount.py"
click node_local_network "https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/local/networking.py"
click node_operator_entry "https://github.com/gefyrahq/gefyra/blob/main/operator/main.py"
click node_client_handler "https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/handler/clients.py"
click node_bridge_handler "https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/handler/bridges.py"
click node_mount_handler "https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/handler/bridge_mounts.py"
click node_client_state "https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/clientstate.py"
click node_cluster_resources "https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/connection/stowaway/resources/statefulsets.py"
click node_rbac "https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/resources/serviceaccounts.py"
click node_stowaway "https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/connection/stowaway/handler.py"
click node_carrier "https://github.com/gefyrahq/gefyra/blob/main/carrier2/src/main.rs"
click node_route_rules "https://github.com/gefyrahq/gefyra/blob/main/carrier2/src/lib.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_entry,node_bridge_api,node_run_api,node_client_api,node_mount_api,node_install_api toneBlue
class node_local_clients,node_local_cargo,node_local_mount,node_local_network,node_kubernetes,node_docker toneAmber
class node_operator_entry,node_client_handler,node_bridge_handler,node_mount_handler,node_client_state toneMint
class node_stowaway,node_carrier,node_route_rules toneRose
class node_cluster_resources,node_rbac,node_developer toneIndigo
```

## Components

### Developer CLI

- [CLI Commands](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/cli/main.py): `client/gefyra/cli/main.py`
- [Bridge API](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/bridge.py): `client/gefyra/api/bridge.py`
- [Run API](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/run.py): `client/gefyra/api/run.py`
- [Client API](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/clients.py): `client/gefyra/api/clients.py`
- [Mount API](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/mount.py): `client/gefyra/api/mount.py`
- [Install API](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/api/install.py): `client/gefyra/api/install.py`

### Local Runtime

- [Client Runtime](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/local/clients.py): `client/gefyra/local/clients.py`
- [Container Runtime](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/local/cargo.py): `client/gefyra/local/cargo.py`
- [Mount Runtime](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/local/mount.py): `client/gefyra/local/mount.py`
- [Local Networking](https://github.com/gefyrahq/gefyra/blob/main/client/gefyra/local/networking.py): `client/gefyra/local/networking.py`

### Operator Control Plane

- [Operator Startup](https://github.com/gefyrahq/gefyra/blob/main/operator/main.py): `operator/main.py`
- [Client Reconciliation](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/handler/clients.py): `operator/gefyra/handler/clients.py`
- [Bridge Reconciliation](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/handler/bridges.py): `operator/gefyra/handler/bridges.py`
- [Mount Reconciliation](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/handler/bridge_mounts.py): `operator/gefyra/handler/bridge_mounts.py`
- [Client State](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/clientstate.py): `operator/gefyra/clientstate.py`

### Traffic and Connection

- [Stowaway Link](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/connection/stowaway/handler.py): `operator/gefyra/connection/stowaway/handler.py`
- [Traffic Proxy](https://github.com/gefyrahq/gefyra/blob/main/carrier2/src/main.rs): `carrier2/src/main.rs`
- [Proxy Match Rules](https://github.com/gefyrahq/gefyra/blob/main/carrier2/src/lib.rs): `carrier2/src/lib.rs`

### Cluster Resources

- [Cluster Resources](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/connection/stowaway/resources/statefulsets.py): `operator/gefyra/connection/stowaway/resources/statefulsets.py`
- [Client Permissions](https://github.com/gefyrahq/gefyra/blob/main/operator/gefyra/resources/serviceaccounts.py): `operator/gefyra/resources/serviceaccounts.py`

### Other components

- **Developer**
- **Kubernetes API**
- **Docker Engine**

## Connections

- Developer → CLI Commands: issues commands
- CLI Commands → Bridge API: dispatches bridge
- CLI Commands → Run API: dispatches run
- CLI Commands → Client API: manages clients
- CLI Commands → Mount API: manages mounts
- CLI Commands → Install API: installs components
- Run API → Container Runtime: starts container
- Container Runtime → Docker Engine: creates container
- Bridge API → Kubernetes API: configures bridge
- Client API → Client Runtime: creates client
- Client Runtime → Kubernetes API: writes client resource
- Mount API → Mount Runtime: configures mount
- Mount Runtime → Docker Engine: mounts files
- Install API → Kubernetes API: installs components
- Operator Startup → Client Reconciliation: registers handler
- Operator Startup → Bridge Reconciliation: registers handler
- Operator Startup → Mount Reconciliation: registers handler
- Client Reconciliation → Client State: reconciles state
- Client Reconciliation → Kubernetes API: watches client objects
- Bridge Reconciliation → Kubernetes API: reconciles bridges
- Mount Reconciliation → Kubernetes API: reconciles mounts
- Client State → Client Permissions: manages permissions
- Client State → Stowaway Link: enables connection
- Stowaway Link → Kubernetes API: updates routes
- Cluster Resources → Kubernetes API: creates link resources
- Stowaway Link → Traffic Proxy: connects proxy
- Traffic Proxy → Proxy Match Rules: evaluates matches