From 8d2ce27a748973ece87d2a283596c5b6550d1e36 Mon Sep 17 00:00:00 2001
From: H3ALY <ross@healy.xyz>
Date: Tue, 28 Oct 2025 22:46:11 +0000
Subject: [PATCH] commented code

---
 cmd/api/main.go | 41 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 37 insertions(+), 4 deletions(-)

diff --git a/cmd/api/main.go b/cmd/api/main.go
index ca7fec4..648e7d4 100644
--- a/cmd/api/main.go
+++ b/cmd/api/main.go
@@ -1,5 +1,33 @@
-// Path /cmd/api
+// Path: /cmd/api
 // File: main.go
+//
+// Purpose
+//   Application entrypoint. Wires the bootstrapped App into HTTP runtime concerns:
+//   - Initializes template helpers with session + site meta
+//   - Mounts global middleware that require *App (Auth, Remember)
+//   - Registers all route groups outside of bootstrap
+//   - Starts the HTTP server and performs graceful shutdown on SIGINT/SIGTERM
+//
+// Responsibilities (as implemented here)
+//   1) Build the application kernel via bootstrap.Load(configPath).
+//   2) Initialize template helpers with SessionManager and site metadata.
+//   3) Attach global middleware that depend on App (Auth first, then Remember).
+//   4) Register route groups (Home, Account, Admin, Syndicate, Statistics).
+//   5) Start http.Server in a goroutine and log the bound address.
+//   6) Block on OS signals and perform a 10s graceful shutdown.
+//
+// Notes (code-accurate)
+//   - Config path uses a backslash; consider using forward slashes or filepath.Join
+//     to be OS-neutral (Go accepts forward slashes cross-platform).
+//   - Middleware order matters and matches the master reference: Auth → Remember
+//     (CSRF is already applied inside bootstrap handler wrapping).
+//   - ListenAndServe error handling correctly ignores http.ErrServerClosed.
+//   - Shutdown uses a fixed 10s timeout; consider making this configurable.
+//
+// TODOs
+//   - Replace panic on bootstrap/startup with structured logging and exit codes.
+//   - Move config path to env/flag for deploy-time configurability.
+//   - If background workers are added, coordinate their shutdown with the same context.
 
 package main
 
@@ -20,25 +48,29 @@ import (
 )
 
 func main() {
+	// Build application kernel (config → DB → schema → sessions → router → CSRF → server)
 	app, err := bootstrap.Load("internal\\platform\\config\\config.json")
 	if err != nil {
 		panic(fmt.Errorf("bootstrap: %w", err))
 	}
 
+	// Initialize template helpers that require session + site metadata
 	templateHelpers.InitSessionManager(app.SessionManager)
 	templateHelpers.InitSiteMeta(app.Config.Site.SiteName, app.Config.Site.CopyrightYearStart, 0)
 
 	// Global middleware that depends on *App
+	// Order is important: AuthMiddleware (idle timeout/last activity) → RememberMiddleware (optional)
 	app.Router.Use(middleware.AuthMiddleware())
-	app.Router.Use(middleware.RememberMiddleware(app))
+	app.Router.Use(middleware.RememberMiddleware(app)) // rotation optional; security hardening TBD
 
-	// Route registration lives OUTSIDE bootstrap
+	// Route registration lives OUTSIDE bootstrap (keeps bootstrap infra-only)
 	routes.RegisterHomeRoutes(app)
 	routes.RegisterAccountRoutes(app)
 	routes.RegisterAdminRoutes(app)
 	routes.RegisterSyndicateRoutes(app)
 	routes.RegisterStatisticsRoutes(app)
 
+	// Start the HTTP server
 	srv := app.Server
 	go func() {
 		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
@@ -48,6 +80,7 @@ func main() {
 
 	fmt.Printf("Server running on http://%s\n", srv.Addr)
 
+	// Graceful shutdown on SIGINT/SIGTERM
 	stop := make(chan os.Signal, 1)
 	signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
 	<-stop
@@ -55,5 +88,5 @@ func main() {
 	fmt.Println("Shutting down...")
 	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
 	defer cancel()
-	_ = srv.Shutdown(ctx)
+	_ = srv.Shutdown(ctx) // best-effort; log if needed
 }