honeyDueAPI/internal/router/router.go

package router

import (
	"errors"
	"fmt"
	"net/http"
	"time"

	"github.com/go-playground/validator/v10"
	"github.com/labstack/echo/v4"
	"github.com/labstack/echo/v4/middleware"
	"github.com/rs/zerolog/log"
	"gorm.io/gorm"

	"github.com/treytartt/casera-api/internal/admin"
	"github.com/treytartt/casera-api/internal/apperrors"
	"github.com/treytartt/casera-api/internal/config"
	"github.com/treytartt/casera-api/internal/dto/responses"
	"github.com/treytartt/casera-api/internal/handlers"
	"github.com/treytartt/casera-api/internal/i18n"
	custommiddleware "github.com/treytartt/casera-api/internal/middleware"
	"github.com/treytartt/casera-api/internal/monitoring"
	"github.com/treytartt/casera-api/internal/push"
	"github.com/treytartt/casera-api/internal/repositories"
	"github.com/treytartt/casera-api/internal/services"
	customvalidator "github.com/treytartt/casera-api/internal/validator"
	"github.com/treytartt/casera-api/pkg/utils"
)

const Version = "2.0.0"

// Dependencies holds all dependencies needed by the router
type Dependencies struct {
	DB                *gorm.DB
	Cache             *services.CacheService
	Config            *config.Config
	EmailService      *services.EmailService
	PDFService        *services.PDFService
	PushClient        *push.Client // Direct APNs/FCM client
	StorageService    *services.StorageService
	MonitoringService *monitoring.Service
}

