docs: architecture diagram

[adityachoudhari26]

Summary by CodeRabbit

• Documentation
  • Added comprehensive architecture documentation covering the orchestration flow from deployment version registration through job dispatch and results processing.
  • Added detailed workspace-engine service documentation describing the release processing workflow and controller chain.
  • New "Architecture" section added to documentation navigation for easier access.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces two new developer-facing architecture documents explaining the ctrlplane orchestration system. The overview page illustrates the end-to-end flow from CLI version registration to job completion, while the workspace-engine guide details the core Postgres-backed controller orchestration. Navigation configuration is updated to surface these new pages under an "Architecture" tab.

Changes

Architecture Documentation

Layer / File(s)	Summary
System Overview Architecture docs/architecture/overview.mdx	End-to-end orchestration flow from API registration through Postgres work queue, engine controller leasing, job dispatch to agents, webhook result handling, and follow-up work enqueueing. Includes Mermaid flowchart visualizing component interactions and labeled step transitions.
Workspace-Engine Detailed Architecture docs/architecture/workspace-engine.mdx	Comprehensive guide to workspace-engine service, including release-flow controller chain (desired-release → job-eligibility → job-dispatch → job-verification-metric → loop back), insert-then-lease handoff model, stateless reconciliation pattern, detailed desiredrelease policy-gated version selection logic, and responsibilities of each controller stage. Clarifies which controllers are core vs. auxiliary and guides readers on tracing version-push behavior.
Documentation Navigation docs/docs.json	Adds new "Architecture" top-level navigation tab with a "System" group containing links to the overview and workspace-engine documentation pages.

🎯 1 (Trivial) | ⏱️ ~3 minutes

🐰 Two new maps for wandering through the orchestration's grand design,
Where versions dance through Postgres queues in a graceful design.
The overview shows the big picture bright,
While workspace-engine guides deep into the night.
Now seekers can learn how controllers align! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'docs: architecture diagram' is vague and generic; it doesn't accurately reflect that the PR adds comprehensive architecture documentation for the ctrlplane orchestration flow and workspace-engine service, not just a diagram.	Consider a more descriptive title like 'docs: add architecture documentation for orchestration flow and workspace-engine' to better capture the scope of the documentation additions.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch architecture-docs

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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 and usage tips.}

[Copilot]

Pull request overview

Adds a new "Architecture" docs tab with two pages — a system overview and a deep-dive into the workspace-engine — including Mermaid diagrams that explain how releases flow through the reconcile queue.

Changes:

• Register a new "Architecture" tab with a "System" group containing two pages in docs/docs.json.
• Add docs/architecture/overview.mdx describing the high-level orchestration loop between web/api/engine/agents.
• Add docs/architecture/workspace-engine.mdx describing controllers, the release-flow chain, and the desiredrelease internals.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
docs/docs.json	Adds the Architecture tab and its two pages to the docs navigation.
docs/architecture/overview.mdx	New high-level system overview with a Mermaid flowchart.
docs/architecture/workspace-engine.mdx	New deep-dive on the workspace-engine controllers and release flow.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🤖 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/workspace-engine.mdx`:
- Line 8: Change the misspelled word "enqueueing" to "enqueuing" in the sentence
"and runs the matching controller. Each controller's output is enqueueing more"
so the line reads "... Each controller's output is enqueuing more" (search for
the phrase containing "enqueueing" in workspace-engine.mdx to locate the
occurrence).

🪄 Autofix (Beta)

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: Pro

Run ID: 48a38f18-2817-47cb-8565-2a5198ff08a0

📥 Commits

Reviewing files that changed from the base of the PR and between 96a87ca and 109e347.

📒 Files selected for processing (3)

• docs/architecture/overview.mdx
• docs/architecture/workspace-engine.mdx
• docs/docs.json

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix spelling at Line 8 (enqueueing → enqueuing).

This is a user-facing docs typo and should be corrected for consistency.

🧰 Tools

🪛 LanguageTool

[grammar] ~8-~8: Ensure spelling is correct
Context: ...controller. Each controller's output is enqueueing more work, so a single release moves th...

(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)

🤖 Prompt for 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.

In `@docs/architecture/workspace-engine.mdx` at line 8, Change the misspelled word
"enqueueing" to "enqueuing" in the sentence "and runs the matching controller.
Each controller's output is enqueueing more" so the line reads "... Each
controller's output is enqueuing more" (search for the phrase containing
"enqueueing" in workspace-engine.mdx to locate the occurrence).