Cortex AI — Multi-Agent AI Orchestration Platform

Cortex AI is a state-of-the-art, microservice-based AI platform that coordinates specialized AI agents (using LangGraph and LangChain) to solve complex workflows. Users can chat with general assistants, run programming scripts, generate PDFs or PowerPoint presentations, execute semantic search queries over documents (RAG), use computer vision, and generate images.

🏗️ Architecture Overview

Cortex AI is structured as a collection of decoupled microservices managed by an API Gateway:

graph TD
    User([User/Browser]) -->|HTTP/WebSockets| Gateway[API Gateway :8000]
    Gateway -->|Rate Limiter| Redis[(Redis :6379)]
    Gateway -->|Auth Check| AuthService[Auth Service :8001]
    Gateway -->|Proxies Requests| ChatService[Chat Service :8002]
    Gateway -->|Proxies Requests| AgentService[Agent Service :8003]
    Gateway -->|Proxies Requests| BillingService[Billing Service :8004]

    AuthService --> MongoDB_Auth[(MongoDB: cortex_auth)]
    AuthService --> Firebase[Firebase Auth & Admin SDK]

    ChatService --> MongoDB_Chat[(MongoDB: cortex_chat)]

    AgentService --> MongoDB_Agent[(MongoDB: cortex_agent)]
    AgentService --> LangGraph[LangGraph Agent Orchestrator]
    AgentService --> LLMs[LLMs: Gemini / Groq / OpenRouter]
    AgentService --> Qdrant[(Qdrant Vector DB)]
    AgentService --> S3[AWS S3 File Storage]

    BillingService --> MongoDB_Billing[(MongoDB: cortex_billing)]
    BillingService --> Razorpay[Razorpay Payment Gateway]

Repository Structure

cortex-ai/
├── package.json                   # Workspace root package.json for script orchestration
├── frontend/                      # React SPA with Vite, Redux, Tailwind CSS v4, and Monaco Editor
│   ├── .env.example
│   ├── firebase.js                # Firebase client-side config
│   └── src/
└── backend/                       # Backend microservices and utilities
    ├── docker-compose.yml         # Dev services setup (Redis)
    ├── package.json
    ├── gateway/                   # API Gateway (Express Proxy, Redis rate limiting)
    │   └── .env.example
    ├── shared/                    # Code shared between services (e.g. Redis client connection)
    └── services/
        ├── agent/                 # LangGraph agent orchestration service
        │   ├── .env.example
        │   ├── agents/            # Specialized agents (chat, coding, search, pdf, ppt, etc.)
        │   └── graph/             # Supervisor state graph setup
        ├── auth/                  # Authentication service (Firebase Admin API, MongoDB)
        │   ├── .env.example
        │   └── serviceAccount.json # Firebase Admin credentials
        ├── billing/               # Billing and payment integration (Razorpay, MongoDB)
        │   └── .env.example
        └── chat/                  # Chat state persistence service (MongoDB)
            └── .env.example

🛠️ Tech Stack & Specialized Agents

Frontend: React (v19), Vite, Tailwind CSS (v4), Redux Toolkit, Framer Motion, Monaco Editor (@monaco-editor/react), Lucide React.
Backend Microservices: Node.js (ESM), Express.js (v5), ioredis, mongoose, multer, pdfkit, pptxgenjs, pdf-parse.
AI Framework & Orchestration: LangGraph, LangChain Core, Tavily Search, Qdrant Vector Database.
Authentication: Firebase Authentication (Client-side) & Firebase Admin SDK (Server-side verification).
Payments: Razorpay Node SDK.
Storage: AWS S3 Node SDK (for file uploads and PDF/PPT artifacts).

LangGraph Agent Graph

Cortex AI routes user prompt requests dynamically via a Supervisor Router Node to these specialized agent nodes:

chat: Standard chat assistant (powered by Llama 3.3 70B via Groq).
coding: Code analysis and script generator (powered by DeepSeek-Chat via OpenRouter).
search: Online search capability (using Tavily API to fetch real-time search context).
pdf: Dynamic PDF document generator (using pdfkit).
ppt: Dynamic PowerPoint slideshow generator (using pptxgenjs).
image: Generates and edits images.
vision: Image description and visual understanding (powered by Gemini 2.5 Flash).
pdf_rag: Document search & question answering (using Qdrant and text splitters).

📋 Prerequisites

Before starting local development, make sure you have the following:

Node.js (v18.x or above)
Docker Desktop (for Redis container)
MongoDB Instance running locally or via Atlas
Accounts & API Keys for:
- Firebase (Web Project & Admin SDK Private Key)
- Groq API
- Google AI Studio (Gemini)
- OpenRouter
- Tavily Search
- Qdrant (Cloud or local database instance)
- AWS S3 (Bucket & Access Credentials)
- Razorpay (API Key ID & Secret)

