PackageRevision controller architecture docs (#971)

* docs: add PackageRevision controller architecture docs (draft)

Add v1alpha2 architecture documentation for the PackageRevision controller
as Hugo draft pages. These render in deploy previews but are hidden from
the production build.

New pages:
- deployment-modes.md: v1alpha1 vs v1alpha2 architecture comparison
- packagerevision-controller/_index.md: controller overview
- packagerevision-controller/design.md: internal design
- packagerevision-controller/interactions.md: component interactions

Also adds docs/config/development.toml (buildDrafts=true) and
docs/config/production.toml so the existing Netlify build command
picks up environment-specific settings.

* Rewrite and restructuring

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* Address copilot comments

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* Fix netlify build

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

* Address review comments

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

---------

Signed-off-by: Fiachra Corcoran <fiachra.corcoran@est.tech>

Author: efiacor

README.md

@@ -10,7 +10,7 @@ project as of December 2023.
 
 ## Documentation
 
-Documentation of Porch is available in the [Porch documentation page](https://docs.porch.nephio.org/).
+Documentation of Porch is available in the [Porch documentation page](https://porch.kpt.dev/).
 
 ## License compliance
 

docs/README.md

@@ -1,3 +1,3 @@
 # Docs
 
-The documentation was moved to the [kpt Porch repo](https://github.com/kptdev/porch/tree/main/docs/content/en/docs) and rendered in the [Porch documentation page](https://docs.nephio.org/docs/porch/). 
+The documentation was moved to the [kpt Porch repo](https://github.com/kptdev/porch/tree/main/docs/content/en/docs) and rendered on the [Porch documentation page](https://porch.kpt.dev/). 

docs/assets/scss/_main.scss

@@ -58,6 +58,16 @@ p {
 	.td-main main {
 		padding-top: 5rem;
 	}
+
+	// Ensure the three-column layout flexes properly when sidebar is resized.
+	.td-main > .row {
+		flex-wrap: nowrap;
+	}
+	.td-main main.col-12 {
+		flex: 1 1 0;
+		min-width: 0;
+	}
+
 	.td-box .row {
 		padding-left: 0vw;
 		padding-right: 0vw;

docs/assets/scss/_sidebar-left.scss

@@ -1,21 +1,38 @@
-// Sidebar left.
+// Sidebar left: wider default + resizable.
 .td-sidebar {
 	padding-bottom: 20px;
 	padding-top: 1rem;
 	background-color: $td-sidebar-bg-color;
 
-	.td-sidebar-version {
-		padding-top: 0.5rem;
-		padding-bottom: 0.5rem;
-		border-bottom: 1px solid #ddd;
+	@media (min-width: 768px) {
+		min-width: 200px;
+		width: var(--td-sidebar-width, 300px);
+		max-width: 50vw;
+		flex: 0 0 var(--td-sidebar-width, 300px) !important;
+		position: relative;
 
-		.td-version-menu {
-			.nav-link {
-				color: $black;
-				padding: 0.25rem 0;
-				font-size: 1rem;
-				font-weight: 600;
-			}
+		// Override Bootstrap column max-width constraints.
+		&.col-md-3,
+		&.col-xl-2 {
+			max-width: none;
+		}
+	}
+
+	// Drag handle for resizing.
+	.td-sidebar-resize-handle {
+		position: absolute;
+		top: 0;
+		right: -3px;
+		width: 6px;
+		height: 100%;
+		cursor: col-resize;
+		z-index: 100;
+		background: transparent;
+		transition: background 0.15s;
+
+		&:hover,
+		&.dragging {
+			background: rgba($primary, 0.3);
 		}
 	}
 	.td-sidebar__inner {
@@ -24,104 +41,32 @@
 		}
 	}
 
+	// Version selector: more prominent with top padding.
+	.td-version-menu {
+		padding-top: 0.75rem;
+		padding-bottom: 0.5rem;
+		padding-left: 1rem;
+
+		.td-version-menu__title {
+			font-weight: 700;
+			font-size: 1.1rem;
+			color: $black;
+			padding: 0;
+		}
+	}
+
 	// Navigation in Left-sidebar.
 	.td-sidebar-nav {
 		@media (min-width: 768px) {
 			@supports ((position: -webkit-sticky) or (position: sticky)) {
-				// shadow overflow.
-				background: linear-gradient(#f4f4f4 33%, rgba(255, 255, 255, 0)),
-					linear-gradient(rgba(255, 255, 255, 0), #f4f4f4 66%) 0 100%,
-					radial-gradient(farthest-side at 50% 0, rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0)),
-					radial-gradient(farthest-side at 50% 100%, rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0)) 0 100%;
-				background-color: #f4f4f4;
-				background-repeat: no-repeat;
-				background-attachment: local, local, scroll, scroll;
-				background-size: 100% 57px, 100% 57px, 100% 19px, 100% 19px;
 				max-height: calc(100vh - 12.5rem);
+				overflow-y: auto;
 			}
 		}
 		@media (min-width: 1024px) {
 			@supports ((position: -webkit-sticky) or (position: sticky)) {
 				max-height: calc(100vh - 14rem);
 			}
 		}
-
-		> .td-sidebar-nav__section {
-			padding-left: 1.5rem;
-
-			ul {
-				padding-left: 0.5rem !important;
-			}
-		}
-		.td-sidebar-nav__section-title {
-			margin-bottom: 5px;
-			> ul {
-				margin-top: 5px;
-
-				.td-sidebar-nav__section-title.with-child {
-					> a {
-						position: relative;
-						display: flex;
-						justify-content: space-between;
-						padding-right: 20px;
-						&::after {
-							display: inline-flex;
-							content: '\f078';
-							font-family: 'Font Awesome 6 Free';
-							font-weight: 900;
-						}
-					}
-					&.active-path {
-						> a {
-							&::after {
-								transform: rotate(180deg);
-							}
-						}
-					}
-					ul.foldable {
-						margin-left: 10px;
-					}
-				}
-			}
-			// Same name but this is a child of the same.
-			.td-sidebar-nav__section-title {
-				margin-right: 15px;
-				@media (min-width: 768px) {
-					margin-right: 0;
-				}
-			}
-			.td-sidebar-link {
-				// Style.
-				font-weight: 700;
-				font-size: 16px;
-				line-height: 150%;
-				letter-spacing: 0.02em;
-				color: $black;
-				// Spacing.
-				display: flex;
-				padding-top: 8px;
-				padding-bottom: 8px;
-				border-radius: 5px;
-				border-left: 4px solid transparent;
-				filter: drop-shadow(0px 0px 5px rgba(0, 0, 0, 0));
-				span {
-					padding-left: 10px;
-					padding-right: 20px;
-				}
-				&:hover {
-					color: $link-color;
-				}
-				&.active {
-					background-color: #eee;
-					filter: drop-shadow(0px 0px 5px rgba(0, 0, 0, 0.05));
-				}
-				@media (min-width: 768px) {
-					&.active {
-						background-color: #f8f8f8;
-					}	
-				}
-
-			}
-		}
 	}
 }

docs/assets/scss/_sidebar-toc.scss

@@ -8,13 +8,16 @@
 	@supports (position: sticky) {
 		position: sticky;
 		top: 4rem;
-		height: calc(100vh - 6rem);
+		height: calc(100vh - 4rem);
 		overflow-y: auto;
+		align-self: flex-start;
 	}
 
 	order: 2;
 	padding-bottom: 1.5rem;
 	vertical-align: top;
+	flex: 0 0 200px;
+	min-width: 160px;
 }
 
 .td-page-meta {

docs/config.toml

@@ -36,11 +36,6 @@ pygmentsStyle = "tango"
     [markup.goldmark.parser]
       [markup.goldmark.parser.attribute]
         title = true
-    [markup.goldmark.renderer.headingAnchor]
-      enable = true
-      prefix = ""
-      suffix = ""
-      plainID = true
 
   [markup.highlight]
     style = "tango"
@@ -128,6 +123,7 @@ footer_about_disable = true
 navbar_logo = true
 navbar_translucent_over_cover_disable = false
 sidebar_menu_compact = true
+sidebar_menu_foldable = true
 sidebar_search_disable = false
 
 # Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.

docs/config/development.toml

@@ -0,0 +1,3 @@
+# Development/preview environment overrides
+# Enables draft content in deploy previews and branch deploys
+buildDrafts = true

docs/config/production.toml

@@ -0,0 +1,3 @@
+# Production environment overrides
+# Drafts are excluded by default (Hugo's default behavior)
+# This file exists so the Netlify build command doesn't warn about a missing config merge

docs/content/en/docs/12_contributing/docs-contribution/_index.md

@@ -248,6 +248,35 @@ To add a new top-level section:
 3. Set appropriate `weight` in front matter
 4. Add content files as needed
 
+### Documenting Unreleased Features
+
+When documenting a feature that isn't ready for public release, use Hugo's draft mechanism to keep pages out of the production site while still allowing review in deploy previews.
+
+Add `draft: true` to the page's front matter:
+
+```yaml
+---
+title: "New Feature"
+type: docs
+draft: true
+---
+```
+
+Draft pages are excluded from production builds but included in Netlify deploy previews (pull request previews). This is controlled by environment-specific config files:
+
+- `docs/config/production.toml` — default Hugo behavior (no drafts)
+- `docs/config/development.toml` — sets `buildDrafts = true`
+
+Netlify sets `HUGO_ENV=production` for the main deploy and `HUGO_ENV=development` for deploy previews, so draft pages automatically appear in PR previews and stay hidden on the live site.
+
+To preview drafts locally:
+
+```bash
+hugo server -D
+```
+
+When the feature is ready to publish, remove `draft: true` from the front matter and add any navigation links (e.g. references from parent `_index.md` pages) in the same commit. Avoid adding `relref` links to draft pages from non-draft pages — Hugo will fail the production build with a broken link error.
+
 ## Review Process
 
 Documentation PRs are reviewed by maintainers. Expect feedback on:

docs/content/en/docs/1_overview/_index.md

@@ -3,7 +3,7 @@ title: "Overview"
 type: docs
 weight: -1
 description: >
-  Porch is a Kubernetes extension apiserver for managing the lifecycle of KRM configuration packages in Git repositories. It provides a Kubernetes-native API for package operations, enabling GitOps workflows with approval gates, automation, and collaboration.
+  Porch is a Kubernetes-based system for managing the lifecycle of KRM configuration packages stored in Git repositories. It exposes package operations as Kubernetes resources, enabling GitOps workflows with approval gates, automation, and collaboration.
 ---
 
 Porch (Package Orchestration Server) is part of the [kpt project](https://github.com/kptdev/kpt). The name "Porch" is short for "Package ORCHestration."
@@ -66,12 +66,20 @@ Porch sits between package authors and deployment tools, providing the orchestra
 
 ## Architecture
 
-Porch consists of four main deployable components.
+Porch consists of three main deployable components.
 
-The **Porch Server** is a Kubernetes aggregated apiserver that exposes the PackageRevision and Repository APIs. It includes the Engine (orchestration logic), the Cache (repository content), and Repository Adapters that abstract Git backends.
+The **Porch Server** is a Kubernetes aggregated apiserver that serves the `porch.kpt.dev/v1alpha1` API PackageRevision, PackageRevisionResources, and Package resources. It includes the Engine (orchestration logic), the Cache (repository content), and Repository Adapters that abstract Git backends. As the architecture evolves toward the CRD-based model, the server will remain, and continue to serve PackageRevisionResources (PRR) package file content that can exceed etcd size limits and provides the v1alpha1 API for existing PackageRevisionResources (PRR) clients.
 
 The **Function Runner** is a separate gRPC service that runs KRM functions in containers. It can execute both functions provided by Porch and externally developed function images.
 
-**Controllers** are Kubernetes controllers that automate package operations. The PackageVariant controller clones and updates packages; the PackageVariantSet controller manages sets of package variants.
+The **Controllers** are a set of Kubernetes controllers that manage package lifecycle and automate operations:
+
+- [**PackageRevision Controller**]({{% relref "/docs/5_architecture_and_components/controllers/packagerevision-controller" %}}) — manages PackageRevision custom resources (`porch.kpt.dev/v1alpha2`), handling package creation, rendering, and lifecycle transitions.
+- [**Repository Controller**]({{% relref "/docs/5_architecture_and_components/controllers/repository-controller" %}}) — synchronizes Repository custom resources with their backing Git repositories.
+- [**PackageVariant Controllers**]({{% relref "/docs/5_architecture_and_components/controllers/packagevariants" %}}) — automate creation and management of package variants through declarative configuration.
 
 The **Cache** is a storage backend used to cache repository content for performance. Porch supports a CR-based cache backed by Kubernetes custom resources, or a PostgreSQL-based cache for larger deployments.
+
+{{% alert title="Architecture Direction" color="info" %}}
+Porch is transitioning from an aggregated API model (where the API server orchestrates all operations) to a CRD-based controller model (where native Kubernetes CRDs and controllers handle package lifecycle). The aggregated API server remains for serving PackageRevisionResources content.
+{{% /alert %}}