CortexAI

A full-stack, multi-agent AI workspace for research, coding, document generation, vision, and retrieval-augmented conversations

CortexAI is a locally operational AI product that combines a responsive React workspace with an API gateway, independently packaged Node.js services, a LangGraph supervisor, persistent conversations, Redis memory, RAG, multimodal input, generated artifacts, authentication, usage controls, and billing.

The application routes each request to a specialized agent automatically or lets the user select an agent explicitly. The result can be a Markdown answer, a web-grounded response, a multi-file code project, an image, a downloadable PDF or presentation, a vision analysis, or an answer grounded in an uploaded PDF.

Project status: The complete application is implemented and working end to end in the local environment. Firebase, MongoDB Atlas, Redis, Qdrant, AWS S3, Razorpay, and the configured AI/search providers are wired into the product. Public cloud hosting is intentionally outside the current milestone; no live production URL or production-traffic claim is made.

Demo

Watch the 18-second CortexAI walkthrough

The walkthrough and screenshots below were captured from the running application at http://localhost:5173.

Conversational AI with rich Markdown	Multi-file coding artifact

Image generation and S3 delivery	Plans, credits, and Razorpay billing UI

Firebase authentication gate

What makes this an AI engineering project

• Agent orchestration: a LangGraph state machine classifies each request and dispatches it to one of eight specialized execution paths.
• Retrieval-augmented generation: uploaded PDFs are parsed, chunked, embedded, indexed in Qdrant, retrieved with similarity search, and used as grounded LLM context.
• Model and tool routing: Groq, Gemini, OpenRouter, Tavily, Pollinations, Qdrant, and S3 are selected according to workload rather than hidden behind a single generic prompt.
• Multimodal input: the upload pipeline accepts images for Gemini vision analysis and PDFs for document question answering.
• Artifact-aware generation: the coding agent returns structured files that open in a Monaco editor with file tabs, copy controls, and a sandboxed HTML preview.
• Persistent product experience: MongoDB stores conversations and messages while Redis provides sessions, recent model context, and rate-limit counters.
• Platform concerns: Firebase authentication, service-to-service routing, credit deduction, per-agent rate limits, Razorpay verification, and presigned file delivery are separated from agent logic.

Implemented features

Feature	Implementation	Output
Automatic routing	LangGraph supervisor plus an LLM router	Selected specialist agent
General chat	Groq-backed assistant with Redis conversation memory	Markdown response
Web research	Tavily retrieval followed by the chat synthesis path	Search-grounded response and images
Coding assistant	Intent detection for generation, review, explanation, debugging, optimization, conversion, and documentation	Markdown or structured project files
Code workspace	Monaco editor, file tabs, copy action, and sandboxed preview	Interactive code artifact
PDF generation	LLM-authored content rendered through PDFKit and uploaded to S3	Expiring download link
Presentation generation	Structured slide generation through PptxGenJS and S3	.pptx download link
Image generation	Prompt enhancement, Pollinations generation, and S3 persistence	Inline image and download link
Vision	Uploaded image encoded for Gemini multimodal analysis	Grounded Markdown analysis
PDF RAG	PDF parsing, recursive chunks, Google embeddings, Qdrant top-k retrieval, grounded generation	Document-grounded answer
Authentication	Firebase Google sign-in, Firebase Admin verification, Redis-backed session cookie	Authenticated workspace
Conversations	MongoDB conversation/message persistence and recent-chat navigation	Restorable chat history
Usage controls	Per-agent Redis rate limits and persistent credit deduction	Controlled provider usage
Billing	Razorpay order creation, signature verification, and plan/credit updates	Starter and Pro upgrades
Voice input	Browser Speech Recognition with en-IN transcription	Prompt text

Architecture

