I wanted a tool that answers that honestly, and with a bit of humour. You type a GitHub username. You get a score out of 1000, a funny roast, and a clear list of things to fix. You also get a link you can share.

That is GitRoasted. In this blog I will explain how I built it, why I made certain choices, and what I would do again.

Live demo: git-roasted-ai.vercel.app
Code: github.com/ahmmikun/GitRoasted

Where the Idea Came From

I want to be honest here. The idea of roasting GitHub profiles already existed. There is an earlier project also called GitRoasted by MdKasif0, and I used it as inspiration for features like a leaderboard, comparison and improvement tips.

I did not copy its code, text or design. I built my own scoring system, my own architecture and my own UI. But I think it is right to say where the spark came from.

The first version (the MVP) was very small:

1. User enters a username.
2. App fetches the profile and repositories.
3. AI writes a roast, a score and some tips.
4. Result is saved in MongoDB and shown on a public link.

No login. No signup. That was a deliberate choice. A tool like this only works if people can try it in five seconds.

The Stack

I also used Kiro to work in a spec-driven way. I wrote requirements first, broke them into tasks, and then built each task. You can still see this in my code comments, which refer to requirement numbers. It kept a project with many moving parts organised.

The Full Flow\

When someone submits a username, this is what happens:

1. Validate the username.
2. Check the cache. If this user was roasted recently, return the saved result. No GitHub call, no AI call.
3. Check the rate limit. Only on a cache miss.
4. Fetch profile, repositories and contribution data from GitHub.
5. Calculate the score with plain code.
6. Ask the AI to write the roast.
7. Validate the AI output.
8. Save to MongoDB with a unique slug.
9. Return a shareable page at /r/[slug].

Most of my design decisions come from one question: what can go wrong at each step?

The Most Important Decision: The AI Does Not Decide the Score

My first idea was simple. Send the profile to an AI and ask, "Give this developer a score out of 100."

I dropped it quickly. AI models are not consistent. The same profile can get 72 today and 81 tomorrow. And a model can simply invent numbers.

So I split the work in two:

• Code calculates the score. It is deterministic. Same profile in, same score out.
• AI only writes the words. The roast, the tone, the jokes.

And I added one more safety step. Even if the AI returns its own score, I overwrite it:

// Whatever score the model returned, replace it with the real one
// calculated by our analyzer. The model can never change the number.
return withCanonicalScore(parsed.value, analyzerScore);

This one function is why people can trust the number. The AI can be funny, but it cannot lie about your score.

The 1000-Point Developer Score\

\

The score is split into eight dimensions. Each one has its own maximum, and together they add up to exactly 1000.

Why Impact Has the Biggest Share

Stars are the clearest signal that other people found your work useful, so Impact gets the largest slice.

Fairness: Logarithmic Scoring

If score grew in a straight line with stars, one viral repository would beat everything else. So I used a logarithmic curve:

// Early progress is rewarded a lot.
// Later progress gives smaller and smaller gains.
// Result is always between 0 and 1.
Math.log10(1 + value) / Math.log10(1 + target)

Going from 0 to 50 stars feels big and is rewarded. Going from 4,950 to 5,000 barely changes anything. This is much fairer for new developers.

Consistency Rewards Steady Work

Consistency is split into two parts: 60% volume (how many contributions) and 40% spread (how many weeks you were active out of 52). So someone who codes every week beats someone who did one huge weekend.

What If We Don't Have the Data?

Contribution history needs GitHub's GraphQL API. If that is not available, I do not punish the user, and I do not pretend I have verified data either. The score falls back to an estimate and is capped at half credit. The breakdown clearly says it is an estimate.

Tiers

The final number maps to a tier and grade, from "Getting Started" (F) up to "Elite" (S, 900+).

The AI Fallback Chain\

AI providers fail. They hit rate limits, return broken JSON, or go down. I did not want my app to show an error page because one provider had a bad day.

So I built a chain. The app tries providers in order:

1. OpenRouter
2. Gemini
3. OpenAI
4. Grok

If every provider fails, it uses a rule-based roast engine I wrote myself. If even that fails, it returns a hardcoded default roast.

