Code documentation

internal/platform/config/config.go

@@ -1,3 +1,37 @@
+// Package config
+// Path: /internal/platform/config
+// File: config.go
+//
+// Purpose
+//   Provide a safe one-time initialization and global access point for
+//   the application's Config object, once it has been constructed during
+//   bootstrap.
+//
+//   This allows other packages to retrieve configuration without needing
+//   dependency injection at every call site, while still preventing
+//   accidental mutation after init.
+//
+// Responsibilities (as implemented here)
+//   1) Store a single *Config instance for the lifetime of the process.
+//   2) Ensure Init() can only succeed once via sync.Once.
+//   3) Expose Get() as a global accessor.
+//
+// Design notes
+//   - Config is written once at startup via Init() inside bootstrap.
+//   - Calls to Init() after the first are ignored silently.
+//   - Get() may return nil if called before Init() — caller must ensure
+//     bootstrap has completed.
+//
+// TODOs (from current architectural direction)
+//   - Evaluate replacing global access with explicit dependency injection
+//     in future modules for stronger compile-time guarantees.
+//   - Consider panicking or logging if Get() is called before Init().
+//   - Move non-static configuration into runtime struct(s) owned by App.
+//   - Ensure immutability: avoid mutating Config fields after Init().
+//
+// Change log
+//   [2025-10-28] Documentation aligned with real runtime responsibilities.
+
 package config
 
 import (