OAPE-815: Add ARCHITECTURE.md and CONTRIBUTING.md for contextification

[PillaiManish]

Summary

Adds Level 1 repo-level context documentation as part of the Track 1: Contextification initiative (OAPE-815). These files fulfill the repo-level expected files requirement, helping both humans and AI agents understand the codebase structure and contribution workflow.

Files Added

• ARCHITECTURE.md — Describes the high-level architecture following the matklad ARCHITECTURE.md style:

  • Bird's eye view of what the operator does
  • Upstream SPIFFE/SPIRE components and how they interact
  • Code map with architecture invariants for each major directory
  • Cross-cutting concerns (reconciliation pattern, status conditions, image configuration, build system, testing)

• CONTRIBUTING.md — Practical guide for new contributors:

  • Prerequisites and repository setup
  • Development workflow with Makefile targets
  • Code organization conventions
  • Linting and testing expectations
  • Pull request process and code review workflow (OWNERS, Prow commands)

Motivation

The Contextification initiative requires every repository to have four standard files: README.md, CONTRIBUTING.md, AGENTS.md, and ARCHITECTURE.md. This PR adds the two that were missing (ARCHITECTURE.md and CONTRIBUTING.md). README.md already exists with adequate content.

Test Plan

• Verify markdown renders correctly on GitHub
• Review technical accuracy of architecture descriptions against current codebase
• Confirm contributing workflow steps match actual CI/build behavior

Made with Cursor

Summary by CodeRabbit

• Documentation
  • Added a new architecture guide describing the product’s high-level design, core components, key behavior rules, repository layout, and testing approach.
  • Added a contributor guide with setup requirements, development workflow, verification steps, test instructions, and pull request guidance.

[openshift-ci-robot]

@PillaiManish: This pull request references OAPE-815 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 sub-task to target the "5.0.0" version, but no target version was set.

Details

In response to this:

Summary

Adds Level 1 repo-level context documentation as part of the Track 1: Contextification initiative (OAPE-815). These files fulfill the repo-level expected files requirement, helping both humans and AI agents understand the codebase structure and contribution workflow.

Files Added

• ARCHITECTURE.md — Describes the high-level architecture following the matklad ARCHITECTURE.md style:

• Bird's eye view of what the operator does

• Upstream SPIFFE/SPIRE components and how they interact

• Code map with architecture invariants for each major directory

• Cross-cutting concerns (reconciliation pattern, status conditions, image configuration, build system, testing)

• CONTRIBUTING.md — Practical guide for new contributors:

• Prerequisites and repository setup

• Development workflow with Makefile targets

• Code organization conventions

• Linting and testing expectations

• Pull request process and code review workflow (OWNERS, Prow commands)

Motivation

The Contextification initiative requires every repository to have four standard files: README.md, CONTRIBUTING.md, AGENTS.md, and ARCHITECTURE.md. This PR adds the two that were missing (ARCHITECTURE.md and CONTRIBUTING.md). README.md already exists with adequate content.

Test Plan

• Verify markdown renders correctly on GitHub
• Review technical accuracy of architecture descriptions against current codebase
• Confirm contributing workflow steps match actual CI/build behavior

Made with Cursor

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.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository: openshift/coderabbit/.coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ea3d64ce-6cc5-4b74-ac69-edfbae304d87

📥 Commits

Reviewing files that changed from the base of the PR and between 6a7cb74 and a481b78.

📒 Files selected for processing (2)

• ARCHITECTURE.md
• CONTRIBUTING.md

---

Walkthrough

Two new documentation files are added: ARCHITECTURE.md describes the operator's high-level design, component interactions, code map, reconciliation pattern, and build/test tooling; CONTRIBUTING.md provides contribution prerequisites, development workflow, code organization conventions, linting/testing guidance, and PR process.

Changes

Project Documentation

Layer / File(s)	Summary
Operator architecture ARCHITECTURE.md	Describes the operator as a controller-runtime single-binary, documents SPIFFE/SPIRE component interactions, maps the repository layout, explains reconciliation and condition semantics, image configuration via env vars, and build/test tooling.
Contribution guide CONTRIBUTING.md	Covers prerequisites, repo setup, make-based development workflow, code organization conventions, linting, unit/E2E testing, PR process, Prow-based code review commands, and issue reporting.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

🚥 Pre-merge checks | ✅ 15

✅ Passed checks (15 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and accurately summarizes the main change: adding ARCHITECTURE.md and CONTRIBUTING.md for contextification.
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.
Stable And Deterministic Test Names	✅ Passed	PR only adds docs; no Ginkgo tests or test titles were introduced or modified.
Test Structure And Quality	✅ Passed	PR only adds ARCHITECTURE.md and CONTRIBUTING.md; no Ginkgo tests or cluster-interaction code changed, so this check is not applicable.
Microshift Test Compatibility	✅ Passed	PR adds only ARCHITECTURE.md and CONTRIBUTING.md; no new Ginkgo e2e tests or API-using code were introduced.
Single Node Openshift (Sno) Test Compatibility	✅ Passed	This commit only adds ARCHITECTURE.md and CONTRIBUTING.md; no Ginkgo e2e tests or test files were changed, so the SNO check is not applicable.
Topology-Aware Scheduling Compatibility	✅ Passed	Only ARCHITECTURE.md and CONTRIBUTING.md were added; no manifests, controllers, or operator code changed, so the topology-aware scheduling check is not applicable.
Ote Binary Stdout Contract	✅ Passed	PR delta only adds ARCHITECTURE.md and CONTRIBUTING.md; no process-level code or stdout writes were changed.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	PR only adds ARCHITECTURE.md and CONTRIBUTING.md; no Ginkgo/e2e test code or network-dependent tests were introduced.
No-Weak-Crypto	✅ Passed	The added docs contain no weak-crypto APIs, custom crypto code, or secret comparisons; searches of ARCHITECTURE.md and CONTRIBUTING.md found none.
Container-Privileges	✅ Passed	PR only adds markdown docs; neither file includes privileged/hostNetwork/etc, and no workspace diff touches container manifests.
No-Sensitive-Data-In-Logs	✅ Passed	Only ARCHITECTURE.md and CONTRIBUTING.md were added; they contain no log statements or sensitive fields, just general contributor guidance.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[openshift-ci]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: PillaiManish
Once this PR has been reviewed and has the lgtm label, please assign nhegde07 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

[openshift-ci]

@PillaiManish: 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.