docs(gateway): rewrite gateway architecture spec

[renuka-fernando]

Purpose

The previous gateway/spec/architecture/architecture.md had drifted from the current shape of the gateway — it conflated the Gateway Controller with the Platform API as a single "control plane," under-documented the build-time vs deploy-time split, and omitted several flows that are load-bearing in practice (per-chain body mode, multi-gateway DB scoping, custom policy advertisement, deployment acknowledgement). This PR rewrites the spec so a new contributor or operator can read it top-to-bottom and end up with an accurate mental model of the gateway as it actually runs today.

Goals

• Make the Data Plane vs Control Plane distinction explicit and correct: the gateway is a Data Plane product; the Platform API is the (optional) Control Plane; the Gateway Controller is an internal control plane within the Data Plane.
• Document the architectural invariants that take multiple files to discover (zero-built-in-policy engine, two-image matched-version pair from the builder, two distinct xDS servers, gateway_id-scoped multi-gateway DB sharing, EventHub DB-poll sync, immutable mode semantics).
• Cover Platform-API integration end-to-end: authentication, REST + WebSocket channels, custom policy manifest sync, deployment acknowledgement, startup reconciliation.
• Add a dedicated subsection describing the customer-managed policy flow — how the manifest is tagged with managedBy, how system policies are filtered out, and how the Console-triggered sync promotes entries into the org-scoped attachment catalogue.

Approach

• Rewrite gateway/spec/architecture/architecture.md end-to-end (Document Version bumped to 2.0).
• Restructure top-level sections: Overview → Top-Level Architecture → Components → xDS Streams → Request Lifecycle → Configuration → Deployment Modes → HA → Observability → Key Architectural Decisions → Versioning.
• Add Mermaid diagrams for: top-level data-plane/control-plane layout, multi-gateway DB scoping, three-process runtime container, builder pipeline, xDS channels, request lifecycle, Platform-API integration, HA topology.
• Add a new #### Custom Policy Sync subsection under Platform-API Control Plane Mode documenting managedBy tagging, system-policy filtering at the gateway, manifest persistence on the platform side, and the Console-triggered POST /api/v1/gateway-custom-policies/sync promotion step.
• Bump document Last Updated to 2026-05-20.

User stories

• As a new contributor, I can read one document and understand how the gateway is composed at build time and at deploy time, without grepping the source tree.
• As an operator, I can identify which components are Data Plane vs Control Plane, what state is shared via the database, and how multiple gateways can safely share one PostgreSQL.
• As a Platform-API integrator, I can see exactly what the gateway sends on the manifest push, what is filtered, and what triggers a custom policy becoming attachable in the Console.

Documentation

N/A — this PR is the documentation. The file updated is the in-repo architecture spec at gateway/spec/architecture/architecture.md; no external doc site change is required.

Automation tests

• Unit tests

  N/A — documentation-only change.

• Integration tests

  N/A — documentation-only change.

Security checks

• Followed secure coding standards in http://wso2.com/technical-reports/wso2-secure-engineering-guidelines? yes (no code changed)
• Ran FindSecurityBugs plugin and verified report? N/A — no code changed
• Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets? yes

Samples

N/A

Related PRs

N/A

Test environment

N/A — documentation-only change. Mermaid diagrams rendered locally to verify they parse.

[coderabbitai]

📝 Walkthrough

Summary

This pull request rewrites the gateway architecture specification document (Document Version 2.0) to align it with the current Envoy-based implementation and serve as a comprehensive reference for contributors, operators, and Platform-API integrators.

Key Changes

Architecture Clarification:

• Establishes explicit Data Plane vs Control Plane distinction: Gateway as Data Plane, Platform API as optional external Control Plane, and Gateway Controller as internal control plane
• Documents core architectural invariants including zero built-in policy engine, matched-version image pairs from the builder, dual xDS servers, and immutable mode semantics

Components Documentation:

