CodeCompare AI

An AI-powered software project comparison platform that allows users to upload two versions of the same project, compare them visually, analyze code changes, classify the modifications, and generate human-readable summaries.

Features

• Authentication: Firebase-based email/password authentication
• Project Upload: Upload two project versions as ZIP files
• File Processing: Extract and scan project files with intelligent ignoring of unnecessary files
• Diff Engine: Compare old and new projects file-by-file
• AI Analysis: Gemini-powered analysis for technical summaries, classifications, and impact assessment
• Visual Diff: Side-by-side code comparison viewer
• Comparison History: Save and revisit previous comparisons
• Report Export: Export comparison reports as HTML or text

Tech Stack

Frontend

• React 18 with TypeScript
• Tailwind CSS
• shadcn/ui components
• Zustand for state management
• React Router for navigation
• Firebase SDK for authentication

Backend

• Node.js with Express
• TypeScript
• Firebase Admin SDK
• Gemini AI API for code analysis
• adm-zip for ZIP extraction
• diff library for text comparison

Project Structure

CodeCompareAI/
├── frontend/                    # React frontend application
│   ├── src/
│   │   ├── components/
│   │   │   ├── ui/           # shadcn/ui components
│   │   │   └── layout/       # Layout components
│   │   ├── pages/            # Page components
│   │   ├── stores/           # Zustand stores
│   │   ├── services/         # API services
│   │   ├── types/            # TypeScript types
│   │   └── lib/               # Library configs
│   └── ...
├── backend/                    # Express backend API
│   ├── src/
│   │   ├── routes/           # API routes
│   │   ├── services/         # Business logic
│   │   ├── middleware/        # Express middleware
│   │   ├── utils/            # Utilities
│   │   └── config/           # Configuration
│   └── ...
├── SPEC.md                     # Technical specification
└── README.md                   # This file

Prerequisites

• Node.js 18+
• npm or yarn
• Firebase project (with Firestore, Authentication, and Storage enabled)
• Gemini API key

Setup Instructions

1. Clone and Install

# Clone the repository
cd CodeCompareAI

# Install root dependencies
npm install

# Install frontend dependencies
cd frontend && npm install
cd ..

# Install backend dependencies
cd backend && npm install
cd ..

2. Firebase Setup

1. Create a Firebase project at console.firebase.google.com

2. Enable the following services:

   • Authentication: Enable Email/Password provider
   • Firestore: Create a database (start in test mode for development)
   • Storage: Create a storage bucket (start in test mode for development)

3. Get your Firebase configuration:

   • Go to Project Settings > General > Your apps
   • Add a Web app and copy the configuration

4. Generate a private key for the backend:

   • Go to Project Settings > Service accounts
   • Click "Generate new private key"
   • Save the JSON file (you'll need it for the backend)

3. Gemini API Setup

1. Get a Gemini API key from Google AI Studio

4. Environment Configuration

Create environment files in both frontend and backend:

Frontend (.env)

cd frontend
cp .env.example .env

Edit frontend/.env:

VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_API_URL=http://localhost:3001/api

Backend (.env)

cd backend
cp .env.example .env

Edit backend/.env:

PORT=3001
NODE_ENV=development
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_CLIENT_EMAIL=your_client_email
FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
GEMINI_API_KEY=your_gemini_api_key
ALLOWED_ORIGINS=http://localhost:5173
MAX_FILE_SIZE=104857600

5. Firebase Security Rules

For development/testing, use permissive rules. For production, configure proper rules.

Firestore Rules:

rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
    match /comparisons/{comparisonId} {
      allow read, write: if request.auth != null && request.auth.uid == resource.data.userId;
    }
    match /comparison_files/{fileId} {
      allow read, write: if request.auth != null;
    }
  }
}

Storage Rules:

rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    match /projects/{userId}/{comparisonId}/{fileName} {
      allow read, write: if request.auth != null && request.auth.uid == userId;
    }
  }
}

Running the Application

Development Mode

From the root directory:

npm run dev

This will start both frontend and backend concurrently:

• Frontend: http://localhost:5173
• Backend: http://localhost:3001

Individual Services

Frontend only:

cd frontend
npm run dev

Backend only:

cd backend
npm run dev

Production Build

# Build both
npm run build

# Or individually
cd frontend && npm run build
cd backend && npm run build

API Endpoints

Authentication

• POST /api/auth/register - Register new user
• POST /api/auth/login - Login with Firebase token
• POST /api/auth/logout - Logout
• GET /api/auth/me - Get current user

Comparisons

• POST /api/comparisons - Create new comparison
• GET /api/comparisons - List user's comparisons
• GET /api/comparisons/:id - Get comparison details
• DELETE /api/comparisons/:id - Delete comparison
• POST /api/comparisons/:id/upload - Upload ZIP files
• POST /api/comparisons/:id/analyze - Start analysis
• GET /api/comparisons/:id/status - Get analysis status
• GET /api/comparisons/:id/files - List comparison files
• GET /api/comparisons/:id/files/:fileId - Get file details
• GET /api/comparisons/:id/files/:fileId/diff - Get file diff
• POST /api/comparisons/:id/export - Export report

Usage Flow

1. Register/Login: Create an account or login
2. Create Comparison: Click "New Comparison" and enter a title
3. Upload Files: Drag and drop ZIP files for old and new versions
4. Analyze: Wait for processing and AI analysis
5. View Results: Browse files, view diffs, read AI summaries
6. Export: Download HTML or text reports

AI Classification Categories

• UI/UX: User interface and visual elements
• Functionality: Core business logic and features
• Architecture: Structural changes and design patterns
• Config: Configuration files and dependencies
• Documentation: README and documentation files
• Other: Uncategorized changes

Ignored Files

The following patterns are automatically ignored during comparison:

• node_modules/**
• .git/**
• dist/**, build/**, .next/**
• Binary files (images, videos, fonts, etc.)
• Lock files and logs
• OS-specific files (.DS_Store, Thumbs.db)

Troubleshooting

CORS Errors

Ensure ALLOWED_ORIGINS in backend .env includes your frontend URL.

Firebase Auth Issues

• Verify Firebase config is correct
• Check that Authentication is enabled in Firebase console
• Ensure the email/password sign-in method is enabled

Gemini API Errors

• Verify the API key is correct
• Check API quotas and billing
• Ensure the API is enabled for your project

Upload Fails

• Check file size limits (default 100MB)
• Ensure file is a valid ZIP
• Verify Firebase Storage is properly configured

License

MIT

👨‍💻 Author

Nadeem Dayoub
CubeCode Studio

💡 Tagline

"Understand code changes like a human, not just a machine."