Open Source Project Discovery

Mwadali — Sun, 01 Mar 2026 17:12:17 +0000

This is a submission for the DEV Weekend Challenge: Community

The Community

Open source contributors — from nervous first-timers to seasoned maintainers. The people who want to give back, learn by doing, and build something meaningful. But here's the problem: GitHub has 100+ million repositories. Finding the right project that matches your skills, needs contributors, and has a welcoming community? That's like finding a specific grain of sand on a beach.

I built this for anyone who's ever:

Stared at "good first issue" labels on projects using languages they've never heard of
Wanted to contribute but had no idea where to start
Spent hours browsing GitHub, only to find abandoned repos or projects way beyond their skill level
Felt paralyzed by choice overload

What I Built

🧭 OSS Compass — your personal navigator through the open source galaxy.

You tell it three things:

Your skill level (Beginner / Intermediate / Expert)
Languages you know (JavaScript, Python, Rust, etc.)
What excites you (Web Dev, ML, CLI Tools, Security, Games...)

It hands you 5 active, well-maintained GitHub projects that actually need people like you. Not random repos. Not abandoned projects. Not stuff that's way over your head.

Real projects. Real communities. Real impact.

The Magic Ingredients

✨ Smart GitHub Queries — Different search strategies for different skill levels. Beginners get projects with 5+ good-first-issues. Experts get high-impact repos with complex challenges.

🔍 Live Validation — Every project is checked in real-time: Is it active? How many stars? Good first issues? When was the last commit? No dead projects make the cut.

💾 Your Journey, Remembered — Auto-save your profile, bookmark favorites, track search history. Come back tomorrow, skip the form, see your results.

⚡ Supercharged UX — Keyboard navigation, animated progress bars, instant filtering by language/stars/activity, mobile-responsive. It feels good to use.

🛡️ Rate Limiting & Caching — Smart caching means same profile = instant results. Rate limiting protects the API without killing the experience.

Demo

Live Experience

Try it yourself: https://open-source-santa-7jnj.vercel.app/

Quick Tour

Step 1: Pick your skill level
![Skill level selection with three cards: Beginner, Intermediate, Expert]

Step 2: Select your languages (JavaScript, Python, Go, TypeScript...)

Step 3: Choose your interests (Web Dev, ML, DevTools, Games...)

Results: Your personalized project recommendations
![Project cards with stars, languages, descriptions, and action buttons]

Each project card shows:

Real-time GitHub stats (⭐ stars, open issues)
Last commit date (no ghost towns)
Good-first-issue badge for beginners
A personalized "why this project" explanation
Your specific first step to contribute

Filter & Search:

Search by name, description, or tags
Sort by relevance, stars, or recent activity
Filter by programming language
Bookmark favorites for later

Code

https://github.com/wellingtonmwadali/OpenSourceSanta

Key Technical Decisions

1. No LLM API Needed

I initially planned to use Claude or GPT for recommendations. Then I realized: GitHub's search API is already incredibly powerful. Why add cost, latency, and API dependencies when intelligent query construction does the job?

// Different queries for different skill levels
function buildSearchQuery(languages: string[], interests: string[], level: string) {
  let baseCriteria = "";
  if (level === "beginner") {
    baseCriteria = "good-first-issues:>3 stars:>100 forks:>10";
  } else if (level === "intermediate") {
    baseCriteria = "stars:>500 forks:>50";
  } else {
    baseCriteria = "stars:>1000 forks:>100";
  }
  // Combine with languages and interest topics...
}

2. Real-Time Repo Validation

Every project gets validated against 7 criteria: stars, open issues, has good-first-issues labels, last push date, activity status, topics, and homepage. Dead repos never see the light of day.

export async function validateAndEnrichRepo(repoSlug: string): Promise<RepoData | null> {
  const { data } = await octokit.repos.get({ owner, repo });

  // Check for good-first-issue labels
  const { data: labels } = await octokit.issues.listLabelsForRepo({ owner, repo });
  const hasGoodFirstIssues = labels.some(label => 
    label.name.toLowerCase().includes("good") && 
    label.name.toLowerCase().includes("first")
  );

  // Check if active (pushed within 3 months)
  const lastPush = new Date(data.pushed_at);
  const threeMonthsAgo = new Date();
  threeMonthsAgo.setMonth(threeMonthsAgo.getMonth() - 3);
  const isActive = lastPush > threeMonthsAgo;

  return { stars, openIssues, hasGoodFirstIssues, lastPushDate, isActive, ... };
}

3. Client-Side State Machine

The app has 3 states: form → loading → results. Each state has its own UX. Loading state cycles through encouraging messages every 2 seconds while showing progress from 0→100%.

const LOADING_MESSAGES = [
  "Scanning active GitHub repositories…",
  "Checking community health signals…",
  "Matching your skills to open issues…",
  "Evaluating project friendliness…",
  "Curating your perfect matches…",
];