• Gateway Controller: REST management APIs, admin/debug endpoints, Envoy SotW xDS server, Policy xDS server, persistence model (SQLite default, PostgreSQL for HA), and multi-replica synchronization via DB-backed event hub
• Gateway Runtime: OCI image with entrypoint-managed trio (Envoy Router, Go Policy Engine, optional Python Executor), request/chain body buffering behavior, policy chain execution flow, and build-time policy compilation
• Gateway Builder: Six-phase pipeline, extend-base-image pattern, and manifest/emission outputs

Platform-API Integration:

• End-to-end coverage including authentication, REST and WebSocket channels, custom policy manifest sync, deployment acknowledgement, and startup reconciliation
• Dedicated Custom Policy Sync subsection documenting managedBy tagging, system-policy filtering, manifest persistence, and Console-triggered promotion to attachment catalogue

Document Restructuring:

• Reorganized with expanded sections: Overview, Top-Level Architecture, Components, xDS Streams, Request Lifecycle, Configuration, Deployment Modes, High Availability, Observability, Key Architectural Decisions, and Versioning
• Added layered configuration model, artifact templating/secrets handling, mutable vs immutable mode behavior, Kubernetes operator integration flows
• Added multiple Mermaid diagrams: data-plane/control-plane layout, multi-gateway DB scoping, three-process runtime container, builder pipeline, xDS channels, request lifecycle, Platform-API integration, and HA topology

Metadata:

• Document Last Updated: 2026-05-20
• Lines changed: +552/-99
• No code or tests modified; diagrams verified locally

Walkthrough

This pull request comprehensively rewrites the API Platform Gateway architecture specification to document a policy-centric, xDS-driven control plane model. The document is reorganized to describe the Gateway Controller (control plane) with REST APIs, xDS servers, and persistence; the Gateway Runtime (data plane) as an OCI image with Envoy, a Go Policy Engine, and optional Python executor; and the Gateway Builder's build pipeline. It expands documentation of the xDS communication contract, per-request lifecycle execution, configuration templating with AES-GCM encryption, and deployment modes including mutable/immutable behavior and Platform-API integration. The specification concludes with high-availability patterns, observability mechanisms, key architectural decisions, and versioning/compatibility rules.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs(gateway): rewrite gateway architecture spec' accurately and concisely describes the main change—a comprehensive rewrite of the gateway architecture documentation.
Description check	✅ Passed	The PR description thoroughly addresses all template sections relevant to a documentation-only change, including clear Purpose, Goals, Approach, User stories, and appropriate 'N/A' entries for testing and samples.
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

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

gateway/spec/architecture/architecture.md (1)

460-460: ⚡ Quick win

Track this TODO with a concrete issue reference.

Please replace this inline TODO with a linked issue (or add the issue ID next to it) so the missing event-gateway/spec/architecture/architecture.md work is discoverable and auditable in planning/release flows.

Would you like me to draft the issue body and acceptance criteria for this follow-up?

🤖 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 `@gateway/spec/architecture/architecture.md` at line 460, Replace the inline
TODO line about the missing architecture doc with a link/reference to a concrete
issue (e.g., add the issue number or URL next to the TODO) so the work is
tracked; specifically update the TODO text in
gateway/spec/architecture/architecture.md to include the created issue ID or URL
for "event-gateway/spec/architecture/architecture.md" and, if desired, add a
short one-line summary or acceptance criteria in the comment to make the
tracking entry discoverable in planning and release flows.

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

Nitpick comments:
In `@gateway/spec/architecture/architecture.md`:
- Line 460: Replace the inline TODO line about the missing architecture doc with
a link/reference to a concrete issue (e.g., add the issue number or URL next to
the TODO) so the work is tracked; specifically update the TODO text in
gateway/spec/architecture/architecture.md to include the created issue ID or URL
for "event-gateway/spec/architecture/architecture.md" and, if desired, add a
short one-line summary or acceptance criteria in the comment to make the
tracking entry discoverable in planning and release flows.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 51be8e1d-b37f-4086-8c47-87e89304747b

📥 Commits

Reviewing files that changed from the base of the PR and between 38fd18b and a4168aa.

📒 Files selected for processing (1)

• gateway/spec/architecture/architecture.md