# movacx/bc250-control-center architecture

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

- Interactive diagram: https://gitdiagram.com/movacx/bc250-control-center
- Repository: https://github.com/movacx/bc250-control-center
- Video tour (about a minute): https://gitdiagram.com/movacx/bc250-control-center/video

## Overview

BC250 Control Center is a Linux desktop control and monitoring application for AMD BC-250 hardware, with a CLI and optional SteamOS Decky panel. The main workflow is to start the desktop app, inspect system status, prepare supported dependencies when needed, then review and apply bounded hardware changes. Its domain branches cover GPU governance, CPU tuning, Compute Unit and fan control, plus diagnostics and recovery. The graph uses documented capabilities and the composition-root source; several subsystem paths are represented by their enclosing directories because their wiring was not sampled.

Main entry points: [`frontends/desktop/app.py`](https://github.com/movacx/bc250-control-center/blob/main/frontends/desktop/app.py) (Desktop interface), [`frontends/desktop/main.py`](https://github.com/movacx/bc250-control-center/blob/main/frontends/desktop/main.py) (Desktop entry), [`privileged/lib/bc250_contract.py`](https://github.com/movacx/bc250-control-center/blob/main/privileged/lib/bc250_contract.py) (Privileged helpers), [`src/bc250cc/application/system`](https://github.com/movacx/bc250-control-center/tree/main/src/bc250cc/application/system) (System service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontends["User interfaces"]
  node_desktop_entry["Desktop entry<br/>[main.py]"]
  node_desktop_window["Desktop interface<br/>[app.py]"]
  node_cli["CLI<br/>[cli.py]"]
  node_decky_panel["Decky Quick Access<br/>[index.tsx]"]
end

subgraph group_application["Application services"]
  node_container["Service composition<br/>[container.py]"]
  node_system_service["System service"]
  node_preparation["Dependency preparation<br/>[service.py]"]
  node_monitoring["Monitoring and health<br/>[aggregator.py]"]
end

subgraph group_hardware["Hardware controls"]
  node_gpu_control["GPU governance"]
  node_cpu_control["CPU tuning<br/>[use_cases.py]"]
  node_cu_control["Compute Units<br/>[operations.py]"]
  node_fan_control["Fan control<br/>[policy.py]"]
end

subgraph group_platform["Platform integrations"]
  node_gpu_runtime["GPU runtime adapter<br/>[cyan_gpu_engine.py]"]
  node_gpu_repository["GPU repository<br/>[gpu_repository.py]"]
  node_dependency_repository["Dependency repository"]
  node_privileged_helpers["Privileged helpers<br/>[bc250_contract.py]"]
  node_decky_backend["Decky backend<br/>[main.py]"]
end

subgraph group_safety["State and safety"]
  node_recovery["Recovery snapshots<br/>[service.py]"]
  node_recovery_store[("Recovery snapshot store<br/>[recovery_engine.py]")]
end

node_desktop_user(("Desktop user"))
node_hardware_system{{"Linux hardware and services"}}

node_desktop_user -->|"starts"| node_desktop_entry
node_desktop_entry -->|"constructs services"| node_container
node_desktop_entry -->|"opens"| node_desktop_window
node_container -->|"provides"| node_system_service
node_desktop_window -->|"uses"| node_system_service
node_cli -->|"accesses"| node_system_service
node_desktop_window -->|"requests preparation"| node_preparation
node_preparation -->|"executes preparation"| node_dependency_repository
node_desktop_window -->|"presents status"| node_monitoring
node_desktop_window -->|"requests GPU changes"| node_gpu_control
node_desktop_window -->|"requests CPU tuning"| node_cpu_control
node_desktop_window -->|"requests CU changes"| node_cu_control
node_desktop_window -->|"requests fan changes"| node_fan_control
node_desktop_window -->|"requests snapshots"| node_recovery
node_recovery -->|"captures and reads"| node_recovery_store
node_gpu_control -->|"reads and writes"| node_gpu_repository
node_gpu_repository -->|"delegates runtime control"| node_gpu_runtime
node_gpu_runtime -->|"reads evidence and controls"| node_hardware_system
node_dependency_repository -->|"checks and prepares"| node_hardware_system
node_cu_control -.->|"dispatches operations"| node_privileged_helpers
node_fan_control -->|"controls fan"| node_hardware_system
node_cpu_control -->|"tunes CPU"| node_hardware_system
node_decky_panel -->|"dispatches requests"| node_decky_backend
node_decky_backend -->|"runs named operations"| node_privileged_helpers
node_privileged_helpers -->|"applies privileged changes"| node_hardware_system

click node_desktop_entry "https://github.com/movacx/bc250-control-center/blob/main/frontends/desktop/main.py"
click node_desktop_window "https://github.com/movacx/bc250-control-center/blob/main/frontends/desktop/app.py"
click node_cli "https://github.com/movacx/bc250-control-center/blob/main/frontends/cli.py"
click node_decky_panel "https://github.com/movacx/bc250-control-center/blob/main/integrations/decky/bc250-quick-access/src/index.tsx"
click node_container "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/container.py"
click node_system_service "https://github.com/movacx/bc250-control-center/tree/main/src/bc250cc/application/system"
click node_preparation "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/preparation/service.py"
click node_monitoring "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/health/aggregator.py"
click node_recovery "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/recovery/service.py"
click node_gpu_control "https://github.com/movacx/bc250-control-center/tree/main/src/bc250cc/application/gpu"
click node_cpu_control "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/cpu/use_cases.py"
click node_cu_control "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/compute_units/operations.py"
click node_fan_control "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/fan/policy.py"
click node_gpu_runtime "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/infrastructure/gpu/cyan_gpu_engine.py"
click node_gpu_repository "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/infrastructure/gpu_repository.py"
click node_dependency_repository "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/infrastructure/dependencias_repository.py"
click node_recovery_store "https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/infrastructure/persistence/recovery_engine.py"
click node_privileged_helpers "https://github.com/movacx/bc250-control-center/blob/main/privileged/lib/bc250_contract.py"
click node_decky_backend "https://github.com/movacx/bc250-control-center/blob/main/integrations/decky/bc250-quick-access/main.py"

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_desktop_entry,node_desktop_window,node_cli,node_decky_panel,node_desktop_user toneBlue
class node_container,node_system_service,node_preparation,node_monitoring toneAmber
class node_gpu_control,node_cpu_control,node_cu_control,node_fan_control toneMint
class node_gpu_runtime,node_gpu_repository,node_dependency_repository,node_privileged_helpers,node_decky_backend toneRose
class node_recovery,node_recovery_store,node_hardware_system toneIndigo
```

## Components

### User interfaces

- [Desktop entry](https://github.com/movacx/bc250-control-center/blob/main/frontends/desktop/main.py): `frontends/desktop/main.py`
- [Desktop interface](https://github.com/movacx/bc250-control-center/blob/main/frontends/desktop/app.py): `frontends/desktop/app.py`
- [CLI](https://github.com/movacx/bc250-control-center/blob/main/frontends/cli.py): `frontends/cli.py`
- [Decky Quick Access](https://github.com/movacx/bc250-control-center/blob/main/integrations/decky/bc250-quick-access/src/index.tsx): `integrations/decky/bc250-quick-access/src/index.tsx`

### Application services

- [Service composition](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/container.py): `src/bc250cc/application/container.py`
- [System service](https://github.com/movacx/bc250-control-center/tree/main/src/bc250cc/application/system): `src/bc250cc/application/system`
- [Dependency preparation](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/preparation/service.py): `src/bc250cc/application/preparation/service.py`
- [Monitoring and health](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/health/aggregator.py): `src/bc250cc/application/health/aggregator.py`

### Hardware controls

- [GPU governance](https://github.com/movacx/bc250-control-center/tree/main/src/bc250cc/application/gpu): `src/bc250cc/application/gpu`
- [CPU tuning](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/cpu/use_cases.py): `src/bc250cc/application/cpu/use_cases.py`
- [Compute Units](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/compute_units/operations.py): `src/bc250cc/application/compute_units/operations.py`
- [Fan control](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/fan/policy.py): `src/bc250cc/application/fan/policy.py`

### Platform integrations

- [GPU runtime adapter](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/infrastructure/gpu/cyan_gpu_engine.py): `src/bc250cc/infrastructure/gpu/cyan_gpu_engine.py`
- [GPU repository](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/infrastructure/gpu_repository.py): `src/bc250cc/infrastructure/gpu_repository.py`
- [Dependency repository](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/infrastructure/dependencias_repository.py): `src/bc250cc/infrastructure/dependencias_repository.py`
- [Privileged helpers](https://github.com/movacx/bc250-control-center/blob/main/privileged/lib/bc250_contract.py): `privileged/lib/bc250_contract.py`
- [Decky backend](https://github.com/movacx/bc250-control-center/blob/main/integrations/decky/bc250-quick-access/main.py): `integrations/decky/bc250-quick-access/main.py`

### State and safety

- [Recovery snapshots](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/application/recovery/service.py): `src/bc250cc/application/recovery/service.py`
- [Recovery snapshot store](https://github.com/movacx/bc250-control-center/blob/main/src/bc250cc/infrastructure/persistence/recovery_engine.py): `src/bc250cc/infrastructure/persistence/recovery_engine.py`

### Other components

- **Desktop user**
- **Linux hardware and services**

## Connections

- Desktop user → Desktop entry: starts
- Desktop entry → Service composition: constructs services
- Desktop entry → Desktop interface: opens
- Service composition → System service: provides
- Desktop interface → System service: uses
- CLI → System service: accesses
- Desktop interface → Dependency preparation: requests preparation
- Dependency preparation → Dependency repository: executes preparation
- Desktop interface → Monitoring and health: presents status
- Desktop interface → GPU governance: requests GPU changes
- Desktop interface → CPU tuning: requests CPU tuning
- Desktop interface → Compute Units: requests CU changes
- Desktop interface → Fan control: requests fan changes
- Desktop interface → Recovery snapshots: requests snapshots
- Recovery snapshots → Recovery snapshot store: captures and reads
- GPU governance → GPU repository: reads and writes
- GPU repository → GPU runtime adapter: delegates runtime control
- GPU runtime adapter → Linux hardware and services: reads evidence and controls
- Dependency repository → Linux hardware and services: checks and prepares
- Compute Units → Privileged helpers: dispatches operations
- Fan control → Linux hardware and services: controls fan
- CPU tuning → Linux hardware and services: tunes CPU
- Decky Quick Access → Decky backend: dispatches requests
- Decky backend → Privileged helpers: runs named operations
- Privileged helpers → Linux hardware and services: applies privileged changes