// SetupRouter creates and configures the Echo router
func SetupRouter(deps *Dependencies) *echo.Echo {
	cfg := deps.Config

	e := echo.New()
	e.HideBanner = true
	e.Validator = customvalidator.NewCustomValidator()
	e.HTTPErrorHandler = customHTTPErrorHandler

	// NOTE: Removed AddTrailingSlash() middleware - it conflicted with admin routes
	// which don't use trailing slashes. Mobile API routes explicitly include trailing slashes.

	// Global middleware
	e.Use(utils.EchoRecovery())
	e.Use(utils.EchoLogger())
	e.Use(corsMiddleware(cfg))
	e.Use(i18n.Middleware())

	// Monitoring metrics middleware (if monitoring is enabled)
	if deps.MonitoringService != nil {
		if metricsMiddleware := deps.MonitoringService.MetricsMiddleware(); metricsMiddleware != nil {
			e.Use(metricsMiddleware)
		}
	}

	// Serve landing page static files (if static directory is configured)
	staticDir := cfg.Server.StaticDir
	if staticDir != "" {
		e.Static("/css", staticDir+"/css")
		e.Static("/js", staticDir+"/js")
		e.Static("/images", staticDir+"/images")
		e.File("/favicon.ico", staticDir+"/images/favicon.svg")

		// Serve index.html at root
		e.GET("/", func(c echo.Context) error {
			return c.File(staticDir + "/index.html")
		})
	}

	// Health check endpoint (no auth required)
	e.GET("/api/health/", healthCheck)

	// Initialize onboarding email service for tracking handler
	onboardingService := services.NewOnboardingEmailService(deps.DB, deps.EmailService, cfg.Server.BaseURL)

	// Email tracking endpoint (no auth required - used by email tracking pixels)
	trackingHandler := handlers.NewTrackingHandler(onboardingService)
	e.GET("/api/track/open/:trackingID", trackingHandler.TrackEmailOpen)

	// NOTE: Public static file serving removed for security.
	// All uploaded media is now served through authenticated proxy endpoints:
	// - GET /api/media/document/:id
	// - GET /api/media/document-image/:id
	// - GET /api/media/completion-image/:id
	// These endpoints verify the user has access to the residence before serving files.

	// Initialize repositories
	userRepo := repositories.NewUserRepository(deps.DB)
	residenceRepo := repositories.NewResidenceRepository(deps.DB)
	taskRepo := repositories.NewTaskRepository(deps.DB)
	contractorRepo := repositories.NewContractorRepository(deps.DB)
	documentRepo := repositories.NewDocumentRepository(deps.DB)
	notificationRepo := repositories.NewNotificationRepository(deps.DB)
	subscriptionRepo := repositories.NewSubscriptionRepository(deps.DB)
	taskTemplateRepo := repositories.NewTaskTemplateRepository(deps.DB)

	// Initialize services
	authService := services.NewAuthService(userRepo, cfg)
	authService.SetNotificationRepository(notificationRepo) // For creating notification preferences on registration
	userService := services.NewUserService(userRepo)
	residenceService := services.NewResidenceService(residenceRepo, userRepo, cfg)
	residenceService.SetTaskRepository(taskRepo) // Wire up task repo for statistics
	taskService := services.NewTaskService(taskRepo, residenceRepo)
	contractorService := services.NewContractorService(contractorRepo, residenceRepo)
	documentService := services.NewDocumentService(documentRepo, residenceRepo)
	notificationService := services.NewNotificationService(notificationRepo, deps.PushClient)

	// Wire up notification, email, residence, and storage services to task service
	taskService.SetNotificationService(notificationService)
	taskService.SetEmailService(deps.EmailService)
	taskService.SetResidenceService(residenceService) // For including TotalSummary in CRUD responses
	taskService.SetStorageService(deps.StorageService) // For reading completion images for email
	subscriptionService := services.NewSubscriptionService(subscriptionRepo, residenceRepo, taskRepo, contractorRepo, documentRepo)
	taskTemplateService := services.NewTaskTemplateService(taskTemplateRepo)

	// Initialize webhook handler for Apple/Google subscription notifications
	subscriptionWebhookHandler := handlers.NewSubscriptionWebhookHandler(subscriptionRepo, userRepo)

	// Initialize middleware
	authMiddleware := custommiddleware.NewAuthMiddleware(deps.DB, deps.Cache)

	// Initialize Apple auth service
	appleAuthService := services.NewAppleAuthService(deps.Cache, cfg)

	// Initialize handlers
	authHandler := handlers.NewAuthHandler(authService, deps.EmailService, deps.Cache)
	authHandler.SetAppleAuthService(appleAuthService)
	userHandler := handlers.NewUserHandler(userService)
	residenceHandler := handlers.NewResidenceHandler(residenceService, deps.PDFService, deps.EmailService)
	taskHandler := handlers.NewTaskHandler(taskService, deps.StorageService)
	contractorHandler := handlers.NewContractorHandler(contractorService)
	documentHandler := handlers.NewDocumentHandler(documentService, deps.StorageService)
	notificationHandler := handlers.NewNotificationHandler(notificationService)
	subscriptionHandler := handlers.NewSubscriptionHandler(subscriptionService)
	staticDataHandler := handlers.NewStaticDataHandler(residenceService, taskService, contractorService, taskTemplateService, deps.Cache)
	taskTemplateHandler := handlers.NewTaskTemplateHandler(taskTemplateService)

	// Initialize upload handler (if storage service is available)
	var uploadHandler *handlers.UploadHandler
	var mediaHandler *handlers.MediaHandler
	if deps.StorageService != nil {
		uploadHandler = handlers.NewUploadHandler(deps.StorageService)
		mediaHandler = handlers.NewMediaHandler(documentRepo, taskRepo, residenceRepo, deps.StorageService)
	}

	// Set up admin routes with monitoring handler (if available)
	var monitoringHandler *monitoring.Handler
	if deps.MonitoringService != nil {
		monitoringHandler = deps.MonitoringService.Handler()
	}

	adminDeps := &admin.Dependencies{
		EmailService:      deps.EmailService,
		PushClient:        deps.PushClient,
		OnboardingService: onboardingService,
		MonitoringHandler: monitoringHandler,
	}
	admin.SetupRoutes(e, deps.DB, cfg, adminDeps)

	// API group
	api := e.Group("/api")
	{
		// Public auth routes (no auth required)
		setupPublicAuthRoutes(api, authHandler)

		// Public data routes (no auth required)
		setupPublicDataRoutes(api, residenceHandler, taskHandler, contractorHandler, staticDataHandler, subscriptionHandler, taskTemplateHandler)

		// Subscription webhook routes (no auth - called by Apple/Google servers)
		setupWebhookRoutes(api, subscriptionWebhookHandler)

		// Protected routes (auth required)
		protected := api.Group("")
		protected.Use(authMiddleware.TokenAuth())
		protected.Use(custommiddleware.TimezoneMiddleware())
		{
			setupProtectedAuthRoutes(protected, authHandler)
			setupResidenceRoutes(protected, residenceHandler)
			setupTaskRoutes(protected, taskHandler)
			setupContractorRoutes(protected, contractorHandler)
			setupDocumentRoutes(protected, documentHandler)
			setupNotificationRoutes(protected, notificationHandler)
			setupSubscriptionRoutes(protected, subscriptionHandler)
			setupUserRoutes(protected, userHandler)

			// Upload routes (only if storage service is configured)
			if uploadHandler != nil {
				setupUploadRoutes(protected, uploadHandler)
			}

			// Media routes (authenticated media serving)
			if mediaHandler != nil {
				setupMediaRoutes(protected, mediaHandler)
			}
		}
	}

	return e
}

