docs: scope the architecture diagram to the operator path

[renecannao]

The Architecture at a glance diagram sits directly under the table advertising three Helm charts, so it reads as though it explains all three. It does not — it shows only the operator path:

• ProxySQLCluster reconciling into a StatefulSet, Services, Secrets and a PDB
• ProxySQLConfig pushing SQL to the admin port

Neither standalone chart has a CRD, a controller, or a SQL push anywhere in it, so a reader following the table into the diagram comes away with the wrong model of charts/proxysql and charts/proxysql-cluster.

What this changes

Docs only — one file, +14/−1. No code, charts or CRDs touched.

• retitles the section to "Architecture at a glance — the operator path"
• adds two clarifications beneath the diagram:
  • it is the operator path only; the standalone charts render proxysql.cnf from their Helm values into a ConfigMap (charts/proxysql) or a Secret (charts/proxysql-cluster), read on first start
  • the SQL push targets every replica rather than one, linking to the existing rationale in docs/architecture.md

Verification

Each claim was checked against the code rather than the prose:

Claim	Evidence
charts/proxysql uses a ConfigMap	charts/proxysql/templates/configmap.yaml — kind: ConfigMap, key proxysql.cnf
charts/proxysql-cluster uses a Secret	charts/proxysql-cluster/templates/secret-cnf.yaml — kind: Secret, same key; its own header notes the rendered cnf embeds the admin/radmin/monitor passwords
standalone charts read the cnf on first start	neither passes --reload, unlike operator/internal/controller/builders/statefulset.go:357
cluster sync is a backstop, not the mechanism	proxysqlcluster_controller_test.go:142 asserts replicas=3 populates proxysql_servers, while the operator still writes to all

The two standalone charts genuinely differ from each other here — ConfigMap vs Secret — which is easy to flatten into "a ConfigMap" if writing from memory.

Why

Raised by a reader who hit exactly this ambiguity: having read the three-chart table, they expected the diagram to cover all three and asked what it actually referred to.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified the operator architecture and standalone deployment flow.
  • Documented how standalone charts generate configuration from Helm values.
  • Explained SQL configuration delivery to replicas and the role of cluster synchronization.
  • Added a link to the design rationale.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yml

Review profile: CHILL

Plan: Pro Plus

Run ID: c455459a-5b3e-4b70-a9e5-d0981d246563

📥 Commits

Reviewing files that changed from the base of the PR and between ce17a8a and 8370a51.

📒 Files selected for processing (1)

• README.md

---

📝 Walkthrough

Walkthrough

The README now distinguishes the operator reconciliation path from standalone chart deployments. It documents standalone configuration rendering, direct SQL writes to replicas, cluster-sync fallback, and the related design rationale.

Changes

Architecture documentation

Layer / File(s)	Summary
Architecture path and configuration clarifications README.md	The architecture heading identifies the operator path. The documentation explains standalone chart behavior, configuration rendering, per-replica SQL writes, cluster-sync fallback, and the related design rationale.

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

Possibly related PRs

• ProxySQL/proxysql-on-k8s#1: Documents standalone Helm charts that bypass the operator and render proxysql.cnf from values.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main documentation change: limiting the architecture diagram to the operator path.
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
• Commit unit tests in branch docs/clarify-architecture-diagram-scope

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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