🚀 Getting Started

Step 1: Install Dependencies

From the root workspace directory, run:

npm run install:all

This script installs parent dependencies, concurrently (for running services), and automatically triggers npm install inside all subprojects (frontend, gateway, agent, auth, billing, and chat).

Step 2: Set Up Environment Files

Copy the environment template files in each service directory and populate them with your secrets:

# Frontend
cp frontend/.env.example frontend/.env

# Gateway
cp backend/gateway/.env.example backend/gateway/.env

# Services
cp backend/services/auth/.env.example backend/services/auth/.env
cp backend/services/chat/.env.example backend/services/chat/.env
cp backend/services/agent/.env.example backend/services/agent/.env
cp backend/services/billing/.env.example backend/services/billing/.env

Step 3: Firebase Admin Setup

Go to your Firebase Console -> Project Settings -> Service Accounts.
Click Generate New Private Key.
Download the JSON file, rename it to serviceAccount.json, and place it in the backend/services/auth/ directory:
```
# Path to place the credentials:
backend/services/auth/serviceAccount.json
```

Step 4: Start Databases & Cache

Use Docker Compose to spin up Redis:

npm run redis:up

Step 5: Start the Development Server

Launch the entire frontend and all microservices concurrently with one command:

npm run dev:all

Once initialized, the services will be running on:

Frontend SPA: http://localhost:5173
API Gateway: http://localhost:8000
Auth Service: http://localhost:8001
Chat Service: http://localhost:8002
Agent Service: http://localhost:8003
Billing Service: http://localhost:8004

To shut down Redis when finished:

npm run redis:down

🔧 Environment Variables Guidance

Frontend Config (`frontend/.env`)

Variable	Description	Example / Required
`VITE_FIREBASE_API_KEY`	Client-side Firebase project API key.	`AIzaSyA1...`
`VITE_SERVER_URL`	Base API Gateway endpoint address.	`http://localhost:8000`
`VITE_RAZORPAY_KEY`	Razorpay Key ID used to initialize Checkout.	`rzp_test_...`

API Gateway Config (`backend/gateway/.env`)

Variable	Description	Example / Required
`PORT`	API Gateway entry port.	`8000`
`REDIS_URL`	Redis instance connection URL.	`redis://localhost:6379`
`AUTH_SERVICE`	Auth microservice local URL.	`http://localhost:8001`
`CHAT_SERVICE`	Chat microservice local URL.	`http://localhost:8002`
`AGENT_SERVICE`	Agent microservice local URL.	`http://localhost:8003`
`BILLING_SERVICE`	Billing microservice local URL.	`http://localhost:8004`

Agent Service Config (`backend/services/agent/.env`)

Variable	Description	Example / Required
`PORT`	Running port for the Agent Service.	`8003`
`MONGODB_URL`	MongoDB database connection URI.	`mongodb://localhost:27017/cortex_agent`
`GOOGLE_API_KEY`	Gemini API Key for vision models.	`AIzaSy...`
`GROQ_API_KEY`	Groq API Key for Llama 3.3.	`gsk_...`
`OPENROUTER_API_KEY`	API Key for DeepSeek-Chat.	`sk-or-v1-...`
`TAVILY_API_KEY`	Web Search tool key.	`tvly-...`
`QDRANT_URL`	Qdrant vector database URL.	`https://...` or `http://localhost:6333`
`QDRANT_API_KEY`	Qdrant Database API credentials.	`your_key`
`AWS_ACCESS_KEY_ID`	AWS developer credentials for S3.	`AKIA...`
`AWS_SECRET_ACCESS_KEY`	AWS secret access key.	`your_secret`
`AWS_REGION`	AWS S3 Bucket hosting region.	`ap-south-1`
`AWS_BUCKET_NAME`	S3 bucket name.	`cortex-ai-artifacts`
`GATEWAY_URL`	Gateway URL.	`http://localhost:8000`
`AUTH_SERVICE`	Auth microservice address.	`http://localhost:8001`
`CHAT_SERVICE`	Chat microservice address.	`http://localhost:8002`

Auth Service Config (`backend/services/auth/.env`)

Variable	Description	Example / Required
`PORT`	Running port for the Auth Service.	`8001`
`MONGODB_URL`	MongoDB database connection URI.	`mongodb://localhost:27017/cortex_auth`
`FRONTEND_URL`	Client URL allowed for CORS.	`http://localhost:5173`

Billing Service Config (`backend/services/billing/.env`)

