GitScope - Complete Setup Guide

📋 Project Overview

GitScope is a full-stack web application that analyzes GitHub profiles and provides actionable recommendations. It includes:

• ✅ Frontend with interactive UI
• ✅ Node.js/Express backend
• ✅ SQLite database
• ✅ Email notifications
• ✅ Contact form management

---

🚀 Quick Start

1. Install Node.js

Download and install from: https://nodejs.org (LTS version recommended)

2. Install Dependencies

npm install

3. Setup Environment Variables

Copy .env.example to .env and configure:

cp .env.example .env

Edit .env with your email credentials:

PORT=3000
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-16-char-app-password
ADMIN_EMAIL=mamididhana145@gmail.com

4. Start the Server

npm start

Server will run on: http://localhost:3000

---

📂 Project Structure

GitProject/
├── index.html           # Main frontend page
├── style.css            # Styling
├── script.js            # Frontend logic + API calls
├── server.js            # Express backend server
├── package.json         # Node dependencies
├── github-analyzer.db   # SQLite database (auto-created)
├── .env                 # Environment variables (create this)
├── .env.example         # Environment template
├── SETUP.md            # Detailed setup guide
└── README.md           # This file

---

🔐 Email Configuration

Gmail Setup

1. Enable 2FA: https://myaccount.google.com/security
2. Generate App Password: https://myaccount.google.com/apppasswords
   • Select: Mail → Windows Computer
   • Copy the 16-character password
   • Paste into .env as EMAIL_PASSWORD

Alternative Email Services

• SendGrid: Update nodemailer config in server.js
• AWS SES: Use AWS credentials
• Mailgun: Use Mailgun transport

---

💾 Database

SQLite Tables

users table

CREATE TABLE users (
    id INTEGER PRIMARY KEY,
    username TEXT UNIQUE,
    email TEXT,
    lastAnalyzed TIMESTAMP,
    analysisCount INTEGER,
    createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

reports table

CREATE TABLE reports (
    id INTEGER PRIMARY KEY,
    username TEXT,
    email TEXT,
    score INTEGER,
    grade TEXT,
    analysisData TEXT,
    createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

contacts table

CREATE TABLE contacts (
    id INTEGER PRIMARY KEY,
    name TEXT,
    email TEXT,
    subject TEXT,
    message TEXT,
    status TEXT DEFAULT 'unread',
    createdAt TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

---

🔌 API Endpoints

Save Analysis Report

POST /api/save-report
Content-Type: application/json

{
    "username": "octocat",
    "email": "user@example.com",
    "score": 85,
    "grade": "B",
    "analysisData": { /* analysis object */ }
}

Response:
{
    "success": true,
    "message": "Detailed report sent to user@example.com",
    "reportId": 1
}

Submit Contact Form

POST /api/contact
Content-Type: application/json

{
    "name": "John Doe",
    "email": "john@example.com",
    "subject": "Support Request",
    "message": "Need help with my profile"
}

Response:
{
    "success": true,
    "message": "Message saved. We will respond within 24 hours."
}

Get User Reports

GET /api/user/:email

Response:
[
    {
        "id": 1,
        "username": "octocat",
        "email": "user@example.com",
        "score": 85,
        "grade": "B",
        "createdAt": "2026-02-25 10:30:00"
    }
]

Get All Contacts (Admin)

GET /api/contacts

Response:
[
    {
        "id": 1,
        "name": "John Doe",
        "email": "john@example.com",
        "subject": "Support",
        "message": "Help me...",
        "status": "unread",
        "createdAt": "2026-02-25 10:30:00"
    }
]

---

🎨 Frontend Integration

The frontend automatically sends reports to the backend when users click "Get My Free Detailed Report".

Key Variables in script.js

const API_URL = 'http://localhost:3000'; // Change for production
let currentUsername = '';
let currentScore = 0;
let currentGrade = '';
let currentAnalysisData = {};

Email Subscription Function

async function subscribeReport() {
    const email = document.getElementById('reportEmail')?.value;
    
    const response = await fetch(`${API_URL}/api/save-report`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
            username: currentUsername,
            email: email,
            score: currentScore,
            grade: currentGrade,
            analysisData: currentAnalysisData
        })
    });
    
    const result = await response.json();
    alert(result.message);
}

---

🌐 Production Deployment

Heroku Deployment

1. Install Heroku CLI: https://devcenter.heroku.com/articles/heroku-cli

2. Login to Heroku

heroku login

3. Create App

heroku create github-analyzer

4. Set Environment Variables

heroku config:set EMAIL_USER=your-email@gmail.com
heroku config:set EMAIL_PASSWORD=your-app-password
heroku config:set ADMIN_EMAIL=admin@gmail.com

5. Deploy

git push heroku main

6. View Logs

heroku logs --tail

Railway.app Deployment

1. Connect GitHub repo to Railway
2. Set environment variables in dashboard
3. Deploy automatically

Other Platforms

• Render.com: Similar to Railway
• Fly.io: Docker-based deployment
• AWS: EC2 + RDS database

---

🐛 Troubleshooting

Email Not Sending?

• ✓ Verify .env configuration
• ✓ Check Gmail App Password is correct
• ✓ Ensure 2FA is enabled on Gmail
• ✓ Check server logs: npm start

Database Errors?

• ✓ Delete github-analyzer.db and restart
• ✓ Verify SQLite3 is installed: npm ls sqlite3

Port Already in Use?

• ✓ Change PORT in .env to 3001, 3002, etc.
• ✓ Kill existing process: lsof -i :3000

CORS Errors?

• ✓ Ensure CORS is enabled in server.js
• ✓ Update API_URL in script.js for production

---

📞 Support

Email: mamididhana145@gmail.com
GitHub: Your repository
Issues: Use project's issue tracker

---

📄 License

MIT License - See LICENSE file for details

---

✨ Features

• ✅ Analyze GitHub profiles instantly
• ✅ Get personalized recommendations
• ✅ Receive detailed reports via email
• ✅ Track analysis history
• ✅ Contact form with notifications
• ✅ Dark/Light theme support
• ✅ Responsive design
• ✅ Secure data handling
• ✅ Fast database queries
• ✅ Email management system

---

🔄 Updates & Maintenance

Update Dependencies

npm update

Check for Vulnerabilities

npm audit
npm audit fix

Database Backup

cp github-analyzer.db github-analyzer.backup.db

---

Last Updated: February 25, 2026