# cuongpv1309/bex architecture

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

- Interactive diagram: https://gitdiagram.com/cuongpv1309/bex
- Repository: https://github.com/cuongpv1309/bex

## Overview

bex is a self-hostable PaaS control plane: a developer or agent submits a Git-backed service or Blueprint, the control plane represents desired state, and the Kubernetes operator builds and rolls out workloads, routing and TLS. The README also describes data services, operational tooling, team administration, and multiple interfaces. The graph uses documented workflow links; source excerpts are limited, so internal links not explicitly shown are omitted.

Main entry points: [`lego/backend/internal/api/server.go`](https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/api/server.go) (REST / GraphQL / MCP), [`dashboard/src`](https://github.com/cuongpv1309/bex/tree/main/dashboard/src) (Dashboard), [`lego/operator/internal/controller/app_controller.go`](https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go) (Kubernetes Operator), [`lego/cli/main.go`](https://github.com/cuongpv1309/bex/blob/main/lego/cli/main.go) (Render-compatible CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Control Plane Interfaces"]
  node_dashboard["Dashboard"]
  node_api["REST / GraphQL / MCP<br/>[server.go]"]
  node_cli["Render-compatible CLI<br/>[main.go]"]
  node_mobile["Mobile Client"]
end

subgraph group_deploy["Deployment Lifecycle"]
  node_blueprint["Blueprint API<br/>[server.go]"]
  node_app_database["App and Database Resources"]
  node_operator["Kubernetes Operator<br/>[app_controller.go]"]
  node_build_rollout["Build and Rollout<br/>[app_controller.go]"]
  node_routing_tls["Routing and TLS<br/>[app_controller.go]"]
end

subgraph group_runtime["Runtime Services"]
  node_workloads["Workloads<br/>[app_controller.go]"]
  node_managed_data[("Managed Postgres and Valkey<br/>[database_types.go]")]
end

subgraph group_agents["Agent Platform"]
  node_agent_sessions["Agent Sessions"]
  node_agent_driver["Agent Image Driver"]
end

subgraph group_operations["Operations and Teams"]
  node_ops_features["Deploys, Logs, Metrics<br/>[server.go]"]
  node_teams_billing["Teams and Billing<br/>[pipeline.go]"]
end

node_developer(("Developer"))
node_coding_agent(("Coding Agent"))
node_git_repo["Git Repository"]

node_developer -->|"manages services"| node_dashboard
node_developer -->|"deploys with"| node_cli
node_coding_agent -->|"deploys via MCP"| node_api
node_git_repo -->|"provides source"| node_blueprint
node_dashboard -->|"uses control plane"| node_api
node_cli -->|"operates control plane"| node_api
node_api -->|"serves Blueprint API"| node_blueprint
node_blueprint -->|"compiles intent"| node_app_database
node_app_database -->|"reconciles resources"| node_operator
node_operator -->|"builds and rolls out"| node_build_rollout
node_build_rollout -->|"runs workloads"| node_workloads
node_operator -->|"configures routing"| node_routing_tls
node_developer -->|"provisions data"| node_managed_data
node_dashboard -->|"views operations"| node_ops_features
node_dashboard -->|"manages teams"| node_teams_billing
node_coding_agent -->|"uses sessions"| node_agent_sessions
node_agent_sessions -.->|"runs agent turns"| node_agent_driver
node_mobile -.->|"uses control plane"| node_api

click node_dashboard "https://github.com/cuongpv1309/bex/tree/main/dashboard/src"
click node_api "https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/api/server.go"
click node_cli "https://github.com/cuongpv1309/bex/blob/main/lego/cli/main.go"
click node_blueprint "https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/api/server.go"
click node_app_database "https://github.com/cuongpv1309/bex/tree/main/lego/types/v1alpha1"
click node_operator "https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go"
click node_build_rollout "https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go"
click node_routing_tls "https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go"
click node_workloads "https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go"
click node_managed_data "https://github.com/cuongpv1309/bex/blob/main/lego/types/v1alpha1/database_types.go"
click node_ops_features "https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/api/server.go"
click node_teams_billing "https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/workspaces/pipeline.go"
click node_agent_sessions "https://github.com/cuongpv1309/bex/tree/main/dashboard/src/features/agent-sessions"
click node_agent_driver "https://github.com/cuongpv1309/bex/tree/main/lego/agent-image/driver/src"
click node_mobile "https://github.com/cuongpv1309/bex/tree/main/mobile/src/features/capabilities"

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_dashboard,node_api,node_cli,node_mobile toneBlue
class node_blueprint,node_app_database,node_operator,node_build_rollout,node_routing_tls toneAmber
class node_workloads,node_managed_data toneMint
class node_agent_sessions,node_agent_driver toneRose
class node_ops_features,node_teams_billing,node_developer,node_coding_agent,node_git_repo toneIndigo
```

## Components

### Control Plane Interfaces

- [Dashboard](https://github.com/cuongpv1309/bex/tree/main/dashboard/src): `dashboard/src`
- [REST / GraphQL / MCP](https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/api/server.go): `lego/backend/internal/api/server.go`
- [Render-compatible CLI](https://github.com/cuongpv1309/bex/blob/main/lego/cli/main.go): `lego/cli/main.go`
- [Mobile Client](https://github.com/cuongpv1309/bex/tree/main/mobile/src/features/capabilities): `mobile/src/features/capabilities`

### Deployment Lifecycle

- [Blueprint API](https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/api/server.go): `lego/backend/internal/api/server.go`
- [App and Database Resources](https://github.com/cuongpv1309/bex/tree/main/lego/types/v1alpha1): `lego/types/v1alpha1`
- [Kubernetes Operator](https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go): `lego/operator/internal/controller/app_controller.go`
- [Build and Rollout](https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go): `lego/operator/internal/controller/app_controller.go`
- [Routing and TLS](https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go): `lego/operator/internal/controller/app_controller.go`

### Runtime Services

- [Workloads](https://github.com/cuongpv1309/bex/blob/main/lego/operator/internal/controller/app_controller.go): `lego/operator/internal/controller/app_controller.go`
- [Managed Postgres and Valkey](https://github.com/cuongpv1309/bex/blob/main/lego/types/v1alpha1/database_types.go): `lego/types/v1alpha1/database_types.go`

### Agent Platform

- [Agent Sessions](https://github.com/cuongpv1309/bex/tree/main/dashboard/src/features/agent-sessions): `dashboard/src/features/agent-sessions`
- [Agent Image Driver](https://github.com/cuongpv1309/bex/tree/main/lego/agent-image/driver/src): `lego/agent-image/driver/src`

### Operations and Teams

- [Deploys, Logs, Metrics](https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/api/server.go): `lego/backend/internal/api/server.go`
- [Teams and Billing](https://github.com/cuongpv1309/bex/blob/main/lego/backend/internal/workspaces/pipeline.go): `lego/backend/internal/workspaces/pipeline.go`

### Other components

- **Developer**
- **Coding Agent**
- **Git Repository**

## Connections

- Developer → Dashboard: manages services (evidence: `README.md`)
- Developer → Render-compatible CLI: deploys with (evidence: `README.md`)
- Coding Agent → REST / GraphQL / MCP: deploys via MCP (evidence: `README.md`)
- Git Repository → Blueprint API: provides source (evidence: `README.md`)
- Dashboard → REST / GraphQL / MCP: uses control plane (evidence: `README.md`)
- Render-compatible CLI → REST / GraphQL / MCP: operates control plane (evidence: `README.md`)
- REST / GraphQL / MCP → Blueprint API: serves Blueprint API (evidence: `lego/backend/internal/api/server.go`)
- Blueprint API → App and Database Resources: compiles intent (evidence: `README.md`)
- App and Database Resources → Kubernetes Operator: reconciles resources (evidence: `README.md`)
- Kubernetes Operator → Build and Rollout: builds and rolls out (evidence: `README.md`)
- Build and Rollout → Workloads: runs workloads (evidence: `README.md`)
- Kubernetes Operator → Routing and TLS: configures routing (evidence: `README.md`)
- Developer → Managed Postgres and Valkey: provisions data (evidence: `README.md`)
- Dashboard → Deploys, Logs, Metrics: views operations (evidence: `README.md`)
- Dashboard → Teams and Billing: manages teams (evidence: `README.md`)
- Coding Agent → Agent Sessions: uses sessions (evidence: `README.md`)
- Agent Sessions → Agent Image Driver: runs agent turns
- Mobile Client → REST / GraphQL / MCP: uses control plane
