app.js

// app.js
const express = require("express");
const crypto = require("crypto");
const dotenv = require("dotenv");
const fs = require("fs");
const zerodbService = require('./services/zerodbService');
const databaseAdapter = require('./services/databaseAdapter');
const { addVersionHeaders, createVersionedRoutes, validateApiVersion } = require('./middleware/apiVersioning');
const compression = require('compression');
const cookieParser = require('cookie-parser');
const helmetMiddleware = require('./middleware/security/helmet');
const corsMiddleware = require('./middleware/security/cors');
const secureHeadersMiddleware = require('./middleware/secureHeadersMiddleware'); // OCAE-304: Import secure headers
const {
  rateLimiter,
  authRateLimiter,
  createRouteRateLimit,
  createTieredRateLimit,
  includeAdvancedHeaders
} = require('./middleware/security/rateLimit');
const getLoggingMiddleware = require('./middleware/logging');
const { securityLogger } = require('./middleware/securityAuditLogger'); // OCAE-306: Import security audit logging
const { verifyCompanyAccess } = require('./middleware/companyAuth');
const { enforceCompanyScope } = require('./middleware/companyScope');
const { authenticateToken } = require('./middleware/authMiddleware');
// testEndpoints removed - no longer needed
const { setupSwagger } = require('./middleware/swaggerDocs'); // OCAE-210: Import Swagger middleware
const { databaseMonitor, metricsMiddleware } = require('./middleware/databaseMonitor'); // GitHub Issue #8: Database monitoring

// Initialize dotenv to load environment variables
dotenv.config();

// Validate environment variables before anything else
const { validateEnvironment } = require('./config/validateEnv');
try {
  validateEnvironment();
} catch (err) {
  console.error(err.message);
  if (process.env.NODE_ENV === 'production') {
    process.exit(1);
  }
}

// Initialize the Express app
const app = express();

// Trust first proxy (for rate limiting behind reverse proxy)
app.set('trust proxy', 1);

// Apply security middleware first
app.use(helmetMiddleware);
app.use(corsMiddleware);
app.use(secureHeadersMiddleware()); // OCAE-304: Apply secure headers middleware

// Apply compression middleware early in the pipeline
app.use(compression());

// Request logging middleware
const loggingMiddleware = getLoggingMiddleware();
if (Array.isArray(loggingMiddleware)) {
  loggingMiddleware.forEach(middleware => app.use(middleware));
} else {
  app.use(loggingMiddleware);
}

// GitHub Issue #8: Database monitoring metrics endpoint
app.use(metricsMiddleware);

// Stripe webhook needs raw body BEFORE json parser and auth middleware
// Mount the webhook handler directly here so it bypasses all auth
const billingController = require('./controllers/billingController');
const webhookRateLimiter = createRouteRateLimit('webhook', 100, 60 * 1000); // 100 requests per minute
app.post('/api/v1/billing/webhook', webhookRateLimiter, express.raw({ type: 'application/json' }), billingController.handleStripeWebhook);

// Issue #567: Stripe Connect webhook for accountant payouts (raw body required)
const stripeConnectWebhookController = require('./controllers/stripeConnectWebhookController');
app.post('/api/v1/webhooks/stripe-connect', webhookRateLimiter, express.raw({ type: 'application/json' }), stripeConnectWebhookController.handleStripeConnectWebhook);

// Issue #613: Clerk webhook — user sync (raw body required for Svix signature verification)
const clerkWebhookController = require('./controllers/clerkWebhookController');
app.post(
  '/api/v1/webhooks/clerk',
  webhookRateLimiter,
  express.raw({ type: 'application/json' }),
  (req, res, next) => {
    // Expose raw body string for signature verification
    if (Buffer.isBuffer(req.body)) {
      req.rawBody = req.body.toString('utf8');
      try { req.body = JSON.parse(req.rawBody); } catch { /* handled in controller */ }
    }
    next();
  },
  clerkWebhookController.handleClerkWebhook
);

// Issue #664: Clerky webhook — document signing events (raw body required for HMAC verification)
const clerkyWebhookController = require('./controllers/clerkyWebhookController');
app.post(
  '/api/v1/webhooks/clerky',
  webhookRateLimiter,
  express.raw({ type: '*/*' }),
  (req, res, next) => {
    // Expose raw body string for HMAC signature verification
    if (Buffer.isBuffer(req.body)) {
      req.rawBody = req.body.toString('utf8');
      try { req.body = JSON.parse(req.rawBody); } catch { /* handled in controller */ }
    }
    next();
  },
  clerkyWebhookController.handleWebhook
);

// Body parsers
app.use(express.json());
app.use(express.urlencoded({ extended: true }));

// Cookie parser middleware
app.use(cookieParser());

// Apply advanced rate limiting headers
app.use(includeAdvancedHeaders());

// Create route-specific rate limiters
// Increased limits to support SPA with multiple concurrent API calls
const apiRateLimiter = createRouteRateLimit('api', 1000, 15 * 60 * 1000);
const adminRateLimiter = createRouteRateLimit('admin', 500, 15 * 60 * 1000);

// Apply default rate limiting
app.use(rateLimiter);

// Apply stricter rate limiting to auth routes
app.use('/auth', authRateLimiter);

// Apply route-specific rate limiting
app.use('/api', apiRateLimiter);
app.use('/admin', adminRateLimiter);

// Apply tiered rate limiting to premium routes if user is authenticated
app.use('/api/premium', (req, res, next) => {
  // Check if user exists and has a role/tier
  if (req.user && req.user.tier) {
    // Apply appropriate tier limiter
    const tierLimiter = createTieredRateLimit(req.user.tier);
    return tierLimiter(req, res, next);
  }
  // If no user or tier, proceed without tier-specific rate limiting
  next();
});

// Apply API versioning middleware
app.use(addVersionHeaders);
app.use(validateApiVersion);

// OCAE-306: Apply security audit logging middleware
app.use(securityLogger.errorHandler());

// OCAE-210: Setup Swagger documentation middleware
setupSwagger(app);

// Test endpoints removed - using real OpenCAP Stack API only

// Determine if the environment is a test environment
const isTestEnv = process.env.NODE_ENV === "test";

// ============================================================================
// ZERODB INITIALIZATION
// ============================================================================
// ZeroDB is the primary and only database for OpenCap Stack
// ============================================================================
// T2-2: ZeroDB initialization - made available as a promise for blocking startup
const zerodbReady = (async () => {
  if (isTestEnv || process.env.ENABLE_ZERODB !== 'true') return;

  if (!process.env.AINATIVE_API_TOKEN) {
    const msg = 'ZeroDB enabled but AINATIVE_API_TOKEN not set';
    console.warn(`⚠️  ${msg}`);
    return;
  }

  try {
    const result = await zerodbService.initialize(process.env.AINATIVE_API_TOKEN);
    console.log(`✅ ZeroDB initialized (project: ${result.projectId}, tables: ${result.databaseStatus?.tables || 0})`);
    databaseMonitor.setupZeroDBMonitoring(zerodbService);
    await databaseAdapter.initialize(process.env.AINATIVE_API_TOKEN);
    console.log('✅ DatabaseAdapter initialized');

    // Seed any new tables that don't auto-create on first insert
    const newTables = ['reconstruction_jobs', 'mercury_snapshots', 'mercury_events'];
    for (const tbl of newTables) {
      try {
        await zerodbService.createTable(tbl, { fields: {} });
        console.log(`✅ Table "${tbl}" ensured`);
      } catch (tblErr) {
        // 409 = already exists; ZeroDB also returns 500 with UniqueViolation when table exists
        const detail = tblErr.response?.data?.detail || '';
        const alreadyExists = tblErr.response?.status === 409 ||
          tblErr.message?.includes('already exist') ||
          detail.includes('UniqueViolation') ||
          detail.includes('already exists');
        if (!alreadyExists) {
          console.warn(`⚠️  Could not pre-create table "${tbl}": ${tblErr.message}`);
        }
      }
    }
  } catch (err) {
    console.error('❌ ZeroDB initialization failed:', err.message);
    // Server continues running — DB ops will fail gracefully per request
  }
})();

