OpenCode
68a9071cf1
Local branch had diverged from origin/master (sibling commits on the same base). Rewrote local history linearly on top of origin/master, folding in all local content: exa/hot-platform discovery hunters, leaks ledger, nightly sweep orchestrator, updated .gitignore and skill docs, plus the latest hunt output and vault state. Remote-only files (vault keys, channel scripts) were restored rather than dropped, so the resulting tree is a full union of both sides.
1 line
50 KiB
JSON
1 line
50 KiB
JSON
{"repo": "abhishekgujar28/nexus", "files": {"nexus/server/src/core/config.ts": {"ba7051860879fec7b9c33ae38b16665dc9186b93": {"t": 1785745609.4727852, "n": 4829, "h": "f1bf60209a0320a9", "c": "import 'dotenv/config';\n\nconst bool = (v: string | undefined): boolean => v === 'true' || v === '1';\n\nconst cleanEnvKey = (v: string | undefined): string => {\n if (!v) return '';\n const trimmed = v.trim();\n if (/^(your-.*|change-this-.*|placeholder)$/i.test(trimmed)) return '';\n return trimmed;\n};\n\nexport const config = {\n env: process.env.NODE_ENV || 'development',\n port: parseInt(process.env.PORT || '5000'),\n frontendUrl: process.env.FRONTEND_URL || 'http://localhost:5173',\n mongoUri: process.env.MONGODB_URI || 'mongodb://localhost:27017/nexus',\n redisUrl: process.env.REDIS_URL || 'redis://localhost:6379',\n redis: {\n host: process.env.REDIS_HOST || 'localhost',\n port: parseInt(process.env.REDIS_PORT || '6379', 10),\n password: process.env.REDIS_PASSWORD || undefined,\n db: parseInt(process.env.REDIS_DB || '0', 10),\n url: process.env.REDIS_URL || 'redis://localhost:6379',\n },\n jwt: {\n // No hardcoded fallbacks — validated at startup by validateConfig().\n secret: process.env.JWT_SECRET || '',\n refreshSecret: process.env.JWT_REFRESH_SECRET || '',\n expiresIn: process.env.JWT_EXPIRES_IN || '15m',\n refreshExpiresIn: process.env.JWT_REFRESH_EXPIRES_IN || '7d',\n },\n geminiApiKey: cleanEnvKey(process.env.GEMINI_API_KEY),\n defaultAiProvider: process.env.DEFAULT_AI_PROVIDER || 'openrouter',\n ai: {\n openrouter: {\n apiKey: cleanEnvKey(process.env.OPENROUTER_API_KEY),\n baseUrl: process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1',\n },\n gemini: {\n apiKey: cleanEnvKey(process.env.GEMINI_API_KEY),\n },\n openai: {\n apiKey: cleanEnvKey(process.env.OPENAI_API_KEY),\n },\n anthropic: {\n apiKey: cleanEnvKey(process.env.ANTHROPIC_API_KEY),\n },\n groq: {\n apiKey: cleanEnvKey(process.env.GROQ_API_KEY),\n },\n deepseek: {\n apiKey: cleanEnvKey(process.env.DEEPSEEK_API_KEY),\n },\n together: {\n apiKey: cleanEnvKey(process.env.TOGETHER_API_KEY),\n },\n },\n serperApiKey: cleanEnvKey(process.env.SERPER_API_KEY),\n githubToken: cleanEnvKey(process.env.GITHUB_TOKEN),\n semanticScholarApiKey: cleanEnvKey(process.env.SEMANTIC_SCHOLAR_API_KEY),\n ieeeApiKey: cleanEnvKey(process.env.IEEE_XPLORE_API_KEY),\n chromaUrl: process.env.CHROMA_URL || 'http://localhost:8000',\n rag: {\n chunkSize: parseInt(process.env.RAG_CHUNK_SIZE || '1200'),\n chunkOverlap: parseInt(process.env.RAG_CHUNK_OVERLAP || '150'),\n topK: parseInt(process.env.RAG_TOP_K || '8'),\n maxContextChars: parseInt(process.env.RAG_MAX_CONTEXT_CHARS || '12000'),\n },\n research: {\n workerConcurrency: parseInt(process.env.RESEARCH_WORKER_CONCURRENCY || '2'),\n jobAttempts: parseInt(process.env.RESEARCH_JOB_ATTEMPTS || '2'),\n providerTimeoutMs: parseInt(process.env.PROVIDER_TIMEOUT_MS || '15000'),\n maxSourcesPerProvider: parseInt(process.env.MAX_SOURCES_PER_PROVIDER || '10'),\n },\n copilot: {\n historyWindow: parseInt(process.env.COPILOT_HISTORY_WINDOW || '10'),\n },\n vectorStore: process.env.VECTOR_STORE || 'memory', // 'chroma' | 'memory'\n} as const;\n\n/**\n * Fail-fast validation of required environment. Called once at startup\n * (and by the worker) before anything security-sensitive runs.\n */\nexport const validateConfig = (): void => {\n const missing: string[] = [];\n if (!config.jwt.secret) missing.push('JWT_SECRET');\n if (!config.jwt.refreshSecret) missing.push('JWT_REFRESH_SECRET');\n\n if (missing.length > 0) {\n throw new Error(\n `Missing required environment variables: ${missing.join(', ')}. ` +\n `Set them (see .env.example) before starting the server.`\n );\n }\n\n if (isNaN(config.redis.port) || config.redis.port <= 0 || config.redis.port > 65535) {\n throw new Error(`Invalid REDIS_PORT: \"${process.env.REDIS_PORT}\". Must be a valid port number (1-65535).`);\n }\n\n if (config.redis.url && !/^rediss?:\\/\\//i.test(config.redis.url)) {\n throw new Error(`Invalid REDIS_URL format: \"${config.redis.url}\". Must start with redis:// or rediss://`);\n }\n\n if (config.env === 'production') {\n if (config.jwt.secret.length < 32 || config.jwt.refreshSecret.length < 32) {\n throw new Error('JWT secrets must be at least 32 characters in production.');\n }\n if (config.jwt.secret === config.jwt.refreshSecret) {\n throw new Error('JWT_SECRET and JWT_REFRESH_SECRET must differ.');\n }\n }\n};\n\nexport const providerStatus = {\n gemini: () => ({ name: 'Gemini', configured: !!config.geminiApiKey }),\n serper: () => ({ name: 'Serper', configured: !!config.serperApiKey }),\n github: () => ({ name: 'GitHub', configured: !!config.githubToken }),\n arxiv: () => ({ name: 'arXiv', configured: true }),\n semanticScholar: () => ({ name: 'Semantic Scholar', configured: true }),\n ieee: () => ({ name: 'IEEE Xplore', configured: !!config.ieeeApiKey }),\n};\n"}, "4b02d14b7e68a4befea8c319a67dcbfba662f9c5": {"t": 1785754759.592956, "n": 4829, "h": "f1bf60209a0320a9", "c": "import 'dotenv/config';\n\nconst bool = (v: string | undefined): boolean => v === 'true' || v === '1';\n\nconst cleanEnvKey = (v: string | undefined): string => {\n if (!v) return '';\n const trimmed = v.trim();\n if (/^(your-.*|change-this-.*|placeholder)$/i.test(trimmed)) return '';\n return trimmed;\n};\n\nexport const config = {\n env: process.env.NODE_ENV || 'development',\n port: parseInt(process.env.PORT || '5000'),\n frontendUrl: process.env.FRONTEND_URL || 'http://localhost:5173',\n mongoUri: process.env.MONGODB_URI || 'mongodb://localhost:27017/nexus',\n redisUrl: process.env.REDIS_URL || 'redis://localhost:6379',\n redis: {\n host: process.env.REDIS_HOST || 'localhost',\n port: parseInt(process.env.REDIS_PORT || '6379', 10),\n password: process.env.REDIS_PASSWORD || undefined,\n db: parseInt(process.env.REDIS_DB || '0', 10),\n url: process.env.REDIS_URL || 'redis://localhost:6379',\n },\n jwt: {\n // No hardcoded fallbacks — validated at startup by validateConfig().\n secret: process.env.JWT_SECRET || '',\n refreshSecret: process.env.JWT_REFRESH_SECRET || '',\n expiresIn: process.env.JWT_EXPIRES_IN || '15m',\n refreshExpiresIn: process.env.JWT_REFRESH_EXPIRES_IN || '7d',\n },\n geminiApiKey: cleanEnvKey(process.env.GEMINI_API_KEY),\n defaultAiProvider: process.env.DEFAULT_AI_PROVIDER || 'openrouter',\n ai: {\n openrouter: {\n apiKey: cleanEnvKey(process.env.OPENROUTER_API_KEY),\n baseUrl: process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1',\n },\n gemini: {\n apiKey: cleanEnvKey(process.env.GEMINI_API_KEY),\n },\n openai: {\n apiKey: cleanEnvKey(process.env.OPENAI_API_KEY),\n },\n anthropic: {\n apiKey: cleanEnvKey(process.env.ANTHROPIC_API_KEY),\n },\n groq: {\n apiKey: cleanEnvKey(process.env.GROQ_API_KEY),\n },\n deepseek: {\n apiKey: cleanEnvKey(process.env.DEEPSEEK_API_KEY),\n },\n together: {\n apiKey: cleanEnvKey(process.env.TOGETHER_API_KEY),\n },\n },\n serperApiKey: cleanEnvKey(process.env.SERPER_API_KEY),\n githubToken: cleanEnvKey(process.env.GITHUB_TOKEN),\n semanticScholarApiKey: cleanEnvKey(process.env.SEMANTIC_SCHOLAR_API_KEY),\n ieeeApiKey: cleanEnvKey(process.env.IEEE_XPLORE_API_KEY),\n chromaUrl: process.env.CHROMA_URL || 'http://localhost:8000',\n rag: {\n chunkSize: parseInt(process.env.RAG_CHUNK_SIZE || '1200'),\n chunkOverlap: parseInt(process.env.RAG_CHUNK_OVERLAP || '150'),\n topK: parseInt(process.env.RAG_TOP_K || '8'),\n maxContextChars: parseInt(process.env.RAG_MAX_CONTEXT_CHARS || '12000'),\n },\n research: {\n workerConcurrency: parseInt(process.env.RESEARCH_WORKER_CONCURRENCY || '2'),\n jobAttempts: parseInt(process.env.RESEARCH_JOB_ATTEMPTS || '2'),\n providerTimeoutMs: parseInt(process.env.PROVIDER_TIMEOUT_MS || '15000'),\n maxSourcesPerProvider: parseInt(process.env.MAX_SOURCES_PER_PROVIDER || '10'),\n },\n copilot: {\n historyWindow: parseInt(process.env.COPILOT_HISTORY_WINDOW || '10'),\n },\n vectorStore: process.env.VECTOR_STORE || 'memory', // 'chroma' | 'memory'\n} as const;\n\n/**\n * Fail-fast validation of required environment. Called once at startup\n * (and by the worker) before anything security-sensitive runs.\n */\nexport const validateConfig = (): void => {\n const missing: string[] = [];\n if (!config.jwt.secret) missing.push('JWT_SECRET');\n if (!config.jwt.refreshSecret) missing.push('JWT_REFRESH_SECRET');\n\n if (missing.length > 0) {\n throw new Error(\n `Missing required environment variables: ${missing.join(', ')}. ` +\n `Set them (see .env.example) before starting the server.`\n );\n }\n\n if (isNaN(config.redis.port) || config.redis.port <= 0 || config.redis.port > 65535) {\n throw new Error(`Invalid REDIS_PORT: \"${process.env.REDIS_PORT}\". Must be a valid port number (1-65535).`);\n }\n\n if (config.redis.url && !/^rediss?:\\/\\//i.test(config.redis.url)) {\n throw new Error(`Invalid REDIS_URL format: \"${config.redis.url}\". Must start with redis:// or rediss://`);\n }\n\n if (config.env === 'production') {\n if (config.jwt.secret.length < 32 || config.jwt.refreshSecret.length < 32) {\n throw new Error('JWT secrets must be at least 32 characters in production.');\n }\n if (config.jwt.secret === config.jwt.refreshSecret) {\n throw new Error('JWT_SECRET and JWT_REFRESH_SECRET must differ.');\n }\n }\n};\n\nexport const providerStatus = {\n gemini: () => ({ name: 'Gemini', configured: !!config.geminiApiKey }),\n serper: () => ({ name: 'Serper', configured: !!config.serperApiKey }),\n github: () => ({ name: 'GitHub', configured: !!config.githubToken }),\n arxiv: () => ({ name: 'arXiv', configured: true }),\n semanticScholar: () => ({ name: 'Semantic Scholar', configured: true }),\n ieee: () => ({ name: 'IEEE Xplore', configured: !!config.ieeeApiKey }),\n};\n"}, "84d72533448a28ba64b6251cdcc4916d272402e7": {"t": 1785754762.8222654, "n": 4416, "h": "fb05addaccd7bdb7", "c": "import 'dotenv/config';\n\nconst bool = (v: string | undefined): boolean => v === 'true' || v === '1';\n\nexport const config = {\n env: process.env.NODE_ENV || 'development',\n port: parseInt(process.env.PORT || '5000'),\n frontendUrl: process.env.FRONTEND_URL || 'http://localhost:5173',\n mongoUri: process.env.MONGODB_URI || 'mongodb://localhost:27017/nexus',\n redisUrl: process.env.REDIS_URL || 'redis://localhost:6379',\n redis: {\n host: process.env.REDIS_HOST || 'localhost',\n port: parseInt(process.env.REDIS_PORT || '6379', 10),\n password: process.env.REDIS_PASSWORD || undefined,\n db: parseInt(process.env.REDIS_DB || '0', 10),\n url: process.env.REDIS_URL || 'redis://localhost:6379',\n },\n jwt: {\n // No hardcoded fallbacks — validated at startup by validateConfig().\n secret: process.env.JWT_SECRET || '',\n refreshSecret: process.env.JWT_REFRESH_SECRET || '',\n expiresIn: process.env.JWT_EXPIRES_IN || '15m',\n refreshExpiresIn: process.env.JWT_REFRESH_EXPIRES_IN || '7d',\n },\n geminiApiKey: process.env.GEMINI_API_KEY || '',\n defaultAiProvider: process.env.DEFAULT_AI_PROVIDER || 'openrouter',\n ai: {\n openrouter: {\n apiKey: process.env.OPENROUTER_API_KEY || '',\n baseUrl: process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api/v1',\n },\n gemini: {\n apiKey: process.env.GEMINI_API_KEY || '',\n },\n openai: {\n apiKey: process.env.OPENAI_API_KEY || '',\n },\n anthropic: {\n apiKey: process.env.ANTHROPIC_API_KEY || '',\n },\n groq: {\n apiKey: process.env.GROQ_API_KEY || '',\n },\n deepseek: {\n apiKey: process.env.DEEPSEEK_API_KEY || '',\n },\n together: {\n apiKey: process.env.TOGETHER_API_KEY || '',\n },\n },\n serperApiKey: process.env.SERPER_API_KEY || '',\n githubToken: process.env.GITHUB_TOKEN || '',\n semanticScholarApiKey: process.env.SEMANTIC_SCHOLAR_API_KEY || '',\n chromaUrl: process.env.CHROMA_URL || 'http://localhost:8000',\n rag: {\n chunkSize: parseInt(process.env.RAG_CHUNK_SIZE || '1200'),\n chunkOverlap: parseInt(process.env.RAG_CHUNK_OVERLAP || '150'),\n topK: parseInt(process.env.RAG_TOP_K || '8'),\n maxContextChars: parseInt(process.env.RAG_MAX_CONTEXT_CHARS || '12000'),\n },\n research: {\n workerConcurrency: parseInt(process.env.RESEARCH_WORKER_CONCURRENCY || '2'),\n jobAttempts: parseInt(process.env.RESEARCH_JOB_ATTEMPTS || '2'),\n providerTimeoutMs: parseInt(process.env.PROVIDER_TIMEOUT_MS || '15000'),\n maxSourcesPerProvider: parseInt(process.env.MAX_SOURCES_PER_PROVIDER || '10'),\n },\n copilot: {\n historyWindow: parseInt(process.env.COPILOT_HISTORY_WINDOW || '10'),\n },\n vectorStore: process.env.VECTOR_STORE || 'memory', // 'chroma' | 'memory'\n} as const;\n\n/**\n * Fail-fast validation of required environment. Called once at startup\n * (and by the worker) before anything security-sensitive runs.\n */\nexport const validateConfig = (): void => {\n const missing: string[] = [];\n if (!config.jwt.secret) missing.push('JWT_SECRET');\n if (!config.jwt.refreshSecret) missing.push('JWT_REFRESH_SECRET');\n\n if (missing.length > 0) {\n throw new Error(\n `Missing required environment variables: ${missing.join(', ')}. ` +\n `Set them (see .env.example) before starting the server.`\n );\n }\n\n if (isNaN(config.redis.port) || config.redis.port <= 0 || config.redis.port > 65535) {\n throw new Error(`Invalid REDIS_PORT: \"${process.env.REDIS_PORT}\". Must be a valid port number (1-65535).`);\n }\n\n if (config.redis.url && !/^rediss?:\\/\\//i.test(config.redis.url)) {\n throw new Error(`Invalid REDIS_URL format: \"${config.redis.url}\". Must start with redis:// or rediss://`);\n }\n\n if (config.env === 'production') {\n if (config.jwt.secret.length < 32 || config.jwt.refreshSecret.length < 32) {\n throw new Error('JWT secrets must be at least 32 characters in production.');\n }\n if (config.jwt.secret === config.jwt.refreshSecret) {\n throw new Error('JWT_SECRET and JWT_REFRESH_SECRET must differ.');\n }\n }\n};\n\nexport const providerStatus = {\n gemini: () => ({ name: 'Gemini', configured: !!config.geminiApiKey }),\n serper: () => ({ name: 'Serper', configured: !!config.serperApiKey }),\n github: () => ({ name: 'GitHub', configured: !!config.githubToken }),\n arxiv: () => ({ name: 'arXiv', configured: true }),\n semanticScholar: () => ({ name: 'Semantic Scholar', configured: true }),\n};\n"}, "ddfa2a549fb070320082c4e5a3e54fe4157c9663": {"t": 1785754764.815954, "n": 3069, "h": "50f031874a09804d", "c": "import 'dotenv/config';\n\nconst bool = (v: string | undefined): boolean => v === 'true' || v === '1';\n\nexport const config = {\n env: process.env.NODE_ENV || 'development',\n port: parseInt(process.env.PORT || '5000'),\n frontendUrl: process.env.FRONTEND_URL || 'http://localhost:5173',\n mongoUri: process.env.MONGODB_URI || 'mongodb://localhost:27017/nexus',\n redisUrl: process.env.REDIS_URL || 'redis://localhost:6379',\n jwt: {\n // No hardcoded fallbacks — validated at startup by validateConfig().\n secret: process.env.JWT_SECRET || '',\n refreshSecret: process.env.JWT_REFRESH_SECRET || '',\n expiresIn: process.env.JWT_EXPIRES_IN || '15m',\n refreshExpiresIn: process.env.JWT_REFRESH_EXPIRES_IN || '7d',\n },\n geminiApiKey: process.env.GEMINI_API_KEY || '',\n serperApiKey: process.env.SERPER_API_KEY || '',\n githubToken: process.env.GITHUB_TOKEN || '',\n semanticScholarApiKey: process.env.SEMANTIC_SCHOLAR_API_KEY || '',\n chromaUrl: process.env.CHROMA_URL || 'http://localhost:8000',\n rag: {\n chunkSize: parseInt(process.env.RAG_CHUNK_SIZE || '1200'),\n chunkOverlap: parseInt(process.env.RAG_CHUNK_OVERLAP || '150'),\n topK: parseInt(process.env.RAG_TOP_K || '8'),\n maxContextChars: parseInt(process.env.RAG_MAX_CONTEXT_CHARS || '12000'),\n },\n research: {\n workerConcurrency: parseInt(process.env.RESEARCH_WORKER_CONCURRENCY || '2'),\n jobAttempts: parseInt(process.env.RESEARCH_JOB_ATTEMPTS || '2'),\n providerTimeoutMs: parseInt(process.env.PROVIDER_TIMEOUT_MS || '15000'),\n maxSourcesPerProvider: parseInt(process.env.MAX_SOURCES_PER_PROVIDER || '10'),\n },\n copilot: {\n historyWindow: parseInt(process.env.COPILOT_HISTORY_WINDOW || '10'),\n },\n vectorStore: process.env.VECTOR_STORE || 'memory', // 'chroma' | 'memory'\n} as const;\n\n/**\n * Fail-fast validation of required environment. Called once at startup\n * (and by the worker) before anything security-sensitive runs.\n */\nexport const validateConfig = (): void => {\n const missing: string[] = [];\n if (!config.jwt.secret) missing.push('JWT_SECRET');\n if (!config.jwt.refreshSecret) missing.push('JWT_REFRESH_SECRET');\n\n if (missing.length > 0) {\n throw new Error(\n `Missing required environment variables: ${missing.join(', ')}. ` +\n `Set them (see .env.example) before starting the server.`\n );\n }\n\n if (config.env === 'production') {\n if (config.jwt.secret.length < 32 || config.jwt.refreshSecret.length < 32) {\n throw new Error('JWT secrets must be at least 32 characters in production.');\n }\n if (config.jwt.secret === config.jwt.refreshSecret) {\n throw new Error('JWT_SECRET and JWT_REFRESH_SECRET must differ.');\n }\n }\n};\n\nexport const providerStatus = {\n gemini: () => ({ name: 'Gemini', configured: !!config.geminiApiKey }),\n serper: () => ({ name: 'Serper', configured: !!config.serperApiKey }),\n github: () => ({ name: 'GitHub', configured: !!config.githubToken }),\n arxiv: () => ({ name: 'arXiv', configured: true }),\n semanticScholar: () => ({ name: 'Semantic Scholar', configured: true }),\n};\n"}}, "README.md": {"31b889eb8567f573371f6e402e9977d8fee7ee03": {"t": 1786068443.257596, "n": 30798, "h": "83b7ba3a141592f7", "c": "<div align=\"center\">\n\n# ⚡ NEXUS\n### Autonomous AI Research Copilot & Strategic Technology Engine\n\n[](LICENSE)\n[](https://nodejs.org/)\n[](https://react.dev/)\n[](https://www.typescriptlang.org/)\n[](https://expressjs.com/)\n[](https://www.mongodb.com/)\n[](https://redis.io/)\n[](https://docs.bullmq.io/)\n[](https://tailwindcss.com/)\n\n**NEXUS** is an enterprise-grade, multi-agent AI research platform designed to automate deep technological research, academic paper aggregation, web evidence mining, market gap discovery, adversarial stress-testing, and system architecture design.\n\n[Key Features](#2-key-features) • [System Architecture](#3-system-architecture) • [Tech Stack](#5-tech-stack) • [Installation Guide](#7-installation-guide) • [AI Pipeline](#10-ai-pipeline) • [API Documentation](#11-api-overview)\n\n---\n\n</div>\n\n## 📋 Table of Contents\n\n- [1. Project Introduction](#1-project-introduction)\n- [2. Key Features](#2-key-features)\n- [3. System Architecture](#3-system-architecture)\n- [4. Folder Structure](#4-folder-structure)\n- [5. Tech Stack](#5-tech-stack)\n- [6. Prerequisites](#6-prerequisites)\n- [7. Installation Guide](#7-installation-guide)\n- [8. Environment Variables](#8-environment-variables)\n- [9. Running the Project](#9-running-the-project)\n- [10. AI Pipeline](#10-ai-pipeline)\n- [11. API Overview](#11-api-overview)\n- [12. Database Schema](#12-database-schema)\n- [13. Queue System](#13-queue-system)\n- [14. AI & Search Providers](#14-ai--search-providers)\n- [15. Application Screenshots](#15-application-screenshots)\n- [16. Performance & Optimizations](#16-performance--optimizations)\n- [17. Security Architecture](#17-security-architecture)\n- [18. Development Workflow](#18-development-workflow)\n- [19. Contributing Guide](#19-contributing-guide)\n- [20. Future Roadmap](#20-future-roadmap)\n- [21. License](#21-license)\n- [22. Author](#22-author)\n- [23. Acknowledgements](#23-acknowledgements)\n\n---\n\n## 1. Project Introduction\n\n### What is NEXUS?\n**NEXUS** is an autonomous, multi-agent AI research copilot and strategic decision engine. It replaces manual web searches, academic paper reviews, and architectural planning with an automated, 11-stage research orchestrator.\n\n### What Problem Does It Solve?\nBuilding modern, state-of-the-art software applications requires extensive pre-implementation research:\n1. **Scattered Evidence**: Finding relevant papers, repositories, web discussions, and package ecosystems requires searching multiple disparate platforms.\n2. **Analysis Paralysis**: Evaluating existing market solutions and pinpointing technical innovation gaps is time-consuming.\n3. **Unvalidated Assumptions**: System designs often fail due to unverified edge cases or lack of adversarial stress-testing.\n\nNEXUS automates this end-to-end workflow by dispatching autonomous AI agents to query multi-source search providers, score source credibility, discover market gaps, stress-test ideas against real-world constraints, design software architecture diagrams, and build actionable execution roadmaps.\n\n### Why Was It Built?\nNEXUS was created to bridge the gap between initial software ideation and production-ready technical specification. By leveraging multi-agent AI collaboration and robust fallback routing across major LLM providers, NEXUS ensures every research insight is backed by verified multi-source evidence.\n\n### Who Is It For?\n- **Software Engineers & Architects**: Designing microservices, choosing tech stacks, and verifying trade-offs.\n- **Product Managers & Strategists**: Conducting competitive analysis and market gap discovery.\n- **R&D Teams & Founders**: Accelerating feasibility studies and technical proof-of-concepts.\n- **Academic & Industry Researchers**: Aggregating literature from arXiv, IEEE Xplore, and Semantic Scholar.\n\n---\n\n## 2. Key Features\n\n- 🤖 **Multi-Agent Swarm**: 11 specialized AI agents working together (Problem Understanding, Query Planner, Deep Search, Analysis, Gap Finder, Critic, Architect, Roadmap, Security, Cost, Performance).\n- 🔍 **Multi-Provider Search Integration**: Unified search across **Serper (Google Web)**, **arXiv**, **Semantic Scholar**, **IEEE Xplore**, **GitHub Repositories**, **NPM Packages**, and **Stack Overflow**.\n- 🔀 **Resilient AI Router (`AIRouter`)**: Automatic fallback management across **7 AI Providers** (OpenRouter, Gemini, OpenAI, Anthropic, Groq, DeepSeek, Together) with circuit breaking and exponential backoff.\n- ⚡ **Background Queue Workers**: Dedicated Redis + BullMQ process (`research.worker.ts`) executing long-running jobs asynchronously with retry policies.\n- 📡 **Real-Time WebSocket Streaming**: Socket.io live log stream, stage progress, and alert notifications pushed directly to the UI.\n- 🧠 **RAG Retrieval Engine**: Built-in chunking, text embedding, and ChromaDB vector store support (with in-memory fallback) for contextual evidence retrieval.\n- 💬 **Interactive AI Copilot**: Project-aware copilot assistant (`copilot.agent.ts`) with access to live research job states and vector index context.\n- 📊 **Architecture & Diagram Generation**: Auto-generates system architecture specifications and Mermaid.js sequence/architecture diagrams.\n- 🔐 **Enterprise Auth & RBAC**: Dual JWT authentication (Access & Refresh tokens), password hashing with `bcryptjs`, and role-based access control (`owner`, `editor`, `viewer`).\n- 📁 **Export Capabilities**: Export comprehensive research reports to Markdown, JSON, PDF, or rendered Kroki SVG diagrams.\n\n---\n\n## 3. System Architecture\n\nNEXUS uses a decoupled client-server architecture powered by an asynchronous queue worker and real-time Socket.io communication.\n\n```mermaid\nflowchart TD\n subgraph Client [\"Client Layer (Frontend)\"]\n UI[\"React 18 + Vite UI\"]\n State[\"Zustand Store\"]\n SocketClient[\"Socket.io Client\"]\n UI --> State\n UI --> SocketClient\n end\n\n subgraph API [\"Server Layer (Express API)\"]\n Router[\"Express REST API /api\"]\n AuthMiddleware[\"Auth & RBAC Middleware\"]\n Controllers[\"Controller Handlers\"]\n SocketServer[\"Socket.io Realtime Server\"]\n \n Router --> AuthMiddleware --> Controllers\n end\n\n subgraph Database [\"Persistence Layer\"]\n Mongo[(\"MongoDB Database\")]\n Redis[(\"Redis Cache & BullMQ\")]\n end\n\n subgraph Worker [\"Asynchronous Worker Layer\"]\n ResearchWorker[\"BullMQ Research Worker\"]\n Orchestrator[\"Research Orchestrator (11 Stages)\"]\n AgentSwarm[\"Multi-Agent AI Swarm\"]\n \n ResearchWorker --> Orchestrator --> AgentSwarm\n end\n\n subgraph AI [\"AI Routing & RAG Layer\"]\n AIRouter[\"AIRouter (Circuit Breaker & Fallback)\"]\n RAGPipeline[\"RAG Engine (Chunker + Embedder + ChromaDB)\"]\n end\n\n subgraph External [\"External Providers\"]\n LLMs[\"LLM APIs (OpenRouter, Gemini, OpenAI, Anthropic, etc.)\"]\n SearchAPIs[\"Search APIs (Serper, arXiv, IEEE, GitHub, NPM, etc.)\"]\n end\n\n %% Flow connections\n Client -- \"HTTP Requests\" --> Router\n Controllers -- \"Dispatch Job\" --> Redis\n Redis -- \"Queue Jobs\" --> ResearchWorker\n SocketServer <--> SocketClient\n Orchestrator -- \"Stream Progress\" --> SocketServer\n AgentSwarm --> AIRouter\n AgentSwarm --> SearchAPIs\n AIRouter --> LLMs\n AgentSwarm --> RAGPipeline\n Controllers <--> Mongo\n ResearchWorker <--> Mongo\n```\n\n### Component Breakdown\n\n| Component | Responsibility |\n| :--- | :--- |\n| **Frontend App** | Single Page Application built with React 18, Vite, TailwindCSS, and Radix UI components. |\n| **Express API** | Handles REST requests, authentication, rate limiting, and project permissions. |\n| **BullMQ Worker** | Standalone Node.js process consuming queue jobs and managing long-running agent pipelines. |\n| **Research Orchestrator** | Coordinates execution of the 11 research stages, saving checkpoints to MongoDB. |\n| **AIRouter** | Manages provider health, circuit breaker state, model fallbacks, and usage metrics. |\n| **RAG Pipeline** | Processes scraped sources, generates vector embeddings, and performs top-K semantic search. |\n| **Socket.io Server** | Pushes real-time progress, stage state mutations, and copilot streams to connected clients. |\n\n---\n\n## 4. Folder Structure\n\n```\nnexus/\n├── package.json # Root package runner (starts Frontend, Backend, Worker)\n├── README.md # Project documentation\n│\n├── frontend/ # Client Single Page Application\n│ ├── package.json\n│ ├── vite.config.ts\n│ ├── tailwind.config.js\n│ └── src/\n│ ├── components/ # UI components (Copilot, Pipeline, Diagram, Export, Shared)\n│ ├── features/ # Feature modules (Auth, Projects, Research)\n│ ├── hooks/ # Custom React hooks (useAuth, useSocket, etc.)\n│ ├── layouts/ # Page layout containers (DashboardLayout, AuthLayout)\n│ ├── pages/ # Top-level view routes (Dashboard, Project, Discoveries, etc.)\n│ ├── stores/ # Global Zustand state stores\n│ └── types/ # Shared TypeScript interface definitions\n│\n└── server/ # Node.js Express & Worker Backend\n ├── package.json\n ├── .env.example # Template environment configuration\n └── src/\n ├── agents/ # AI Agent definitions (DeepSearch, Architect, Critic, etc.)\n ├── circuit-breaker/ # Circuit breaker registry & fault tolerance\n ├── controllers/ # REST API request handlers\n ├── core/ # System core (Config, Logger, Database, Redis)\n ├── export/ # Report export utilities (PDF, Markdown, JSON)\n ├── integrations/ # AIRouter & AI provider adapters (Gemini, OpenAI, OpenRouter, etc.)\n ├── middleware/ # Auth, Rate Limiting, RBAC, Backpressure middleware\n ├── models/ # Mongoose Database Schemas (Project, ResearchJob, User, etc.)\n ├── observability/ # Prometheus metrics & logger stream\n ├── orchestrator/ # ResearchOrchestrator pipeline coordinator\n ├── rag/ # Chunker, Embedder, Retriever & ChromaDB integration\n ├── research/ # Search Provider Registry (Serper, arXiv, IEEE, GitHub, etc.)\n ├── routes/ # Express API Route definitions\n ├── schemas/ # Zod validation schemas\n ├── socket/ # Socket.io connection handlers & event emitters\n ├── workers/ # BullMQ background workers (research.worker.ts)\n ├── app.ts # Express application initialization\n └── server.ts # HTTP & Socket.io server entry point\n```\n\n---\n\n## 5. Tech Stack\n\n| Category | Technology | Description |\n| :--- | :--- | :--- |\n| **Frontend Framework** | React 18 | Declarative UI library with functional components and hooks. |\n| **Build Tool** | Vite | Next-generation fast frontend bundler and HMR dev server. |\n| **Styling** | TailwindCSS | Utility-first CSS framework for custom responsive styling. |\n| **State Management** | Zustand | Lightweight, unopinionated client state management. |\n| **Backend Runtime** | Node.js (v18+) | Server-side JavaScript runtime engine. |\n| **Web Server** | Express | Fast, unopinionated Web Framework for HTTP endpoints. |\n| **Database** | MongoDB & Mongoose | Document object database and schema modeling layer. |\n| **Task Queue** | Redis & BullMQ | In-memory data store powering asynchronous background jobs. |\n| **Real-time Server** | Socket.io | Bidirectional WebSocket event-based communication. |\n| **AI Router** | AIRouter (Custom) | Fault-tolerant multi-LLM router with circuit breaking. |\n| **Vector DB** | ChromaDB / Memory Store | High-performance vector database for semantic RAG search. |\n| **Validation** | Zod | TypeScript-first schema declaration and validation. |\n| **Language** | TypeScript | Static type safety across both frontend and backend. |\n\n---\n\n## 6. Prerequisites\n\nBefore installing NEXUS, ensure your environment meets the following requirements:\n\n- **Node.js**: `v18.0.0` or higher (recommended: `v20.x`)\n- **npm**: `v9.0.0` or higher\n- **MongoDB**: Local instance running on port `27017` OR a MongoDB Atlas connection string.\n- **Redis**: Local instance running on port `6379` (or custom port).\n- **API Keys** *(At least one required for AI operations)*:\n - **OpenRouter API Key** (Recommended gateway) OR **Gemini API Key** / **OpenAI API Key**\n - **Serper API Key** *(Optional, for Google Web search capability)*\n - **GitHub Token** *(Optional, for repository code search)*\n\n---\n\n## 7. Installation Guide\n\nFollow these steps to clone and set up the NEXUS platform:\n\n### 1. Clone the Repository\n```bash\ngit clone https://github.com/your-org/nexus.git\ncd nexus\n```\n\n### 2. Install Root & Sub-Workspace Dependencies\nExecute `npm install` at the root project directory. This installs `concurrently` at the root and downloads required workspace dependencies:\n```bash\n# Install root dependencies\nnpm install\n\n# Install server dependencies\nnpm --prefix server install --legacy-peer-deps\n\n# Install frontend dependencies\nnpm --prefix frontend install\n```\n\n### 3. Configure Environment Variables\nCopy `.env.example` in the `server` directory to `.env`:\n```bash\ncp server/.env.example server/.env\n```\nEdit `server/.env` and insert your MongoDB URI, Redis credentials, JWT secrets, and AI provider API keys.\n\n---\n\n## 8. Environment Variables\n\nThe backend requires key environment variables configured in `server/.env`. Below is a breakdown of the configuration keys:\n\n| Variable | Description | Required? | Default / Example Value |\n| :--- | :--- | :---: | :--- |\n| `NODE_ENV` | Application runtime environment. | Yes | `development` |\n| `PORT` | HTTP port for backend Express server. | Yes | `5000` |\n| `FRONTEND_URL` | CORS allowed client origin. | Yes | `http://localhost:5173` |\n| `MONGODB_URI` | Connection URI for MongoDB database. | Yes | `mongodb://localhost:27017/nexus` |\n| `REDIS_URL` | Connection URL for Redis server. | Yes | `redis://localhost:6379` |\n| `JWT_SECRET` | Primary signing key for Access Tokens. | Yes | `use-a-strong-secret-min-32-chars` |\n| `JWT_REFRESH_SECRET` | Signing key for Refresh Tokens. | Yes | `use-a-different-strong-secret` |\n| `JWT_EXPIRES_IN` | Validity duration of access tokens. | No | `15m` |\n| `JWT_REFRESH_EXPIRES_IN` | Validity duration of refresh tokens. | No | `7d` |\n| `DEFAULT_AI_PROVIDER` | Primary LLM provider identifier. | Yes | `openrouter` |\n| `OPENROUTER_API_KEY` | OpenRouter API gateway key. | Recommended | `sk-or-v1-...` |\n| `GEMINI_API_KEY` | Google Gemini API key. | Optional | `AIzaSy...` |\n| `OPENAI_API_KEY` | OpenAI API key. | Optional | `sk-...` |\n| `ANTHROPIC_API_KEY` | Anthropic Claude API key. | Optional | `sk-ant-...` |\n| `SERPER_API_KEY` | Serper API key for Google Web search. | Optional | `b973...` |\n| `GITHUB_TOKEN` | GitHub Personal Access Token for search. | Optional | `ghp_...` |\n| `IEEE_XPLORE_API_KEY` | IEEE Xplore API key for academic papers. | Optional | `e9g9...` |\n| `VECTOR_STORE` | RAG Vector Store mode (`memory` or `chroma`). | No | `memory` |\n| `CHROMA_URL` | ChromaDB vector server endpoint. | Optional | `http://localhost:8000` |\n\n---\n\n## 9. Running the Project\n\nNEXUS includes a unified root workspace script that launches all three micro-services concurrently in a single terminal.\n\n### Single Command Execution\n\nRun the following command from the root directory:\n\n```bash\nnpm run dev\n```\n\n### What Starts Internally?\n\nExecuting `npm run dev` spawns three concurrent child processes using `npm --prefix`:\n\n```mermaid\nflowchart LR\n Root[\"npm run dev (Root)\"] --> Frontend[\"[FRONTEND] npm --prefix frontend run dev (Port 5173)\"]\n Root --> Backend[\"[BACKEND] npm --prefix server run dev (Port 5000)\"]\n Root --> Worker[\"[WORKER] npm --prefix server run worker (BullMQ Worker)\"]\n```\n\n1. 🩵 **`[FRONTEND]`**: Launches Vite dev server at `http://localhost:5173`.\n2. 💙 **`[BACKEND]`**: Launches Express REST API & Socket.io server with `tsx watch` at `http://localhost:5000`.\n3. 🩷 **`[WORKER]`**: Launches the standalone BullMQ research worker background process.\n\n---\n\n## 10. AI Pipeline\n\nThe core of NEXUS is an 11-stage autonomous research pipeline executed by `ResearchOrchestrator`. Each stage performs a specific function and updates the job's progress state:\n\n```\n ┌────────────────┐ ┌────────────────┐ ┌────────────────┐\n │ 1. Understand │ ───> │ 2. Plan │ ───> │ 3. Search Web │\n └────────────────┘ └────────────────┘ └────────────────┘\n │\n ┌────────────────┐ ┌────────────────┐ │\n │ 6. Analyze │ <─── │ 5. GitHub │ <─── ┌───────┴────────┐\n └────────────────┘ └────────────────┘ │ 4. Papers │\n │ └────────────────┘\n ▼\n ┌────────────────┐ ┌────────────────┐ ┌────────────────┐\n │ 7. Solutions │ ───> │ 8. Gaps │ ───> │ 9. Stress │\n └────────────────┘ └────────────────┘ └────────────────┘\n │\n ┌────────────────┐ │\n │ 11. Roadmap │ <─── ┌────────────────┐ <────┘\n └────────────────┘ │10. Architecture│\n └────────────────┘\n```\n\n### Stage Details\n\n1. **`understand`** *(Problem Understanding)*: Extracts domain constraints, core objectives, and technical challenges from the project prompt.\n2. **`plan`** *(Query Planning)*: Formulates targeted, boolean search queries tailored for search providers.\n3. **`search_web`** *(Web Search)*: Dispatches web queries via Serper API to collect current web articles and technical blogs.\n4. **`search_papers`** *(Academic Search)*: Fetches peer-reviewed papers from arXiv, Semantic Scholar, and IEEE Xplore.\n5. **`search_github`** *(Repository Search)*: Scrapes repository structures, stars, topics, and package dependency information.\n6. **`analyze`** *(Evidence Analysis)*: Synthesizes harvested sources, verifies relevance, and indexes text into the RAG vector store.\n7. **`solutions`** *(Solution Mapping)*: Categorizes existing market solutions, listing their pros, cons, and architectural patterns.\n8. **`gaps`** *(Innovation Gap Discovery)*: Identifies unaddressed technical gaps, scalability bottlenecks, and market opportunities.\n9. **`stress`** *(Adversarial Stress Testing)*: Critic agent subjects proposed solutions to failure mode analysis and security evaluations.\n10. **`architecture`** *(Architecture Design)*: Generates comprehensive component design specifications and Mermaid sequence/C4 diagrams.\n11. **`roadmap`** *(Roadmap Generation)*: Constructs a milestone-driven execution plan categorized into Phase 1 (MVP), Phase 2 (Scaling), and Phase 3 (Enterprise).\n\n---\n\n## 11. API Overview\n\nNEXUS exposes a structured RESTful API under the `/api` route prefix.\n\n### Authentication Endpoints (`/api/auth`)\n| Method | Endpoint | Description | Auth Required |\n| :--- | :--- | :--- | :---: |\n| `POST` | `/api/auth/register` | Register a new user account | No |\n| `POST` | `/api/auth/login` | Authenticate credentials & return JWT tokens | No |\n| `POST` | `/api/auth/refresh` | Obtain new access token via refresh token | No |\n| `POST` | `/api/auth/logout` | Invalidate active user session | Yes |\n| `GET` | `/api/auth/me` | Fetch authenticated user profile | Yes |\n\n### Project Endpoints (`/api/projects`)\n| Method | Endpoint | Description | Auth / Role |\n| :--- | :--- | :--- | :---: |\n| `GET` | `/api/projects` | List all user projects | Viewer |\n| `POST` | `/api/projects` | Create a new research project | Authenticated |\n| `GET` | `/api/projects/:id` | Get project details & metadata | Viewer |\n| `PUT` | `/api/projects/:id` | Update project title or description | Editor |\n| `DELETE`| `/api/projects/:id` | Soft-delete project | Owner |\n| `POST` | `/api/projects/:id/members` | Invite new team member | Owner |\n\n### Research Pipeline Endpoints (`/api/projects/:projectId/research`)\n| Method | Endpoint | Description | Auth / Role |\n| :--- | :--- | :--- | :---: |\n| `POST` | `/api/projects/:id/research/start` | Queue an 11-stage research job | Editor |\n| `GET` | `/api/projects/:id/research/job` | Fetch current research job state | Viewer |\n| `GET` | `/api/projects/:id/research/sources` | Retrieve harvested sources | Viewer |\n| `GET` | `/api/projects/:id/research/evidence` | Fetch extracted evidence claims | Viewer |\n| `GET` | `/api/projects/:id/research/solutions` | Fetch existing solution matrices | Viewer |\n| `GET` | `/api/projects/:id/research/gaps` | Fetch identified innovation gaps | Viewer |\n| `GET` | `/api/projects/:id/research/architecture` | Fetch generated system architecture | Viewer |\n| `GET` | `/api/projects/:id/research/roadmap` | Fetch implementation roadmap | Viewer |\n| `POST` | `/api/projects/:id/research/stresstest` | Trigger adversarial stress-test agent | Editor |\n\n### Copilot Endpoints (`/api/projects/:projectId/copilot`)\n| Method | Endpoint | Description | Auth / Role |\n| :--- | :--- | :--- | :---: |\n| `POST` | `/api/projects/:id/copilot/chat` | Send message to project Copilot agent | Viewer |\n| `GET` | `/api/projects/:id/copilot/conversations` | List project copilot sessions | Viewer |\n| `GET` | `/api/projects/:id/copilot/history` | Fetch message history for session | Viewer |\n\n---\n\n## 12. Database Schema\n\nNEXUS uses Mongoose schemas to persist projects, jobs, evidence, and user data in MongoDB:\n\n```mermaid\nerDiagram\n USER ||--o{ PROJECT_MEMBER : belongs_to\n PROJECT ||--o{ PROJECT_MEMBER : contains\n PROJECT ||--o{ RESEARCH_JOB : owns\n PROJECT ||--o{ RESEARCH_SOURCE : contains\n PROJECT ||--o{ EVIDENCE_CLAIM : contains\n PROJECT ||--o{ EXISTING_SOLUTION : tracks\n PROJECT ||--o{ INNOVATION_GAP : discovers\n RESEARCH_JOB ||--o{ RESEARCH_SOURCE : produces\n PROJECT ||--o{ DIAGRAM_ARTIFACT : generates\n USER ||--o{ CONVERSATION : initiates\n```\n\n### Primary Collections\n\n- **`User`**: User profile credentials, hashed password, role, and avatar settings.\n- **`Project`**: Root container storing project title, description, domain, status, and owner reference.\n- **`ResearchJob`**: Tracks execution state of an 11-stage pipeline, including stage status, progress %, timings, and errors.\n- **`ResearchSource`**: Harvested raw source metadata, title, author, URL, content snippet, and provider origin.\n- **`EvidenceClaim`**: Extracted claims verified by analysis agents, mapped with credibility scores.\n- **`ExistingSolution`**: Analysis of competitors, software frameworks, and existing market alternatives.\n- **`InnovationGap`**: Identified technical limitations, market voids, and opportunity vectors.\n- **`DiagramArtifact`**: Rendered Mermaid.js diagram definitions and Kroki URLs.\n- **`AIUsageLog`**: Audit record logging token consumption, execution latency, and cost per AI request.\n\n---\n\n## 13. Queue System\n\nLong-running research jobs are executed asynchronously outside the main API thread using **BullMQ** and **Redis**.\n\n```\n[REST API: POST /start] ──> Enqueue Job ──> [Redis Queue: 'research']\n │\n ▼\n[Worker: research.worker.ts] <── Dequeue Job ─────┘\n │\n ├── Process 11 Stages\n ├── Update MongoDB Checkpoints\n └── Emit Socket.io Events ──> [Connected Frontend Clients]\n```\n\n### Queue Characteristics\n- **Queue Name**: `research`\n- **Worker Concurrency**: Configured via `RESEARCH_WORKER_CONCURRENCY` (Default: `2`).\n- **Retry Strategy**: Exponential backoff with `RESEARCH_JOB_ATTEMPTS` retry attempts (Default: `2`).\n- **Graceful Shutdown**: Listens for `SIGTERM`/`SIGINT` to allow active in-flight jobs to complete checkpointing before releasing connections.\n\n---\n\n## 14. AI & Search Providers\n\n### Integrated LLM Providers (`AIRouter`)\n\nNEXUS connects to 7 major LLM providers via a unified interface:\n\n1. **OpenRouter**: Primary API gateway supporting unified access to top open and closed models.\n2. **Google Gemini**: Direct integration supporting `gemini-1.5-pro` and `gemini-1.5-flash`.\n3. **OpenAI**: Native adapter supporting `gpt-4o`, `gpt-4o-mini`, and embeddings models.\n4. **Anthropic**: Direct integration for `claude-3-5-sonnet` and `claude-3-haiku`.\n5. **Groq**: Ultra-low-latency provider for fast open-source inference (`llama-3`).\n6. **DeepSeek**: Adapter supporting `deepseek-chat` (V3) and `deepseek-reasoner` (R1).\n7. **Together AI**: Provider for open-weights model inference.\n\n### Integrated Search Providers\n\n1. 🌐 **Serper**: Google Web Search engine API.\n2. 📄 **arXiv**: Open-access academic paper repository search.\n3. 🔬 **Semantic Scholar**: Scientific paper metadata and citation engine.\n4. 📚 **IEEE Xplore**: Engineering literature and IEEE publication search.\n5. 🐙 **GitHub**: Repository, codebase structure, and topic search.\n6. 📦 **NPM Registry**: Node.js ecosystem package metadata lookup.\n7. 💬 **Stack Overflow**: Community technical Q&A search.\n\n---\n\n## 15. Application Screenshots\n\n*(Placeholder section — add application screenshots below)*\n\n<details>\n<summary>📸 View Application UI Placeholders</summary>\n\n### 1. Dashboard View\n\n\n### 2. Live Research Pipeline\n\n\n### 3. Architecture & Diagram Viewer\n\n\n### 4. Interactive Copilot\n\n\n</details>\n\n---\n\n## 16. Performance & Optimizations\n\n- 🚀 **Asynchronous Worker Execution**: Offloads heavy web scraping and LLM synthesis to background workers, keeping the API responsive.\n- ⚡ **Multi-Provider Fallback**: `AIRouter` dynamically routes past rate-limited or degraded LLM APIs without failing jobs.\n- 🧹 **Source Deduplication**: `deduplicator.ts` removes duplicate search results across providers based on normalized URL hashing.\n- 🧠 **Vector RAG Caching**: Chunks and caches indexed source embeddings to reduce redundant LLM context window consumption.\n- 📡 **WebSockets vs Polling**: Pushes real-time updates via Socket.io channels instead of requiring clients to perform expensive HTTP polling.\n\n---\n\n## 17. Security Architecture\n\n- **Token Security**: Short-lived JWT Access Tokens (15 mins) paired with HTTP-only Refresh Tokens (7 days).\n- **Password Protection**: Passwords hashed using strong `bcryptjs` salt rounds before DB persistence.\n- **Fail-Fast Config Validation**: `validateConfig()` validates presence of JWT secrets and valid port numbers at startup before opening database connections.\n- **Rate Limiting**: `express-rate-limit` enforces endpoint-specific request caps on authentication routes and research mutation calls.\n- **HTTP Security Headers**: `helmet` middleware configures standard XSS, MIME sniffing, and clickjacking protection headers.\n- **Strict Data Validation**: Request payloads are sanitized using `Zod` validation schemas before reaching controllers.\n\n---\n\n## 18. Development Workflow\n\n### Git Branching Model\n- `main`: Production-ready release branch.\n- `develop`: Integration branch for upcoming feature releases.\n- `feature/<feature-name>`: Topic branches for new capabilities.\n- `fix/<bug-name>`: Patch branches for issue fixes.\n\n### Commit Conventions\nNEXUS uses conventional commit messages:\n```text\nfeat(pipeline): add IEEE search provider integration\nfix(redis): prevent reconnect errors when client is active\ndocs(readme): update environment setup instructions\n```\n\n---\n\n## 19. Contributing Guide\n\nWe welcome contributions to NEXUS! Please follow these steps to contribute:\n\n1. **Fork the Repository**: Click the \"Fork\" button on GitHub.\n2. **Clone your Fork**:\n ```bash\n git clone https://github.com/your-username/nexus.git\n cd nexus\n ```\n3. **Create a Feature Branch**:\n ```bash\n git checkout -b feature/amazing-new-feature\n ```\n4. **Commit your Changes**:\n ```bash\n git commit -m \"feat(agent): implement new security audit agent\"\n ```\n5. **Push to Branch**:\n ```bash\n git push origin feature/amazing-new-feature\n ```\n6. **Open a Pull Request**: Describe your proposed changes and reference any related open issues.\n\n---\n\n## 20. Future Roadmap\n\n- [ ] **Multi-Tenancy & Teams**: Full organization management with custom workspaces.\n- [ ] **Autonomous Web Crawler**: Headless browser agent for interactive web page crawling.\n- [ ] **ChromaDB Cloud Cluster**: Native connector for remote managed vector indexes.\n- [ ] **Automated PDF Exporter**: High-fidelity PDF report generation with embedded charts.\n- [ ] **VS Code / IDE Extension**: Direct integration to view research insights inside the code editor.\n- [ ] **Slack & Discord Bots**: Trigger research pipelines via chat commands (`/nexus research \"idea\"`).\n\n---\n\n## 21. License\n\nDistributed under the **MIT License**. See `LICENSE` for more details.\n\n---\n\n## 22. Author\n\n**NEXUS R&D Team**\n- GitHub: [@Abhishekgujar28](https://github.com/Abhishekgujar28)\n- Project Repository: [https://github.com/Abhishekgujar28/NEXUS](https://github.com/Abhishekgujar28/NEXUS)\n\n---\n\n## 23. Acknowledgements\n\nSpecial thanks to the open-source projects and libraries that make NEXUS possible:\n\n- [React](https://react.dev/) & [Vite](https://vitejs.dev/)\n- [Express](https://expressjs.com/) & [Node.js](https://nodejs.org/)\n- [MongoDB](https://www.mongodb.com/) & [Mongoose](https://mongoosejs.com/)\n- [BullMQ](https://docs.bullmq.io/) & [Redis](https://redis.io/)\n- [OpenRouter](https://openrouter.ai/) & [Google Gemini](https://ai.google.dev/)\n- [TailwindCSS](https://tailwindcss.com/) & [Radix UI](https://www.radix-ui.com/)\n- [Mermaid.js](https://mermaid.js.org/) & [Kroki](https://kroki.io/)\n\n---\n\n<div align=\"center\">\n <sub>Built with ❤️ for developers, researchers, and technology pioneers worldwide.</sub>\n</div>\n"}}}} |