// corsMiddleware configures CORS - allowing all origins for API access
func corsMiddleware(cfg *config.Config) echo.MiddlewareFunc {
	return middleware.CORSWithConfig(middleware.CORSConfig{
		AllowOrigins:     []string{"*"},
		AllowMethods:     []string{http.MethodGet, http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete, http.MethodOptions},
		AllowHeaders:     []string{echo.HeaderOrigin, echo.HeaderContentType, echo.HeaderAccept, echo.HeaderAuthorization, "X-Requested-With", "X-Timezone"},
		ExposeHeaders:    []string{echo.HeaderContentLength},
		AllowCredentials: false,
		MaxAge:           int((12 * time.Hour).Seconds()),
	})
}

// healthCheck returns API health status
func healthCheck(c echo.Context) error {
	return c.JSON(http.StatusOK, map[string]interface{}{
		"status":    "healthy",
		"version":   Version,
		"framework": "Echo",
		"timestamp": time.Now().UTC().Format(time.RFC3339),
	})
}

// setupPublicAuthRoutes configures public authentication routes
func setupPublicAuthRoutes(api *echo.Group, authHandler *handlers.AuthHandler) {
	auth := api.Group("/auth")
	{
		auth.POST("/login/", authHandler.Login)
		auth.POST("/register/", authHandler.Register)
		auth.POST("/forgot-password/", authHandler.ForgotPassword)
		auth.POST("/verify-reset-code/", authHandler.VerifyResetCode)
		auth.POST("/reset-password/", authHandler.ResetPassword)
		auth.POST("/apple-sign-in/", authHandler.AppleSignIn)
	}
}

// setupProtectedAuthRoutes configures protected authentication routes
func setupProtectedAuthRoutes(api *echo.Group, authHandler *handlers.AuthHandler) {
	auth := api.Group("/auth")
	{
		auth.POST("/logout/", authHandler.Logout)
		auth.GET("/me/", authHandler.CurrentUser)
		auth.PUT("/profile/", authHandler.UpdateProfile)
		auth.PATCH("/profile/", authHandler.UpdateProfile)
		auth.POST("/verify/", authHandler.VerifyEmail)       // Alias for mobile app compatibility
		auth.POST("/verify-email/", authHandler.VerifyEmail) // Original route
		auth.POST("/resend-verification/", authHandler.ResendVerification)
	}
}

// setupPublicDataRoutes configures public data routes (lookups, static data)
func setupPublicDataRoutes(api *echo.Group, residenceHandler *handlers.ResidenceHandler, taskHandler *handlers.TaskHandler, contractorHandler *handlers.ContractorHandler, staticDataHandler *handlers.StaticDataHandler, subscriptionHandler *handlers.SubscriptionHandler, taskTemplateHandler *handlers.TaskTemplateHandler) {
	// Static data routes (public, cached)
	staticData := api.Group("/static_data")
	{
		staticData.GET("/", staticDataHandler.GetStaticData)
		staticData.POST("/refresh/", staticDataHandler.RefreshStaticData)
	}

	// Public subscription routes (upgrade triggers needed at app start before login)
	subscriptionPublic := api.Group("/subscription")
	{
		subscriptionPublic.GET("/upgrade-triggers/", subscriptionHandler.GetAllUpgradeTriggers)
	}

	// Lookup routes (public)
	api.GET("/residences/types/", residenceHandler.GetResidenceTypes)
	api.GET("/tasks/categories/", taskHandler.GetCategories)
	api.GET("/tasks/priorities/", taskHandler.GetPriorities)
	api.GET("/tasks/frequencies/", taskHandler.GetFrequencies)
	api.GET("/contractors/specialties/", contractorHandler.GetSpecialties)

	// Task template routes (public, for app autocomplete)
	templates := api.Group("/tasks/templates")
	{
		templates.GET("/", taskTemplateHandler.GetTemplates)
		templates.GET("/grouped/", taskTemplateHandler.GetTemplatesGrouped)
		templates.GET("/search/", taskTemplateHandler.SearchTemplates)
		templates.GET("/by-category/:category_id/", taskTemplateHandler.GetTemplatesByCategory)
		templates.GET("/:id/", taskTemplateHandler.GetTemplate)
	}
}