// Function to safely require routes
const safeRequire = (routePath) => {
  try {
    const fullPath = routePath.endsWith('.js') ? routePath : `${routePath}.js`;

    if (!fs.existsSync(fullPath)) {
      if (process.env.NODE_ENV === 'development') {
        console.warn(`Route file not found: ${fullPath}`);
      }
      return null;
    }

    return require(fullPath);
  } catch (err) {
    console.error(`Error loading route ${routePath}:`, err.message);
    return null;
  }
};

// AX discovery routes (public, no auth) — served at root paths for agent discoverability
const axDiscoveryRoutes = require('./routes/axDiscoveryRoutes');
app.use('/', axDiscoveryRoutes);

// NLWeb-style conversational search (public, no auth) — GET /ask?q=...
const nlwebAskRoutes = require('./routes/nlwebAskRoutes');
app.use('/', nlwebAskRoutes);

// Agent self-onboarding (public, no auth required) — mounted before auth-protected routes
const agentOnboardingRoutes = require('./routes/v1/agentOnboardingRoutes');
app.use('/api/v1/agents', agentOnboardingRoutes);

// Import route modules using absolute paths
const path = require('path');
const routes = {
  // Core routes that should always exist
  financialReportRoutes: safeRequire(path.join(__dirname, 'routes/v1/financialReportingRoutes')),
  userRoutes: safeRequire(path.join(__dirname, 'routes/v1/userRoutes')),
  shareClassRoutes: safeRequire(path.join(__dirname, 'routes/v1/shareClassRoutes')),
  stakeholderRoutes: safeRequire(path.join(__dirname, 'routes/v1/stakeholderRoutes')),
  documentRoutes: safeRequire(path.join(__dirname, 'routes/v1/documentRoutes')),
  fundraisingRoundRoutes: safeRequire(path.join(__dirname, 'routes/v1/fundraisingRoundRoutes')),
  equityPlanRoutes: safeRequire(path.join(__dirname, 'routes/v1/equityPlanRoutes')),
  documentEmbeddingRoutes: safeRequire(path.join(__dirname, 'routes/v1/documentEmbeddingRoutes')),
  // employeeRoutes removed — employeeInviteRoutes handles /employees with per-route auth.
  // employeeRoutes has router.use(authenticateToken) which blocks the public accept-invite endpoint.
  // The generic mapper would mount it at /api/v1/employee which prefix-matches /api/v1/employees/*.
  activityRoutes: safeRequire(path.join(__dirname, 'routes/v1/activityRoutes')),
  investmentTrackerRoutes: safeRequire(path.join(__dirname, 'routes/v1/investmentTrackerRoutes')),
  adminRoutes: safeRequire(path.join(__dirname, 'routes/v1/adminRoutes')),
  documentAccessRoutes: safeRequire(path.join(__dirname, 'routes/v1/documentAccessRoutes')),
  investorRoutes: safeRequire(path.join(__dirname, 'routes/v1/investorRoutes')),
  companyRoutes: safeRequire(path.join(__dirname, 'routes/v1/companyRoutes')),
  authRoutes: safeRequire(path.join(__dirname, 'routes/v1/authRoutes')),
  communicationRoutes: safeRequire(path.join(__dirname, 'routes/v1/communicationRoutes')),
  notificationRoutes: safeRequire(path.join(__dirname, 'routes/v1/notificationRoutes')),
  inviteManagementRoutes: safeRequire(path.join(__dirname, 'routes/v1/inviteManagementRoutes')),
  spvRoutes: safeRequire(path.join(__dirname, 'routes/v1/spvRoutes')),
  spvAssetRoutes: safeRequire(path.join(__dirname, 'routes/v1/spvAssetRoutes')),
  complianceCheckRoutes: safeRequire(path.join(__dirname, 'routes/v1/complianceCheckRoutes')),
  integrationModuleRoutes: safeRequire(path.join(__dirname, 'routes/v1/integrationModuleRoutes')),
  taxCalculatorRoutes: safeRequire(path.join(__dirname, 'routes/v1/taxCalculatorRoutes')),
  securityAuditRoutes: safeRequire(path.join(__dirname, 'routes/v1/securityAuditRoutes')),
  financialDataRoutes: safeRequire(path.join(__dirname, 'routes/v1/financialDataRoutes')),
  semanticSearchRoutes: safeRequire(path.join(__dirname, 'routes/v1/semanticSearchRoutes')),
  searchRoutes: safeRequire(path.join(__dirname, 'routes/v1/searchRoutes')), // Issue #190: Global multi-entity search
  agentMemoryRoutes: safeRequire(path.join(__dirname, 'routes/v1/agentMemoryRoutes')), // Issue #27: Agent memory
  rlhfRoutes: safeRequire(path.join(__dirname, 'routes/v1/rlhfRoutes')), // Issue #29: RLHF data collection
  advancedAnalyticsRoutes: safeRequire(path.join(__dirname, 'routes/v1/advancedAnalyticsRoutes')), // Issue #31: Analytics
  eventStreamingRoutes: safeRequire(path.join(__dirname, 'routes/v1/eventStreamingRoutes')), // Issue #28: Event streaming
  fileStorageRoutes: safeRequire(path.join(__dirname, 'routes/v1/fileStorageRoutes')), // Issue #30: File storage
  safeRoutes: safeRequire(path.join(__dirname, 'routes/v1/safeRoutes')), // Issue #64, #66, #68: SAFE management
  taskRoutes: safeRequire(path.join(__dirname, 'routes/v1/taskRoutes')), // Issue #121: Task management
  healthRoutes: safeRequire(path.join(__dirname, 'routes/v1/healthRoutes')), // Issue #35: Production readiness health checks
  valuation409ARoutes: safeRequire(path.join(__dirname, 'routes/v1/valuation409ARoutes')), // Issue #59: 409A Valuation Request System
  valuation409AExportRoutes: safeRequire(path.join(__dirname, 'routes/v1/valuation409AExportRoutes')), // Issue #269: 409A Data Export API
  materialEventRoutes: safeRequire(path.join(__dirname, 'routes/v1/materialEventRoutes')), // Issue #60: Material Events Tracking
  valuationPartnerRoutes: safeRequire(path.join(__dirname, 'routes/v1/valuationPartnerRoutes')), // Issue #61: Valuation Specialist Integration
  equityGrantRoutes: safeRequire(path.join(__dirname, 'routes/v1/equityGrantRoutes')), // Issue #77: Equity Grant Management
  exerciseRoutes: safeRequire(path.join(__dirname, 'routes/v1/exerciseRoutes')), // Issue #79: Exercise Management System
  terminationRoutes: safeRequire(path.join(__dirname, 'routes/v1/terminationRoutes')), // Issue #81: Termination Equity Workflow
  bulkMessageRoutes: safeRequire(path.join(__dirname, 'routes/v1/bulkMessageRoutes')), // Issue #86: Bulk Messaging System
  emailTrackingRoutes: safeRequire(path.join(__dirname, 'routes/v1/emailTrackingRoutes')), // Issue #87: Email Delivery Tracking
  investorRightsRoutes: safeRequire(path.join(__dirname, 'routes/v1/investorRightsRoutes')), // Issue #92: Investor Rights Tracking
  investorCommunicationRoutes: safeRequire(path.join(__dirname, 'routes/v1/investorCommunicationRoutes')), // Issue #91: Investor Communication System
  messageTriggerRoutes: safeRequire(path.join(__dirname, 'routes/v1/messageTriggerRoutes')), // Issue #88: Automated Triggered Messages
  securityIssuanceRoutes: safeRequire(path.join(__dirname, 'routes/v1/securityIssuanceRoutes')), // Issue #76: Security Issuances Register
  vestingScheduleRoutes: safeRequire(path.join(__dirname, 'routes/v1/vestingScheduleRoutes')), // Issue #78: Automated Vesting Schedules
  equityPlanReportRoutes: safeRequire(path.join(__dirname, 'routes/v1/equityPlanReportRoutes')), // Issue #110: Equity Plan Reports
  financialAnalyticsRoutes: safeRequire(path.join(__dirname, 'routes/v1/financialAnalyticsRoutes')), // Issue #44: Financial Analytics
  riskAssessmentRoutes: safeRequire(path.join(__dirname, 'routes/v1/riskAssessmentRoutes')), // Issue #44: Risk Assessment
  currencyRoutes: safeRequire(path.join(__dirname, 'routes/v1/currencyRoutes')), // Issue #44: Currency Service
  waterfallAnalysisRoutes: safeRequire(path.join(__dirname, 'routes/v1/waterfallAnalysisRoutes')), // Issue #56: Waterfall Analysis Engine
  documentAuditRoutes: safeRequire(path.join(__dirname, 'routes/v1/documentAuditRoutes')), // Issue #102: Document Audit Trail
  cacheRoutes: safeRequire(path.join(__dirname, 'routes/v1/cacheRoutes')), // Issue #47: Database Optimization and Caching
  fundraiseModelRoutes: safeRequire(path.join(__dirname, 'routes/v1/fundraiseModelRoutes')), // Issue #195: Interactive Fundraising Modeling Engine
  customReportRoutes: safeRequire(path.join(__dirname, 'routes/v1/customReportRoutes')), // Issue #197: Custom Report Builder Engine
  dataRoomRoutes: safeRequire(path.join(__dirname, 'routes/v1/dataRoomRoutes')), // Issue #194: Data Room Backend Infrastructure
  reportLibraryRoutes: safeRequire(path.join(__dirname, 'routes/v1/reportLibraryRoutes')), // Issue #199: Report Library Categorization
  integrationMarketplaceRoutes: safeRequire(path.join(__dirname, 'routes/v1/integrationMarketplaceRoutes')), // Issue #202: Integration Marketplace
  documentTemplateRoutes: safeRequire(path.join(__dirname, 'routes/v1/documentTemplateRoutes')), // Issue #193: Document Template System
  fundraisingAnalyticsRoutes: safeRequire(path.join(__dirname, 'routes/v1/fundraisingAnalyticsRoutes')), // Issue #196: Fundraising Analytics Service
  billingRoutes: safeRequire(path.join(__dirname, 'routes/v1/billingRoutes')), // Issue #201: Billing Dashboard APIs
  stakeholderReportRoutes: safeRequire(path.join(__dirname, 'routes/v1/stakeholderReportRoutes')), // Issue #198: Stakeholder Report Generation
  accessPolicyRoutes: safeRequire(path.join(__dirname, 'routes/v1/accessPolicyRoutes')), // Issue #247: Access Policies Endpoints
  accessGroupRoutes: safeRequire(path.join(__dirname, 'routes/v1/accessGroupRoutes')), // Issue #274: Access Groups Endpoints
  taxDocumentRoutes: safeRequire(path.join(__dirname, 'routes/v1/taxDocumentRoutes')), // Issue #246: Tax Document Download Endpoint
  bulkReportsRoutes: safeRequire(path.join(__dirname, 'routes/v1/bulkReportsRoutes')), // Issue #238: Bulk Reports Endpoint
  dilutionRoutes: safeRequire(path.join(__dirname, 'routes/v1/dilutionRoutes')), // Dilution calculator
  agentOnboardingRoutes: safeRequire(path.join(__dirname, 'routes/v1/agentOnboardingRoutes')), // AX: Agent self-onboarding
  mcpRoutes: safeRequire(path.join(__dirname, 'routes/v1/mcpRoutes')), // Issue #495: MCP Server
  pluginAuthRoutes: safeRequire(path.join(__dirname, 'routes/v1/pluginAuthRoutes')), // Issue #505: Plugin OAuth
  pluginRoutes: safeRequire(path.join(__dirname, 'routes/v1/pluginRoutes')), // Issue #506: Plugin tools
  boardMeetingRoutes: safeRequire(path.join(__dirname, 'routes/v1/boardMeetingRoutes')), // Board meeting management
  boardMemberRoutes: safeRequire(path.join(__dirname, 'routes/v1/boardMemberRoutes')), // Board member management
  boardResolutionRoutes: safeRequire(path.join(__dirname, 'routes/v1/boardResolutionRoutes')), // Board resolutions with persistence
  messageRoutes: safeRequire(path.join(__dirname, 'routes/v1/messageRoutes')), // Messaging / conversations
  accountantRoutes: safeRequire(path.join(__dirname, 'routes/v1/accountantRoutes')), // AI 409A accountant review workflow
  investorDatabaseRoutes: safeRequire(path.join(__dirname, 'routes/v1/investorDatabaseRoutes')), // System-wide VC investor directory
  dataRoomReconstructRoutes: safeRequire(path.join(__dirname, 'routes/v1/dataRoomReconstructRoutes')), // Issue #631: AI Data Room Reconstruction
  migrationRoutes: safeRequire(path.join(__dirname, 'routes/v1/migrationRoutes')), // Issue #652: Carta migration score tool
  exportRoutes: safeRequire(path.join(__dirname, 'routes/v1/exportRoutes')), // CSV/XLSX export endpoints
  capTableHealthRoutes: safeRequire(path.join(__dirname, 'routes/v1/capTableHealthRoutes')), // Issue #660: Cap table health scorecard
  scenarioRoutes: safeRequire(path.join(__dirname, 'routes/v1/scenarioRoutes')), // Issue #661: Scenario modeling unified endpoint
  employeeInviteRoutes: safeRequire(path.join(__dirname, 'routes/v1/employeeInviteRoutes')), // Phase 3: Employee invite flow
  employeeSelfServiceRoutes: safeRequire(path.join(__dirname, 'routes/v1/employeeSelfServiceRoutes')), // Phase 3: Employee self-service equity API
  serviceProviderRoutes: safeRequire(path.join(__dirname, 'routes/v1/serviceProviderRoutes')), // Phase 4: Service provider invite flow
  auditLogRoutes: safeRequire(path.join(__dirname, 'routes/v1/auditLogRoutes')), // Phase 5: Audit logging
  readinessRoutes: safeRequire(path.join(__dirname, 'routes/v1/readinessRoutes')), // Issue #651: Investor readiness score
  clerkyIntegrationRoutes: safeRequire(path.join(__dirname, 'routes/v1/clerkyIntegrationRoutes')), // Issue #662: Clerky integration
  eightythreeBRoutes: safeRequire(path.join(__dirname, 'routes/v1/eightythreeBRoutes')), // Issue #667: 83(b) deadline tracking
  googleIntegrationRoutes: safeRequire(path.join(__dirname, 'routes/v1/googleIntegrationRoutes')), // Issue #234: Google Drive/Gmail integration
  emailTemplateRoutes: safeRequire(path.join(__dirname, 'routes/v1/emailTemplateRoutes')), // Email template CRUD
  mercuryRoutes: safeRequire(path.join(__dirname, 'routes/v1/mercuryRoutes')), // Issue #671: Mercury banking integration
  mercuryWebhookRoutes: safeRequire(path.join(__dirname, 'routes/v1/mercuryWebhookRoutes')), // Issue #678: Mercury webhooks
  investorPortalRoutes: safeRequire(path.join(__dirname, 'routes/v1/investorPortalRoutes')), // Issue #684: Investor portal summary, invite, access
  kycRoutes: safeRequire(path.join(__dirname, 'routes/v1/kycRoutes')), // KYC/Accredited Investor Verification
  // Optional routes that may not exist in all environments
  financialMetricsRoutes: safeRequire(path.join(__dirname, 'routes/v1/financialMetricsRoutes')),
  tenderOfferRoutes: safeRequire(path.join(__dirname, 'routes/v1/tenderOfferRoutes')), // Issue #167: Tender offer management
  paymentRoutes: safeRequire(path.join(__dirname, 'routes/v1/paymentRoutes')), // Issue #167: Payment processing
  subscriptionRoutes: safeRequire(path.join(__dirname, 'routes/v1/subscriptionRoutes')), // Issue #167: Subscription management
  subscriptionTierRoutes: safeRequire(path.join(__dirname, 'routes/v1/subscriptionTierRoutes')), // Issue #167: Subscription tiers
  webhookRoutes: safeRequire(path.join(__dirname, 'routes/v1/webhookRoutes')), // Issue #167: Application webhooks
  digitalSignatureRoutes: safeRequire(path.join(__dirname, 'routes/v1/digitalSignatureRoutes')), // Issue #167: Digital signatures
  documentFolderRoutes: safeRequire(path.join(__dirname, 'routes/v1/documentFolderRoutes')), // Issue #167: Document folders
  documentVersionRoutes: safeRequire(path.join(__dirname, 'routes/v1/documentVersionRoutes')), // Issue #167: Document versioning
  secondaryMarketRoutes: safeRequire(path.join(__dirname, 'routes/v1/secondaryMarketRoutes')), // Issue #167: Secondary market
  secondaryTransactionRoutes: safeRequire(path.join(__dirname, 'routes/v1/secondaryTransactionRoutes')), // Issue #167: Secondary transactions
  transferApprovalRoutes: safeRequire(path.join(__dirname, 'routes/v1/transferApprovalRoutes')), // Issue #167: Transfer approvals
  transferRequestRoutes: safeRequire(path.join(__dirname, 'routes/v1/transferRequestRoutes')), // Issue #167: Transfer requests
  scheduledTriggerRoutes: safeRequire(path.join(__dirname, 'routes/v1/scheduledTriggerRoutes')), // Issue #167: Scheduled triggers
  reportSchedulingRoutes: safeRequire(path.join(__dirname, 'routes/v1/reportSchedulingRoutes')), // Issue #167: Report scheduling
  reportAggregationRoutes: safeRequire(path.join(__dirname, 'routes/v1/reportAggregationRoutes')), // Issue #167: Report aggregation
};

