refactor(backend): Phase 3 — decompose internal/api into feature-scoped handler packages

.github/workflows/ci.yml

@@ -43,7 +43,7 @@ jobs:
         run: go install github.com/swaggo/swag/cmd/swag@latest
       - name: Generate Swagger docs
         working-directory: backend
-        run: swag init -d cmd/server,internal/api -g main.go --parseDependency --parseInternal -o docs
+        run: swag init -d cmd/server,internal/handler -g main.go --parseDependency --parseInternal -o docs
       - name: Test
         run: cd backend && go test ./...
 

.github/workflows/codeql.yml

@@ -45,7 +45,7 @@ jobs:
       - name: Generate Swagger docs
         if: matrix.language == 'go'
         working-directory: backend
-        run: swag init -d cmd/server,internal/api -g main.go --parseDependency --parseInternal -o docs
+        run: swag init -d cmd/server,internal/handler -g main.go --parseDependency --parseInternal -o docs
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v4

.github/workflows/release.yml

@@ -57,7 +57,7 @@ jobs:
 
       - name: Generate Swagger docs
         working-directory: backend
-        run: swag init -d cmd/server,internal/api -g main.go --parseDependency --parseInternal -o docs
+        run: swag init -d cmd/server,internal/handler -g main.go --parseDependency --parseInternal -o docs
 
       - name: Build binary
         working-directory: backend

CHANGELOG.md

@@ -17,6 +17,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- HTTP handlers have been decomposed from the monolithic `internal/api`
+  package into feature-scoped subpackages under `internal/handler/`
+  (`auth`, `calls`, `bookmarks`, `share`, `setup`, `health`,
+  `admin/{imports,radioreference,transcriptions}`). Route registration
+  now lives in `internal/handler/routes`, and shared swagger DTOs and
+  helpers live in `internal/handler/shared`. No route paths, methods,
+  middleware ordering, response shapes, or status codes changed.
 - Admin CRUD business logic has been extracted from `internal/ws` into a
   new transport-agnostic `internal/admin` package. The WebSocket layer
   now only routes `ADM_REQ` frames to `admin.Operations` methods; the

backend/.golangci.yml

@@ -50,7 +50,7 @@ issues:
     - "internal/db/models\\.go$"
     - "internal/db/db\\.go$"
     - "internal/db/querier\\.go$"
-    - "internal/api/swagger_models\\.go$" # swagger stubs — field names must mirror wire shape for doc readability
+    - "internal/handler/shared/dto\\.go$" # swagger stubs — field names must mirror wire shape for doc readability
   exclude-rules:
     # Test files: relax a handful of rules that don't add value there.
     - path: _test\.go

backend/Makefile

@@ -9,7 +9,7 @@ VERSION?=$(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
 LDFLAGS=-s -w -X github.com/openscanner/openscanner/internal/config.Version=$(VERSION)
 
 build:
-	swag init -d cmd/server,internal/api -g main.go --parseDependency --parseInternal -o docs
+	swag init -d cmd/server,internal/handler -g main.go --parseDependency --parseInternal -o docs
 	go build -ldflags="$(LDFLAGS)" -o $(OUTPUT) $(CMD)
 
 dev:

backend/cmd/server/main.go

@@ -37,7 +37,7 @@ import (
 	"github.com/gin-gonic/gin"
 	"github.com/kardianos/service"
 	"github.com/openscanner/openscanner/internal/admin"
-	"github.com/openscanner/openscanner/internal/api"
+	"github.com/openscanner/openscanner/internal/handler/routes"
 	"github.com/openscanner/openscanner/internal/audio"
 	"github.com/openscanner/openscanner/internal/auth"
 	"github.com/openscanner/openscanner/internal/cli"
@@ -892,7 +892,7 @@ func (p *program) run() {
 	// Start transcription result consumer (stores results in DB, broadcasts TRN).
 	go consumeTranscriptionResults(ctx, queries, hub, transcriberMgr)
 
-	api.RegisterRoutes(router, api.Deps{
+	routes.RegisterRoutes(router, routes.Deps{
 		Queries:            queries,
 		RateLimiter:        rateLimiter,
 		Processor:          processor,