// setupResidenceRoutes configures residence routes
func setupResidenceRoutes(api *echo.Group, residenceHandler *handlers.ResidenceHandler) {
	residences := api.Group("/residences")
	{
		residences.GET("/", residenceHandler.ListResidences)
		residences.POST("/", residenceHandler.CreateResidence)
		residences.GET("/my-residences/", residenceHandler.GetMyResidences)
		residences.GET("/summary/", residenceHandler.GetSummary)
		residences.POST("/join-with-code/", residenceHandler.JoinWithCode)

		residences.GET("/:id/", residenceHandler.GetResidence)
		residences.PUT("/:id/", residenceHandler.UpdateResidence)
		residences.PATCH("/:id/", residenceHandler.UpdateResidence)
		residences.DELETE("/:id/", residenceHandler.DeleteResidence)

		residences.POST("/:id/generate-share-code/", residenceHandler.GenerateShareCode)
		residences.POST("/:id/generate-share-package/", residenceHandler.GenerateSharePackage)
		residences.POST("/:id/generate-tasks-report/", residenceHandler.GenerateTasksReport)
		residences.GET("/:id/users/", residenceHandler.GetResidenceUsers)
		residences.DELETE("/:id/users/:user_id/", residenceHandler.RemoveResidenceUser)
	}
}

// setupTaskRoutes configures task routes
func setupTaskRoutes(api *echo.Group, taskHandler *handlers.TaskHandler) {
	tasks := api.Group("/tasks")
	{
		tasks.GET("/", taskHandler.ListTasks)
		tasks.POST("/", taskHandler.CreateTask)
		tasks.GET("/by-residence/:residence_id/", taskHandler.GetTasksByResidence)

		tasks.GET("/:id/", taskHandler.GetTask)
		tasks.PUT("/:id/", taskHandler.UpdateTask)
		tasks.PATCH("/:id/", taskHandler.UpdateTask)
		tasks.DELETE("/:id/", taskHandler.DeleteTask)

		tasks.POST("/:id/mark-in-progress/", taskHandler.MarkInProgress)
		tasks.POST("/:id/cancel/", taskHandler.CancelTask)
		tasks.POST("/:id/uncancel/", taskHandler.UncancelTask)
		tasks.POST("/:id/archive/", taskHandler.ArchiveTask)
		tasks.POST("/:id/unarchive/", taskHandler.UnarchiveTask)
		tasks.POST("/:id/quick-complete/", taskHandler.QuickComplete)
		tasks.GET("/:id/completions/", taskHandler.GetTaskCompletions)
	}

	// Task Completions
	completions := api.Group("/task-completions")
	{
		completions.GET("/", taskHandler.ListCompletions)
		completions.POST("/", taskHandler.CreateCompletion)
		completions.GET("/:id/", taskHandler.GetCompletion)
		completions.DELETE("/:id/", taskHandler.DeleteCompletion)
	}
}

// setupContractorRoutes configures contractor routes
func setupContractorRoutes(api *echo.Group, contractorHandler *handlers.ContractorHandler) {
	contractors := api.Group("/contractors")
	{
		contractors.GET("/", contractorHandler.ListContractors)
		contractors.POST("/", contractorHandler.CreateContractor)
		contractors.GET("/by-residence/:residence_id/", contractorHandler.ListContractorsByResidence)
		contractors.GET("/:id/", contractorHandler.GetContractor)
		contractors.PUT("/:id/", contractorHandler.UpdateContractor)
		contractors.PATCH("/:id/", contractorHandler.UpdateContractor)
		contractors.DELETE("/:id/", contractorHandler.DeleteContractor)
		contractors.POST("/:id/toggle-favorite/", contractorHandler.ToggleFavorite)
		contractors.GET("/:id/tasks/", contractorHandler.GetContractorTasks)
	}
}