// ── Public endpoints — mounted BEFORE any auth middleware ──
// Accept-invite is public (invite token IS the credential, no JWT needed)
const { acceptInvite } = require('./controllers/employeeInviteController');
app.post('/api/v1/employees/accept-invite', acceptInvite);

// Billing plans is public so pricing page works without login
app.get('/api/v1/billing/plans', billingController.getPlans);

// Newsletter subscribe is public (no auth needed)
const newsletterRoutes = require('./routes/v1/newsletterRoutes');
app.use('/api/v1/newsletter', newsletterRoutes);

// Support widget → ServiceOS (public, no auth — widget is on public pages)
const supportRoutes = require('./routes/v1/supportRoutes');
app.use('/api/v1/support', supportRoutes);

// Frontend URL for OAuth redirects (backend is api.opencapstack.com, frontend is opencapstack.com)
const FRONTEND_URL = process.env.FRONTEND_URL || 'https://opencapstack.com';

const oauthStates = new Map();
const OAUTH_STATE_TTL_MS = 10 * 60 * 1000;

function generateOAuthState(userId) {
  const state = crypto.randomBytes(16).toString('hex');
  oauthStates.set(state, { userId: userId || 'anonymous', createdAt: Date.now() });
  for (const [key, val] of oauthStates) {
    if (Date.now() - val.createdAt > OAUTH_STATE_TTL_MS) {
      oauthStates.delete(key);
    }
  }
  return state;
}

