🚀 Project-Atlas — AI-Powered Open Source Contribution Assistant

An intelligent Hybrid Client + Node.js Execution Engine web application designed to supercharge open-source contributions. By combining a lightweight Node.js backend (with shallow Git cloning, persistent job queues, and real-time SSE streaming) with the reasoning power of Google Gemini and Groq (LLaMA 3.3 70B), Project-Atlas helps developers analyze codebases locally, discover architectural patterns, hunt bugs, identify good first issues, generate remediation plans, and draft pull requests automatically.

---

🌟 Why It's Useful (The Value Proposition)

Navigating a new open-source repository can be overwhelming. Contributors spend hours reading documentation, mapping out dependencies, and understanding code styles before writing a single line of code. Maintainers struggle to triage issues and write detailed onboarding guides.

Project-Atlas v2.0.0 bridges this gap by providing an instant AI co-maintainer:

• ⚡ Hybrid Execution Engine: Runs a lightweight local Node.js backend that handles shallow Git cloning (--depth 10 --single-branch), AST indexing, and AI job orchestration. Your repository clones and API keys remain strictly on your local machine.
• 📦 Persistent Workspace & Local Caching: Clones repositories into a dedicated local workspace/ folder. Re-analyzing a previously visited repo takes just seconds via smart git fetch caching.
• 🔍 Real-Time SSE Terminal & Granular Progress: Watch an 11-stage AI workflow execute in real-time with color-coded terminal logs, file scan counters, AI generation stats, and dynamic progress bars.
• 🎯 Targeted Opportunity Matching & Bug Hunting: Evaluates open issues and performs automated local bug hunting to uncover unlisted code errors, security risks, and architectural bottlenecks.
• 🛠️ End-to-End Workflow: From initial repository exploration to generating copy-pasteable Pull Request titles, descriptions, and verification tests.
• 🤖 AI Coding Assistant Integration: Exports structured context files (AGENTS.md) optimized for modern AI coding agents like Antigravity, Cursor, and Windsurf.

---

✨ Key Features & Modules

Feature Module	Description
📊 Dashboard & Overview	Real-time repository metrics, commit activity visualizations, language distribution charts, and interactive file tree browser.
🏗️ Architecture Analyzer	Uncovers architectural design patterns, maps component dependencies, and explains system hierarchy.
🎯 Opportunity Finder	Discovers actionable contribution opportunities by matching open issues with high-impact codebase areas.
🐛 Bug & Security Auditor	Performs automated AI code reviews on critical source files to detect bugs, security vulnerabilities, and quality bottlenecks.
🛠️ Step-by-Step Fix Planner	Generates concrete, step-by-step code remediation plans and patches for any identified issue or bug.
🚀 Automated PR Generator	Automatically drafts polished Pull Request summaries, detailed changelogs, testing steps, and impact analyses.
📁 Agent Files Generator	Synthesizes repository rules and workflows into custom .agents/AGENTS.md files for local AI development tools.

---

🏛️ System Architecture

Project-Atlas v2.0.0 is built with a lightweight Hybrid Architecture, combining a responsive vanilla frontend with a robust Node.js execution backend that handles Git operations, AST indexing, persistent job queuing, and SSE streaming.

🔄 Architecture & Data Flow

graph TD
    subgraph Frontend [Client-Side Browser Dashboard]
        UI[Interactive UI Shell / index.html]
        Router[App Router & Modal Manager / app.js]
        SSEClient[SSE & REST Client / api-client.js]
    end

    subgraph Backend [Node.js Execution Engine / port 3000]
        Server[Express Server & REST Routes / server.js]
        Queue[Persistent Job Queue / jobQueue.js]
        Orchestrator[11-Stage Workflow Orchestrator / orchestrator.js]
        Git[Shallow Git Manager & Workspace Cache / gitManager.js]
    end

    subgraph Agents [Modular AI Agents / backend/agents]
        Planner[Stage 4: Strategy Planner]
        BugHunter[Stage 5: Bug Hunter]
        SecAudit[Stage 6: Security Auditor]
        Quality[Stage 7: Quality Reviewer]
        Contrib[Stage 8: Contribution Finder]
        Synth[Stage 9: Report Synthesizer]
    end

    subgraph External [External Services & Storage]
        GitHub[GitHub REST / Git CLI]
        Groq[Groq LLaMA 3.3 70B API]
        Gemini[Google Gemini 2.5 Flash API]
        FS[Local Workspace / workspace/]
    end

    UI --> Router
    Router <--> |REST / SSE Real-Time Logs| SSEClient
    SSEClient <--> Server
    Server --> Queue
    Queue --> Orchestrator
    Orchestrator <--> |Shallow Clone / Sync| Git
    Git <--> |Clones & Diffs| GitHub
    Git <--> |Read / Write Local Repos| FS
    Orchestrator --> |Dispatch Tasks| Agents
    Agents <--> |Fast Code Reasoning| Groq
    Agents <--> |Deep Report Synthesis| Gemini