// setupDocumentRoutes configures document routes
func setupDocumentRoutes(api *echo.Group, documentHandler *handlers.DocumentHandler) {
	documents := api.Group("/documents")
	{
		documents.GET("/", documentHandler.ListDocuments)
		documents.POST("/", documentHandler.CreateDocument)
		documents.GET("/warranties/", documentHandler.ListWarranties)
		documents.GET("/:id/", documentHandler.GetDocument)
		documents.PUT("/:id/", documentHandler.UpdateDocument)
		documents.PATCH("/:id/", documentHandler.UpdateDocument)
		documents.DELETE("/:id/", documentHandler.DeleteDocument)
		documents.POST("/:id/activate/", documentHandler.ActivateDocument)
		documents.POST("/:id/deactivate/", documentHandler.DeactivateDocument)
	}
}

// setupNotificationRoutes configures notification routes
func setupNotificationRoutes(api *echo.Group, notificationHandler *handlers.NotificationHandler) {
	notifications := api.Group("/notifications")
	{
		notifications.GET("/", notificationHandler.ListNotifications)
		notifications.GET("/unread-count/", notificationHandler.GetUnreadCount)
		notifications.POST("/mark-all-read/", notificationHandler.MarkAllAsRead)
		notifications.POST("/:id/read/", notificationHandler.MarkAsRead)

		notifications.POST("/devices/", notificationHandler.RegisterDevice)
		notifications.POST("/devices/register/", notificationHandler.RegisterDevice) // Alias for mobile clients
		notifications.GET("/devices/", notificationHandler.ListDevices)
		notifications.DELETE("/devices/:id/", notificationHandler.DeleteDevice)

		notifications.GET("/preferences/", notificationHandler.GetPreferences)
		notifications.PUT("/preferences/", notificationHandler.UpdatePreferences)
		notifications.PATCH("/preferences/", notificationHandler.UpdatePreferences)
	}
}

// setupSubscriptionRoutes configures subscription routes (authenticated)
// Note: /upgrade-triggers/ is in setupPublicDataRoutes (public, no auth required)
func setupSubscriptionRoutes(api *echo.Group, subscriptionHandler *handlers.SubscriptionHandler) {
	subscription := api.Group("/subscription")
	{
		subscription.GET("/", subscriptionHandler.GetSubscription)
		subscription.GET("/status/", subscriptionHandler.GetSubscriptionStatus)
		subscription.GET("/upgrade-trigger/:key/", subscriptionHandler.GetUpgradeTrigger)
		subscription.GET("/features/", subscriptionHandler.GetFeatureBenefits)
		subscription.GET("/promotions/", subscriptionHandler.GetPromotions)
		subscription.POST("/purchase/", subscriptionHandler.ProcessPurchase)
		subscription.POST("/cancel/", subscriptionHandler.CancelSubscription)
		subscription.POST("/restore/", subscriptionHandler.RestoreSubscription)
	}
}

// setupUserRoutes configures user routes
func setupUserRoutes(api *echo.Group, userHandler *handlers.UserHandler) {
	users := api.Group("/users")
	{
		users.GET("/", userHandler.ListUsers)
		users.GET("/:id/", userHandler.GetUser)
		users.GET("/profiles/", userHandler.ListProfiles)
	}
}

// setupUploadRoutes configures file upload routes
func setupUploadRoutes(api *echo.Group, uploadHandler *handlers.UploadHandler) {
	uploads := api.Group("/uploads")
	{
		uploads.POST("/image/", uploadHandler.UploadImage)
		uploads.POST("/document/", uploadHandler.UploadDocument)
		uploads.POST("/completion/", uploadHandler.UploadCompletion)
		uploads.DELETE("/", uploadHandler.DeleteFile)
	}
}

// setupMediaRoutes configures authenticated media serving routes
func setupMediaRoutes(api *echo.Group, mediaHandler *handlers.MediaHandler) {
	media := api.Group("/media")
	{
		media.GET("/document/:id", mediaHandler.ServeDocument)
		media.GET("/document-image/:id", mediaHandler.ServeDocumentImage)
		media.GET("/completion-image/:id", mediaHandler.ServeCompletionImage)
	}
}

// setupWebhookRoutes configures subscription webhook routes for Apple/Google server-to-server notifications
// These routes are public (no auth) since they're called by Apple/Google servers
func setupWebhookRoutes(api *echo.Group, webhookHandler *handlers.SubscriptionWebhookHandler) {
	webhooks := api.Group("/subscription/webhook")
	{
		webhooks.POST("/apple/", webhookHandler.HandleAppleWebhook)
		webhooks.POST("/google/", webhookHandler.HandleGoogleWebhook)
	}
}