function consumeOAuthState(state) {
  const entry = oauthStates.get(state);
  if (!entry) return null;
  oauthStates.delete(state);
  if (Date.now() - entry.createdAt > OAUTH_STATE_TTL_MS) return null;
  return entry.userId;
}

// OAuth auth endpoints require authentication to prevent userId hijack (Issues #174, #169)
const axios = require('axios');

const GOOGLE_DRIVE_REDIRECT = `${process.env.NEXT_PUBLIC_API_URL || 'https://api.opencapstack.com'}/api/v1/connect/google/google-drive/callback`;
const GMAIL_REDIRECT = `${process.env.NEXT_PUBLIC_API_URL || 'https://api.opencapstack.com'}/api/v1/connect/google/gmail/callback`;

app.get('/api/v1/connect/google/google-drive/auth', authenticateToken, (req, res) => {
  const clientId = process.env.GOOGLE_CLIENT_ID;
  const scope = encodeURIComponent('https://www.googleapis.com/auth/drive.readonly https://www.googleapis.com/auth/gmail.readonly');
  const state = generateOAuthState(req.user.userId);
  const authUrl = `https://accounts.google.com/o/oauth2/v2/auth?client_id=${clientId}&redirect_uri=${encodeURIComponent(GOOGLE_DRIVE_REDIRECT)}&response_type=code&scope=${scope}&access_type=offline&prompt=consent&state=${encodeURIComponent(state)}`;
  res.redirect(authUrl);
});

app.get('/api/v1/connect/google/google-drive/callback', async (req, res) => {
  const { code, state, error: oauthError } = req.query;
  if (oauthError || !code) {
    console.error('Google OAuth error:', oauthError || 'no code');
    return res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?google=error&reason=' + encodeURIComponent(oauthError || 'no_code'));
  }
  try {
    const tokenParams = new URLSearchParams({
      code,
      client_id: process.env.GOOGLE_CLIENT_ID,
      client_secret: process.env.GOOGLE_CLIENT_SECRET,
      redirect_uri: GOOGLE_DRIVE_REDIRECT,
      grant_type: 'authorization_code',
    });
    const { data: tokens } = await axios.post('https://oauth2.googleapis.com/token', tokenParams.toString(), {
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    });

    if (!tokens.access_token) {
      console.error('Google token response missing access_token:', tokens);
      return res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?google=error&reason=no_access_token');
    }

    const { data: userInfo } = await axios.get('https://www.googleapis.com/oauth2/v2/userinfo', {
      headers: { Authorization: `Bearer ${tokens.access_token}` },
    });

    const userId = consumeOAuthState(decodeURIComponent(state || ''));
    if (!userId) {
      return res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?google=error&reason=invalid_state');
    }
    const zerodbService = require('./services/zerodbService');
    let encAccessToken = tokens.access_token;
    let encRefreshToken = tokens.refresh_token || null;
    try {
      const { encrypt } = require('./utils/tokenEncryption');
      encAccessToken = encrypt(tokens.access_token);
      if (tokens.refresh_token) {
        encRefreshToken = encrypt(tokens.refresh_token);
      }
    } catch (e) {
      console.warn('Token encryption unavailable, storing plaintext:', e.message);
    }
    await zerodbService.insertRow('integrations', {
      userId,
      provider: 'google',
      accessToken: encAccessToken,
      refreshToken: encRefreshToken,
      tokenExpiry: tokens.expires_in ? new Date(Date.now() + tokens.expires_in * 1000).toISOString() : null,
      email: userInfo.email,
      scopes: 'drive.readonly,gmail.readonly',
      connectedAt: new Date().toISOString(),
    });

    console.log(`Google connected for ${userInfo.email} (user: ${userId})`);
    res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?google=connected&email=' + encodeURIComponent(userInfo.email));
  } catch (err) {
    const detail = err.response?.data?.error_description || err.response?.data?.error || err.response?.data?.message || err.message;
    console.error('Google Drive connect failed:', { status: err.response?.status, detail, url: err.config?.url });
    res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?google=error&reason=' + encodeURIComponent(detail));
  }
});