Loading

🗂️ Codebase Component Breakdown

OSS REPO ASSISTANT/
├── index.html              # Main application shell, sidebar navigation, modal dialogs, and layout
├── package.json            # Node.js dependencies and server start scripts
├── backend/                # Node.js Execution Engine & API Server
│   ├── server.js           # Express server entry point (port 3000) serving static assets and API
│   ├── routes/api.js       # REST endpoints (/analyze, /jobs, /report) and Server-Sent Events (SSE)
│   ├── services/           # Core background services
│   │   ├── gitManager.js   # Shallow Git cloning (--depth 10), AST parsing, and file utilities
│   │   ├── jobQueue.js     # Persistent job state tracking and event broadcasting
│   │   ├── orchestrator.js # 11-stage AI workflow execution engine and concurrency limiter
│   │   └── issueStreamer.js# Background pagination and caching for GitHub issues
│   └── agents/             # Modular AI worker agents
│       ├── planner.js      # Strategy formulation and file ranking
│       ├── bugHunter.js    # Deep code analysis for bugs and edge cases
│       ├── security.js     # Vulnerability scanning (SQLi, XSS, ReDoS, auth bypass)
│       ├── quality.js      # Maintainability and code smell audits
│       └── synthesizer.js  # Lead Gemini report synthesis
├── css/                    # Modular styling design system
│   ├── main.css            # Core CSS variables, layout grid, typography, and dark mode themes
│   └── components.css      # UI component styling (cards, badges, modals, toast alerts, workflow bar)
├── js/                     # Client-side application logic
│   ├── app.js              # State management, navigation routing, and modal handling
│   ├── api-client.js       # REST fetch wrappers and EventSource SSE stream listener
│   ├── analysis.js         # Client-side AI fallback helpers and schemas
│   └── utils.js            # Key storage (localStorage), formatting, and toast notifications
└── pages/                  # Modular view controllers for each application section
    ├── dashboard.js        # Overview dashboard with repo activity and quick actions
    ├── overview.js         # Repository structure, README viewer, and language distribution
    ├── architecture.js     # AI-generated architectural breakdown and pattern detection
    ├── issues.js           # Issue triage and background streaming status
    ├── opportunities.js    # Curated contribution opportunities and task recommendations
    ├── findings.js         # 11-stage workflow progress UI and real-time terminal logger
    ├── fixer.js            # Step-by-step fix planner and code remediation suggestions
    ├── prgenerator.js      # Automated Pull Request draft and changelog creator
    ├── agentfiles.js       # AI agent instruction file exporter (AGENTS.md)
    └── report.js           # Comprehensive synthesized repository analysis report

---

🛠️ Setup Guide & Usage

Project-Atlas offers two convenient ways to configure your API keys: using the interactive GUI modal or via a local .env file.

Note

All API keys are stored locally in your browser's localStorage or read directly from your local file. They are never sent to external servers other than the official AI providers (Google and Groq).

Method 1: Interactive GUI Setup (Recommended for Quick Start)

1. Open index.html in your web browser (or serve it using a local development server like npx serve . or VS Code Live Server).
2. Upon launching, the Project-Atlas Setup Modal will automatically appear (you can also open it anytime by clicking API Settings in the bottom-left sidebar).
3. Paste your API keys into the modal fields:
   • Gemini API Key: Required for deep report synthesis. Get a free key here.
   • Groq API Key: Required for high-speed LLaMA 3.3 code reasoning. Get a free key here.
   • GitHub Personal Access Token (PAT): Optional but recommended. Increases GitHub API rate limits from 60 to 5,000 requests per hour and allows analyzing private repositories. Generate a token here.
4. Click Save & Continue. You're ready to analyze any GitHub repository!

Method 2: Local Environment File (.env Setup)

If you are running the project locally or serving it via a web server, you can configure your credentials using an environment file:

1. Locate the .env.example file in the project root directory.
2. Rename the file from .env.example to .env:

   # On Windows (PowerShell / CMD)
   ren .env.example .env
   
   # On Linux / macOS
   mv .env.example .env

3. Open .env in your code editor and paste your API keys:

   GEMINI_KEY="AIzaSyYourActualGoogleGeminiApiKeyHere"
   GROQ_KEY="gsk_YourActualGroqApiKeyHere"
   GITHUB_TOKEN="ghp_YourOptionalGitHubPersonalAccessTokenHere"