flowchart LR
UI["React 19 + Vite workspace"] -->|"HTTP + session cookie"| GW["Express gateway :8000"]
GW --> AUTH["Auth service :8001"]
GW --> CHAT["Chat service :8002"]
GW --> AGENT["Agent service :8003"]
GW --> BILLING["Billing service :8004"]
AUTH --> MONGO[(MongoDB Atlas)]
CHAT --> MONGO
AGENT --> MONGO
BILLING --> MONGO
GW --> REDIS[(Redis)]
AUTH --> REDIS
AGENT --> REDIS
AGENT --> GRAPH["LangGraph supervisor"]
GRAPH --> SPECIALISTS["Chat / Search / Code / PDF / PPT / Image / Vision / PDF RAG"]
SPECIALISTS --> MODELS["Groq / Gemini / OpenRouter"]
SPECIALISTS --> TOOLS["Tavily / Qdrant / S3 / Pollinations"]
AUTH --> FIREBASE["Firebase Auth"]
BILLING --> RAZORPAY["Razorpay"]

Loading

Request lifecycle

1. The React client signs the user in through Firebase Google Authentication.
2. The auth service verifies the Firebase ID token, persists the user, creates a Redis session, and returns an HTTP-only cookie.
3. The gateway validates the session and forwards the trusted user ID to the appropriate internal service.
4. The agent service stores the user message and invokes the LangGraph supervisor.
5. The supervisor respects an explicit agent selection or classifies the prompt automatically.
6. The chosen agent calls its model and tool dependencies, deducts credits, and returns text, images, or structured artifacts.
7. The assistant result is persisted in MongoDB and added to Redis-backed conversation memory.

Agent routing

Route	Model/tool path
auto	Groq router -> selected specialist
chat	Groq llama-3.3-70b-versatile + Redis memory
search	Tavily -> Groq synthesis
coding	OpenRouter deepseek/deepseek-chat -> structured artifact parser
pdf	Groq -> PDFKit -> S3
ppt	Groq -> PptxGenJS -> S3
image	Groq prompt enhancement -> Pollinations -> S3
vision	Gemini 2.5 Flash with uploaded image content
pdf_rag	PDF Parse -> Google embeddings -> Qdrant -> Groq

Technology stack

Layer	Technologies
Frontend	React 19, Vite, Redux Toolkit, Tailwind CSS, Framer Motion
AI workspace	React Markdown, syntax highlighting, Monaco Editor, sandboxed iframe preview
API and services	Node.js 22, Express 5, HTTP proxying, Multer
Agent system	LangGraph, LangChain, Groq, Gemini, OpenRouter
Retrieval and tools	Qdrant, Google embeddings, Tavily, PDF Parse, Pollinations
Data and cache	MongoDB Atlas, Mongoose, Redis, ioredis
Generated artifacts	PDFKit, PptxGenJS, AWS S3 presigned URLs
Identity and payments	Firebase Authentication, Firebase Admin, Razorpay
Packaging	Independent npm manifests/lockfiles and service-level Dockerfiles

Repository structure

cortex-ai/
|-- frontend/
| |-- src/components/ # Chat, navigation, billing, and artifact UI
| |-- src/features/ # API adapters
| |-- src/redux/ # Client state
| |-- src/utils/ # Axios and language detection
| `-- firebase.js # Firebase web client
|-- backend/
| |-- gateway/ # Public API gateway and session middleware
| |-- services/
| | |-- auth/ # Firebase verification, users, Redis sessions
| | |-- chat/ # Conversations and messages
| | |-- agent/ # LangGraph and eight specialized agent paths
| | `-- billing/ # Razorpay and plan/credit updates
| |-- shared/redis/ # Shared Redis client
| `-- docker-compose.yml # Local Redis service
|-- docs/screenshots/ # Captures from the running product
|-- docs/demo/ # Short product walkthrough
`-- README.md

Reproduce the project locally

These steps reproduce the complete system from a fresh clone. All secrets stay in ignored local environment files. Firebase Admin additionally requires one ignored service-account JSON file.

1. Prerequisites

• Node.js 22.x and npm 10+
• Docker Desktop with Docker Compose, or a local Redis installation
• A MongoDB Atlas cluster or local MongoDB instance
• A Firebase project with Google Authentication enabled
• API credentials for the features you intend to exercise

