Issue Finder Case Study

Situation & Problem Statement

Contributing to open-source software is one of the most effective ways for developers to build real-world experience, expand their portfolios, and collaborate with global engineering teams. However, finding the right first issue is notoriously difficult:

• GitHub's native issue search requires complex manual syntax filters (e.g., is:open is:issue label:"good first issue" no:assignee language:TypeScript).
• There is no central dashboard that aggregates and ranks beginner-friendly issues across trending repositories.
• Aspiring contributors often spend 45+ minutes browsing dead issues or repository backlogs, leading to contributor burnout before writing a single line of code.

Project Vision & Scope

I created Issue Finder to serve as a fast, intuitive discovery engine for open-source contributors:

1. Aggregated Discovery: Index beginner-friendly issues (good first issue, help wanted, documentation, beginner) across thousands of active GitHub repositories.
2. Multi-Faceted Filtering: Filter instantaneously by programming language, star thresholds, recent update activity, and comment count.
3. Smart Rate-Limit Management: Handle GitHub API search limits gracefully without cutting off users during peak discovery sessions.
4. Frictionless Workflow: Allow developers to bookmark issues, filter out assigned tasks, and jump directly to code in one click.

Technical Architecture

[User Filters & Search Query]
              │
              ▼
    [Next.js App Router]
              │
    ┌─────────┴─────────┐
    ▼                   ▼
[Cache Layer (Supabase)] [GitHub Search API Gateway]
    │                   │ (Rate Limit Throttling & Queue)
    └─────────┬─────────┘
              ▼
[Normalized Issue JSON Stream] ───> [Responsive Client Grid]

1. GitHub API Gateway & Rate-Limit Throttling

GitHub's Search API enforces strict rate limits (30 requests/minute for authenticated tokens, 10 for unauthenticated requests). To overcome this constraint:

• Engineered a server-side caching and deduplication layer in Next.js API routes backed by Supabase.
• Standard search query combinations (e.g. TypeScript + good-first-issue + 1k+ stars) are cached for 2 hours, serving hundreds of repeat searches with 0 upstream GitHub API calls.
• Implemented exponential backoff and rate-limit header parsing (x-ratelimit-remaining, x-ratelimit-reset).

2. Search Syntax Construction

Constructed a dynamic query compiler that translates user UI selections into optimized GitHub search queries:

const buildGitHubSearchQuery = ({ language, label, minStars }: FilterParams) => {
  const parts = [
    "is:issue",
    "is:open",
    "no:assignee",
    `label:"${label || "good first issue"}"`,
  ];
  if (language) parts.push(`language:${language}`);
  if (minStars) parts.push(`stars:>=${minStars}`);
  return parts.join(" ");
};

3. Progressive Web App (PWA) Client

• Designed with Tailwind CSS using an adaptable dark-mode developer palette.
• Configured with offline PWA manifests, allowing users to review previously bookmarked issues even when disconnected.

Measurable Results

• Time to First Issue: Reduced the average time required to discover an actionable beginner issue from 25+ minutes to under 30 seconds.
• Community Adoption: Hundreds of monthly active developers searching for open-source opportunities.
• Search Latency: Cached queries resolve in under 120ms.
• Live Deployment: Live at issue-finder.acharyanischal.com.np with full open-source code on GitHub.

Frequently Asked Questions

How does Issue Finder determine if an issue is genuinely unassigned?

Issue Finder verifies both the assignee field and recent PR timeline events to ensure that someone else hasn't already submitted a pending fix, saving contributors from duplicate effort.

Can I search by specific tech stacks like Next.js, Laravel, or Rust?

Yes. You can filter by top languages as well as text keywords, allowing you to target specific frameworks, libraries, or ecosystem tools.