4. When the application loads, js/utils.js automatically fetches and parses the .env file, populating your API keys seamlessly without requiring manual GUI input!

---

🤖 How to Change & Customize AI Models

Project-Atlas is designed with model flexibility in mind. The AI models used across different analysis tasks are centrally configured in js/utils.js.

1. Changing Default Model Assignments

To switch AI models for specific tasks (e.g., upgrading to a newer LLaMA model or switching to Gemini 1.5 Pro), open js/utils.js and locate the MODEL_CONFIG object around line 64:

// ── Model Configurations (js/utils.js) ────────────────────────
const MODEL_CONFIG = {
  bugHunter: "llama-3.3-70b-versatile",         // Change to "llama-3.1-8b-instant" for faster/cheaper runs
  securityAuditor: "llama-3.3-70b-versatile",     // Swap with "mixtral-8x7b-32768" if desired
  qualityReviewer: "llama-3.3-70b-versatile",
  contributionFinder: "llama-3.3-70b-versatile",
  reportSynthesizer: "gemini-2.5-flash",          // Swap with "gemini-1.5-pro" for deeper reasoning
  issueExplainer: "llama-3.3-70b-versatile",
  fileSummarizer: "llama-3.3-70b-versatile"
};

2. Customizing Inference Parameters & System Prompts

If you want to tune temperature, sampling behavior, or system prompts, open js/analysis.js. The AnalysisEngine object defines how requests are dispatched:

• Groq Inference (AnalysisEngine.groq): Configures JSON mode and temperature (default 0.2 for deterministic analytical reasoning). You can adjust temperature per task inside analysis.js.
• Gemini Inference (AnalysisEngine.gemini): Handles large-context report generation and executive summaries.

Tip

Prompt Engineering: You can customize the AI personas (e.g., making the Bug Hunter more rigorous or focusing on accessibility issues) by editing the prompt templates inside js/analysis.js.

---

🚀 Systems & Features to Work On (Roadmap)

We actively welcome contributions! Whether you are looking for a Good First Issue or a major architectural project, here are the key systems and features currently on our development roadmap:

1. 🛡️ Multi-Node Background Worker Scaling

• Current State: Single Node.js backend instance (backend/server.js) managing persistent job queues and SSE streams locally.
• Feature to Work On: Add Redis or RabbitMQ job queue backing to allow horizontal scaling of backend worker agents across multiple server instances for enterprise org-level repository scanning.

2. 🧠 Vector Embeddings & Semantic Code Search

• Current State: Codebase ingestion relies on heuristics (js/ingestion.js) to rank and select up to 12 key files (max 6,000 characters each).
• Feature to Work On: Implement client-side vector search using Transformers.js (running embeddings locally via WebAssembly/WebGPU) or IndexedDB vector indexing. This will enable semantic querying across entire large repositories without context window limitations.

3. 🧪 Live In-Browser Test Runner & Validation

• Current State: The Fix Planner and PR Generator output code snippets and markdown instructions.
• Feature to Work On: Integrate WebContainer API or Pyodide/WebAssembly sandbox execution so users can apply AI-generated fix plans and execute unit tests directly inside the browser before submitting a PR.

4. 🔀 Multi-Repository Comparison & Ecosystem Triage

• Current State: Single repository analysis per session.
• Feature to Work On: Create a multi-repo comparison dashboard that analyzes organization-wide dependency health, cross-repository issues, and ecosystem compatibility.

5. 🎨 Custom Reviewer Personas & Rules Editor

• Current State: Fixed analysis prompts in js/analysis.js.
• Feature to Work On: Add an interactive UI settings panel allowing users to create, save, and share custom review personas (e.g., "Strict Rust Security Reviewer", "Junior Frontend Mentor", "Performance & Memory Auditor").

6. 📑 Export & Shareable Reports

• Current State: Reports are viewed in the browser dashboard.
• Feature to Work On: Implement one-click export to standalone PDF documents, Markdown archives, or shareable URL snapshots (via GitHub Gists or local JSON file import/export).

---

🤝 How to Contribute

1. Fork the repository on GitHub.
2. Clone your fork locally:

   git clone https://github.com/your-username/oss-repo-assistant.git
   cd oss-repo-assistant

3. Create your feature branch: git checkout -b feature/amazing-feature.
4. Configure your .env file from .env.example as detailed in the Setup Guide.
5. Commit your changes and open a Pull Request! Our automated PR generator can even help you write the description! 🚀

---

Built with ❤️ for the Open Source Community.