docs: update architecture diagram

[polarweasel]

Updating the architecture diagram, and removing the old and wrong NICo Site Controller overview diagram.

While I was in there, I did some lint/language fixes on the architecture overview page.

Related issues

Fixes internal bug ID 6376596.

Type of Change

• Add - New feature or capability
• Change - Changes in existing functionality
• Fix - Bug fixes
• Remove - Removed features or deprecated functionality
• Internal - Internal changes (refactoring, tests, docs, etc.)

Breaking Changes

• This PR contains breaking changes

Testing

• Unit tests added/updated
• Integration tests added/updated
• Manual testing performed
• No testing required (docs, internal refactor, etc.)

Additional Notes

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 98f017f0-6a5c-43c3-ad88-d77a8d76c579

📥 Commits

Reviewing files that changed from the base of the PR and between 8ca3ed0 and f9ad6fc.

⛔ Files ignored due to path filters (1)

• docs/static/nico_arch_diagram.svg is excluded by !**/*.svg

📒 Files selected for processing (1)

• docs/architecture/overview.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/architecture/overview.md

---

Summary by CodeRabbit

• Documentation
  • Reformatted the architecture overview for improved readability and consistency.
  • Clarified descriptions for managed hosts, Scout, DPU Agent, DHCP, control plane, NICo Core, Machine Update Manager, IB Fabric Monitor, persistent storage, optional services, and FMDS.
  • Expanded Debug UI capabilities, state-machine scope and linking, and Site Explorer details.
  • Updated terminology, grammar, and examples, including HTTP terminology for FMDS.
  • Removed obsolete site-controller diagram references.

Walkthrough

The architecture overview was reformatted and clarified. Obsolete diagrams were removed. NICo Core details were expanded. Service descriptions and the Fern configuration version were updated.

Changes

Architecture Overview

Layer / File(s)	Summary
Overview structure and service descriptions docs/architecture/overview.md, fern/fern.config.json	The introductory service list and Scout, DPU Agent, DHCP Server, and NICo control-plane sections received wording and formatting updates. Obsolete diagrams were removed. Fern was updated from version 5.89.1 to 5.94.0.
NICo Core architecture details docs/architecture/overview.md	NICo Core documentation now describes Debug UI capabilities, supported state machines, state handling, and Site Explorer details.
Service operations and storage descriptions docs/architecture/overview.md	Machine Update Manager, IB Fabric Monitor, persistent-storage, optional-service, and FMDS descriptions were clarified and reformatted.

Estimated code review effort: 1 (Trivial) | ~5 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the primary documentation change: updating the architecture diagram.
Description check	✅ Passed	The description accurately covers the diagram update, obsolete diagram removal, and documentation corrections.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[polarweasel]

/ok to test

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pull-request-4833.docs.buildwithfern.com/infra-controller

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture/overview.md`:
- Line 158: Clarify the health-capacity sentence in the Machine Update Manager
description by specifying whether the scheduler counts healthy Machines or
healthy hosts across the site, using the exact terminology established by the
implementation and surrounding documentation. Keep the explanation of limiting
concurrent updates and protecting the Machine health SLA unchanged.
- Line 92: Update the affected prose to use the compound adjectives
“machine-readable” at the gRPC reflection description, “admin-level” at the
referenced administration text, and “up-to-date” at the referenced status text;
at the HTTP reference, use “an HTTP-based” with the correct article. Preserve
the surrounding wording and meaning.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 7f5fb9da-2a76-44ce-82df-5c71adda3b29

📥 Commits

Reviewing files that changed from the base of the PR and between a69c085 and 4dc1c6a.

⛔ Files ignored due to path filters (1)

• docs/static/nico_arch_diagram.svg is excluded by !**/*.svg

📒 Files selected for processing (1)

• docs/architecture/overview.md

[polarweasel]

/ok to test

[coderabbitai]

