⚡ CodeCatalyst – Multi-Agent AI Repository Modernizer

📖 Overview

CodeCatalyst is a production-grade, multi-agent AI system that automatically analyzes GitHub repositories, detects security vulnerabilities, and migrates legacy code (JavaScript → TypeScript, Python 2 → 3) using a LangGraph orchestration with real-time streaming.

Built with a zero-cost architecture using open-source tools and Groq's free LLM tier, it demonstrates advanced AI engineering patterns including agentic workflows, RAG (Retrieval-Augmented Generation), and asynchronous microservices.

🔥 Live Demo: https://code-catalyst-loqv.onrender.com

🎯 Why CodeCatalyst?

Problem	Solution
Developers spend hours manually migrating legacy codebases	Automates the entire migration pipeline
Security vulnerabilities are hard to detect at scale	AI-powered security auditing with RAG
Migration often introduces new bugs	Critic agent validates and loops back until code passes
No transparency into AI decision-making	Real-time WebSocket streaming shows every agent's reasoning

🏗️ System Architecture

graph TD
    UI[React Frontend] -->|Paste GitHub URL| API[Node.js Express API]
    API -->|Submit Job| QUEUE[RabbitMQ]
    QUEUE -->|Consume Task| WORKER[Python Worker]
    WORKER -->|LangGraph StateGraph| SUP[Supervisor Agent]
    SUP -->|Route| PL[Planner Agent]
    PL -->|File Tree & Dependencies| SEC[Security Agent]
    SEC -->|RAG Query| CHROMA[ChromaDB / Mock RAG]
    SEC -->|Send Code| REF[Refactor Agent]
    REF -->|Rewrite using Groq/AST| CRIT[Critic Agent]
    CRIT -->|Linter Failed?| REF
    CRIT -->|Passed| DONE[Output Refactored Code]
    WORKER -->|Socket.IO Events| API
    API -->|Live Logs| UI

🤖 The 5 Specialized Agents

Agent	Role	Technology
Supervisor	Routes tasks and orchestrates the pipeline	Groq/Llama-3.1-70B
Planner	Maps dependencies and analyzes file structure	Python AST, `package.json` parser
Security	Detects vulnerabilities via RAG + pattern matching	ChromaDB, CVE database
Refactor	Rewrites code to modern standards	Groq + AST fallback
Critic	Validates code quality with correction loops	Pylint/ESLint + AST validation

✨ Features

🧠 Intelligent Agent Orchestration

5 specialized LangGraph agents with a Critic-led correction loop
Dynamic routing based on code analysis progress
Up to 3 retry loops for code quality assurance

🔒 Self-Populating RAG Pipeline

Automatically indexes codebases at function/class granularity
Semantic search for 10,000+ CVE vulnerability patterns
Fallback mechanisms if ChromaDB or Groq API is unavailable

📡 Real-Time Streaming

WebSocket (Socket.IO) streaming of agent reasoning
Live terminal-style logs in the browser
Transparency into every step of the AI decision-making

🐇 Async Microservices Architecture

RabbitMQ decouples the Node.js API from Python workers
Non-blocking, scalable job processing
Graceful fallback for API rate limits

💰 100% Free Stack

ChromaDB (local vector database)
Groq Llama-3.1-70B (free API tier)
All open-source tools – no hidden cloud costs

🛠️ Tech Stack

Layer	Technology
Frontend	React, Tailwind CSS, Socket.IO Client
Backend API	Node.js, Express, Socket.IO
Message Broker	RabbitMQ (CloudAMQP)
AI Orchestration	LangGraph (Python)
LLM	Groq (Llama-3.1-70B)
Vector DB	ChromaDB / Mock RAG
Code Parsing	Python AST, Regex
Containerization	Docker
Deployment	Render

📋 Prerequisites

Python 3.10+
Node.js 18+ & npm
RabbitMQ (or CloudAMQP free tier)
Groq API Key – Get it free here

🚀 Quick Start

1. Clone the Repository

git clone https://github.com/samrasdra-cmyk/code-catalyst.git
cd code-catalyst

2. Install Dependencies

Backend (Node.js):

cd backend
npm install

Frontend (React):

cd ../frontend
npm install

Worker (Python):

cd ../worker
pip install -r requirements.txt

3. Configure Environment Variables

Create a .env file in the worker/ folder:

GROQ_API_KEY=your_groq_api_key_here
RABBITMQ_URL=amqps://user:pass@your-rabbitmq-host/instance

4. Start the Infrastructure

With Docker (recommended):

docker compose up -d

Without Docker (Windows native):

# Start RabbitMQ (Admin PowerShell)
net start RabbitMQ

5. Launch the Application

Open 3 separate terminals:

Terminal	Command
Backend	`cd backend && node src/app.js`
Worker	`cd worker && python main.py`
Frontend	`cd frontend && npm start`

Visit http://localhost:3000 – paste a GitHub repo URL and watch the agents work! 🎬

🐳 Docker Deployment

Build and Run Locally

# Build the image
docker build -t codecatalyst .

# Run the container
docker run -d -p 5000:5000 -e GROQ_API_KEY="your_key" --name codecatalyst-app codecatalyst

# View logs
docker logs -f codecatalyst-app

Deploy to Render