app.get('/api/v1/connect/google/gmail/auth', authenticateToken, (req, res) => {
  const clientId = process.env.GOOGLE_CLIENT_ID;
  const scope = encodeURIComponent('https://www.googleapis.com/auth/gmail.readonly');
  const state = generateOAuthState(req.user.userId);
  const authUrl = `https://accounts.google.com/o/oauth2/v2/auth?client_id=${clientId}&redirect_uri=${encodeURIComponent(GMAIL_REDIRECT)}&response_type=code&scope=${scope}&access_type=offline&prompt=consent&state=${encodeURIComponent(state)}`;
  res.redirect(authUrl);
});

app.get('/api/v1/connect/google/gmail/callback', async (req, res) => {
  const { code, state, error: oauthError } = req.query;
  if (oauthError || !code) {
    return res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?gmail=error&reason=' + encodeURIComponent(oauthError || 'no_code'));
  }
  try {
    const tokenParams = new URLSearchParams({
      code,
      client_id: process.env.GOOGLE_CLIENT_ID,
      client_secret: process.env.GOOGLE_CLIENT_SECRET,
      redirect_uri: GMAIL_REDIRECT,
      grant_type: 'authorization_code',
    });
    const { data: tokens } = await axios.post('https://oauth2.googleapis.com/token', tokenParams.toString(), {
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    });

    if (!tokens.access_token) {
      console.error('Gmail token response missing access_token:', tokens);
      return res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?gmail=error&reason=no_access_token');
    }

    const { data: userInfo } = await axios.get('https://www.googleapis.com/oauth2/v2/userinfo', {
      headers: { Authorization: `Bearer ${tokens.access_token}` },
    });

    const userId = consumeOAuthState(decodeURIComponent(state || ''));
    if (!userId) {
      return res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?gmail=error&reason=invalid_state');
    }
    const zerodbService = require('./services/zerodbService');
    let encAccessToken = tokens.access_token;
    let encRefreshToken = tokens.refresh_token || null;
    try {
      const { encrypt } = require('./utils/tokenEncryption');
      encAccessToken = encrypt(tokens.access_token);
      if (tokens.refresh_token) {
        encRefreshToken = encrypt(tokens.refresh_token);
      }
    } catch (e) {
      console.warn('Token encryption unavailable, storing plaintext:', e.message);
    }
    await zerodbService.insertRow('integrations', {
      userId,
      provider: 'gmail',
      accessToken: encAccessToken,
      refreshToken: encRefreshToken,
      tokenExpiry: tokens.expires_in ? new Date(Date.now() + tokens.expires_in * 1000).toISOString() : null,
      email: userInfo.email,
      scopes: 'gmail.readonly',
      connectedAt: new Date().toISOString(),
    });

    console.log(`Gmail connected for ${userInfo.email} (user: ${userId})`);
    res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?gmail=connected&email=' + encodeURIComponent(userInfo.email));
  } catch (err) {
    const detail = err.response?.data?.error_description || err.response?.data?.error || err.response?.data?.message || err.message;
    console.error('Gmail connect failed:', { status: err.response?.status, detail, url: err.config?.url });
    res.redirect(FRONTEND_URL + '/data-rooms/reconstruct?gmail=error&reason=' + encodeURIComponent(detail));
  }
});

// ── Mercury OAuth endpoints (Issue #671) ──
const MERCURY_REDIRECT = `${process.env.NEXT_PUBLIC_API_URL || 'https://api.opencapstack.com'}/api/v1/connect/mercury/callback`;

app.get('/api/v1/connect/mercury/auth', authenticateToken, (req, res) => {
  const clientId = process.env.MERCURY_CLIENT_ID;
  if (!clientId) {
    return res.status(500).json({ error: 'Mercury integration not configured' });
  }
  const state = generateOAuthState(req.user.userId);
  const authUrl = `https://app.mercury.com/oauth/authorize?client_id=${clientId}&redirect_uri=${encodeURIComponent(MERCURY_REDIRECT)}&response_type=code&state=${encodeURIComponent(state)}`;
  res.redirect(authUrl);
});

app.get('/api/v1/connect/mercury/callback', async (req, res) => {
  const { code, state, error: oauthError } = req.query;
  if (oauthError || !code) {
    console.error('Mercury OAuth error:', oauthError || 'no code');
    return res.redirect(FRONTEND_URL + '/settings/integrations?mercury=error&reason=' + encodeURIComponent(oauthError || 'no_code'));
  }
  try {
    const { data: tokens } = await axios.post('https://api.mercury.com/oauth/token', {
      code,
      client_id: process.env.MERCURY_CLIENT_ID,
      client_secret: process.env.MERCURY_CLIENT_SECRET,
      redirect_uri: MERCURY_REDIRECT,
      grant_type: 'authorization_code',
    });

    const userId = consumeOAuthState(decodeURIComponent(state || ''));
    if (!userId) {
      return res.redirect(FRONTEND_URL + '/settings/integrations?mercury=error&reason=invalid_state');
    }
    const zerodbSvc = require('./services/zerodbService');
    let encAccessToken = tokens.access_token;
    let encRefreshToken = tokens.refresh_token || null;
    try {
      const { encrypt } = require('./utils/tokenEncryption');
      encAccessToken = encrypt(tokens.access_token);
      if (tokens.refresh_token) {
        encRefreshToken = encrypt(tokens.refresh_token);
      }
    } catch (e) {
      console.warn('Token encryption unavailable, storing plaintext:', e.message);
    }
    await zerodbSvc.insertRow('integrations', {
      userId,
      provider: 'mercury',
      accessToken: encAccessToken,
      refreshToken: encRefreshToken,
      tokenExpiry: tokens.expires_in ? new Date(Date.now() + tokens.expires_in * 1000).toISOString() : null,
      connectedAt: new Date().toISOString(),
    });

    console.log(`Mercury connected for user: ${userId}`);
    res.redirect(FRONTEND_URL + '/settings/integrations?mercury=connected');
  } catch (err) {
    console.error('Mercury token exchange failed:', err.response?.data || err.message);
    res.redirect(FRONTEND_URL + '/settings/integrations?mercury=error&reason=' + encodeURIComponent(err.message));
  }
});

app.delete('/api/v1/connect/mercury/disconnect', require('./middleware/authMiddleware').authenticateToken, async (req, res) => {
  try {
    const userId = req.user.userId;
    if (!userId) {
      return res.status(400).json({ error: 'Authenticated user has no userId' });
    }

    const zerodbSvc = require('./services/zerodbService');

    // Look up the integration to attempt token revocation
    const result = await zerodbSvc.queryRows('integrations', { userId, provider: 'mercury' }, { limit: 1 });
    const rows = result?.data || [];

    if (rows.length > 0) {
      const record = rows[0].row_data;
      // Best-effort revocation — Mercury may not support explicit revocation
      try {
        await axios.post('https://api.mercury.com/oauth/revoke', {
          token: record.accessToken,
          client_id: process.env.MERCURY_CLIENT_ID,
          client_secret: process.env.MERCURY_CLIENT_SECRET,
        });
      } catch (_revokeErr) {
        // Revocation is best-effort; continue with local cleanup
      }

      await zerodbSvc.deleteRowById('integrations', rows[0].row_id);
    }

    res.status(200).json({ success: true, message: 'Mercury disconnected' });
  } catch (err) {
    console.error('Mercury disconnect failed:', err.message);
    res.status(500).json({ error: 'Failed to disconnect Mercury' });
  }
});

