Adding more comprehensive package documentation

Author: fernando-villalba

pkg/cluster-handler/controller/multigrescluster/doc.go

@@ -0,0 +1,28 @@
+// Package multigrescluster implements the controller for the root MultigresCluster resource.
+//
+// The MultigresCluster controller acts as the central orchestrator for the database system.
+// It is responsible for translating the high-level user intent into specific child resources.
+// Its primary responsibilities include:
+//
+//  1. Global Component Management:
+//     It directly manages singleton resources defined at the cluster level, such as the
+//     Global TopoServer (via a child TopoServer CR) and the MultiAdmin deployment.
+//
+//  2. Resource Fan-Out (Child CR Management):
+//     It projects the configuration defined in the MultigresCluster spec (Cells and Databases)
+//     into discrete child Custom Resources (Cell and TableGroup). These child resources are
+//     then reconciled by their own respective controllers.
+//
+//  3. Template Resolution:
+//     It leverages the 'pkg/resolver' module to fetch CoreTemplates, CellTemplates, and
+//     ShardTemplates, merging them with user-defined overrides to produce the final
+//     specifications for child resources.
+//
+//  4. Status Aggregation:
+//     It continually observes the status of its child resources to produce a high-level
+//     summary of the cluster's health (e.g., "All cells ready", "Database X has Y/Z shards ready").
+//
+//  5. Lifecycle Management:
+//     It utilizes finalizers to ensure that all child resources are gracefully terminated
+//     and cleaned up before the parent MultigresCluster is removed.
+package multigrescluster

pkg/cluster-handler/controller/tablegroup/doc.go

@@ -0,0 +1,23 @@
+// Package tablegroup implements the controller for the TableGroup resource.
+//
+// The TableGroup controller acts as a "middle-manager" in the Multigres hierarchy,
+// sitting between the root MultigresCluster and the leaf Shard resources.
+//
+// Responsibilities:
+//
+//  1. Shard Lifecycle Management:
+//     It watches TableGroup resources and creates, updates, or deletes (prunes)
+//     child Shard resources to match the list of fully resolved shard specifications
+//     provided in the TableGroup spec.
+//
+//  2. Status Aggregation:
+//     It monitors the status of all owned Shards and aggregates them into the
+//     TableGroup's status (e.g., ReadyShards / TotalShards), providing a summarized
+//     view for the parent MultigresCluster controller.
+//
+// Design Note:
+// This controller is intentionally "dumb" regarding configuration logic. It does not
+// perform template resolution or defaulting. It expects fully resolved specs to be
+// pushed down from the parent MultigresCluster controller, and its only job is to
+// enforce that state on the child Shards.
+package tablegroup

pkg/resolver/doc.go

@@ -0,0 +1,47 @@
+// Package resolver provides the central logic for calculating the "Effective Specification" of a MultigresCluster.
+//
+// In the Multigres Operator, a cluster's configuration can come from multiple sources:
+//  1. Inline Configurations (defined directly in the MultigresCluster CR).
+//  2. Template References (pointing to CoreTemplate, CellTemplate, or ShardTemplate CRs).
+//  3. Overrides (partial patches applied on top of a template).
+//  4. Hardcoded Defaults (fallback values for safety).
+//
+// The Resolver is the single source of truth for merging these sources. It ensures that
+// the Reconciler and the Webhook always agree on what the final configuration should be.
+//
+// # Logic Hierarchy
+//
+// When calculating the final configuration for a component, the Resolver applies the
+// following precedence (highest to lowest):
+//
+//  1. Inline Spec (if provided, it ignores templates entirely).
+//  2. Overrides (patches specific fields of the template).
+//  3. Template Spec (the base configuration from the referenced CR).
+//  4. Global Defaults (hardcoded constants like default images or replicas).
+//
+// # Dual Usage
+//
+// This package is designed to be used in two distinct phases:
+//
+//  1. Mutation (Webhook):
+//     The 'PopulateClusterDefaults' method is safe to call during admission. It applies
+//     static defaults (images, explicit template names) to the API object itself,
+//     solving the "Invisible Defaults" problem without making external API calls.
+//
+//  2. Reconciliation (Controller):
+//     The 'Resolve...' and 'Merge...' methods are used during reconciliation. They
+//     fetch external templates from the API server and merge them to determine the
+//     actual state the child resources (StatefulSets, Services) should match.
+//
+// Usage:
+//
+//	// Create a resolver
+//	res := resolver.NewResolver(client, namespace, cluster.Spec.TemplateDefaults)
+//
+//	// Webhook: Apply static defaults to the object
+//	res.PopulateClusterDefaults(cluster)
+//
+//	// Controller: Calculate final config for a specific component
+//	template, err := res.ResolveShardTemplate(ctx, "my-shard-template")
+//	finalConfig := resolver.MergeShardConfig(template, overrides, nil)
+package resolver

pkg/resolver/resolver.go

@@ -1,8 +1,3 @@
-// Package resolver provides the central logic for resolving MultigresCluster
-// defaults, templates, and configurations.
-//
-// It serves as the single source of truth for merging user inputs,
-// cluster-level defaults, and external templates into a final resource specification.
 package resolver
 
 import (