Variable	Description	Example / Required
`PORT`	Running port for the Billing Service.	`8004`
`MONGODB_URL`	MongoDB database connection URI.	`mongodb://localhost:27017/cortex_billing`
`AUTH_SERVICE`	Auth microservice address.	`http://localhost:8001`
`RAZORPAY_KEY_ID`	Razorpay Developer Key ID.	`rzp_test_...`
`RAZORPAY_KEY_SECRET`	Razorpay Private Secret Key.	`your_razorpay_secret`

Chat Service Config (`backend/services/chat/.env`)

Variable	Description	Example / Required
`PORT`	Running port for the Chat Service.	`8002`
`MONGODB_URL`	MongoDB database connection URI.	`mongodb://localhost:27017/cortex_chat`

🤝 Contribution Guidelines

We welcome contributions! Please adhere to the following steps to ensure smooth collaboration:

1. Code Standards

Keep files written as ES Modules (import/export).
Do not hardcode API credentials. Always use process.env in the backend and import.meta.env in Vite.
Document helper functions and include comments explaining complex logic, especially within LangGraph agents.

2. How to Add a New AI Agent to the Orchestrator

To extend the orchestrator with a new agent (e.g. translation):

Create the Agent Logic: Create a new file in backend/services/agent/agents/translation.agent.js:

export const translationAgent = async (state) => {
    // 1. Perform rate limiting & credit deductions
    // 2. Load model from utils/model.js
    // 3. Process instructions
    // 4. Return updated state
};

Define Model Binding: Add any new model instances to backend/services/agent/utils/model.js in the getModel switch.
Update Graph Annotation State: If your agent needs custom context fields, append them to AgentState in backend/services/agent/graph/state.js.

Register the Node: Import and add the agent node in backend/services/agent/graph/supervisor.graph.js:

import { translationAgent } from "../agents/translation.agent.js";
// ...
workflow.addNode("translation", translationAgent);

Configure Routing: In the router conditional switch block inside supervisor.graph.js, add the transition logic routing to "translation", and wire up the edge:
```
workflow.addEdge("translation", "__end__");
```

3. Git Workflow

Fork the repository and create your branch from main:
```
git checkout -b feature/amazing-feature
```
Test your changes locally.

Commit your changes following standard messages:

git commit -m "feat: add translation agent to supervisor"

Push your changes and open a Pull Request.

📄 License

This project is licensed under the ISC License.

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
backend		backend
frontend		frontend
.gitignore		.gitignore
README.md		README.md
package.json		package.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Cortex AI — Multi-Agent AI Orchestration Platform

🏗️ Architecture Overview

Repository Structure

🛠️ Tech Stack & Specialized Agents

LangGraph Agent Graph

📋 Prerequisites

🚀 Getting Started

Step 1: Install Dependencies

Step 2: Set Up Environment Files

Step 3: Firebase Admin Setup

Step 4: Start Databases & Cache

Step 5: Start the Development Server

🔧 Environment Variables Guidance

Frontend Config (`frontend/.env`)

API Gateway Config (`backend/gateway/.env`)

Agent Service Config (`backend/services/agent/.env`)

Auth Service Config (`backend/services/auth/.env`)

Billing Service Config (`backend/services/billing/.env`)

Chat Service Config (`backend/services/chat/.env`)

🤝 Contribution Guidelines

1. Code Standards

2. How to Add a New AI Agent to the Orchestrator

3. Git Workflow

📄 License

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Cortex AI — Multi-Agent AI Orchestration Platform

🏗️ Architecture Overview

Repository Structure

🛠️ Tech Stack & Specialized Agents

LangGraph Agent Graph

📋 Prerequisites

🚀 Getting Started

Step 1: Install Dependencies

Step 2: Set Up Environment Files

Step 3: Firebase Admin Setup

Step 4: Start Databases & Cache

Step 5: Start the Development Server

🔧 Environment Variables Guidance

Frontend Config (frontend/.env)

API Gateway Config (backend/gateway/.env)

Agent Service Config (backend/services/agent/.env)

Auth Service Config (backend/services/auth/.env)

Billing Service Config (backend/services/billing/.env)

Chat Service Config (backend/services/chat/.env)

🤝 Contribution Guidelines

1. Code Standards

2. How to Add a New AI Agent to the Orchestrator

3. Git Workflow

📄 License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Frontend Config (`frontend/.env`)

API Gateway Config (`backend/gateway/.env`)

Agent Service Config (`backend/services/agent/.env`)

Auth Service Config (`backend/services/auth/.env`)

Billing Service Config (`backend/services/billing/.env`)

Chat Service Config (`backend/services/chat/.env`)