// Authenticate tokens at app level so req.user is set before company-scope checks
app.use('/api/v1', (req, res, next) => {
  const skipPaths = ['/auth', '/health', '/agents', '/mcp', '/plugin', '/webhooks', '/reconstruct', '/readiness', '/connect', '/employees/accept-invite', '/billing/plans', '/billing/webhook', '/newsletter', '/support', '/service-providers/accept-invite'];
  if (skipPaths.some(p => req.path.startsWith(p))) {
    return next();
  }
  return authenticateToken(req, res, next);
});

// Apply company-scope authorization to all API routes (after auth above)
app.use('/api/v1', (req, res, next) => {
  const skipPaths = ['/auth', '/health', '/agents', '/mcp', '/plugin', '/webhooks', '/reconstruct', '/readiness', '/connect', '/employees/accept-invite', '/billing/plans', '/billing/webhook', '/companies', '/newsletter', '/support', '/service-providers/accept-invite'];
  if (skipPaths.some(p => req.path.startsWith(p))) {
    return next();
  }
  return verifyCompanyAccess()(req, res, next);
});

app.use('/api/v1', (req, res, next) => {
  const skipPaths = ['/auth', '/health', '/agents', '/mcp', '/plugin', '/webhooks', '/reconstruct', '/readiness', '/connect', '/employees/accept-invite', '/billing/plans', '/billing/webhook', '/companies', '/newsletter', '/support', '/service-providers/accept-invite'];
  if (skipPaths.some(p => req.path.startsWith(p))) {
    return next();
  }
  return enforceCompanyScope(req, res, next);
});

