Massive Dependency Modernization Project

server.ts

@@ -25,9 +25,12 @@ import { backgroundJobService, startBackgroundJobs } from './src/services/backgr
 import { websocketService } from './src/services/websocketService.server';
 import type { UserProfile } from './src/types';
 
-// API Documentation (ADR-018)
+// API Documentation (ADR-018) - tsoa-generated OpenAPI spec
 import swaggerUi from 'swagger-ui-express';
-import { swaggerSpec } from './src/config/swagger';
+import tsoaSpec from './src/config/tsoa-spec.json' with { type: 'json' };
+
+// tsoa-generated routes
+import { RegisterRoutes } from './src/routes/tsoa-generated';
 import {
   analyticsQueue,
   weeklyAnalyticsQueue,
@@ -197,11 +200,13 @@ if (!process.env.JWT_SECRET) {
 
 // --- API Documentation (ADR-018) ---
 // Only serve Swagger UI in non-production environments to prevent information disclosure.
+// Uses tsoa-generated OpenAPI specification.
 if (process.env.NODE_ENV !== 'production') {
+  // Serve tsoa-generated OpenAPI documentation
   app.use(
     '/docs/api-docs',
     swaggerUi.serve,
-    swaggerUi.setup(swaggerSpec, {
+    swaggerUi.setup(tsoaSpec, {
       customCss: '.swagger-ui .topbar { display: none }',
       customSiteTitle: 'Flyer Crawler API Documentation',
     }),
@@ -210,7 +215,7 @@ if (process.env.NODE_ENV !== 'production') {
   // Expose raw OpenAPI JSON spec for tooling (SDK generation, testing, etc.)
   app.get('/docs/api-docs.json', (_req, res) => {
     res.setHeader('Content-Type', 'application/json');
-    res.send(swaggerSpec);
+    res.send(tsoaSpec);
   });
 
   logger.info('API Documentation available at /docs/api-docs');
@@ -230,12 +235,27 @@ app.get('/api/v1/health/queues', async (req, res) => {
   }
 });
 
+// --- tsoa-generated Routes ---
+// Register routes generated by tsoa from controllers.
+// These routes run in parallel with existing routes during migration.
+// tsoa routes are mounted directly on the app (basePath in tsoa.json is '/api').
+// The RegisterRoutes function adds routes at /api/health/*, /api/_tsoa/*, etc.
+//
+// IMPORTANT: tsoa routes are registered BEFORE the backwards compatibility redirect
+// middleware so that tsoa routes (like /api/health/ping, /api/_tsoa/verify) are
+// matched directly without being redirected to /api/v1/*.
+// During migration, both tsoa routes and versioned routes coexist:
+// - /api/health/ping -> handled by tsoa HealthController
+// - /api/v1/health/ping -> handled by versioned health.routes.ts
+// As controllers are migrated, the versioned routes will be removed.
+RegisterRoutes(app);
+
 // --- Backwards Compatibility Redirect (ADR-008: API Versioning Strategy) ---
 // Redirect old /api/* paths to /api/v1/* for backwards compatibility.
 // This allows clients to gradually migrate to the versioned API.
-// IMPORTANT: This middleware MUST be mounted BEFORE createApiRouter() so that
-// unversioned paths like /api/users are redirected to /api/v1/users BEFORE
-// the versioned router's detectApiVersion middleware rejects them as invalid versions.
+// IMPORTANT: This middleware MUST be mounted:
+// - AFTER tsoa routes (so tsoa routes are matched directly)
+// - BEFORE createApiRouter() (so unversioned paths are redirected to /api/v1/*)
 app.use('/api', (req, res, next) => {
   // Check if the path starts with a version-like prefix (/v followed by digits).
   // This includes both supported versions (v1, v2) and unsupported ones (v99).