CNTRLPLANE-3555: Add ARCHITECTURE.md to repository root

[celebdor]

Summary

• Adds ARCHITECTURE.md to satisfy the HPSTRAT-6 contextification initiative, which requires every active repo to have README.md, CONTRIBUTING.md, AGENTS.md, and ARCHITECTURE.md
• Concise overview (~50 lines) covering purpose, key concepts, core components, design invariants, and platform support
• Links to detailed docs in docs/content/reference/ rather than duplicating content

Jira

• Feature: OCPSTRAT-3200 — [Control Plane] Phase 1: Contextification
• Epic: CNTRLPLANE-3554 — HyperShift Contextification — Repo Context Files
• Story: CNTRLPLANE-3555 — Add ARCHITECTURE.md to the hypershift repository

Test plan

• File renders correctly on GitHub (plain markdown, no Mermaid)
• All relative links to docs pages resolve correctly

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added comprehensive Architecture documentation detailing design principles, key concepts, core components, and platform support information.

[openshift-merge-bot]

Pipeline controller notification
This repo is configured to use the pipeline controller. Second-stage tests will be triggered either automatically or after lgtm label is added, depending on the repository configuration. The pipeline controller will automatically detect which contexts are required and will utilize /test Prow commands to trigger the second stage.

For optional jobs, comment /test ? to see a list of all defined jobs. To trigger manually all jobs from second stage use /pipeline required command.

This repository is configured in: LGTM mode

[openshift-ci-robot]

@celebdor: This pull request references CNTRLPLANE-3555 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the story to target the "5.0.0" version, but no target version was set.

Details

In response to this:

Summary

• Adds ARCHITECTURE.md to satisfy the HPSTRAT-6 contextification initiative, which requires every active repo to have README.md, CONTRIBUTING.md, AGENTS.md, and ARCHITECTURE.md
• Concise overview (~50 lines) covering purpose, key concepts, core components, design invariants, and platform support
• Links to detailed docs in docs/content/reference/ rather than duplicating content

Jira

• Feature: OCPSTRAT-3200 — [Control Plane] Phase 1: Contextification
• Epic: CNTRLPLANE-3554 — HyperShift Contextification — Repo Context Files
• Story: CNTRLPLANE-3555 — Add ARCHITECTURE.md to the hypershift repository

Test plan

• File renders correctly on GitHub (plain markdown, no Mermaid)
• All relative links to docs pages resolve correctly

🤖 Generated with Claude Code

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: 114f494a-c7af-454e-b2ec-3a173a992c97

📥 Commits

Reviewing files that changed from the base of the PR and between e25a87a and fdfcdb6.

📒 Files selected for processing (1)

• ARCHITECTURE.md

---

📝 Walkthrough

Walkthrough

This pull request adds a new ARCHITECTURE.md file to the HyperShift repository. The document provides an overview of HyperShift's architecture, explaining its role as middleware for hosting OpenShift control planes at scale. It introduces key concepts, documents core components with their directory locations and responsibilities, describes design invariants, lists supported platforms, and includes links to further reading resources.

Suggested reviewers

• csrwng
• cblecker

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Container-Privileges	❌ Error	PR adds Kubernetes manifests with privileged configs: kubelet daemonset (hostPID, hostNetwork, privileged), CSI daemonset (privileged, allowPrivilegeEscalation), and e2e test pod (privileged).	Verify privilege escalation in added manifests has appropriate security justifications and follows least-privilege principles for production.

✅ Passed checks (10 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding ARCHITECTURE.md to the repository root, which is the primary objective of this pull request.
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.
Stable And Deterministic Test Names	✅ Passed	PR adds only ARCHITECTURE.md (documentation). No test files or Ginkgo test patterns modified; check is not applicable to documentation-only changes.
Test Structure And Quality	✅ Passed	Custom check for Ginkgo test quality is not applicable; PR contains only documentation changes (ARCHITECTURE.md) with no test code modifications.
Topology-Aware Scheduling Compatibility	✅ Passed	This PR adds only ARCHITECTURE.md, a documentation-only file. The custom check applies to deployment manifests, operator code, or controllers—none of which are modified in this change.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	New Ginkgo e2e tests show no IPv4-only addresses, proper IPv6-compatible URL building with net.JoinHostPort, and no external connectivity requirements.
No-Weak-Crypto	✅ Passed	PR adds only ARCHITECTURE.md documentation with no code changes. The weak-crypto check is not applicable to documentation-only changes.
No-Sensitive-Data-In-Logs	✅ Passed	ARCHITECTURE.md contains no passwords, tokens, API keys, PII, session IDs, or customer data; only architectural documentation with descriptive references to credentials.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: celebdor
Once this PR has been reviewed and has the lgtm label, please assign cblecker for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 41.44%. Comparing base (e25a87a) to head (fdfcdb6).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #8668   +/-   ##
=======================================
  Coverage   41.44%   41.44%           
=======================================
  Files         756      756           
  Lines       93644    93644           
=======================================
  Hits        38807    38807           
  Misses      52114    52114           
  Partials     2723     2723           

Flag	Coverage Δ
cmd-support	34.87% <ø> (ø)
cpo-hostedcontrolplane	43.50% <ø> (ø)
cpo-other	42.79% <ø> (ø)
hypershift-operator	51.56% <ø> (ø)
other	31.64% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[bryan-cox]

/hold

For internal discussion if we need this or not

[openshift-ci]

@celebdor: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.

[enxebre]

/lgtm

[openshift-merge-bot]

Pipeline controller notification

No second-stage tests were triggered for this PR.

This can happen when:

• The changed files don't match any pipeline_run_if_changed patterns
• All files match pipeline_skip_if_only_changed patterns
• No pipeline-controlled jobs are defined for the main branch

Use /test ? to see all available tests.

[bryan-cox]

/hold cancel