Project Overview
Project Atlas (OSS Repo Assistant) is an engineering tool designed to ease the onboarding ramp for open-source contributors. Running a local Node.js middleware backend, it clones target repositories, generates AST module maps, evaluates open issues, and dispatches specialized worker agents to write step-by-step fix plans and draft pull requests.
Problem & Motivation
The Problem
New open-source contributors experience friction when mapping codebase hierarchy and finding 'good first issues'. Maintainers face burnout reviewing poorly documented PRs. Project Atlas streamlines both sides by automating issue mapping, patch drafting, and PR text generation.
The Motivation
Diving into a massive, unfamiliar repository (like SymPy or Astropy) is intimidating. Developers spend hours reading file trees, looking up dependencies, and trying to trace functions. Project Atlas was built to act as an instant, local co-maintainer that explains exactly how a repo is structured and plans fixes for specific issues.
System Architecture
A hybrid execution engine. The lightweight local Node.js backend handles shallow Git cloning, workspace file indexing, and AI job scheduling. A visual frontend dashboard communicates with the backend via REST routes and Server-Sent Events (SSE) for real-time log streaming. Specialized agents (Planner, BugHunter, Security Auditor) utilize LLaMA 3.3 and Gemini for high-speed local codebase reasoning.
AST (Abstract Syntax Tree) indexing engine parsing files locally without uploading complete repositories to external cloud storage.
Shallow Git management using git clone --depth 10 --single-branch to optimize network and disk usage during analysis.
Real-time Server-Sent Events (SSE) logs pushing multi-stage workflow status updates directly to the client terminal overlay.
Centralized model dispatch configurations managing payload tokens between Groq (LLaMA 3.3 70B) and Gemini 2.5 Flash.
Key Features & Capabilities
11-Stage Workflow Orchestration
Real-time progress tracker and audit visualizer.
Architecture Analyzer
Maps file hierarchies and uncovers code patterns.
Bug & Security Auditor
Scans source trees for SQLi, XSS, ReDoS, and quality smells.
Automated PR Creator
Generates formatted PR markdown titles, descriptions, and testing steps.
Engineering Challenges
LLM Context Window Limits on Codebases
Large repositories exceed the context limits of affordable APIs. Passing entire codebases leads to high costs, latency, or truncated outputs.
Built a local File Ranking Heuristic Engine. Before sending data to the LLM, the backend scans the folder structure and ranks modules based on import density, size, and relevance to the target issue, selecting up to 12 critical files (max 6,000 characters each) to form a high-density prompt context.
Development Timeline
Designed shallow clone git manager services.
Created 11-stage orchestrator.js and agent pipelines.
Completed browser UI dashboard and integrated SSE streaming.
Lessons Learned
- Local hybrid architectures (local file operations + cloud API reasoning) provide the best mix of data privacy, speed, and cost efficiency.
- SSE streaming is far more reliable and easier to implement than WebSockets for pushing structured log feeds to dashboards.
Future Improvements
- Implement fully local semantic search using WebAssembly-compiled vector libraries.
- Integrate WebContainer APIs to run and validate generated patches directly in the client browser sandbox.