For the full feature set, configure Groq, Google AI, OpenRouter, Tavily, Qdrant Cloud, AWS S3, and Razorpay Test Mode. The basic authenticated chat path needs Firebase, MongoDB, Redis, and Groq.

2. Clone the repository

git clone https://github.com/tusharg007/Cortex.git cortex-ai
cd cortex-ai

This is a private repository, so the cloning GitHub account must be granted access first.

3. Install dependencies

Each service is independently packaged and has its own lockfile.

cd backend
npm ci
cd gateway && npm ci &&cd ..
cd services/auth && npm ci &&cd ../..
cd services/chat && npm ci &&cd ../..
cd services/agent && npm ci &&cd ../..
cd services/billing && npm ci &&cd ../../..
cd frontend
npm ci
cd ..

On Windows PowerShell, use npm.cmd if the script execution policy blocks npm.ps1.

4. Create the environment files

All of the following files are covered by the root .gitignore.

frontend/.env

VITE_FIREBASE_API_KEY=<firebase-web-api-key>VITE_SERVER_URL=http://localhost:8000VITE_RAZORPAY_KEY=<razorpay-test-key-id>

The repository already contains the public Firebase identifiers for the configured CortexAI web app. If reproducing against a different Firebase project, replace the public authDomain, projectId, storageBucket, messagingSenderId, and appId values in frontend/firebase.js with the web configuration supplied by that Firebase project.

backend/gateway/.env

PORT=8000REDIS_URL=redis://127.0.0.1:6379AUTH_SERVICE=http://localhost:8001CHAT_SERVICE=http://localhost:8002AGENT_SERVICE=http://localhost:8003BILLING_SERVICE=http://localhost:8004

backend/services/auth/.env

PORT=8001MONGODB_URL=<mongodb-connection-string>FRONTEND_URL=http://localhost:5173REDIS_URL=redis://127.0.0.1:6379

backend/services/chat/.env

PORT=8002MONGODB_URL=<mongodb-connection-string>

backend/services/agent/.env

PORT=8003MONGODB_URL=<mongodb-connection-string>REDIS_URL=redis://127.0.0.1:6379CHAT_SERVICE=http://localhost:8002AUTH_SERVICE=http://localhost:8001GATEWAY_URL=http://localhost:8000GROQ_API_KEY=<groq-api-key>GOOGLE_API_KEY=<google-ai-api-key>OPENROUTER_API_KEY=<openrouter-api-key>TAVILY_API_KEY=<tavily-api-key>QDRANT_URL=<qdrant-cluster-url>QDRANT_API_KEY=<qdrant-api-key>AWS_ACCESS_KEY_ID=<aws-access-key-id>AWS_SECRET_ACCESS_KEY=<aws-secret-access-key>AWS_REGION=<aws-region>AWS_BUCKET_NAME=<private-s3-bucket-name>

backend/services/billing/.env

PORT=8004MONGODB_URL=<mongodb-connection-string>AUTH_SERVICE=http://localhost:8001RAZORPAY_KEY_ID=<razorpay-test-key-id>RAZORPAY_KEY_SECRET=<razorpay-test-key-secret>

The services may share one Atlas cluster. They can also use separate database names when isolation is preferred.

5. Configure Firebase Admin

1. Open Firebase Console -> Project settings -> Service accounts.

2. Generate a new private key.

3. Save the downloaded file locally as:

   backend/services/auth/serviceAccount.json
   

4. Enable the Google provider under Authentication -> Sign-in method.

5. Ensure localhost is present under Authentication -> Authorized domains.

serviceAccount.json is ignored by Git. Never commit, upload, or share it.

6. Configure the feature providers