Push your code to GitHub.
Go to render.com and sign up.
Click "New +" → "Blueprint".
Connect your GitHub repository.
Render will detect render.yaml.
Add environment variables:
- GROQ_API_KEY
- RABBITMQ_URL (from CloudAMQP)
Click "Apply".

🧠 How the Pipeline Works

1. User Submits GitHub URL

Frontend sends the URL to the backend via Socket.IO

2. Supervisor Agent Routes the Task

Analyzes the user's request
Decides which agent to call next

3. Planner Agent Analyzes the Repo

Clones the repository
Maps dependencies and file structure
Returns file list to the Supervisor

4. Security Agent Audits the Code

Uses ChromaDB RAG to detect vulnerabilities
Queries CVE patterns via semantic search
Returns vulnerability report

5. Refactor Agent Modernizes the Code

Uses Groq/Llama-3.1-70B to rewrite code
Falls back to AST transformations if Groq is unavailable

6. Critic Agent Validates the Output

Runs linters (Pylint/ESLint) on the refactored code
If it fails, loops back to Refactor (up to 3 times)
If it passes, the pipeline ends

7. Results Streamed to the Frontend

job_complete event stops the spinner
Refactored code and logs displayed

📁 Project Structure

code-catalyst/
├── backend/
│   ├── src/
│   │   ├── app.js          # Express server + Socket.IO
│   │   ├── socket.js       # WebSocket configuration
│   │   ├── queue/          # RabbitMQ producer
│   │   └── routes/         # API endpoints
│   └── package.json
├── frontend/
│   ├── src/
│   │   ├── App.js
│   │   ├── components/     # RepoInput, LogStream
│   │   └── socket.js
│   └── package.json
├── worker/
│   ├── main.py             # RabbitMQ consumer
│   ├── agents/             # 5 specialized LangGraph agents
│   ├── core/               # StateGraph & state management
│   ├── rag/                # ChromaDB client & indexer
│   ├── parsers/            # AST analyzers (Python/JS)
│   └── requirements.txt
├── Dockerfile
├── render.yaml
└── README.md

🐞 Troubleshooting

Issue	Solution
`ECONNREFUSED` RabbitMQ	Start RabbitMQ with `net start RabbitMQ` (Admin) or use CloudAMQP
Frontend shows "Could not reach backend gateway"	Update `frontend/src/socket.js` to use `window.location.origin` in production
Worker fails with syntax error	Ensure all `try:` blocks have matching `except` or `finally`
Pipeline completes but spinner keeps spinning	Move `job_complete` emit before `index_repo()` in `main.py`
ChromaDB OOM / slow indexing	Add `MAX_FILES_TO_INDEX = 40` in `indexer.py`
Groq API key exposed	Revoke at console.groq.com and generate a new key

🔑 Environment Variables

Variable	Where	Purpose
`GROQ_API_KEY`	Worker	LLM API key for Supervisor, Refactor, Critic agents
`RABBITMQ_URL`	Backend + Worker	RabbitMQ connection string
`NODE_ENV`	Backend	`production` or `development`
`FRONTEND_ORIGIN`	Backend	CORS allowed origin
`REACT_APP_SOCKET_URL`	Frontend	Socket.IO URL (optional)

🧪 Testing

Test the Backend Health Endpoint

curl https://code-catalyst-loqv.onrender.com/health
# Expected: {"status":"ok"}

Test Locally with a Sample Repo

Open http://localhost:3000
Paste https://github.com/facebook/react
Select "Convert JavaScript to TypeScript"
Click "Launch Multi-Agent Pipeline"
Watch the agents work in real-time!

🤝 Contributing

Pull requests are welcome! If you'd like to add support for a new language (Rust, Go, etc.) or improve the security RAG pipeline, feel free to open an issue first.

Development Setup

# Fork and clone the repo
git clone https://github.com/your-username/code-catalyst.git
cd code-catalyst

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r worker/requirements.txt
cd backend && npm install
cd ../frontend && npm install

# Run the full stack
# (Open 3 terminals as shown in Quick Start)

📜 License

This project is licensed under the MIT License. See LICENSE for details.

🙏 Acknowledgements

LangGraph – Agent orchestration framework
Groq – Free, fast LLM inference
RabbitMQ – Reliable message queuing
ChromaDB – Local vector database
Render – Easy cloud deployment

📞 Contact

Samra Safdar

Made with ❤️ by Samra Safdar – If this project helped you, please give it a ⭐ on GitHub!

🎯 What Makes This Project Stand Out

Feature	Why It's Impressive
Multi-Agent Orchestration	5 specialized agents working together with correction loops
RAG Pipeline	Self-populating vector DB for security auditing
Zero-Cost Architecture	All open-source, no cloud costs
Real-Time Streaming	Full transparency into AI decision-making
Async Microservices	RabbitMQ decoupling for scalability
Graceful Fallbacks	Works even when APIs fail
Production Deployment	Live on Render with Docker

Star ⭐ this repo if you found it useful!

Name		Name	Last commit message	Last commit date
Latest commit History 43 Commits
backend		backend
frontend		frontend
worker		worker
.dockerignore		.dockerignore
Dockerfile		Dockerfile
Dockerfile.backend		Dockerfile.backend
Dockerfile.worker		Dockerfile.worker
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
render.yaml		render.yaml
supervisord.conf		supervisord.conf

Folders and files

Latest commit

History

Repository files navigation