feat: add comments and cleanup unused imports across codebase

internal/middleware/access.go

@@ -6,18 +6,18 @@ import (
 )
 
 type AccessPolicy struct {
-	PublicPaths map[string]struct{}
-	PublicHeads []string
+	PublicPaths map[string]struct{} // exact match paths (e.g. /login)
+	PublicHeads []string             // prefix match paths (e.g. /static/)
 }
 
 func NewAccessPolicy() AccessPolicy {
 	return AccessPolicy{
 		PublicPaths: map[string]struct{}{
-			"/login": {},
+			"/login": {}, // login page is public
 		},
 		PublicHeads: []string{
-			"/static/",
-			"/dist/",
+			"/static/", // static assets
+			"/dist/",    // bundled assets
 		},
 	}
 }
@@ -36,6 +36,8 @@ func (p AccessPolicy) IsPublicPath(path string) bool {
 	return false
 }
 
+// RequireGlobalAuthWithPolicy redirects unauthenticated users to /login
+// uses HX-Redirect for HTMX requests, regular redirect otherwise
 func RequireGlobalAuthWithPolicy(policy AccessPolicy) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {

internal/middleware/auth.go

@@ -9,18 +9,19 @@ import (
 	"mal/internal/db"
 )
 
+// Auth middleware validates the session cookie and injects the user into context
 func Auth(authService *auth.Service) func(http.Handler) http.Handler {
 	return func(next http.Handler) http.Handler {
 		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 			cookie, err := r.Cookie("session_id")
 			if err != nil {
-				next.ServeHTTP(w, r)
+				next.ServeHTTP(w, r) // no cookie, proceed unauthenticated
 				return
 			}
 
 			user, err := authService.ValidateSession(r.Context(), cookie.Value)
 			if err != nil {
-				next.ServeHTTP(w, r)
+				next.ServeHTTP(w, r) // invalid session, proceed unauthenticated
 				return
 			}
 
@@ -30,6 +31,7 @@ func Auth(authService *auth.Service) func(http.Handler) http.Handler {
 	}
 }
 
+// GetUser retrieves the authenticated user from context, or nil if not authenticated
 func GetUser(ctx context.Context) *db.User {
 	user, ok := ctx.Value(ctxpkg.UserKey).(*db.User)
 	if !ok {