// customHTTPErrorHandler handles all errors returned from handlers in a consistent way.
// It converts AppErrors, validation errors, and Echo HTTPErrors to JSON responses.
// Also includes fallback handling for legacy service-level errors.
func customHTTPErrorHandler(err error, c echo.Context) {
	// Already committed? Skip
	if c.Response().Committed {
		return
	}

	// Handle AppError (our custom application errors)
	var appErr *apperrors.AppError
	if errors.As(err, &appErr) {
		message := i18n.LocalizedMessage(c, appErr.MessageKey)
		// If i18n key not found (returns the key itself), use fallback message
		if message == appErr.MessageKey && appErr.Message != "" {
			message = appErr.Message
		} else if message == appErr.MessageKey {
			message = appErr.MessageKey // Use the key as last resort
		}

		// Log internal errors
		if appErr.Err != nil {
			log.Error().Err(appErr.Err).Str("message_key", appErr.MessageKey).Msg("Application error")
		}

		c.JSON(appErr.Code, responses.ErrorResponse{Error: message})
		return
	}

	// Handle validation errors from go-playground/validator
	var validationErrs validator.ValidationErrors
	if errors.As(err, &validationErrs) {
		c.JSON(http.StatusBadRequest, customvalidator.FormatValidationErrors(err))
		return
	}

	// Handle Echo's built-in HTTPError
	var httpErr *echo.HTTPError
	if errors.As(err, &httpErr) {
		msg := fmt.Sprintf("%v", httpErr.Message)
		c.JSON(httpErr.Code, responses.ErrorResponse{Error: msg})
		return
	}

	// Handle service-layer errors and map them to appropriate HTTP status codes
	switch {
	// Task errors - 404 Not Found
	case errors.Is(err, services.ErrTaskNotFound):
		c.JSON(http.StatusNotFound, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.task_not_found"),
		})
		return
	case errors.Is(err, services.ErrCompletionNotFound):
		c.JSON(http.StatusNotFound, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.completion_not_found"),
		})
		return

	// Task errors - 403 Forbidden
	case errors.Is(err, services.ErrTaskAccessDenied):
		c.JSON(http.StatusForbidden, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.task_access_denied"),
		})
		return

	// Task errors - 400 Bad Request
	case errors.Is(err, services.ErrTaskAlreadyCancelled):
		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.task_already_cancelled"),
		})
		return
	case errors.Is(err, services.ErrTaskAlreadyArchived):
		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.task_already_archived"),
		})
		return

	// Residence errors - 404 Not Found
	case errors.Is(err, services.ErrResidenceNotFound):
		c.JSON(http.StatusNotFound, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.residence_not_found"),
		})
		return

	// Residence errors - 403 Forbidden
	case errors.Is(err, services.ErrResidenceAccessDenied):
		c.JSON(http.StatusForbidden, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.residence_access_denied"),
		})
		return
	case errors.Is(err, services.ErrNotResidenceOwner):
		c.JSON(http.StatusForbidden, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.not_residence_owner"),
		})
		return
	case errors.Is(err, services.ErrPropertiesLimitReached):
		c.JSON(http.StatusForbidden, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.properties_limit_reached"),
		})
		return

	// Residence errors - 400 Bad Request
	case errors.Is(err, services.ErrCannotRemoveOwner):
		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.cannot_remove_owner"),
		})
		return
	case errors.Is(err, services.ErrShareCodeExpired):
		c.JSON(http.StatusBadRequest, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.share_code_expired"),
		})
		return

	// Residence errors - 404 Not Found (share code)
	case errors.Is(err, services.ErrShareCodeInvalid):
		c.JSON(http.StatusNotFound, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.share_code_invalid"),
		})
		return

	// Residence errors - 409 Conflict
	case errors.Is(err, services.ErrUserAlreadyMember):
		c.JSON(http.StatusConflict, responses.ErrorResponse{
			Error: i18n.LocalizedMessage(c, "error.user_already_member"),
		})
		return
	}

	// Default: Internal server error (don't expose error details to client)
	log.Error().Err(err).Msg("Unhandled error")
	c.JSON(http.StatusInternalServerError, responses.ErrorResponse{
		Error: i18n.LocalizedMessage(c, "error.internal"),
	})
}