Actionable comments posted: 6

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/architecture/overview.md`:
- Line 53: Update the DHCP description in the NICo architecture overview to use
“the host’s primary networking interfaces” and replace “network - which” with a
comma or em dash construction, preserving the sentence’s meaning.
- Line 49: Update the affected Markdown prose near the hotfix, resource, DHCP,
tenant, and host-console references to use the requested normalized forms:
bare-metal instances, NICo-managed resources, gRPC-based DHCP requests,
bare-metal tenants, and each host’s serial console. Preserve the existing
meaning and apply the same spelling and grammar corrections at all referenced
occurrences.
- Around line 77-78: Remove the stale NICo Core diagram reference, including the
JSX-style source note and the nico-core.png image entry, from the architecture
overview while leaving the surrounding section content intact.
- Around line 99-101: Narrow the “all resources” and “idempotent state-handling”
claims in the “State Machines” section to match the behavior documented by
state_handling.md, unless a complete cross-resource transition reference is
being added. Avoid asserting universal resource coverage or idempotency beyond
the documented scheduling and retry contract.
- Around line 24-28: Update the architecture overview to describe DPU components
as optional, removing the implication that every Managed Host has a DPU BMC or
runs DHCP on a DPU. Document the zero-DPU configuration using dpu_policy:
ignore, a primary HostInband NIC, and central NICo DHCP, and link to the
existing zero-DPU boot and lifecycle contract.
- Line 63: Update the managed-host boot behavior description in the architecture
overview to reflect that NICo may return a boot script, an exit script for a
provisioned OS, or an error script; HTTP chain failures open the iPXE error
menu, while local boot occurs only through the explicit localboot menu action.
Also document what happens when no local boot target exists, and remove the
inaccurate claim that the embedded script automatically tests for one.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 853fe7e9-236d-4c6b-84e4-8f4ca0eb83c5

📥 Commits

Reviewing files that changed from the base of the PR and between b622b79 and 4da14af.

📒 Files selected for processing (1)

• docs/architecture/overview.md

[thossain-nv]

First set of suggestions for the diagram:

• Rename JSON API to REST API to keep the terminology consistent
  • There should be a connector between REST API and PostgreSQL
• Put Admin CLI and Admin Web Browser in a Debug Tools box (NICo CLI should be used when possible)
• Remove NVIDIA NGC Registry and its connection to PostgresQL The containers on the registry is not shared with public and the connection to Postgres is incorrect
• Rename the NVLink element within Site Controller to NVLink Manager
• Add a connector from Tenant and Admin SSH Client to SSH Console Service
• Rename Health to Health Service

@polarweasel I'll research a bit more and get back to you with a few more suggestions.

[thossain-nv]

Second set of suggestions. Sorry it's a lot, but I wanted to have all the information. Not all suggestions need to go into the diagram, since some connectors I'm suggesting might make the diagram very busy.

• We should rename Internal State Handler (gRPC API) to NICo Core (gRPC API). "Internal State Handler" does not appear anywhere in the repo, and the same binary also runs Site Explorer, Preingestion Manager, Machine Update Manager, Host Power Manager, IB Fabric Monitor, and serves the Debug Web UI, so the current name seems too narrow.
• With JSON API becoming REST API, the JSON REST API Components box label should also be REST API Components.
• Powershelf Tray should be Power Shelf Tray, per docs/manuals/rack_level_admin.md.
• We should evaluate whether DSX Exchange should be shown on the diagram. The exchange itself is not part of NICo and OSS builds likely won't have it. NICo can use nico-dsx-exchange-consumer to connect to an existing broker, but it is disabled by default in helm-prereqs deployment.
• Authoritative DNS Service, DHCP Server, Health Service, and the DPU-side DHCP Server all carry the Non-NICo Service icon, but all four are NICo components (crates/dns, crates/dhcp, crates/health, crates/dhcp-server). Health or Health Service should also be a NICo Software Component
• NVIDIA DOCA HBN and NVIDIA DOCA-OVS carry the NICo Software Component icon. NICo installs and configures them, it does not build them.
• Once NVLink becomes NVLink Manager it should carry the NICo component icon too, since it is a background module of NICo Core.
• Is Spectrum X meant to be the Core-side integration as well, or the fabric? Right now it is an External System fed by Core, which reads as neither.
• RMS is a Non-NICo Service while UFM and NMX-C are External System. All three are external managers Core reaches over mTLS, can they share one type?
• Telemetry/Logs OpenTelemetry Prometheus and Vault (secrets) use a grey icon that has no legend entry.
• OOB uses the External System icon while the NICs use Physical Interface. It is a DPU management Interface, so Physical Interface seems closer.
• DPS is drawn inside the Site Controller boundary, but it is an external service. Integration with DPS is not completed, we should add it when the work is complete.
• Core has no connector to the host BMC. The host BMC has exactly three inbound connectors (RMS, SSH Console Service, BMC Proxy), and Core is not one of them, even though Core reaches the DPU BMC, the Switch Tray BMC, and the PMC directly. Site Explorer, Host Power Manager, Preingestion Manager, and the ManagedHost state machine all connect to the host BMC via Redfish, so this seems like an oversight rather than a simplification.
• Health Service currently only reaches the DPU BMC. Per docs/architecture/overview.md, nico-hw-health scrapes all host and DPU BMCs. We should add the host BMC and DPU BMC.
• DHCP Server has one connector, to Core, so nothing shows where DHCP requests come from. We can add the host BMC, DPU BMC, and DPU OOB.
• PXE Service is wired only to the DPU OOB. The host iPXE boot path over HTTP is missing.
• Scout has no connectors. It reports inventory, validation results, and periodic health to Core over mTLS/gRPC, and it runs on the DPU as well as the host.
• Tenant OS has no connectors. Metadata Service serves it over HTTP, which is the reason both nodes are on the diagram.
• DPU Agent has no connector to Core. Its periodic config poll and RecordDpuNetworkStatus callback are the main DPU control path, and currently its only inbound connector comes from the OOB box with no protocol on it.
• Recursive DNS (unbound) has no connectors, even though it is the resolver every managed host, BMC, and DPU actually uses. It should also connect to the Authoritative DNS Service

[shayan1995]

Language and terminology fixes look good — BlueField, InfiniBand, PostgreSQL, bare-metal, etc. are all corrected consistently. Removing the old site-controller-overview diagram is the right call. Left a couple of comments on content gaps but nothing blocking.

[polarweasel]

@thossain-nv I think I got all your changes into the diagram. Thanks so much for the very thorough review!

As an aside, I feel like we're at the limit of what we can do with the current diagram, but I don't have the time to fully redo it at this point. Do we have anyone around who's really good at these things? Visual presentation of complex networks is definitely not my forte. 😬

[thossain-nv]

Thanks for the diagram changes @polarweasel! It looks much better now.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.