// Mount routes with correct paths
Object.entries(routes).forEach(([key, route]) => {
  // Skip if route is null or undefined
  if (!route) {
    return;
  }
  if (route) {
    let path;
    // Special case for auth routes
    if (key === 'authRoutes') {
      path = '/api/v1/auth';
    } else if (key === 'investmentTrackerRoutes') {
      path = '/api/v1/investments';
    } else if (key === 'financialReportRoutes') {
      path = '/api/v1/financial-reports';
    } else if (key === 'documentEmbeddingRoutes') {
      path = '/api/v1/document-embeddings';
    } else if (key === 'documentAccessRoutes') {
      path = '/api/v1/document-accesses';
    } else if (key === 'fundraisingRoundRoutes') {
      path = '/api/v1/fundraising-rounds';
    } else if (key === 'equityPlanRoutes') {
      path = '/api/v1/equity-plans';
    } else if (key === 'shareClassRoutes') {
      path = '/api/v1/share-classes';
    } else if (key === 'stakeholderRoutes') {
      path = '/api/v1/stakeholders';
    } else if (key === 'documentRoutes') {
      path = '/api/v1/documents';
    } else if (key === 'spvAssetRoutes') {
      path = '/api/v1/spv-assets';
    } else if (key === 'spvRoutes') {
      path = '/api/v1/spvs';
    } else if (key === 'complianceCheckRoutes') {
      path = '/api/v1/compliance-checks';
    } else if (key === 'integrationModuleRoutes') {
      path = '/api/v1/integration-modules';
    } else if (key === 'financialMetricsRoutes') {
      path = '/api/v1/metrics';
    } else if (key === 'taxCalculatorRoutes') {
      path = '/api/v1/tax-calculations';
    } else if (key === 'inviteManagementRoutes') {
      path = '/api/v1/invites';
    } else if (key === 'securityAuditRoutes') {
      path = '/api/v1/security-audits';
    } else if (key === 'financialDataRoutes') {
      path = '/api/v1/financial-data';
    } else if (key === 'semanticSearchRoutes') {
      path = '/api/v1/documents/search';
    } else if (key === 'searchRoutes') {
      path = '/api/v1/search';
    } else if (key === 'agentMemoryRoutes') {
      path = '/api/v1/agent-memory';
    } else if (key === 'rlhfRoutes') {
      path = '/api/v1/rlhf';
    } else if (key === 'advancedAnalyticsRoutes') {
      path = '/api/v1/analytics';
    } else if (key === 'eventStreamingRoutes') {
      path = '/api/v1/events';
    } else if (key === 'fileStorageRoutes') {
      path = '/api/v1/files';
    } else if (key === 'safeRoutes') {
      path = '/api/v1/safes';
    } else if (key === 'taskRoutes') {
      path = '/api/v1/tasks';
    } else if (key === 'healthRoutes') {
      path = '/api/v1/health';
    } else if (key === 'valuation409ARoutes') {
      path = '/api/v1/valuations';
    } else if (key === 'valuation409AExportRoutes') {
      path = '/api/v1/valuations/export';
    } else if (key === 'materialEventRoutes') {
      path = '/api/v1/material-events';
    } else if (key === 'valuationPartnerRoutes') {
      path = '/api/v1/valuation-partners';
    } else if (key === 'equityGrantRoutes') {
      path = '/api/v1/equity-grants';
    } else if (key === 'exerciseRoutes') {
      path = '/api/v1'; // Routes already have /exercise-requests prefix
    } else if (key === 'terminationRoutes') {
      path = '/api/v1/terminations';
    } else if (key === 'investorRightsRoutes') {
      path = '/api/v1/investor-rights';
    } else if (key === 'emailTrackingRoutes') {
      path = '/api/v1/email-tracking';
    } else if (key === 'bulkMessageRoutes') {
      path = '/api/v1/bulk-messages';
    } else if (key === 'investorCommunicationRoutes') {
      path = '/api/v1/investor-communications';
    } else if (key === 'messageTriggerRoutes') {
      path = '/api/v1/message-triggers';
    } else if (key === 'securityIssuanceRoutes') {
      path = '/api/v1/security-issuances';
    } else if (key === 'vestingScheduleRoutes') {
      path = '/api/v1';
    } else if (key === 'equityPlanReportRoutes') {
      path = '/api/v1/equity-plan-reports';
    } else if (key === 'financialAnalyticsRoutes') {
      path = '/api/v1/financial-analytics';
    } else if (key === 'riskAssessmentRoutes') {
      path = '/api/v1/risk-assessment';
    } else if (key === 'currencyRoutes') {
      path = '/api/v1/currency';
    } else if (key === 'waterfallAnalysisRoutes') {
      path = '/api/v1'; // Routes already have /waterfall-analyses prefix
    } else if (key === 'documentAuditRoutes') {
      path = '/api/v1/audit'; // Issue #102: Document Audit Trail
    } else if (key === 'cacheRoutes') {
      path = '/api/v1/cache'; // Issue #47: Database Optimization and Caching
    } else if (key === 'customReportRoutes') {
      path = '/api/v1/reports/custom'; // Issue #197: Custom Report Builder Engine
    } else if (key === 'dataRoomRoutes') {
      path = '/api/v1/data-rooms'; // Issue #194: Data Room Backend Infrastructure
    } else if (key === 'reportLibraryRoutes') {
      path = '/api/v1/reports'; // Issue #199: Report Library Categorization
    } else if (key === 'integrationMarketplaceRoutes') {
      path = '/api/v1/integrations'; // Issue #202: Integration Marketplace
    } else if (key === 'documentTemplateRoutes') {
      path = '/api/v1/templates'; // Issue #193: Document Template System
    } else if (key === 'fundraisingAnalyticsRoutes') {
      path = '/api/v1/fundraising'; // Issue #196: Fundraising Analytics Service
    } else if (key === 'billingRoutes') {
      path = '/api/v1/billing'; // Issue #201: Billing Dashboard APIs
    } else if (key === 'stakeholderReportRoutes') {
      path = '/api/v1/stakeholder-reports'; // Issue #198: Stakeholder Report Generation
    } else if (key === 'userRoutes') {
      path = '/api/v1/users';
    } else if (key === 'accessPolicyRoutes') {
      path = '/api/v1/access-policies'; // Issue #247: Access Policies Endpoints
    } else if (key === 'accessGroupRoutes') {
      path = '/api/v1/access-groups'; // Issue #274: Access Groups Endpoints
    } else if (key === 'taxDocumentRoutes') {
      path = '/api/v1/tax-documents'; // Issue #246: Tax Document Download Endpoint
    } else if (key === 'bulkReportsRoutes') {
      path = '/api/v1/reports/bulk'; // Issue #238: Bulk Reports Endpoint
    } else if (key === 'notificationRoutes') {
      path = '/api/v1/notifications';
    } else if (key === 'companyRoutes') {
      path = '/api/v1/companies';
    } else if (key === 'fundraiseModelRoutes') {
      path = '/api/v1/fundraise-models'; // Issue #195: Fundraising Modeling Engine
    } else if (key === 'agentOnboardingRoutes') {
      path = '/api/v1/agents';
    } else if (key === 'mcpRoutes') {
      path = '/api/v1/mcp'; // Issue #495: MCP Server — accessible at /api/v1/mcp and /api/v1/mcp/sse
    } else if (key === 'pluginAuthRoutes') {
      path = '/api/v1/auth/plugin'; // Issue #505: Plugin OAuth
    } else if (key === 'pluginRoutes') {
      path = '/api/v1/plugin'; // Issue #506: Plugin tools
    } else if (key === 'activityRoutes') {
      path = '/api/v1/activities';
    } else if (key === 'boardMeetingRoutes') {
      path = '/api/v1/board-meetings';
    } else if (key === 'boardMemberRoutes') {
      path = '/api/v1/board-members';
    } else if (key === 'boardResolutionRoutes') {
      path = '/api/v1/board-resolutions';
    } else if (key === 'messageRoutes') {
      path = '/api/v1/messages';
    } else if (key === 'accountantRoutes') {
      path = '/api/v1/accountant';
    } else if (key === 'investorDatabaseRoutes') {
      path = '/api/v1/investor-database';
    } else if (key === 'dataRoomReconstructRoutes') {
      path = '/api/v1/reconstruct'; // Issue #631: AI Data Room Reconstruction
    } else if (key === 'migrationRoutes') {
      path = '/api/v1/migration'; // Issue #652: Carta migration score tool
    } else if (key === 'exportRoutes') {
      path = '/api/v1/exports'; // CSV/XLSX export endpoints
    } else if (key === 'capTableHealthRoutes') {
      path = '/api/v1/cap-table'; // Issue #660: Cap table health scorecard
    } else if (key === 'scenarioRoutes') {
      path = '/api/v1/scenarios'; // Issue #661: Scenario modeling unified endpoint
    } else if (key === 'employeeInviteRoutes') {
      path = '/api/v1/employees'; // Phase 3: Employee invite flow
    } else if (key === 'employeeSelfServiceRoutes') {
      path = '/api/v1/me'; // Phase 3: Employee self-service equity API
    } else if (key === 'serviceProviderRoutes') {
      path = '/api/v1/service-providers'; // Phase 4: Service provider invite flow
    } else if (key === 'auditLogRoutes') {
      path = '/api/v1/audit-logs'; // Phase 5: Audit logging
    } else if (key === 'readinessRoutes') {
      path = '/api/v1/readiness'; // Issue #651: Investor readiness score
    } else if (key === 'clerkyIntegrationRoutes') {
      path = '/api/v1/integrations/clerky'; // Issue #662: Clerky integration
    } else if (key === 'eightythreeBRoutes') {
      path = '/api/v1/compliance'; // Issue #667: 83(b) deadline tracking
    } else if (key === 'googleIntegrationRoutes') {
      path = '/api/v1/connect/google'; // Issue #234: Google Drive/Gmail integration (separate from /integrations to avoid auth conflict)
    } else if (key === 'emailTemplateRoutes') {
      path = '/api/v1/email-templates'; // Email template CRUD
    } else if (key === 'mercuryRoutes') {
      path = '/api/v1/integrations/mercury'; // Issue #671: Mercury banking integration
    } else if (key === 'mercuryWebhookRoutes') {
      path = '/api/v1/webhooks/mercury'; // Issue #678: Mercury webhooks
    } else if (key === 'investorPortalRoutes') {
      path = '/api/v1/investor-portal'; // Issue #684: Investor portal summary, invite, access
    } else if (key === 'kycRoutes') {
      path = '/api/v1/kyc'; // KYC/Accredited Investor Verification
    } else if (key === 'tenderOfferRoutes') {
      path = '/api/v1/tender-offers';
    } else if (key === 'paymentRoutes') {
      path = '/api/v1/payments';
    } else if (key === 'subscriptionRoutes') {
      path = '/api/v1/subscriptions';
    } else if (key === 'subscriptionTierRoutes') {
      path = '/api/v1/subscription-tiers';
    } else if (key === 'webhookRoutes') {
      path = '/api/v1/webhooks/app';
    } else if (key === 'digitalSignatureRoutes') {
      path = '/api/v1/digital-signatures';
    } else if (key === 'documentFolderRoutes') {
      path = '/api/v1/document-folders';
    } else if (key === 'documentVersionRoutes') {
      path = '/api/v1/document-versions';
    } else if (key === 'secondaryMarketRoutes') {
      path = '/api/v1/secondary-market';
    } else if (key === 'secondaryTransactionRoutes') {
      path = '/api/v1/secondary-transactions';
    } else if (key === 'transferApprovalRoutes') {
      path = '/api/v1/transfer-approvals';
    } else if (key === 'transferRequestRoutes') {
      path = '/api/v1/transfer-requests';
    } else if (key === 'scheduledTriggerRoutes') {
      path = '/api/v1/scheduled-triggers';
    } else if (key === 'reportSchedulingRoutes') {
      path = '/api/v1/report-scheduling';
    } else if (key === 'reportAggregationRoutes') {
      path = '/api/v1/report-aggregation';
    } else {
      path = `/api/v1/${key.replace('Routes', '').toLowerCase()}`;
    }
    
    // Ensure the route is a function before mounting
    if (typeof route === 'function') {
      app.use(path, route);
    } else {
      console.error(`Route ${key} is not a valid middleware function`);
    }
  }
});