// Try each provider one by one.
// Move to the next one if the call fails OR the output is invalid.
for (const provider of providers) {
  // call provider -> validate with Zod -> return on success
}
// All failed -> rule-based roast -> default roast

The orchestrator never throws. Every result also stores which provider and model were used, and whether a fallback happened, so I can see what really happens in production.

Never Trust Model Output

A provider returning something does not mean it is usable. Every response goes through a Zod schema first. If the shape is wrong, it counts as a failure and the next provider is tried.

Caching and Rate Limiting

AI calls and GitHub calls cost time and money, and a public tool with no login can be abused. I handled both with MongoDB.

Cache

Before doing any work, I check if this username was roasted recently (24 hours by default). If yes, return the saved roast. Nothing else runs.

I also keep a separate profile snapshot (6 hours by default) that feeds the leaderboard, compare and improve pages. That means GitHub is queried at most once per user per window, even if five different features need the same data.

Rate Limit

I limit each IP to 5 fresh roasts per hour, stored in a MongoDB collection.

Two details I like:

• Cached results do not count. If you open a roast that already exists, it is free.
• The decision is a pure function. It takes the existing record, the current time, the limit and the window, and returns allowed or blocked. No database inside it, so it is easy to test.

// Pure function: same input always gives the same decision
computeRateLimitDecision(existing, now, limit, windowMs)

I used MongoDB instead of memory because on Vercel each request can run on a different serverless instance. A counter in memory would reset all the time.

Features Built on Top of the Score

Once the score existed, new features were easy, because they all use the same analysis service.

Leaderboard

Every successful analysis updates a snapshot. The leaderboard shows a podium for the top developers, with search and pagination.

Compare

Enter two usernames and see them side by side. I made one rule: no one is "better". The page only shows measured differences, and highlights which dimensions caused the score gap, so the result is explainable.

Improve

This gives a roadmap with three groups: Quick Wins, Short-term and Long-term. Every tip is triggered by a real measured problem. If your repos have no licence, you get a licence tip. If nothing is wrong, nothing is shown. There is no generic "code more" advice, and no fake promises like "+100 points".

Handling Failures Without Crashing

A rule I followed everywhere: expected failures are returned, not thrown.

// Instead of throwing, return a typed result
{ ok: true, analysis }
{ ok: false, kind: "not_found" | "upstream_error", message }

A username that does not exist, a GitHub rate limit and a network error all become clear results that the API can turn into the right HTTP response. Even a database problem will not block a user: if the snapshot save fails, the roast is still delivered.

Testing: Properties Instead of Examples

I have 289 tests across 22 suites. The part I enjoyed most was property-based testing with fast-check.

Normal tests check one example: "this profile should give 640". Property tests check rules that must always be true, for thousands of random inputs:

• Total score is always a whole number between 0 and 1000.
• Each dimension is between 0 and its maximum.
• Total equals the sum of all dimensions.
• All maximums add up to exactly 1000.
• Same input always gives the same score.

This caught edge cases I would never have written by hand, like empty profiles and missing fields.

Challenges and What I Learned

1. Keeping AI creative but controlled. The fix was giving the AI the words and keeping the numbers for code.

2. Making scoring feel fair. Logarithmic curves and capped estimates made a big difference.

3. Serverless has no memory. Anything that must survive between requests (cache, rate limits) has to live in a database.

4. Small details make it feel real. Slugs like username-x7k92 make every roast link short, unique and shareable.

5. Plan first. Writing requirements before code saved me from rewriting things later.

What's Next

• More signals in the score, like pull request and review activity.
• Better contribution data without needing extra tokens.
• More roast personalities.

Try It

Enter your username and see where you stand. If you disagree with your score, the code is open, so you can see exactly how it was calculated.

• Live demo: git-roasted-ai.vercel.app
• GitHub repo: ahmmikun/GitRoasted

About the author

I'm Salman Ahmad, a developer who enjoys building things people can actually use.

• Portfolio: salmanahmad.tech
• GitHub: @ahmmikun
• LinkedIn: in/ahmmikun
• X: @ahmmikun