/** * RoutesV2 - Canonical Route Map for All Trader Services * * This is the SINGLE SOURCE OF TRUTH for all API endpoints. * All teams (Frontend, ML, Infra) must import from here. * * OWNED BY: Contracts Team * CONSUMERS: Frontend, ML, Infra teams * * Route Categories: * - Frontend: Next.js API routes that proxy to upstream services * - ML: Direct ML service endpoints for signals and predictions * - Infra: IG trading data and portfolio management * - System: Health checks and system status */ // Base URL constants const API_BASE = '/api'; const ML_BASE = '/api/ml'; const IG_BASE = '/api/ig'; const WEALTH_BASE = '/api/wealth'; const PORTFOLIO_BASE = '/api/portfolio'; const ACCOUNTS_BASE = '/api/accounts'; const TRADES_BASE = '/api/trades'; /** * Canonical Route Definitions * * All routes follow the pattern: /api/{service}/{resource} * Deprecated routes are marked and will be removed in v0.14.0 */ export const RoutesV2 = { // ===== FRONTEND API SURFACE ===== // These are Next.js API routes that proxy to upstream services /** Canonical FE health probe. Surface: Frontend API. */ Health: `${API_BASE}/health`, /** Frontend signals query endpoint. Surface: Frontend API. */ SignalsQuery: `${API_BASE}/signals`, /** Frontend ML prediction endpoint. Surface: Frontend API. */ MlPredict: `${API_BASE}/ml/predict`, /** Frontend ML backtest endpoint. Surface: Frontend API. */ MlBacktest: `${API_BASE}/ml/backtest`, /** Frontend portfolio summary endpoint. Surface: Frontend API. */ PortfolioSummary: `${PORTFOLIO_BASE}/summary`, /** Frontend wealth summary endpoint. Surface: Frontend API. */ WealthHl: `${WEALTH_BASE}/hl`, /** Frontend trading accounts endpoint. Surface: Frontend API. */ TradingAccounts: `${ACCOUNTS_BASE}/trading`, /** Frontend open trades endpoint. Surface: Frontend API. */ TradesOpen: `${TRADES_BASE}/open`, /** Frontend closed trades endpoint. Surface: Frontend API. */ TradesClosed: `${TRADES_BASE}/closed`, /** Frontend enhanced holdings endpoint. Surface: Frontend API. */ HoldingsEnhanced: `${API_BASE}/holdings/enhanced`, // ===== ML SERVICE ENDPOINTS ===== // These are direct ML service endpoints /** ML service health check. Surface: ML Service. */ MlHealth: `${ML_BASE}/health`, /** ML service ready status. Surface: ML Service. */ MlReady: `${ML_BASE}/ready`, /** ML service signals endpoint. Surface: ML Service. */ MlSignals: `${ML_BASE}/signals`, /** ML service models endpoint. Surface: ML Service. */ MlModels: `${ML_BASE}/models`, /** ML service schema endpoint. Surface: ML Service. */ MlSchema: `${ML_BASE}/schema`, // ===== v0.15.0 NEW ML ENDPOINTS ===== // These extend the ML service with new matrix and consensus capabilities /** ML signals matrix endpoint. Surface: ML Service. */ MlSignalsMatrix: `${ML_BASE}/signals/matrix`, /** ML latest signals endpoint. Surface: ML Service. */ MlSignalsLatest: `${ML_BASE}/signals/latest`, /** ML consensus decision endpoint. Surface: ML Service. */ MlConsensus: `${ML_BASE}/consensus`, /** ML indicators panel endpoint. Surface: ML Service. */ MlIndicatorsPanel: `${ML_BASE}/panels/indicators`, /** ML signals stream endpoint (SSE). Surface: ML Service. */ MlSignalsStream: `${ML_BASE}/signals/stream`, /** ML indicators catalog endpoint. Surface: ML Service. */ MlIndicatorsCatalog: `${ML_BASE}/indicators`, /** ML reinforcement learning endpoint. Surface: ML Service. */ MlRL: `${ML_BASE}/rl`, /** ML models registry endpoint. Surface: ML Service. */ MlModelsRegistry: `${ML_BASE}/models/registry`, // ===== v0.15.2 INTERNAL ML ENDPOINTS ===== // These are internal endpoints for ML team to persist data to Infra // Authentication required: x-ml-service-token header /** Internal features upsert endpoint. Surface: Infra Service (ML team only). */ MlInternalFeaturesUpsert: `${API_BASE}/internal/ml/features/upsert`, /** Internal signals matrix upsert endpoint. Surface: Infra Service (ML team only). */ MlInternalSignalsMatrixUpsert: `${API_BASE}/internal/ml/signals/matrix/upsert`, /** Internal consensus upsert endpoint. Surface: Infra Service (ML team only). */ MlInternalConsensusUpsert: `${API_BASE}/internal/ml/consensus/upsert`, /** Internal trades upsert endpoint. Surface: Infra Service (ML team only). */ MlInternalTradesUpsert: `${API_BASE}/internal/ml/trades/upsert`, // ===== v0.15.2 ML-SIM INTEGRATION ROUTES ===== // These are new endpoints for ML-SIM integration capabilities /** ML-SIM simulation start endpoint. Surface: ML Service (ML team only). */ MlSimulationStart: `${ML_BASE}/simulation/start`, /** ML-SIM simulation status endpoint. Surface: ML Service (ML team only). */ MlSimulationStatus: `${ML_BASE}/simulation/status`, /** ML-SIM simulation refresh endpoint. Surface: ML Service (ML team only). */ MlSimulationRefresh: `${ML_BASE}/simulation/refresh`, /** ML-SIM training start endpoint. Surface: ML Service (ML team only). */ MlTrainingStart: `${ML_BASE}/training/start`, /** ML-SIM training status endpoint. Surface: ML Service (ML team only). */ MlTrainingStatus: `${ML_BASE}/training/status`, /** ML-SIM training results endpoint. Surface: ML Service (ML team only). */ MlTrainingResults: `${ML_BASE}/training/results`, /** ML-SIM portfolio status endpoint. Surface: ML Service (ML team only). */ MlSimPortfolioStatus: `${ML_BASE}/simulation/portfolio`, /** ML-SIM portfolio positions endpoint. Surface: ML Service (ML team only). */ MlSimPortfolioPositions: `${ML_BASE}/simulation/positions`, /** ML-SIM portfolio history endpoint. Surface: ML Service (ML team only). */ MlSimPortfolioHistory: `${ML_BASE}/simulation/history`, // ===== INFRA SERVICE ENDPOINTS ===== // These are IG trading data endpoints /** Infra service health check. Surface: Infra Service. */ InfraHealth: `${API_BASE}/infra/health`, /** IG accounts data endpoint. Surface: Infra Service. */ IgAccounts: `${IG_BASE}/accounts`, /** IG positions data endpoint. Surface: Infra Service. */ IgPositions: `${IG_BASE}/positions`, /** IG portfolio data endpoint. Surface: Infra Service. */ IgPortfolio: `${IG_BASE}/portfolio`, /** IG health check endpoint. Surface: Infra Service. */ IgHealth: `${IG_BASE}/health`, /** Portfolio health check endpoint. Surface: Infra Service. */ PortfolioHealth: `${PORTFOLIO_BASE}/health`, /** Market prices endpoint. Surface: Infra Service. */ MarketPrices: `${API_BASE}/market/prices`, /** Instrument mapping endpoint. Surface: Infra Service. */ InstrumentMap: `${API_BASE}/market/instruments`, // ===== v0.15.3 IG-SIM INTEGRATION ROUTES ===== // These are simulation endpoints for IG trading (demo/sim mode only) /** IG-SIM endpoints group. Surface: Infra Service. */ IgSim: { /** IG-SIM health check endpoint. */ Health: `${IG_BASE}/sim/health`, /** IG-SIM price stream endpoint (SSE). */ StreamPrices: `${IG_BASE}/sim/stream`, /** IG-SIM order placement endpoint. */ PlaceOrder: `${IG_BASE}/sim/order`, /** IG-SIM account snapshot endpoint. */ Account: `${IG_BASE}/sim/account`, /** IG-SIM reset endpoint. */ Reset: `${IG_BASE}/sim/reset`, }, // Historic price data endpoints Prices: `${API_BASE}/prices`, PricesSymbol: `${API_BASE}/prices/{symbol}`, PricesHistory: `${API_BASE}/prices/{symbol}/history`, PricesHistoric: `${API_BASE}/prices/historic`, // ML Overlays endpoint MlOverlays: `${API_BASE}/ml/overlays`, // ===== ADDITIONAL ML ROUTE CONSTANTS ===== // These are additional routes requested by ML team /** ML legacy batch signals endpoint. Surface: ML Service. */ MlLegacyBatchSignals: `${ML_BASE}/signals/batch`, // ===== v0.15.3 IG ADAPTER ROUTES ===== // These are new endpoints for IG adapter integration /** IG market data endpoint. Surface: Infra Service. */ IgMarketData: `${IG_BASE}/market-data`, /** IG order simulation endpoint. Surface: Infra Service. */ IgOrderSimulation: `${IG_BASE}/order-simulation`, /** IG live trade configuration endpoint. Surface: Infra Service. */ IgLiveTradeConfig: `${IG_BASE}/live-trade-config`, // ===== v0.15.3 ML SIMULATION ROUTES ===== // These are new endpoints for ML simulation integration /** ML live signals endpoint. Surface: ML Service. */ MlSignalsLive: `${ML_BASE}/signals/live`, // ===== DEPRECATED ROUTES ===== // These will be removed in v0.14.0 - DO NOT USE /** @deprecated Use RoutesV2.SignalsQuery instead */ MlSignalsGenerate: `${ML_BASE}/signals/generate`, // DEPRECATED: Use RoutesV2.SignalsQuery /** @deprecated Use RoutesV2.Health instead */ HealthDb: `${API_BASE}/health/db`, // DEPRECATED: Use RoutesV2.Health /** @deprecated Use RoutesV2.MlHealth instead */ MlHealthBacktest: `${ML_BASE}/health/backtest`, // DEPRECATED: Use RoutesV2.MlHealth /** @deprecated Use RoutesV2.MlSignals instead */ MlLogs: `${ML_BASE}/logs`, // DEPRECATED: Use RoutesV2.MlSignals /** @deprecated Use RoutesV2.MlSignals instead */ MlRuns: `${ML_BASE}/runs`, // DEPRECATED: Use RoutesV2.MlSignals /** @deprecated Use RoutesV2.PortfolioSummary instead */ PortfolioFunds: `${PORTFOLIO_BASE}/funds`, // DEPRECATED: Use RoutesV2.PortfolioSummary /** @deprecated Use RoutesV2.IgPortfolio instead */ IgPortfolioLegacy: `${IG_BASE}/portfolio/legacy`, // DEPRECATED: Use RoutesV2.IgPortfolio /** @deprecated Use RoutesV2.InfraHealth instead */ IgHealthLegacy: `${IG_BASE}/health/legacy`, // DEPRECATED: Use RoutesV2.IgHealth /** @deprecated Use RoutesV2.IgAccounts instead */ IgLogin: `${IG_BASE}/login/legacy`, // DEPRECATED: Use RoutesV2.IgAccounts /** @deprecated Use RoutesV2.TradesOpen instead */ IgPositionsOpen: `${IG_BASE}/positions/open/legacy`, // DEPRECATED: Use RoutesV2.TradesOpen /** @deprecated Use RoutesV2.TradesClosed instead */ IgPositionsClosed: `${IG_BASE}/positions/closed/legacy`, // DEPRECATED: Use RoutesV2.TradesClosed /** @deprecated Use RoutesV2.IgPositions instead */ IgMarkets: `${IG_BASE}/markets/legacy`, // DEPRECATED: Use RoutesV2.IgPositions /** @deprecated Use RoutesV2.TradesOpen instead */ IgOpenPosition: `${IG_BASE}/positions/open/legacy2`, // DEPRECATED: Use RoutesV2.TradesOpen /** @deprecated Use RoutesV2.TradesClosed instead */ IgClosePosition: `${IG_BASE}/positions/close/legacy`, // DEPRECATED: Use RoutesV2.TradesClosed /** @deprecated Use RoutesV2.IgAccounts instead */ IgLogout: `${IG_BASE}/logout/legacy`, // DEPRECATED: Use RoutesV2.IgAccounts /** @deprecated Use RoutesV2.TradesClosed instead */ IgTrades: `${IG_BASE}/trades/legacy`, // DEPRECATED: Use RoutesV2.TradesClosed /** @deprecated Use RoutesV2.TradingAccounts instead */ TradingAccountsData: ACCOUNTS_BASE, // DEPRECATED: Use RoutesV2.TradingAccounts /** @deprecated Use RoutesV2.TradesOpen instead */ TradingPositionsData: `${API_BASE}/positions`, // DEPRECATED: Use RoutesV2.TradesOpen /** @deprecated Use RoutesV2.TradesClosed instead */ TradingOrders: `${API_BASE}/orders`, // DEPRECATED: Use RoutesV2.TradesClosed /** @deprecated Use RoutesV2.PortfolioSummary instead */ Portfolio: PORTFOLIO_BASE, // DEPRECATED: Use RoutesV2.PortfolioSummary /** @deprecated Use RoutesV2.WealthHl instead */ WealthSummary: `${WEALTH_BASE}/summary`, // DEPRECATED: Use RoutesV2.WealthHl /** @deprecated Use RoutesV2.TradesOpen instead */ TradingTrades: `${API_BASE}/trading/trades`, // DEPRECATED: Use RoutesV2.TradesOpen /** @deprecated Use RoutesV2.TradesOpen instead */ TradingBroker: `${API_BASE}/trading/broker`, // DEPRECATED: Use RoutesV2.TradesOpen /** @deprecated Use RoutesV2.TradesOpen instead */ TradingPrice: `${API_BASE}/trading/price`, // DEPRECATED: Use RoutesV2.TradesOpen /** @deprecated Use RoutesV2.TradesOpen instead */ TradingCandles: `${API_BASE}/trading/candles`, // DEPRECATED: Use RoutesV2.TradesOpen /** @deprecated Use RoutesV2.TradesOpen instead */ TradingFlat: `${API_BASE}/trading/flat`, // DEPRECATED: Use RoutesV2.TradesOpen } as const; export type RouteV2Key = keyof typeof RoutesV2; /** * Canonical Route Groups * * Grouped by service for easier consumption */ export const RouteGroups = { // Frontend API Surface (Next app) Frontend: { Health: RoutesV2.Health, SignalsQuery: RoutesV2.SignalsQuery, MlPredict: RoutesV2.MlPredict, MlBacktest: RoutesV2.MlBacktest, PortfolioSummary: RoutesV2.PortfolioSummary, WealthHl: RoutesV2.WealthHl, TradingAccounts: RoutesV2.TradingAccounts, }, // ML Service Endpoints ML: { Health: RoutesV2.MlHealth, Ready: RoutesV2.MlReady, Signals: RoutesV2.MlSignals, Models: RoutesV2.MlModels, Schema: RoutesV2.MlSchema, }, // Infra Service Endpoints Infra: { Health: RoutesV2.InfraHealth, IgAccounts: RoutesV2.IgAccounts, IgPositions: RoutesV2.IgPositions, IgPortfolio: RoutesV2.IgPortfolio, // IG-SIM Integration (v0.15.3) IgSim: RoutesV2.IgSim, // IG Adapter Integration (v0.15.3) IgMarketData: RoutesV2.IgMarketData, IgOrderSimulation: RoutesV2.IgOrderSimulation, IgLiveTradeConfig: RoutesV2.IgLiveTradeConfig, }, } as const; /** * Route Validation * * Ensures all routes follow the canonical pattern */ export const validateRoutes = () => { const issues: string[] = []; // Helper function to extract all paths from nested objects const extractPaths = (obj: any): string[] => { const paths: string[] = []; for (const value of Object.values(obj)) { if (typeof value === 'string') { paths.push(value); } else if (typeof value === 'object' && value !== null) { paths.push(...extractPaths(value)); } } return paths; }; // Check for duplicate paths const paths = extractPaths(RoutesV2); const duplicates = paths.filter((path, index) => paths.indexOf(path) !== index); if (duplicates.length > 0) { issues.push(`Duplicate routes found: ${duplicates.join(', ')}`); } // Check for invalid patterns const invalidPatterns = paths.filter(path => !path.startsWith('/api/')); if (invalidPatterns.length > 0) { issues.push(`Invalid route patterns found: ${invalidPatterns.join(', ')}`); } if (issues.length > 0) { throw new Error(`Route validation failed:\n${issues.join('\n')}`); } return true; }; // Validate routes on import validateRoutes(); // ===== MARKETPLACE VENDOR ENDPOINTS ===== export const MARKETPLACE_PROVIDER_ROUTES = { // API Key Management VENDOR_API_KEY_EXCHANGE: '/api/marketplace/vendor/api-key/exchange', VENDOR_API_KEY_ROTATE: '/api/marketplace/vendor/api-key/rotate', VENDOR_API_KEY_GENERATE: '/api/marketplace/vendor/api-key/generate', // Vendor Profile Management VENDOR_REGISTER: '/api/marketplace/vendor/register', VENDOR_PROFILE: '/api/marketplace/vendor/profile', VENDOR_STATS: '/api/marketplace/vendor/stats', VENDOR_CONNECTIONS: '/api/marketplace/vendor/connections', // Training Management TRAINING_SPECS: '/api/marketplace/training/specs', TRAINING_SPECS_CREATE: '/api/marketplace/training/specs', TRAINING_SPECS_GET: '/api/marketplace/training/specs/:id', TRAINING_SPECS_UPDATE: '/api/marketplace/training/specs/:id', TRAINING_SPECS_DELETE: '/api/marketplace/training/specs/:id', TRAINING_RUNS: '/api/marketplace/training/runs', TRAINING_RUNS_CREATE: '/api/marketplace/training/runs', TRAINING_RUNS_GET: '/api/marketplace/training/runs/:id', TRAINING_RUNS_UPDATE: '/api/marketplace/training/runs/:id', TRAINING_RUNS_DELETE: '/api/marketplace/training/runs/:id', TRAINING_RUNS_LOGS: '/api/marketplace/training/runs/:id/logs', TRAINING_RUNS_START: '/api/marketplace/training/runs/:id/start', TRAINING_RUNS_STOP: '/api/marketplace/training/runs/:id/stop', // Model Registry MODELS: '/api/marketplace/models', MODELS_CREATE: '/api/marketplace/models', MODELS_GET: '/api/marketplace/models/:id', MODELS_UPDATE: '/api/marketplace/models/:id', MODELS_DELETE: '/api/marketplace/models/:id', MODELS_PUBLISH: '/api/marketplace/models/:id/publish', MODELS_DEPRECATE: '/api/marketplace/models/:id/deprecate', MODEL_VERSIONS: '/api/marketplace/models/:id/versions', MODEL_VERSIONS_CREATE: '/api/marketplace/models/:id/versions', MODEL_VERSIONS_GET: '/api/marketplace/models/:id/versions/:version_id', // System Management DEPLOYMENTS: '/api/marketplace/deployments', DEPLOYMENTS_CREATE: '/api/marketplace/deployments', DEPLOYMENTS_GET: '/api/marketplace/deployments/:id', DEPLOYMENTS_UPDATE: '/api/marketplace/deployments/:id', DEPLOYMENTS_DELETE: '/api/marketplace/deployments/:id', DEPLOYMENTS_START: '/api/marketplace/deployments/:id/start', DEPLOYMENTS_STOP: '/api/marketplace/deployments/:id/stop', DEPLOYMENTS_SCALE: '/api/marketplace/deployments/:id/scale', DEPLOYMENTS_HEALTH: '/api/marketplace/deployments/:id/health', // Revenue & Analytics REVENUE: '/api/marketplace/revenue', REVENUE_VENDOR: '/api/marketplace/revenue/vendor/:vendor_id', REVENUE_DEPLOYMENT: '/api/marketplace/revenue/deployment/:deployment_id', // Public Catalog CATALOG_MODELS: '/api/marketplace/catalog/models', CATALOG_MODELS_GET: '/api/marketplace/catalog/models/:id', CATALOG_VENDORS: '/api/marketplace/catalog/vendors', CATALOG_VENDORS_GET: '/api/marketplace/catalog/vendors/:id', // Health & Monitoring MARKETPLACE_HEALTH: '/api/marketplace/health', MARKETPLACE_METRICS: '/api/marketplace/metrics', } as const; // ===== AUTHENTICATION ENDPOINTS ===== export const AUTH_ROUTES = { // Supabase Auth (handled by Supabase) SUPABASE_SIGN_IN: '/auth/sign-in', SUPABASE_SIGN_UP: '/auth/sign-up', SUPABASE_SIGN_OUT: '/auth/sign-out', SUPABASE_CALLBACK: '/auth/callback', SUPABASE_FORGOT_PASSWORD: '/auth/forgot-password', SUPABASE_RESET_PASSWORD: '/auth/reset-password', // Custom Auth Endpoints AUTH_PROFILE: '/api/auth/profile', AUTH_ORGANIZATIONS: '/api/auth/organizations', AUTH_ORGANIZATIONS_CREATE: '/api/auth/organizations', AUTH_ORGANIZATIONS_GET: '/api/auth/organizations/:id', AUTH_ORGANIZATIONS_UPDATE: '/api/auth/organizations/:id', AUTH_ORGANIZATIONS_DELETE: '/api/auth/organizations/:id', AUTH_MEMBERSHIPS: '/api/auth/organizations/:org_id/members', AUTH_MEMBERSHIPS_INVITE: '/api/auth/organizations/:org_id/members/invite', AUTH_MEMBERSHIPS_UPDATE: '/api/auth/organizations/:org_id/members/:user_id', AUTH_MEMBERSHIPS_REMOVE: '/api/auth/organizations/:org_id/members/:user_id', } as const; // ===== ORGANIZATION ENDPOINTS ===== export const SYSTEM_ADMIN_ROUTES = { // System Management ORGS: '/api/organizations', ORGS_CREATE: '/api/organizations', ORGS_GET: '/api/organizations/:id', ORGS_UPDATE: '/api/organizations/:id', ORGS_DELETE: '/api/organizations/:id', // Member Management ORG_MEMBERS: '/api/organizations/:org_id/members', ORG_MEMBERS_INVITE: '/api/organizations/:org_id/members/invite', ORG_MEMBERS_UPDATE: '/api/organizations/:org_id/members/:user_id', ORG_MEMBERS_REMOVE: '/api/organizations/:org_id/members/:user_id', // System Settings ORG_SETTINGS: '/api/organizations/:id/settings', ORG_BILLING: '/api/organizations/:id/billing', ORG_USAGE: '/api/organizations/:id/usage', } as const;