// Route aliases for frontend compatibility
// These map alternative path names the frontend uses to the actual backend routes
const stakeholderRouteModule = safeRequire(path.join(__dirname, 'routes/v1/stakeholderRoutes'));
const securityIssuanceRouteModule = safeRequire(path.join(__dirname, 'routes/v1/securityIssuanceRoutes'));
const safeRouteModule = safeRequire(path.join(__dirname, 'routes/v1/safeRoutes'));
if (stakeholderRouteModule) app.use('/api/v1/shareholders', stakeholderRouteModule);
if (securityIssuanceRouteModule) app.use('/api/v1/securities', securityIssuanceRouteModule);
if (safeRouteModule) app.use('/api/v1/safe-agreements', safeRouteModule);
// employees — employeeInviteRoutes (registered above as employeeInviteRoutes at /api/v1/employees)
// handles all employee endpoints including the public accept-invite route.
// Do NOT mount employeeRoutes here — it has router.use(authenticateToken) which
// blocks the public accept-invite endpoint with a 401.
// spv — frontend calls /spv but backend registered at /spvs; alias /spv → /spvs
const spvRouteModule = safeRequire(path.join(__dirname, 'routes/v1/spvRoutes'));
if (spvRouteModule) app.use('/api/v1/spv', spvRouteModule);
// investors (plural) — alias for investor route (singular registered by generic mapper)
const investorRouteModuleAlias = safeRequire(path.join(__dirname, 'routes/v1/investorRoutes'));
if (investorRouteModuleAlias) app.use('/api/v1/investors', investorRouteModuleAlias);
// Scenarios — CRUD stubs moved to scenarioRoutes (Issue #176: RBAC enforcement)

// RBAC middleware for stub route mutations (Issue #180)
const { requireUserNotAgent, hasRole } = require('./middleware/rbacMiddleware');

// Stub routes for frontend pages that have no backend implementation yet
// Returns empty arrays so pages load gracefully without errors
const _stub = (req, res) => res.json([]);
const _stubObj = (req, res) => res.json({});
app.get('/api/v1/assets', _stub);
app.post('/api/v1/assets', hasRole(['admin', 'super_admin', 'founder']), (req, res) => res.status(201).json({ id: Date.now().toString(), status: 'created' }));
// board-resolutions stubs removed — now served by boardResolutionRoutes
app.get('/api/v1/email-templates/history', _stub);
app.get('/api/v1/exports', _stub);
app.post('/api/v1/exports', hasRole(['admin', 'super_admin', 'founder']), (req, res) => res.status(202).json({ status: 'queued', id: Date.now().toString() }));
// document-access (frontend) → document-accesses (backend)
const documentAccessRouteModule = safeRequire(path.join(__dirname, 'routes/v1/documentAccessRoutes'));
if (documentAccessRouteModule) app.use('/api/v1/document-access', documentAccessRouteModule);

const apiKeyRouteModule = safeRequire(path.join(__dirname, 'routes/v1/apiKeyRoutes'));
if (apiKeyRouteModule) app.use('/api/v1/api-keys', apiKeyRouteModule);
// billing sub-routes — frontend calls /billing/current but backend has /billing/current-plan
app.get('/api/v1/billing/current', authenticateToken, requireUserNotAgent, billingController.getCurrentPlan);
// integrations connect/disconnect — now served by integrationMarketplaceRoutes (#582)
// fundraising-analytics — alias → /api/v1/fundraising
const fundraisingAnalyticsRouteModule = safeRequire(path.join(__dirname, 'routes/v1/fundraisingAnalyticsRoutes'));
if (fundraisingAnalyticsRouteModule) app.use('/api/v1/fundraising-analytics', fundraisingAnalyticsRouteModule);
// advanced analytics summary stub
app.get('/api/v1/advanced-analytics/summary', _stubObj);
// fundraising-scenarios stub (used by fundraise model page)
app.get('/api/v1/fundraising-scenarios', _stub);
app.post('/api/v1/fundraising-scenarios', hasRole(['admin', 'super_admin', 'founder']), (req, res) => res.status(201).json({ id: Date.now().toString(), status: 'created' }));

// Health check endpoint - must be before error handlers
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'ok', message: 'Server is running', build: process.env.BUILD_SHA || 'unknown' });
});

// ZeroDB health check endpoint
app.get('/health/zerodb', async (req, res) => {
  try {
    if (!zerodbService.projectId) {
      return res.status(503).json({
        status: 'error',
        message: 'ZeroDB not initialized',
        enabled: process.env.ENABLE_ZERODB === 'true'
      });
    }
    const dbStatus = await zerodbService.getDatabaseStatus();
    res.status(200).json({
      status: 'ok',
      projectId: zerodbService.projectId,
      zerodb: dbStatus
    });
  } catch (error) {
    res.status(503).json({
      status: 'error',
      message: error.message,
      details: process.env.NODE_ENV === 'development' ? error.stack : undefined
    });
  }
});

// Global error handler - must be after all routes (Issue #357)
const { errorResponse } = require('./middleware/errorResponse');
app.use((err, req, res, next) => {
  console.error('Unhandled error:', err);
  const status = err.status || err.statusCode || 500;
  const message = err.message || 'Internal server error';
  errorResponse(res, status, message, err);
});

// Domain-based routing:
//   api.opencapstack.com  → Express API only (returns 404 for non-API routes)
//   opencapstack.com      → Proxy all non-API requests to Next.js (port 5173)
//
// Both domains point to the same Railway container. The Host header determines
// whether a request is for the API or the UI.
const NEXT_PORT = process.env.NEXT_PORT || 5173;
const API_HOST = process.env.API_HOST || 'api.opencapstack.com';
const http = require('http');

app.use('*', (req, res) => {
  const host = (req.headers.host || '').split(':')[0].toLowerCase();

  // If request is coming to the API domain, don't proxy — it's a real 404
  if (host === API_HOST || host === 'localhost' || host === '127.0.0.1') {
    return errorResponse(res, 404, 'Route not found');
  }

  // Frontend domain (opencapstack.com) — proxy GET/HEAD to Next.js
  if (req.method !== 'GET' && req.method !== 'HEAD') {
    return errorResponse(res, 404, 'Route not found');
  }

  const options = {
    hostname: '127.0.0.1',
    port: NEXT_PORT,
    path: req.originalUrl,
    method: req.method,
    headers: { ...req.headers, host: `localhost:${NEXT_PORT}` },
  };

  const proxy = http.request(options, (proxyRes) => {
    res.writeHead(proxyRes.statusCode, proxyRes.headers);
    proxyRes.pipe(res, { end: true });
  });

  proxy.on('error', () => {
    errorResponse(res, 404, 'Route not found');
  });

  req.pipe(proxy, { end: true });
});

// Set up server and start listening
if (process.env.NODE_ENV !== 'test') {
  const PORT = process.env.PORT || 3000;
  // Start HTTP server immediately so healthcheck responds during DB init
  const startServer = async () => {
    const srv = app.listen(PORT, () => {
      console.log(`🚀 Server running on port ${PORT}`);
      console.log(`📚 API Documentation available at http://localhost:${PORT}/api-docs`);
    });
    // ZeroDB initializes in background — startup failure is logged but not fatal
    zerodbReady.catch(err => {
      console.error('⚠️  ZeroDB initialization failed (server still running):', err.message);
    });
    return srv;
  };
  const server = startServer().catch(err => {
    console.error('Server startup failed:', err);
    process.exit(1);
  });

  // Issue #388: Use enhanced graceful shutdown utility
  const { setupGracefulShutdown, registerCleanupHandler } = require('./utils/gracefulShutdown');

  // Register ZeroDB cleanup (if needed in future for persistent connections)
  registerCleanupHandler(
    async () => {
      console.log('ZeroDB cleanup (stateless HTTP API, no persistent connections)');
    },
    'ZeroDB Cleanup'
  );

  // Setup graceful shutdown after server starts
  server.then(srv => {
    if (srv) setupGracefulShutdown(srv);
  });

  // Catch unhandled promise rejections and uncaught exceptions
  process.on('unhandledRejection', (reason, promise) => {
    console.error('Unhandled Promise Rejection:', reason);
    // Don't crash — log and continue
  });

  process.on('uncaughtException', (error) => {
    console.error('Uncaught Exception:', error);
    // Give time for logging, then exit
    setTimeout(() => process.exit(1), 1000);
  });
}

module.exports = app;