• MongoDB Atlas: allow the development machine's IP and copy the driver connection string into each required MONGODB_URL.
• Qdrant Cloud: create a cluster and use its HTTPS URL/API key. The PDF-RAG path creates a temporary collection per document and removes it after answering.
• AWS S3: use a private bucket and an IAM identity limited to the required object operations. Generated files are delivered through expiring presigned URLs.
• Razorpay: use Test Mode credentials while reproducing the billing flow; do not use a live key for local testing.
• AI/search providers: create provider keys and check each account's current model access and quota.

7. Start Redis

From the repository root:

docker compose -f backend/docker-compose.yml up -d

If Redis is installed directly, start it on 127.0.0.1:6379 instead.

8. Start the backend

Open five terminals from the repository root and start services in this order:

# Terminal 1 - authenticationcd backend/services/auth
npm start

# Terminal 2 - conversationscd backend/services/chat
npm start

# Terminal 3 - AI orchestrationcd backend/services/agent
npm start

# Terminal 4 - billingcd backend/services/billing
npm start

# Terminal 5 - public gatewaycd backend/gateway
npm start

Process	Port
Gateway	8000
Auth	8001
Chat	8002
Agent	8003
Billing	8004
Redis	6379

Confirm the gateway is healthy:

curl http://localhost:8000/

Expected response:

{"service":"gateway","status":"ok"}

9. Start the frontend

cd frontend
npm run dev

Open http://localhost:5173, continue with Google, and create a conversation.

10. Verify every agent path

Path	Reproduction action
Chat	Select Chat and ask Explain retrieval-augmented generation in five bullets.
Automatic routing	Select Auto and ask a clearly coding- or search-oriented question.
Coding	Select Coding and ask Build a responsive analytics dashboard. Open its file tabs and Preview mode.
Search	Select Search and ask a current-information question.
Image	Select Image and request an illustration; verify the inline image and download link.
PDF	Select PDF, request a document, and open its signed download URL.
PPT	Select PPT, request a presentation, and download the generated .pptx.
Vision	Attach a JPG/PNG, ask a question about it, and submit through any agent selection; the router detects the image.
PDF RAG	Attach a PDF and ask a question answered by that document; the router detects the PDF.
Persistence	Reload the page and reopen the conversation from Recents.
Billing	Open the credits icon and inspect the Starter/Pro plans using Razorpay Test Mode.

API surface

All browser-facing requests enter through the gateway at http://localhost:8000.

Route group	Purpose
/api/auth/*	Firebase login and session logout
/api/me	Read the authenticated Redis session
/api/chat/*	Create, list, rename, and restore conversations/messages
/api/agent/chat	Submit prompts, agent selection, and optional PDF/image files
/api/billing/*	Create and verify Razorpay orders

Local verification

The repository was inspected and the application was exercised locally on August 8, 2026:

• Authenticated frontend workspace: working
• Conversation creation and persistence: working
• Markdown chat response: working
• Coding-agent structured artifact and Monaco editor: working
• Image generation and S3-backed delivery: working
• Billing/credit interface: working
• Frontend production build: passed
• Backend JavaScript syntax validation: passed for 52 source files

There is not yet an automated backend integration-test suite, and frontend lint contains existing findings. These are quality-improvement items rather than unimplemented product features.

Security and repository hygiene

• All .env files, private keys, build output, uploads, and serviceAccount.json are excluded from version control.
• Use development/test credentials for local reproduction and rotate any credential that has ever been shared or committed.
• Keep the S3 bucket private and deliver artifacts only through presigned URLs.
• Treat ports 8001 through 8004 as internal service endpoints outside local development.
• Never place Firebase Admin, Razorpay secret, AWS secret, database, or provider credentials in frontend variables.
• Public deployment requires HTTPS cookie, CORS, private-network, health-check, and secret-injection hardening; it is intentionally not claimed here.

Engineering focus

CortexAI is designed as a practical reference implementation for agentic application engineering. It keeps orchestration, data persistence, authentication, billing, and file-generation concerns separate so that each can be inspected, evolved, and tested independently.

The project prioritizes traceable request routing, grounded document workflows, reusable generated artifacts, and local reproducibility over claims of production scale.