# dsx-ai-factory/infra-controller architecture

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

- Interactive diagram: https://gitdiagram.com/dsx-ai-factory/infra-controller
- Repository: https://github.com/dsx-ai-factory/infra-controller

## Overview

NICo is a microservice suite for zero-trust bare-metal AI infrastructure lifecycle automation. Providers and tenants use APIs to request site and tenant operations; NICo coordinates hardware readiness, provisioning, isolation, firmware, and sanitization, with site services managing racks, hosts, BMCs, and DPUs. The graph preserves major documented capabilities and central indexed modules. Many implementation files were not sampled, so documented relationships use README evidence and uncertain internal wiring is omitted.

Main entry points: [`crates/api-core/src/handlers`](https://github.com/dsx-ai-factory/infra-controller/tree/main/crates/api-core/src/handlers) (Lifecycle Handlers), [`crates/component-manager/src/component_manager.rs`](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/component_manager.rs) (Component Manager), [`crates/api-core/src/api.rs`](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/api-core/src/api.rs) (Core API), [`rest-api/api/pkg/api/routes.go`](https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/api/pkg/api/routes.go) (NICo REST)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["API and Operations"]
  node_rest["NICo REST<br/>[routes.go]"]
  node_admin["Admin CLI<br/>[main.rs]"]
end

subgraph group_control["Core Control Plane"]
  node_coreapi["Core API<br/>[api.rs]"]
  node_authorization["Authorization"]
  node_handlers["Lifecycle Handlers"]
  node_state["State Controller<br/>[controller.rs]"]
end

subgraph group_hardware["Hardware Management"]
  node_component["Component Manager"]
  node_compute["Compute Tray Manager"]
  node_nvlink["NVSwitch Manager"]
  node_powershelf["Power Shelf Manager"]
  node_rms["RMS Manager<br/>[rms.rs]"]
  node_mock["Component Mock<br/>[mock.rs]"]
  node_bmc["BMC Discovery<br/>[manager.rs]"]
  node_redfishmock["Redfish BMC Mock<br/>[query_router.rs]"]
  node_trayfirmware["Tray Firmware"]
end

subgraph group_lifecycle["Provisioning and Lifecycle"]
  node_readiness["Hardware Readiness<br/>[controller.rs]"]
  node_dpu["DPU Lifecycle"]
  node_attestation["Trust and Attestation"]
  node_firmware["Firmware Baseline<br/>[cmd.rs]"]
  node_sanitization["Sanitization<br/>[cmd.rs]"]
  node_flow["Rack Workflow<br/>[manager.go]"]
end

subgraph group_network["Networking and Telemetry"]
  node_dhcp["DHCP Service<br/>[grpc_server.rs]"]
  node_ipam["IP Address Management<br/>[storage.go]"]
  node_networkisolation["Network Isolation<br/>[fabric_manager.rs]"]
end

node_provider(("Provider Operator"))
node_tenant(("Tenant"))

node_provider -->|"calls"| node_rest
node_tenant -->|"calls"| node_rest
node_provider -->|"operates"| node_admin
node_admin -->|"uses gRPC"| node_coreapi
node_rest -->|"proxies operations"| node_coreapi
node_coreapi -->|"routes requests"| node_handlers
node_coreapi -.->|"authorizes callers"| node_authorization
node_coreapi -.->|"coordinates lifecycle"| node_state
node_component -->|"dispatches"| node_compute
node_component -->|"dispatches"| node_nvlink
node_component -->|"dispatches"| node_powershelf
node_component -->|"dispatches"| node_rms
node_component -->|"dispatches"| node_mock
node_readiness -->|"discovers BMCs"| node_bmc
node_bmc -.->|"can query"| node_redfishmock
node_component -.->|"manages firmware"| node_trayfirmware
node_dpu -->|"applies desired network"| node_networkisolation
node_handlers -.->|"provisions networking"| node_dhcp
node_handlers -.->|"allocates addresses"| node_ipam
node_handlers -->|"validates machines"| node_readiness
node_handlers -->|"provisions DPUs"| node_dpu
node_handlers -->|"supports attestation"| node_attestation
node_handlers -->|"manages baselines"| node_firmware
node_handlers -->|"sanitizes hosts"| node_sanitization
node_handlers -->|"provisions tenant networks"| node_networkisolation
node_handlers -->|"sequences rack work"| node_flow

click node_rest "https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/api/pkg/api/routes.go"
click node_admin "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/admin-cli/src/main.rs"
click node_coreapi "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/api-core/src/api.rs"
click node_authorization "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/api-core/src/auth/internal_rbac_rules.rs"
click node_handlers "https://github.com/dsx-ai-factory/infra-controller/tree/main/crates/api-core/src/handlers"
click node_state "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/state-controller/src/controller.rs"
click node_component "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/component_manager.rs"
click node_compute "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/compute_tray_manager.rs"
click node_nvlink "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/nv_switch_manager.rs"
click node_powershelf "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/power_shelf_manager.rs"
click node_rms "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/rms.rs"
click node_mock "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/mock.rs"
click node_bmc "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/bmc-explorer/src/manager.rs"
click node_redfishmock "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/bmc-mock/src/redfish/query_router.rs"
click node_trayfirmware "https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/powershelf-manager/pkg/firmwaremanager/firmware_manager.go"
click node_dhcp "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/dhcp-server/src/grpc_server.rs"
click node_ipam "https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/ipam/storage.go"
click node_readiness "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/machine-controller/src/config/controller.rs"
click node_dpu "https://github.com/dsx-ai-factory/infra-controller/blob/main/dev/k8s/dpf-sim-controller/internal/controller/dpudevice_controller.go"
click node_attestation "https://github.com/dsx-ai-factory/infra-controller/tree/main/crates/admin-cli/src/attestation"
click node_firmware "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/admin-cli/src/firmware/nic/desired/cmd.rs"
click node_sanitization "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/admin-cli/src/expected_machines/erase/cmd.rs"
click node_networkisolation "https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/rack-controller/src/fabric_manager.rs"
click node_flow "https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/flow/internal/task/manager/manager.go"

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_rest,node_admin toneBlue
class node_coreapi,node_authorization,node_handlers,node_state toneAmber
class node_component,node_compute,node_nvlink,node_powershelf,node_rms,node_mock,node_bmc,node_redfishmock,node_trayfirmware toneMint
class node_readiness,node_dpu,node_attestation,node_firmware,node_sanitization,node_flow toneRose
class node_dhcp,node_ipam,node_networkisolation,node_provider,node_tenant toneIndigo
```

## Components

### API and Operations

- [NICo REST](https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/api/pkg/api/routes.go): `rest-api/api/pkg/api/routes.go`
- [Admin CLI](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/admin-cli/src/main.rs): `crates/admin-cli/src/main.rs`

### Core Control Plane

- [Core API](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/api-core/src/api.rs): `crates/api-core/src/api.rs`
- [Authorization](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/api-core/src/auth/internal_rbac_rules.rs): `crates/api-core/src/auth/internal_rbac_rules.rs`
- [Lifecycle Handlers](https://github.com/dsx-ai-factory/infra-controller/tree/main/crates/api-core/src/handlers): `crates/api-core/src/handlers`
- [State Controller](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/state-controller/src/controller.rs): `crates/state-controller/src/controller.rs`

### Hardware Management

- [Component Manager](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/component_manager.rs): `crates/component-manager/src/component_manager.rs`
- [Compute Tray Manager](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/compute_tray_manager.rs): `crates/component-manager/src/compute_tray_manager.rs`
- [NVSwitch Manager](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/nv_switch_manager.rs): `crates/component-manager/src/nv_switch_manager.rs`
- [Power Shelf Manager](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/power_shelf_manager.rs): `crates/component-manager/src/power_shelf_manager.rs`
- [RMS Manager](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/rms.rs): `crates/component-manager/src/rms.rs`
- [Component Mock](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/component-manager/src/mock.rs): `crates/component-manager/src/mock.rs`
- [BMC Discovery](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/bmc-explorer/src/manager.rs): `crates/bmc-explorer/src/manager.rs`
- [Redfish BMC Mock](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/bmc-mock/src/redfish/query_router.rs): `crates/bmc-mock/src/redfish/query_router.rs`
- [Tray Firmware](https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/powershelf-manager/pkg/firmwaremanager/firmware_manager.go): `rest-api/powershelf-manager/pkg/firmwaremanager/firmware_manager.go`

### Provisioning and Lifecycle

- [Hardware Readiness](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/machine-controller/src/config/controller.rs): `crates/machine-controller/src/config/controller.rs`
- [DPU Lifecycle](https://github.com/dsx-ai-factory/infra-controller/blob/main/dev/k8s/dpf-sim-controller/internal/controller/dpudevice_controller.go): `dev/k8s/dpf-sim-controller/internal/controller/dpudevice_controller.go`
- [Trust and Attestation](https://github.com/dsx-ai-factory/infra-controller/tree/main/crates/admin-cli/src/attestation): `crates/admin-cli/src/attestation`
- [Firmware Baseline](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/admin-cli/src/firmware/nic/desired/cmd.rs): `crates/admin-cli/src/firmware/nic/desired/cmd.rs`
- [Sanitization](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/admin-cli/src/expected_machines/erase/cmd.rs): `crates/admin-cli/src/expected_machines/erase/cmd.rs`
- [Rack Workflow](https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/flow/internal/task/manager/manager.go): `rest-api/flow/internal/task/manager/manager.go`

### Networking and Telemetry

- [DHCP Service](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/dhcp-server/src/grpc_server.rs): `crates/dhcp-server/src/grpc_server.rs`
- [IP Address Management](https://github.com/dsx-ai-factory/infra-controller/blob/main/rest-api/ipam/storage.go): `rest-api/ipam/storage.go`
- [Network Isolation](https://github.com/dsx-ai-factory/infra-controller/blob/main/crates/rack-controller/src/fabric_manager.rs): `crates/rack-controller/src/fabric_manager.rs`

### Other components

- **Provider Operator**
- **Tenant**

## Connections

- Provider Operator → NICo REST: calls
- Tenant → NICo REST: calls
- Provider Operator → Admin CLI: operates
- Admin CLI → Core API: uses gRPC
- NICo REST → Core API: proxies operations (evidence: `rest-api/api/pkg/api/routes.go`)
- Core API → Lifecycle Handlers: routes requests (evidence: `crates/api-core/src/api.rs`)
- Core API → Authorization: authorizes callers
- Core API → State Controller: coordinates lifecycle
- Component Manager → Compute Tray Manager: dispatches (evidence: `crates/component-manager/src/component_manager.rs`)
- Component Manager → NVSwitch Manager: dispatches (evidence: `crates/component-manager/src/component_manager.rs`)
- Component Manager → Power Shelf Manager: dispatches (evidence: `crates/component-manager/src/component_manager.rs`)
- Component Manager → RMS Manager: dispatches (evidence: `crates/component-manager/src/component_manager.rs`)
- Component Manager → Component Mock: dispatches (evidence: `crates/component-manager/src/component_manager.rs`)
- Hardware Readiness → BMC Discovery: discovers BMCs
- BMC Discovery → Redfish BMC Mock: can query
- Component Manager → Tray Firmware: manages firmware
- DPU Lifecycle → Network Isolation: applies desired network
- Lifecycle Handlers → DHCP Service: provisions networking
- Lifecycle Handlers → IP Address Management: allocates addresses
- Lifecycle Handlers → Hardware Readiness: validates machines
- Lifecycle Handlers → DPU Lifecycle: provisions DPUs
- Lifecycle Handlers → Trust and Attestation: supports attestation
- Lifecycle Handlers → Firmware Baseline: manages baselines
- Lifecycle Handlers → Sanitization: sanitizes hosts
- Lifecycle Handlers → Network Isolation: provisions tenant networks
- Lifecycle Handlers → Rack Workflow: sequences rack work