4. Persistent Storage Without a Database

localStorage handles everything: user profile, search history (last 5), and bookmarked repos. No backend, no auth, no database. Your browser is your database.

export function saveProfile(profile: UserProfile) {
  if (typeof window === 'undefined') return;
  localStorage.setItem('oss_compass_profile', JSON.stringify(profile));
}

export function addBookmark(repoSlug: string) {
  const bookmarks = getBookmarks();
  if (!bookmarks.includes(repoSlug)) {
    bookmarks.push(repoSlug);
    localStorage.setItem('oss_compass_bookmarks', JSON.stringify(bookmarks));
  }
}

5. Smart Caching with 30-Min TTL

Same profile within 30 minutes? Instant results from memory. Reduces API calls, speeds up repeat visits, and keeps the GitHub API happy.

How I Built It

Tech Stack

Next.js 14 (App Router) — Server components + API routes in one framework
TypeScript — Type safety for GitHub API responses and user data
Tailwind CSS — Rapid UI development with utility classes
Octokit (GitHub API) — Official GitHub REST API client
Zod — Runtime validation for API requests

Architecture

📦 OSS Compass
├── app/
│   ├── page.tsx                    # Main client component (564 lines of state management)
│   ├── api/recommend/route.ts      # GitHub search + validation logic
│   └── layout.tsx                  # Root layout with metadata
├── components/
│   ├── SkillLevelPicker.tsx        # Visual skill level selector
│   ├── ChipSelector.tsx            # Multi-select chips for languages/interests
│   ├── ProjectCard.tsx             # Rich project display with GitHub data
│   └── StepIndicator.tsx           # Progress visualization
├── lib/
│   ├── github.ts                   # Octokit wrappers + repo validation
│   ├── validation.ts               # Zod schemas for type-safe APIs
│   ├── storage.ts                  # localStorage abstraction
│   ├── cache.ts                    # In-memory request caching
│   ├── rate-limit.ts               # IP-based rate limiting
│   └── constants.ts                # Languages, interests, skill levels
└── types/
    └── index.ts                    # Shared TypeScript types

The Build Process

Day 1: Core MVP

Built the 3-step form, wired up GitHub API, got basic search working. Realized 60% of results were abandoned repos. Added validation layer.

Day 2: UX Polish

Added keyboard navigation, loading states, progress bars, error handling. Made it feel native.

Day 3: Features That Matter

Implemented filtering, sorting, search, bookmarks, and caching. Turned it from a toy into a tool.

Day 4: Edge Cases & Performance

Rate limiting, error messages, mobile responsiveness, accessibility. The unglamorous stuff that makes or breaks real-world use.

Challenges & Solutions

Problem: GitHub API rate limits (60 req/hour unauthenticated, 5000/hour with token)

Solution: Added caching + rate limiting middleware. Same profile = cached results. Different profiles = track requests per IP.

Problem: Some repos have tons of stars but zero good-first-issues (not beginner-friendly)

Solution: Check labels for each repo, surface "good first issue" badge, adjust "why" messaging based on presence of those issues.

Problem: Users don't want to fill out the form every visit

Solution: Auto-save profile to localStorage, show "Welcome back!" with pre-filled form.

Problem: Results can be overwhelming (language mixing, unclear next steps)

Solution: Added language filter, sort options, search bar, and personalized "first step" guidance per project.

Why This Matters

Open source contribution is often a "if you know, you know" club. You need to:

Know which repos are beginner-friendly
Understand project activity signals (stars, issues, last commit)
Find projects that match your skills
Overcome imposter syndrome enough to make that first PR

OSS Compass removes those barriers. It's not just a search tool — it's a matchmaking service for developers and communities.

What I Learned

GitHub's API is underrated. With smart queries, you can build powerful discovery tools without LLMs.
State management is hard. Juggling form state, API state, filter state, and persistent storage taught me to respect React's useEffect.
UX microinteractions matter. The loading messages, keyboard shortcuts, and animated transitions turned a functional tool into something delightful.
Validation is never optional. Real-world data is messy. Repos can be archived, renamed, or deleted. Always validate before displaying.

What's Next?

GitHub OAuth: Personalized recommendations based on your starred repos and contribution history
Weekly Digest Emails: "Here are 3 new projects that match your profile"
Community Reviews: Let users rate/review projects for others
Contribution Tracking: Track which projects you've contributed to
Project Health Score: More nuanced metrics (PR merge rate, issue response time, maintainer activity)

Final Thoughts

The open source community is built on people helping people. But finding where you fit in? That's still too hard.

OSS Compass is my contribution to making contribution easier.

If you've ever wanted to dive into open source but didn't know where to start — this one's for you. 🧭

Built with 💙 by Wellington

Try it live: https://open-source-santa-7jnj.vercel.app/

Source code: https://github.com/wellingtonmwadali/OpenSourceSanta

DEV Community: Mwadali