DEV Community: Azeez Roheem

Improving AI resume matching with prompt iteration — 7.37 to 8.37/10

Azeez Roheem — Sun, 24 May 2026 17:02:22 +0000

The problem nobody talks about

Here is what most AI resume rewriters actually do when you give them a weak bullet:

Original: "Attended daily standups"

AI rewritten: "Developed responsive web applications using React and TypeScript, collaborating in agile daily standups to deliver high-quality frontend solutions"

That looks better. It has keywords. It has structure. It sounds professional.

It is also a lie.

The candidate never developed React applications. They attended meetings. The AI looked at the job description, saw React and TypeScript, and quietly fabricated experience the candidate doesn't have. If they get an interview, the first technical question will expose it.

This isn't a hypothetical. This is what my resume rewriter — Resume AI Tailor — was doing before I fixed it. I know because I measured it.

What Resume AI Tailor is

Resume AI Tailor is a SaaS product I'm building under NanoCrafts. You upload a resume, paste a job description, and get a tailored version back in seconds. The stack is Next.js, gpt-4o-mini, Clerk, Neon/Drizzle, and Vercel.

The core promise is straightforward: better resume, better match score, better interview chances. The problem is that promise breaks down the moment the AI starts inventing skills the candidate doesn't have.

A resume rewriter that fabricates React experience for a WordPress developer isn't helping that developer. It's setting them up to fail in a room.

What I set out to do

I spent two weeks applying advanced prompt engineering techniques — few-shot prompting, role prompting, and LLM-as-judge eval loops — specifically to the rewrite and analyse routes in Resume AI Tailor.

The goal wasn't to make outputs look better. It was to make them measurably better, with a number I could track across every prompt change.

I started by building an eval loop: a second model call that scores each rewritten bullet on five criteria (action verb, keyword fit, outcome, truthfulness, brevity) using a structured rubric. Then I ran 10 resumes through the pipeline and established a baseline.

Week 1 baseline: 7.37/10 across 38 bullets.

Then I iterated. Two weeks, multiple prompt changes, edge case testing across 5 resume profiles. Every change measured against that baseline.

Final score: 8.37/10. Net improvement: +1.0 points.

This post documents what changed, why it worked, and what I learned that isn't in any prompt engineering tutorial.

Few-shot prompting: show don't tell

The original rewrite prompt looked like this:

const prompt = `You are an expert resume writer. Rewrite the following 
bullet point to be stronger, specific, and results-oriented.

Original bullet: "${bullet}"
Rewritten bullet:`;

This is zero-shot prompting. One instruction, no examples. The model knows what "stronger" means in the abstract but has no idea what stronger looks like in the specific context of a resume bullet for a software engineer applying to a senior role.

The outputs were confident-sounding and structurally inconsistent. Sometimes paragraphs. Sometimes bullet lists. Sometimes the model added metrics. Sometimes it didn't. And sometimes it hallucinated skills entirely.

Few-shot prompting fixes the format problem by demonstrating the output you want rather than describing it.

const REWRITE_SYSTEM_PROMPT = `You are a senior ATS engineer and resume 
specialist with 10 years of experience configuring applicant tracking 
systems at Fortune 500 companies.

Study the examples below carefully. Your output must match this format 
exactly — return only the rewritten bullet, no explanation.

EXAMPLE 1:

Original: "Worked on the backend of the company's main product"
Target keywords: Node.js, REST APIs, microservices
Job title: Senior Software Engineer
Candidate skills: Node.js, PostgreSQL, Docker, REST APIs

Rewritten: Engineered Node.js REST APIs for core product, improving 
system performance across microservices architecture

EXAMPLE 2:

Original: "Attended daily standups"
Target keywords: React, TypeScript, agile, frontend
Job title: Frontend Developer
Candidate skills: HTML, CSS, JavaScript, WordPress

Rewritten: Participated in agile daily standups supporting [React] 
and [TypeScript] frontend delivery

Return ONLY the rewritten bullet. No explanation. Maximum 20 words.`;

Three things are happening simultaneously in that prompt:

The role primes attention. "Senior ATS engineer" tells the model which part of its training to draw on — keyword compliance, format discipline, parse-ability. Not generic writing quality.

The examples pin the format. Every run now produces a single-line output in the exact structure shown. No paragraphs, no numbered lists, no explanatory preamble.

Example 2 demonstrates truthfulness. The candidate has HTML, CSS, JavaScript, WordPress — not React or TypeScript. The example shows the model exactly what to do with missing skills: use bracket placeholders like [React] rather than claiming the skill directly.

That last point is the most important. Instructions alone didn't fix the hallucination problem. Showing the model a worked example of correct placeholder behaviour did.

The key insight: few-shot examples override written instructions when they conflict. If your examples all show confident keyword integration from candidates who plausibly have those skills, the model will follow the examples — not the instruction that says "be truthful." Show what you want. Be careful what you show.

Role prompting: giving the model a lens

Role prompting is assigning a persona to the model via the system prompt before any user content is processed. The model doesn't become that person. It shifts which part of its training data it draws on most heavily.

The difference matters. "You are a hiring manager" is an attention directive, not a capability upgrade. The model already knows what hiring managers care about. The role tells it to weight that knowledge above everything else.

I tested three personas against the same resume on Day 2.

The ATS engineer

`You are a senior ATS engineer with 10 years of experience configuring 
applicant tracking systems at Fortune 500 companies like Greenhouse, 
Workday, and Lever.

When analysing a resume, evaluate it exactly as an ATS would before 
a human ever sees it. Your priorities are:

1. Keyword match — does the resume contain exact terms a recruiter 
   would search for?
2. Formatting compliance — tables, columns, and text boxes cause 
   parsing failures. Flag them.
3. Date formatting — inconsistent dates confuse parsers.`

Output: clinical, narrow, reliable. Caught machine-layer problems — inconsistent date formats, missing keywords, non-standard section names. Ignored everything a human would care about.

The FAANG hiring manager

`You are a senior engineering hiring manager at a FAANG company. 
You have conducted over 500 hiring committee reviews across multiple 
product and infrastructure teams.

When analysing a resume, evaluate it as you would in a 30-second 
hiring committee pre-screen. Your priorities are:

1. Impact framing — does each bullet describe an outcome, not a task?
2. Scope signals — team size, user base, revenue influenced.
3. Levelling language — "Helped" signals junior. "Led" signals senior.`

The "30-second pre-screen" framing was the single most effective addition. It changed the model's evaluative posture from thorough to filtering — prioritising signal density over completeness.

Output: direct, specific, high-signal. Flagged levelling language gaps, missing scope context, and vague bullets that give a hiring committee nothing to evaluate. Most actionable of the three.

The career coach

`You are a senior career coach with 12 years of experience helping 
engineers at all levels land roles they care about.

When analysing a resume, evaluate it as you would in a first coaching 
session: with honesty, warmth, and a focus on what the candidate can 
improve before their next application.`

Output: warm, narrative-focused, occasionally too encouraging. Caught underselling and generic language that the technical personas ignored. Defaulted to "Thank you for sharing your resume!" as an opener — a guardrail I had to add explicitly: "Do not open with pleasantries."

What I shipped

The FAANG hiring manager became the primary analysis prompt. It produced the most actionable feedback by a clear margin.

The ATS engineer runs as a lightweight parallel pass — cheap output, focused scope, catches the machine layer the hiring manager ignores.

The career coach is held for a future Pro tier feature. The instincts are right but it needs tightening before production.

/api/analyse
  ├── hiring manager prompt   (always — primary analysis)
  └── ATS engineer prompt     (always — parallel pass)
  └── career coach prompt     (Pro tier — future)

The key lesson: vocabulary inside the role description matters as much as the job title. "You are a hiring manager" is weaker than "you are a hiring manager who evaluates candidates in 30-second pre-screens and cares about levelling language." The second version gives the model a specific lens, not just a label.

Eval loops: measuring what you built

After a week of prompt iteration I had outputs that looked better. I had no way to know if they actually were better.

Manual scoring across 5 resumes took 45 minutes and produced scores I couldn't fully trust — after reading enough rewrites, judgment drifts. I needed something consistent, fast, and repeatable.

The LLM-as-judge pattern is a second model call that receives both the original and the rewritten bullet, evaluates them against a structured rubric, and returns a quality score plus reasoning.

export async function evalBullet(
  original: string,
  rewritten: string,
  targetKeywords: string[],
  candidateSkills: string[]
): Promise<EvalResult> {
  const response = await openai.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [
      { role: 'system', content: JUDGE_SYSTEM_PROMPT },
      { role: 'user', content: `
        Original bullet: "${original}"
        Rewritten bullet: "${rewritten}"
        Target keywords: ${targetKeywords.join(', ')}
        Candidate skills: ${candidateSkills.join(', ')}
      `}
    ],
    temperature: 0  // always 0 for judges
  });
  // parse and return structured score
}

Temperature must be 0. Your rewriter uses 0.3 because lexical variation is desirable. Your judge needs to score the same bullet the same way every time — temperature above 0 introduces scoring drift that makes baseline comparisons meaningless.

The rubric

The rubric is the most important part. A vague rubric produces vague scores regardless of which model you use.

Score this rewritten bullet on 5 criteria, 2 points each (total 10):

1. Action verb (0-2)
   2 = strong past-tense ownership verb: Led, Built, Architected
   1 = weak or passive: Helped, Worked on, Assisted
   0 = no clear action verb

2. Keyword fit (0-2)
   2 = target keywords integrated naturally — reads well without them
   1 = keywords present but sentence feels constructed around them
   0 = no target keywords present

3. Outcome present (0-2)
   2 = clear measurable outcome, or placeholder [X%] used correctly
   1 = outcome implied but not quantified
   0 = task description only, no outcome signal

4. Truthfulness (0-2)
   2 = all claims supported by original or candidate skills,
       OR missing keywords correctly wrapped in [brackets]
   1 = minor extrapolation, defensible
   0 = claims skill not in original or skills list, not bracketed

5. Brevity (0-2)
   2 = one sentence, 20 words or under, no filler phrases
   1 = slightly long or contains padding
   0 = multiple sentences or significantly over 20 words

The additive structure — 5 criteria, 2 points each — forces the judge to evaluate each dimension independently. Holistic scoring ("rate this 1-10") collapses everything into a gut feeling that drifts. Mechanical criteria with explicit level descriptions produce consistent scores you can aggregate and trend.

Rubric design matters more than judge model

Upgrading from gpt-4o-mini to gpt-4o as your judge produces less improvement than tightening your rubric by one criterion. The bottleneck in LLM-as-judge systems is almost never model capability — it's instruction clarity.

Compare:

// Vague — produces drift
"Rate keyword integration 0-2"

// Precise — produces consistent scores  
"Keyword fit (0-2):
 2 = target keywords integrated naturally — the sentence reads 
     well without them
 1 = keywords present but the sentence feels constructed around them
 0 = no target keywords present"

The precise version gives the judge a test it can apply mechanically. "Would this sentence read well without the keywords?" is a yes/no question. "Is keyword integration good?" is a judgment call. Judgment calls drift. Mechanical tests don't.

Scores are relative not absolute

A bullet scoring 7/10 doesn't mean it's objectively a 7/10 resume bullet. It means it scored 7/10 against your rubric, run by your judge, on this version of your prompt.

What it does have is comparative value. If you change the rewrite prompt and the same 10 bullets average 8.2/10 instead of 6.8/10 — everything else held constant — the prompt improved. That's what systematic prompt engineering looks like: not intuition, evidence.

This is why I log results to a JSON file across runs:

export function logResults(results: EvalResult[], outputPath: string): void {
  const dir = path.dirname(outputPath);
  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });

  const existing = fs.existsSync(outputPath)
    ? JSON.parse(fs.readFileSync(outputPath, 'utf-8'))
    : [];

  fs.writeFileSync(outputPath, JSON.stringify(
    [...existing, ...results], null, 2
  ));
}

Each run appends to the file. The file is your baseline. Without it you're iterating blind.

The fix that actually worked: structural constraints over instructions

After adding few-shot examples and role prompting, the rewriter was still hallucinating on underqualified candidates.

Sarah Johnson has HTML, CSS, JavaScript, and WordPress. She applied to a React and TypeScript role. The rewriter was producing this:

Original:  "Attended daily standups"
Rewritten: "Developed responsive web applications using React and TypeScript,
            collaborating in agile daily standups to deliver frontend solutions"

React and TypeScript. Fabricated. Every time.

I had a truthfulness instruction in the system prompt:

Truthfulness — never invent numbers or metrics not present in the original.
If a target keyword represents a skill the candidate has not explicitly used,
do NOT claim they used it.

It wasn't working. Three prompt iterations, same result. The instruction was being overridden by the few-shot examples — every example showed confident keyword integration from a candidate who plausibly had those skills. The model followed the examples, not the written rule.

The fix wasn't a better instruction. It was a structural change.

Before — instruction only

export async function rewriteBullet(
  bullet: string,
  targetKeywords: string[],
  jobTitle: string
): Promise<string>

The model had no reference list to check keywords against. It knew the job required React. It didn't know the candidate didn't have it. So it integrated React — confidently, fluently, incorrectly.

After — candidateSkills as a parameter

export async function rewriteBullet(
  bullet: string,
  targetKeywords: string[],
  jobTitle: string,
  candidateSkills: string[]  // added
): Promise<string> {
  const userMessage = `Original: "${bullet}"
Target keywords: ${targetKeywords.join(', ')}
Job title: ${jobTitle}
Candidate skills: ${candidateSkills.join(', ')}  // in every call

Rewritten:`;

Now the model has both sides of the equation in every single call. Target keywords on one side. Candidate's actual skills on the other. When it sees React in the keywords but not in the skills list, it uses a placeholder instead of claiming the skill:

Original:  "Attended daily standups"
Rewritten: "Participated in agile daily standups supporting [React] 
            and [TypeScript] frontend delivery"

[React] and [TypeScript] are honest. They tell the candidate: these are the skills the job requires that you don't currently have. The resume becomes a gap analysis rather than a fabrication.

Why this worked when the instruction didn't

Passing candidateSkills as a parameter is a structural constraint. The data is present in the context window on every call. The model has to work with it explicitly.

A prompt instruction saying "be truthful" is a suggestion the model weighs against everything else in its context — including the few-shot examples that demonstrate confident integration. When examples and instructions conflict, examples win.

But a skills list in the context window doesn't compete with examples. It's data. The model can't ignore data the way it can de-prioritise an instruction.

The lesson: structural constraints beat instructional constraints for truthfulness enforcement. If you want the model to check something before acting, give it the thing to check — don't just tell it to check.

This is the most transferable insight from two weeks of prompt iteration. It applies beyond resume rewriting to any situation where you need the model to respect a boundary that its training data might push against.

Results: before and after

The hallucination problem, fixed

Here is the same candidate — Sarah Johnson, HTML/CSS/JavaScript/WordPress developer, applying to a React and TypeScript role — run through three versions of the prompt.

Zero-shot (Week 1 — no examples, no candidateSkills):

Original:  "Worked on client websites"
Rewritten: "Developed responsive client websites using React and TypeScript,
            implementing modern CSS frameworks in an agile environment"

Original:  "Helped with bug fixes"  
Rewritten: "Resolved bugs in React and TypeScript, enhancing frontend 
            performance and responsiveness within agile development cycles"

Original:  "Attended daily standups"
Rewritten: "Developed responsive web applications using React and TypeScript,
            collaborating in agile daily standups to deliver frontend solutions"

React and TypeScript appear in every bullet. Sarah has neither. The rewriter optimised for the job description and ignored the candidate entirely.

Week 2 (role prompting + few-shot + candidateSkills):

Original:  "Worked on client websites"
Rewritten: "Developed client websites using HTML, CSS, and JavaScript, 
            ensuring responsive design and supporting [React] and 
            [TypeScript] frameworks"

Original:  "Helped with bug fixes"
Rewritten: "Assisted in bug fixes for frontend components using HTML, 
            CSS, and JavaScript while supporting agile development 
            and [React] integration, improving [metric] by [X%]"

Original:  "Attended daily standups"
Rewritten: "Participated in agile daily standups supporting [React] 
            and [TypeScript] frontend delivery"

The difference is structural. HTML, CSS, and JavaScript — skills Sarah actually has — are integrated directly. [React] and [TypeScript] appear as bracketed placeholders, not claims. The resume now tells an honest story: here is what I have, here is what the role requires that I don't yet have.

That's more useful to a candidate than a fabrication. It's also something they can actually defend in a room.

Strong bullets preserved correctly

The pipeline doesn't rewrite everything. scoreBullet evaluates each bullet before the rewrite pass and flags which ones actually need work.

Here is Priya Patel's resume — Staff Engineer applying for a Principal Engineer role — run through the same pipeline:

Original:  "Architected event-driven microservices platform handling 
            50M daily events, reducing infrastructure cost by 40%"
Rewritten: [unchanged — scoreBullet returned needs_rewrite: false]

Original:  "Led team of 8 engineers across 3 time zones to deliver 
            platform re-architecture 2 weeks ahead of schedule"
Rewritten: [unchanged]

Original:  "Defined engineering standards adopted across 4 product 
            teams, reducing incident rate by 35%"
Rewritten: [unchanged]

Three of Priya's bullets were preserved. Strong bullets with real metrics, ownership verbs, and scope context don't need rewriting — and the pipeline correctly identifies that. The rewriter amplifies good inputs. It cannot manufacture signal that isn't there.

The score floor

Every bullet that scored below 6/10 in the eval loop traced back to an original with no action verb, no skill, and no outcome:

5/10 — original: "Helped with bug fixes"
       no tool, no scale, no outcome — nothing to amplify

5/10 — original: "Attended daily standups"  
       describes presence, not contribution

No prompt engineering fixes this. The information needed to write a strong bullet doesn't exist in the original. That's a product problem, not a prompt problem. The right fix is surfacing a coaching message to the user: "This bullet doesn't give us enough to work with. Try adding what you built, what tool you used, or what changed because of your work."

The rewriter ceiling on content-free bullets is approximately 6/10 regardless of prompt quality. Knowing that ceiling exists — and being honest about it with users — is more valuable than pretending the AI can fix anything.

The numbers

Score progression

Run	Score	Key change
Week 1 baseline	7.37/10	Combined role + few-shot prompts
Week 2 Day 6	8.26/10	Outcome placeholder instruction
Week 2 Day 7	8.18/10	Edge case fixes — within noise
Week 2 Day 8 final	8.37/10	Stable confirmed score

Net improvement: +1.0 points over two weeks.

Two runs at 8.37 with the same lowest-scoring bullets confirmed this is a stable measurement, not a lucky run. The ±0.15 variance across runs at temperature 0 is the expected noise floor — changes within that range are not meaningful.

Dimension breakdown

Criterion	Week 1	Week 2	Change
Action verb	1.82/2	1.89/2	+0.07
Keyword fit	1.45/2	1.37/2	-0.08
Outcome	1.08/2	1.97/2	+0.89
Truthfulness	1.68/2	1.66/2	-0.02
Brevity	1.26/2	1.47/2	+0.21

The outcome story

Outcome is the standout improvement — +0.89 on a 2-point scale from a single instruction change.

Week 1: the rewriter was good at verbs and keywords but almost never added outcome signal. When the original bullet had no outcome, the model left the rewrite outcome-free too. A bullet that describes a task without a result gives a hiring committee nothing to evaluate.

The fix was one additional priority in the system prompt:

7. Outcome placeholder — if no outcome exists in the original bullet,
   add a placeholder rather than leaving the bullet outcome-free:
   "improving [metric] by [X%]", "resulting in [outcome]",
   "reducing [problem] by [X%]", or "enabling [result]".
   Never leave a rewritten bullet without any outcome signal.

That instruction moved outcome from 1.08/2 to 1.97/2. Nearly a full point on a 2-point scale. The highest ROI prompt change of the two weeks.

The keyword fit regression

Keyword fit dropped slightly from 1.45/2 to 1.37/2. This was deliberate.

The rewriter was injecting generic ATS phrases — "delivery record", "strong portfolio", "5+ years experience" — into every weak bullet regardless of relevance. A filter was added to the route handler:

const GENERIC_KEYWORD_FILTER = [
  'delivery record',
  'strong delivery record',
  '5+ years experience',
  'strong portfolio',
  'fast learner',
  'team player',
];

const targetKeywords = [
  ...new Set([...(missingSkills || []), ...(atsKeywords || [])])
].filter(k => !GENERIC_KEYWORD_FILTER.some(
  g => k.toLowerCase().includes(g.toLowerCase())
));

Filtering generic phrases reduced keyword coverage marginally. It eliminated keyword stuffing across long resumes entirely. That tradeoff is correct — a resume where every bullet ends with "enhancing delivery record and meeting business requirements" signals machine generation to any experienced recruiter.

What 8.37/10 actually means

It's not a grade. It's a baseline.

Every future prompt change gets measured against 8.37. If a change produces 8.6 on the same 10 resumes with the same rubric and judge, the prompt improved. If it produces 8.1, it regressed. The number is only meaningful in comparison — not in isolation.

This is the eval loop working as designed. Without it, every prompt change is a guess. With it, every prompt change is an experiment.

Eval stats

Bullets evaluated:    38
Average score:        8.37 / 10
Improved over orig:   30 / 38 (79%)
Unchanged (strong):   8 / 38

Average breakdown:
  Action verb:        1.89 / 2
  Keyword fit:        1.37 / 2
  Outcome:            1.97 / 2
  Truthfulness:       1.66 / 2
  Brevity:            1.47 / 2

What I learned that isn't in the documentation

1. Few-shot examples override written instructions when they conflict

I wrote "never claim skills the candidate doesn't have" in the system prompt. Every few-shot example showed confident keyword integration from a candidate who plausibly had those skills. The model followed the examples.

This isn't a bug — it's how in-context learning works. The model pattern-matches to demonstrated behaviour more reliably than it follows written rules. Which means the examples you choose are more consequential than the instructions you write.

The practical implication: audit your few-shot examples as carefully as your instructions. If your examples demonstrate behaviour you don't want in edge cases, the model will replicate it in those edge cases regardless of what the instructions say.

Show don't tell. But be careful what you show.

2. Safety and quality are not the same measurement

I had a validateRewrite function that acted as a gate before serving any rewritten bullet:

// Returns: "use_rewrite" | "use_original" | "rewrite_again"
export async function validateRewrite(
  original: string,
  rewritten: string,
  targetKeywords: string[],
  candidateSkills: string[]
)

It answered the question: is this safe to serve? No fabricated skills, keywords present, different from original — use it.

The eval loop answered a different question: how good is this?

A bullet could pass the first question and fail the second:

validateRewrite:  recommendation = use_rewrite
                  truthfulness_risk = low       ← passed the gate

eval loop:        total_score = 5/10
                  action_verb = 1               ← weak verb
                  outcome = 0                   ← no outcome signal
                  brevity = 1                   ← slightly long

The bullet was safe. It wasn't good. Both assessments were correct — they were measuring different things.

Most developers building AI features stop at the safety layer. They add validation to prevent hallucination and call it done. The gap between "safe to serve" and "good enough to be useful" is where user trust quietly erodes. The eval loop makes that gap visible.

The production fix is to wire evalBullet as a second gate with a minimum threshold — bullets that pass safety but fail quality get a coaching message rather than a mediocre rewrite. That's a Week 3 task.

3. There is a hard floor on what prompt engineering can achieve

Every bullet scoring below 6/10 in the eval loop had the same profile: an original with no action verb, no skill, and no outcome.

"Attended daily standups"    → no tool, no contribution, no result
"Helped with bug fixes"      → passive, no scope, no outcome
"Worked on improving things" → no specificity whatsoever

The rewriter ceiling on these bullets is approximately 6/10 regardless of how good the prompt is. The information needed to write a strong bullet simply does not exist in the original.

This is not a prompt problem. It is an input problem.

No amount of instruction, few-shot examples, or role prompting manufactures signal that isn't there. The right response to a content-free bullet is not a better rewrite — it's asking the candidate for more information.

"This bullet doesn't give us enough to work with.
Try adding: what you built, what tool you used, 
or what changed because of your work.

Example: 'Attended daily standups' → 
'Attended daily standups for a 6-person React team 
shipping features weekly'"

That coaching message is more useful to a candidate than any rewrite the model could produce from the original. It's also honest in a way that confident-sounding AI output rarely is.

The most important thing prompt engineering taught me over two weeks is where its limits are. Knowing the ceiling — and being transparent about it with users — is more valuable than pretending the AI can fix anything you give it.

What changes in Week 3

The eval loop surfaced four specific gaps that prompt changes alone cannot fix. These are the opening tasks for Week 3:

Code-level keyword distribution tracking. The keyword distribution instruction in the system prompt has no effect across stateless API calls — each bullet is a separate call with no memory of what keywords appeared in previous bullets. The fix is a post-processing pass in the route handler that tracks keyword frequency across the full rewritten set and removes over-repeated phrases. A partial version is already in production. A proper implementation needs cross-bullet state.

Soft skills matching on zero-technical-match candidates. When a candidate has zero technical skills matching the job description, the model makes a top-level "no match" assessment and stops evaluating the skills array for soft skill overlap. A teacher applying to a data analyst role has Communication and Leadership in her skills array — both required by the job — but the analyser returns matched_skills: []. The fix is a code-level post-processing step that compares the skills array directly against JD keywords in TypeScript, bypassing the model for this field.

Production eval gate. The eval loop currently runs offline as a measurement tool. Week 3 wires evalBullet into the production route as an async quality gate — bullets that pass validateRewrite but score below 6/10 on the eval rubric get a coaching message rather than a mediocre rewrite. The gate runs in the background so it doesn't add latency to the critical path.

Controlled comparison: combined vs few-shot only. Week 1 and Week 2 only tested the combined prompt (role + few-shot). The contribution of role prompting in isolation was never measured. Week 3 runs the same 10 resumes through a few-shot-only variant — no role declaration — and scores that too. The difference between those two scores is the actual measured contribution of role prompting. That's the kind of evidence that makes a blog post technically credible rather than anecdotal.

Target: 8.8/10 average across the same 10 resumes.

The build-in-public part

This post documents Week 2 of a 10-week curriculum applying prompt engineering techniques to a real SaaS product — Resume AI Tailor — that real users pay for.

The eval baseline started at 7.37/10. It ended at 8.37/10. The target for Week 3 is 8.8/10.

I'll publish the Week 3 results — including the controlled comparison, the production eval gate, and whatever new edge cases surface — in the next post. If the score doesn't hit 8.8, I'll say that too.

The code for the eval loop, the prompt variants, and the full pipeline is on GitHub: github.com/Azeez1314/resume-ai

The product is live at: resumetailor.cv

One question for you

If you're building AI-powered features and measuring output quality with more than "it looks good to me" — I'd genuinely like to know what you're using.

The LLM-as-judge pattern is well-documented in research but underused in production SaaS. The gap between knowing the technique exists and actually having a scored baseline you make decisions from is significant. If you've closed that gap, I'd like to hear how.

Leave a comment, or find me on X and LinkedIn as NanoCrafts.

Resume AI Tailor is part of the NanoCrafts portfolio — a collection of focused SaaS tools built and shipped in public.

resumetailor.cv · nanocrafts.xyz · azeezroheem.hashnode.dev

Building an AI Invoice Generator in a Week (Week 8 of My NanoCrafts Build Curriculum)

Azeez Roheem — Wed, 08 Apr 2026 23:06:39 +0000

Week 8 of my NanoCrafts build curriculum had one goal: ship a second SaaS product fast. After spending seven weeks building Resume AI Tailor — a full-stack AI resume rewriter with Stripe, usage limits, and saved resumes — I wanted to validate that the patterns I'd built up weren't project-specific. Could I take the same stack and ship something completely different in a single week?

The invoice generator was the perfect test. Small scope, clear value, real utility. Type a sentence, get a professional PDF. No spreadsheets, no templates, no friction. Here's how I built it.

The NLP Parser — The Most Interesting Part

Every invoice generator has a form. Client name, hours, rate, currency — you fill it in, you get a PDF. Boring. The interesting question was: what if you didn't have to?

The core idea was simple. You type Invoice Acme for 10 hrs at £100/hr and the app figures out the rest. To make that work reliably, I built a two-tier parser.

Tier 1 — Regex (fast path)

The first tier is pure regex. No API call, no latency, no cost. It handles the patterns that cover the vast majority of real inputs:

Invoice Acme for 10 hrs at £100/hr
Bill TechCorp 5 hours at $75 per hour
Charge Wonka Co 3hrs £120/hr
Send invoice to Globex for 8 hours, rate £50

The regex extracts three things: client name, hours, and rate. Currency is inferred from the symbol — £ maps to GBP, $ to USD, € to EUR, with GBP as the default fallback. If all three fields are extracted successfully, the result comes back with confidence: "high" and the UI shows an "Auto-filled" badge in green.

Tier 2 — OpenAI fallback

If the regex fails — ambiguous phrasing, unusual structure, missing fields — the input gets passed to gpt-4o-mini with a tightly scoped system prompt:

Invoice Acme for 10 hrs at £100/hr
Bill TechCorp 5 hours at $75 per hour
Charge Wonka Co 3hrs £120/hr
Send invoice to Globex for 8 hours, rate £50

The model returns structured JSON, which gets parsed and returned with confidence: "low", triggering a yellow "AI-assisted" badge in the UI. The user sees the same form either way — they can always correct the fields before saving.

The confidence field is a small detail that pays off in UX. It tells the user exactly how much to trust the auto-fill without any extra explanation needed.
**
PDF Generation with @react-pdf/renderer
**
One of the advantages of building on a curriculum is that hard problems stay solved. I'd already integrated @react-pdf/renderer in Week 4 for Resume AI Tailor, so the mental model was already there — React components that describe a PDF layout, rendered server-side to a binary buffer and streamed back to the browser.

The invoice PDF is a single with one . The layout has five sections: a branded header with the NanoCrafts name and invoice number, a bill-to block with the client name and due date, a line items table with hours, rate, and amount columns, a totals block with subtotal, VAT at 20%, and grand total, and a payment terms footer.

The gotchas

Three things caught me that are worth documenting.

First, renderToBuffer is a named export, not a method on the default export. This sounds obvious but the library's own examples are inconsistent about it. The correct import is:

const { renderToBuffer } = await import('@react-pdf/renderer');

Not:

const { default: ReactPDF } = await import('@react-pdf/renderer');
await ReactPDF.renderToBuffer(...); // TypeError

Second, renderToBuffer returns a Node.js Buffer, which isn't directly assignable to the Response body in Next.js App Router. You need to convert it first:

const pdfBuffer = await renderToBuffer(element as any);
const uint8 = new Uint8Array(pdfBuffer);

return new Response(uint8, {
  headers: {
    'Content-Type': 'application/pdf',
    'Content-Disposition': `attachment; filename="${invoiceNumber}.pdf"`,
  },
});

Third, @react-pdf/renderer must be in serverExternalPackages in next.config.ts, otherwise Next.js tries to bundle it client-side and throws. This is the same fix from Resume AI Tailor — it carried over directly.

The route

The PDF endpoint lives at GET /api/invoices/[id]/pdf. It fetches the invoice from Neon, checks ownership against the Clerk userId, renders the PDF server-side, and streams the bytes back. The download link on each invoice card is a plain pointing at this route — no JavaScript needed for the download itself.

Lessons vs Resume AI Tailor

The whole point of a curriculum is compounding. Each project should make the next one faster. Here's an honest breakdown of what carried over, what was new, and where I lost time anyway.

What carried over directly

The Clerk v7 setup was identical. proxy.ts instead of middleware.ts (a Next.js 16 convention change), async await auth(), protected routes via createRouteMatcher — copy, paste, done. Same for Drizzle ORM and Neon Postgres. The lib/db/index.ts singleton pattern, the drizzle.config.ts setup, even the drizzle-kit push workflow — all muscle memory by now.

@react-pdf/renderer was the biggest time save. Week 4 cost me several hours figuring out RSC conflicts, Buffer conversions, and the serverExternalPackages config. Week 8 cost me about twenty minutes. That's what compounding looks like in practice.

The Vercel deploy pipeline was also pre-solved. GitHub repo connected, environment variables via npx vercel env add, --prod flag. No surprises.

What was genuinely new

The NLP parser was the core new problem. Resume AI Tailor had no freetext input — everything came from structured file uploads. Building the two-tier regex and OpenAI fallback was the most interesting engineering work of the week.

Optimistic UI for the status changes was also new. Resume AI Tailor had no real-time state updates — results were fetched once and displayed. The invoice dashboard needed instant feedback when marking an invoice as sent or paid, which meant updating local state immediately and reverting on failure. It's a small pattern but a useful one to have in the toolkit.

Where I lost time anyway

Honestly, the biggest time sink of the week had nothing to do with the product. It was a Turbopack and Tailwind v4 workspace root detection bug in Next.js 16. When the project folder sits inside a parent directory that has its own package.json or package-lock.json, Turbopack walks up the tree and tries to resolve CSS imports from the wrong root. The fix was simple — scaffold with create-next-app into a clean location rather than cloning the previous project. That lesson cost about three hours.

The pattern I'd recommend: always start Week N fresh with create-next-app, then manually copy only the files you actually need from the previous project. It takes an extra thirty minutes but saves you from environment issues that are genuinely hard to debug.

T*ime saved overall*

My rough estimate is that reusing patterns from Resume AI Tailor saved around four hours this week. Authentication, database setup, PDF rendering, and deployment would each have taken significantly longer from scratch. That's the compounding effect in action — and it will only get stronger as the curriculum continues.

What I'd Do Differently
Every project teaches you something you wish you'd known at the start. Here are the three things I'd change if I built this again.

*1. Start fresh, don't clone *
I tried to save time by cloning Resume AI Tailor and stripping it down. It backfired. The nested folder structure triggered a Turbopack workspace detection bug that took hours to diagnose. Starting fresh with create-next-app would have taken thirty minutes and saved three hours. From now on, cloning is off the table. Copy individual files manually, never the whole project.

*2. Store line items in the database from day one *
The current schema stores a single hours and rate column per invoice — a simplification I made to ship faster. Line items are supported in the UI but only the first one gets persisted. In practice, almost every real invoice has multiple line items — design work, development, meetings billed separately. The fix is a separate line_items table with a foreign key to invoices. I'll add this in a future iteration, but it would have been cleaner to design it correctly from the start rather than retrofitting.

*3. Make VAT configurable *
VAT is hardcoded at 20% in the PDF component. That works for UK freelancers but breaks for everyone else — US freelancers don't charge VAT at all, EU rates vary by country. A simple vatRate field on the invoice with a default of 20 would have taken thirty minutes to add and made the product genuinely international from launch. Instead it's a v2 feature. The common thread across all three is the same: the shortcuts that feel like time savers at the start of the week tend to create friction at the end. The two that genuinely saved time — reusing Clerk and Drizzle patterns — were things I'd already invested in properly on a previous project. The shortcuts I took specifically for this project are the ones I'm now paying back.

The invoice generator is live at invoice-generator-six-roan-49.vercel.app and the code is open on GitHub at github.com/Azeez1314/invoice-generator. Week 9 of the NanoCrafts curriculum is already planned — if you want to follow along, I post build updates on LinkedIn and Twitter. And if you're a freelancer who invoices clients, give it a try and let me know what's missing.

How I Structured User Data for My AI SaaS

Azeez Roheem — Sun, 22 Mar 2026 18:05:45 +0000

Most developers building their first SaaS make the same mistake I almost made — they reach for sessionStorage because it works in the demo, then discover it breaks the moment a real user opens a second tab. This is the post I wish I'd had before Week 5.

The problem with sessionStorage

Resume Tailor's pipeline works like this: upload a PDF, paste a job description, get AI-rewritten bullets, download a tailored resume. In the demo, sessionStorage holds everything together — the parsed resume, the analysis, the rewritten bullets. It works perfectly. Until a user refreshes the page. Or opens the app on their phone after signing up on their laptop. Or closes the tab by accident. sessionStorage is scoped to a single browser tab. It doesn't survive a refresh. It doesn't sync across devices. It's fine for prototyping — it's not a database. The fix is obvious in hindsight: persist to Postgres, load from the database on every session. But getting there requires a set of decisions that aren't obvious at all.

Why Postgres over MongoDB

The first decision was the database. MongoDB is the default choice for a lot of Node.js developers — flexible schema, JSON-native, easy to get started. For Resume Tailor I chose Postgres, and the reason comes down to one concept: referential integrity.

In MongoDB, if you delete a user, their resume documents don't go anywhere. They sit in the collection, orphaned, pointing at a user ID that no longer exists. You have to remember to clean them up in application code. You will forget.

In Postgres, you enforce the relationship at the schema level:

userId: uuid('user_id')

.notNull()

.references(() => users.id, { onDelete: 'cascade' }),

onDelete: 'cascade' means when a user row is deleted, every resume row that references it is deleted automatically. The database guarantees clean data — not the application code, not a cron job, not a developer remembering to write the right query.

Most developers don't think about what happens to related data when a user deletes their account. That one line is the answer.

The schema

Clerk owns identity. Postgres owns product data. The clerkId field is the bridge between the two systems.

export const users = pgTable('users', {

id: uuid('id').defaultRandom().primaryKey(),

clerkId: text('clerk_id').notNull().unique(),

email: text('email').notNull(),

plan: text('plan').notNull().default('free'),

usageCount: integer('usage_count').notNull().default(0),

usageLimit: integer('usage_limit').notNull().default(5),

createdAt: timestamp('created_at').defaultNow(),

});

export const resumes = pgTable('resumes', {

id: uuid('id').defaultRandom().primaryKey(),

userId: uuid('user_id')

.notNull()

.references(() => users.id, { onDelete: 'cascade' }),

jobTitle: text('job_title'),

jobDescription: text('job_description'),

originalBullets: jsonb('original_bullets').$type<string[]>(),

rewrittenBullets: jsonb('rewritten_bullets').$type<string[]>(),

keywords: jsonb('keywords'),

pdfGenerated: boolean('pdf_generated').default(false),

createdAt: timestamp('created_at').defaultNow(),

});

jsonb for bullets and keywords — not text with JSON.stringify. jsonb is queryable, indexed, and type-safe with Drizzle's .$type(). The difference matters when you want to query resumes by keyword later.

Usage tracking — why atomic increment matters

Free tier means 5 rewrites. Enforcing that limit sounds simple — read the count, check it, increment it. Here's the implementation most developers write:

// Read

const user = await db.select().from(users).where(eq(users.clerkId, clerkId));

// Check

if (user.usageCount >= user.usageLimit) throw new Error('Usage limit reached');

// Write

await db.update(users).set({ usageCount: sql${users.usageCount} + 1 });

This has a race condition. If two requests arrive simultaneously, both read usageCount: 4, both pass the check, both increment. The user ends up at 6 when the limit is 5. I verified this with a Promise.all test — two simultaneous fetch calls to /api/rewrite. Both returned 200. Both incremented.

The fix is a single atomic query:

const result = await db

.update(users)

.set({ usageCount: sql${users.usageCount} + 1 })

.where(

sql${users.clerkId} = ${clerkId} AND ${users.usageCount} < ${users.usageLimit}

)

.returning();

if (result.length === 0) throw new Error('Usage limit reached');

The WHERE clause does the check and the increment in one shot. If two requests arrive simultaneously, only one matches the condition. The other gets no rows back and throws. No race condition possible.

The ownership check — the one line that prevents a data breach

Every resume has a UUID as its ID. UUIDs are hard to guess but not secret — they appear in API responses, URLs, and network logs. Any authenticated user could find a UUID and call DELETE /api/resumes/:id.

Without an ownership check, they can delete anyone's data.

if (result[0].userId !== user.id) { return NextResponse.json({ error: 'Forbidden' }, { status: 403 });

}

This line is not optional. Fetch the row, compare the userId to the authenticated user's ID, return 403 if they don't match. Every delete, every update, every read of sensitive data needs this check.

I tested it deliberately — signed in as User A, called DELETE with a resume ID belonging to User B. Without the check: 200, data gone. With the check: 403, data safe.

What the webhook solves

Clerk handles authentication — sign up, sign in, social providers, session management. But when a user signs up through Clerk, your Postgres database doesn't know about it.

The webhook bridges the two systems:

User signs up on Clerk

→ Clerk fires POST to /api/webhooks/clerk

→ Route verifies the svix signature

→ Inserts a row into the users table

→ clerkId links Clerk and Postgres from this point forward

The same pattern handles account deletion — user.deleted event fires, the route deletes the user row, the cascade foreign key cleans up every resume automatically.

Without the webhook, your database has no record of who signed up. With it, every Clerk event that matters is reflected in Postgres within seconds.

What I'd tell myself before Week 5

Pick Postgres when relationships matter. Use onDelete: cascade — don't leave orphan cleanup to application code. Make usage checks atomic. Always verify ownership before mutating data. Wire the webhook before you build anything that depends on user rows existing.

These aren't advanced concepts. They're the decisions that separate a demo from a product.

Resume Tailor is live at resume-ai-one-lac.vercel.app. Source on GitHub: github.com/Azeez1314/resume-ai.

From PDF to ATS-Optimised Resume in Three Steps — How I Built It with Next.js and OpenAI

Azeez Roheem — Sun, 15 Mar 2026 12:17:54 +0000

Sometimes I would like to know the missing skills and what I already
have on my resume. I wanted an app to fix the gaps automatically —
so I could get a better resume and apply faster.

As job applicants, we need to blend speed with ATS-optimised resumes.
Checking a resume against a job description manually is time-consuming
and requires knowledge most candidates don't have. Most people have
never heard of ATS keywords — let alone know how to use them.

So I built a pipeline to do it automatically. Here's how it works.

Step 1 — PDF Upload and Extraction

The pipeline starts with a PDF upload. PDF is the standard format
for resumes, but extracting clean text from one is harder than it
sounds. Column layouts, custom fonts, and formatting cause the raw
text to come out in the wrong order — a candidate's name can end up
in the wrong section entirely.

extractAndStructure() solves this in two steps. First it cleans the
raw text — removing blank lines, trimming whitespace, and splitting
it into named sections. Then it sends those sections to OpenAI, which
reorganises them into a structured JSON object with fields for name,
experience, skills, education, and contact details.

Structured JSON is returned instead of raw text because every step
after this needs to read specific fields. The analyse route needs the
skills array. The rewrite route needs the experience highlights. Raw
text would require re-parsing at every step — structuring once here
makes the rest of the pipeline simple.

Step 2 — Match Analysis and Keyword Extraction

When the user submits a job description, two functions run at the
same time — extractKeywords() and analyseMatch(). They run in
parallel because neither needs the other's result. Both only need
the resume and job description, so there is no reason to wait.
Running them simultaneously cuts the response time roughly in half.

extractKeywords() pulls required skills, tools and technologies,
and ATS keywords directly from the job description. analyseMatch()
scores the resume against it — returning a match score out of 100,
matched skills, and missing skills.

The match score tells the user how well their resume fits the role
before any rewriting begins. It is most useful for resumes scoring
between 40 and 70 — where real gaps exist but the candidate is not
a wrong fit. The user sees the score and extracted keywords before
continuing, so they can decide whether to proceed with the rewrite
or try a different role entirely.

Step 3 — Bullet Rewriting

When the user hits Rewrite & Continue, the pipeline combines
missingSkills and atsKeywords into one target list. missingSkills
comes from the match analysis — skills the resume lacks. atsKeywords
comes from the job description itself — what the ATS scanner is
looking for. Combining both gives the rewriter the most complete
picture of what the role needs.

For each bullet, three functions run in sequence. scoreBullet()
rates the bullet on three criteria — action verb, skill or tool,
and outcome. Bullets that score poorly are flagged for rewriting.
Bullets that are already strong are left unchanged. rewriteBullet()
then rewrites only the flagged bullets, incorporating the target
keywords naturally. validateRewrite() runs immediately after each
rewrite — checking that the keywords fit naturally and the
truthfulness risk is low. If the rewrite fails validation, the
original bullet is kept.

The user sees a before and after comparison for every bullet that
changed, a summary of how many were improved, and a button to
download the tailored resume.

What I'd Do Differently

The pipeline works best for candidates with match scores between
40 and 70. In this range, real gaps exist but the candidate is not
a wrong fit for the role. Above 80, the resume is already strong —
rewriting bullets won't move the needle. Below 40, the role itself
is likely the wrong target.

The biggest limitation right now is PDF format. Most people write
their resume in Word or Google Docs and export to PDF — but if the
export is done incorrectly, the PDF becomes a scanned image with no
text layer. The pipeline fails at the first step and the user has
no way to continue without fixing their file. Word documents and
Google Docs exports need to be supported directly in a future version.

The final piece is PDF generation. Right now the pipeline analyses
and rewrites but the output lives on a web page. Week 4 turns the
rewritten JSON into a formatted, downloadable PDF — a complete,
ATS-optimised resume the candidate can send directly to recruiters.
That is what transforms this from a pipeline into a product.

This is Week 3 of my AI/ML learning curriculum. Week 2 covered
the Node.js pipeline that powers this app. The full code is on
GitHub: github.com/Azeez1314

6 Job Applications Used to Consume My Day. Here's the AI Pipeline I Built to Fix That.

Azeez Roheem — Fri, 06 Mar 2026 10:40:27 +0000

The Problem

Applying for 6 roles used to consume my day. Refining my CV,
checking for matching words, reordering bullet points — then the
awkward silence. My friends voiced the same frustration. We weren't
bad candidates. The process was just killing our output.

The actual culprit is ATS software — the stern gatekeeper that blocks
resumes from reaching the hiring manager. It filters applications when
keywords don't match the job description closely enough.

I built a pipeline to fix that. Here's how it works.

How the Prompt Chain Works

Step 1 — PDF to Text
Most resumes arrive as PDFs — but PDFs don't store text cleanly.
The pipeline extracts raw text, removes blank lines, trims whitespace,
and separates it into named sections like Experience, Education and Skills.

Step 2 — AI Structuring
Raw sections are not organised. OpenAI reorganises them into clean JSON.
This fixes column ordering issues and joins split lines. When the
candidate's name ends up in the wrong section, OpenAI pulls it out
and places it correctly.

Step 3 — Job Match Analysis
The structured resume is compared against the job description.
The AI returns a match score, matched skills, and missing skills.

Step 4 — Bullet Rewriting
Each bullet is scored on three criteria: action verb, skill, and outcome.
Weak bullets are rewritten to incorporate missing keywords naturally.
A second AI call validates whether the rewrite is truthful before accepting it.

Step 5 — Before/After Measurement
The original and tailored resumes are both scored against the job description.
The difference tells you exactly how much the pipeline improved the match.

Before and After

Example 1:

Before: "Applied agile methodologies like SCRUM for project management"

This is an example of what an ATS scanning for React or Node.js will
just ignore. It has the right idea but stops short — right methodology,
but without context. What are you building? What did SCRUM help you ship?

After: "Implemented Agile/SCRUM methodology to accelerate delivery
across full-stack projects using React and Node.js"

An ATS scanning for React or Node.js will now pick this up. It shows
the tech stack, shows ownership, and connects the methodology to real work.

Example 2:

Before: "Automated invoicing systems reducing admin time by up to 60%"

This already mentions a strong outcome — 60%, an actual figure worth
retaining. But it doesn't mention any tool, so an ATS looking for
Node.js or MongoDB sees nothing.

After: "Automated invoicing systems using Node.js and MongoDB,
reducing admin time by up to 60% for SaaS clients"

Same outcome, same honesty — but now it's visible to ATS systems
scanning for the right keywords.

What I'd Do Differently

The 0 Delta Surprise
When I measured before and after, the score didn't move. My initial
reaction was that something was wrong. However, nothing was wrong.
This is the correct behaviour when a resume already matches the role.
I discovered the pipeline is most valuable for resumes with match
scores of 40-70. High-scoring resumes (80+) need new experience,
not rewriting. Low-scoring resumes (under 40) need a different role target.

The Force-Fitting Problem
The AI kept importing keywords that didn't belong — prompt engineering
appearing in a PDF pipeline bullet, MongoDB showing up in a SCRUM bullet.
The fix is not instructing the AI not to hallucinate. It is passing only
keywords that are truly missing and relevant to that specific bullet's
context. A smarter pre-filter before the rewrite call would have solved this.

What's Next
The output at the end of Week 2 was JSON — which a developer would
understand, but a job applicant needs a document they can forward to
recruiters. In Week 3, that JSON gets turned into a formatted, tailored
PDF — a ready-made resume. This is what transforms the project into a product.

This is Week 2 of my AI/ML learning curriculum. Week 1 covered
OpenAI API fundamentals and keyword extraction. The full code is
on GitHub: github.com/Azeez1314

Building My First AI Resume Parsing Script (Lessons Learned)

Azeez Roheem — Sun, 01 Mar 2026 11:57:36 +0000

Every job applicant knows the feeling — you find a great role,
read through the requirements, and spend 20 minutes manually
figuring out which of your skills to highlight. I wanted to
automate that using the OpenAI API. What I didn't expect was
that the hardest part wouldn't be the AI — it would be
controlling what the AI actually returns.

What I Set Out to Build

Job applicants face two problems. First, their CV often doesn't
get picked because it doesn't match the language the employer
used in the job description. Second, going through each job
description manually is slow — it limits how many quality
applications you can submit in a day.

I wanted to build a script that solves both. Give it any job
description, get back a structured list of the exact keywords
to highlight on your resume. Simple idea. Harder to build
than I expected.

What I Tried That Didn't Work

My first attempt looked like it was working. I sent a job
description to the API and got something back that looked
like JSON. But when I tried to use it in my script,
everything broke.

Here's what the raw output actually looked like:

{
  "keywords": [
    "Senior Frontend Engineer",
    "React",
    "TypeScript",
    "REST APIs"
  ]
}

Notice the backticks wrapping it. That's markdown formatting —
not valid JSON. When I ran JSON.parse() on that raw string,
my script crashed immediately.

But the backticks were only part of the problem. I ran the
same job description 5 times and got 5 slightly different
results. Keywords were dropped between runs. Phrasing changed.
On one run "strong communication skills" appeared, on another
just "communication skills." The structure itself changed —
sometimes the model added explanation text before the JSON,
sometimes not.

The problem wasn't dramatic failures. It was subtle
inconsistency that would silently corrupt a real application
over time. I was being polite with my prompt — "return the
results in JSON format" — when I needed to be strict.

I also made the mistake of setting temperature to 1 while
testing. Higher temperature introduces randomness — useful
for creative tasks, catastrophic for structured extraction.
Temperature 1 didn't just vary the content. It varied the
structure itself, meaning different field names on every run.
For extraction tasks, always use temperature 0.

The Moment response_format Changed Everything

I spent longer than I'd like to admit fighting with output
format before I found this:

response_format: { type: "json_object" }

This single line changed everything. Here's the difference
between asking and enforcing:

Before — prompt instruction only:

content: `Extract keywords and return them in JSON format.`

Result: inconsistent, backtick-wrapped, unparseable output.

After — API-level enforcement:

const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  temperature: 0,
  response_format: { type: "json_object" },
  messages: [...]
});

Result: clean, consistent, directly parseable JSON every time.

When you add response_format you're not giving the model
another instruction. You're flipping a switch at the API
level that forces valid JSON output, validates it before
returning it to you, and guarantees JSON.parse() will
never throw on the response.

No backticks. No explanation text. No inconsistency.

What the Final Script Does

The finished extractor takes any job description and returns
a structured JSON object with 7 fields:

{
  "job_title": "",
  "experience_level": "",
  "required_skills": [],
  "nice_to_have_skills": [],
  "tools_and_technologies": [],
  "soft_skills": [],
  "ats_keywords": []
}

Here's a real example. Input:

Senior React Developer. 3+ years experience required.
Must know React, TypeScript, and REST APIs.
Nice to have: GraphQL, AWS.
Tools: Figma, GitHub, Jira.
Strong communication skills required.

Output:

{
  "job_title": "Senior React Developer",
  "experience_level": "3+ years",
  "required_skills": ["React", "TypeScript", "REST APIs"],
  "nice_to_have_skills": ["GraphQL", "AWS"],
  "tools_and_technologies": ["Figma", "GitHub", "Jira"],
  "soft_skills": ["strong communication skills"],
  "ats_keywords": ["Senior React Developer", "React", 
                   "TypeScript", "REST APIs", "Figma"]
}

The script also includes retry logic with exponential backoff,
input validation that rejects empty or very short descriptions
before spending tokens, output validation that catches
meaningless results, and token tracking on every call so
you're always aware of cost.

Full code is on GitHub: github.com/Azeez1314/ai-keyword-extractor

What I'd Do Differently

Add response_format on day one. I spent hours fighting
inconsistent output that vanished the moment I added that
single line. Enforce structure at the API level — not just
through prompt instructions.

Take prompt engineering more seriously from the start.
I assumed the model would figure out what I meant. It didn't
— it did exactly what I said, which was often not what I
meant. Every vague instruction became a bug. Every specific
constraint became a feature.

Track token usage from the first call. My system prompt
grew from 133 tokens to 700 tokens through refinement. That's
a 5x cost increase per call that I only noticed at the end.
Log tokens on every call from day one.

What's Next

This extractor is the first step in a larger pipeline. The
next version will accept both a job description and a
candidate's resume, compare the extracted keywords against
the candidate's actual experience, and suggest specific
improvements to make the resume a closer match.

If you're building something similar or have questions about
any part of this, the full code is available at:
github.com/Azeez1314/ai-keyword-extractor

Building My Developer Portfolio with Next.js, shadcn/ui & Google Cloud Run 🚀

Azeez Roheem — Sun, 01 Feb 2026 23:11:16 +0000

Hey there! 👋

I'm Azeez Roheem, a full-stack JavaScript developer with 5+ years of experience building scalable ecommerce systems and impact-driven digital products. When I saw the "New Year, New You" Portfolio Challenge by Google AI, I knew it was the perfect opportunity to finally revamp my portfolio website.

💡 Why I Joined This Challenge

My old portfolio was outdated and didn't reflect my current skills or the work I've been doing. I'd been putting off updating it for months (we've all been there, right? 😅).

When I discovered this challenge, I thought: "What better motivation than a deadline, prizes, and the chance to learn something new?"

I wanted to:

Give my portfolio a fresh, modern look
Explore deploying to Google Cloud for the first time
Push myself to learn new tools and workflows

🖥️ Live Portfolio

Live URL: https://developer-portfolio-jgtmqruaaq-uc.a.run.app/

🛠️ Tech Stack

Category	Technology
Framework	Next.js 14 (App Router)
Language	TypeScript
Styling	Tailwind CSS
Components	shadcn/ui (customized)
Animations	Framer Motion
Deployment	Google Cloud Run
Container	Docker (multi-stage build)

🎨 Design Approach

I wanted something that stands out from typical developer portfolios. I went with an editorial meets modern aesthetic:

Playfair Display serif font for elegant headlines
JetBrains Mono for code elements
Warm cream background with vibrant orange accents
Subtle grain texture for depth
Animated code window in the hero section
Smooth scroll-triggered animations with Framer Motion

🚧 The Interesting Challenge: First Time with Google Cloud!

This was my first time deploying anything to Google Cloud, and honestly, it was both exciting and a bit nerve-wracking!

What I Learned Along the Way

1. Setting up the Google Cloud CLI
I had to install the gcloud CLI and authenticate. Simple enough, but it was new territory for me.

gcloud auth login
gcloud config set project personal-portfolio-486121

2. Docker Multi-Stage Builds
I learned how to optimize my Docker image using multi-stage builds to keep the final image small:

# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Stage 2: Build
FROM node:20-alpine AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

# Stage 3: Production (minimal image)
FROM node:20-alpine AS runner
COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static
CMD ["node", "server.js"]

3. Cloud Build + Cloud Run Deployment
The actual deployment was surprisingly straightforward once everything was set up:

# Build the container
gcloud builds submit --tag gcr.io/$PROJECT_ID/developer-portfolio

# Deploy to Cloud Run
gcloud run deploy developer-portfolio \
  --image gcr.io/$PROJECT_ID/developer-portfolio \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

Within minutes, my portfolio was live with a real URL! 🎉

The "Aha!" Moment

Seeing my portfolio deployed and accessible from anywhere was incredibly satisfying. Google Cloud Run handles all the scaling automatically — if my portfolio suddenly gets a lot of traffic (fingers crossed! 🤞), it'll scale up. If no one's visiting, it scales down to zero. Pretty neat for a portfolio site!

🤖 Exploring AI in the Process

While building this portfolio, I also explored using AI as a development companion. It helped me:

Generate boilerplate code faster
Debug deployment issues
Refine my design approach
Write cleaner, more maintainable components

It's amazing how AI tools can accelerate the development process when you're learning new platforms like Google Cloud.

✨ Key Features

Animated Hero Section

A floating code window that "types out" my developer profile:

const developer = {
  name: "Azeez Roheem",
  stack: ["React", "Next.js", "Node"],
  focus: "Scalable Solutions",
  available: true,
};

Interactive Project Cards

Hover effects that reveal project details with smooth transitions.

Scroll-Triggered Animations

Using Framer Motion's whileInView for elegant reveal effects as you scroll.

Fully Responsive

Mobile-first design that looks great on any device.

📁 My Projects Showcased

1. NanoCrafts - Software Consulting Agency
My technology consulting firm delivering end-to-end digital transformation services.
🔗 nanocrafts.xyz

2. Teeq - Ecommerce Dashboard
Full-stack e-commerce solution with product management and inventory tracking.
🔗 teeq.vercel.app

🎓 Key Takeaways

Google Cloud Run is beginner-friendly — Even as a first-timer, I got my app deployed without major issues
Docker knowledge pays off — Understanding containers made the deployment process much smoother
AI accelerates learning — Using AI tools helped me quickly understand new concepts and debug issues
Challenges create motivation — Sometimes you just need a deadline to finally update that portfolio!

🔗 Connect With Me

Portfolio: developer-portfolio-jgtmqruaaq-uc.a.run.app
GitHub: github.com/Azeez1314
LinkedIn: linkedin.com/in/azeezroheem
Website: azeezroheem.dev
Email: nanocrafts199@gmail.com

🙏 Thanks for Reading!

This challenge pushed me out of my comfort zone and taught me something new. If you've been putting off updating your portfolio (like I was), take this as your sign to just start!

Drop a ❤️ if you found this helpful, or leave a comment — I'd love to hear about your experience with the challenge!

Happy coding! 🚀

Built with Next.js, shadcn/ui, Tailwind CSS, and deployed on Google Cloud Run for the Google AI "New Year, New You" Portfolio Challenge 2026

Using Postgres Full-Text Search on a Next.JS Fullstack App

Azeez Roheem — Fri, 02 Jan 2026 20:43:09 +0000

Although workshops can be both instructive and exhausting, I made certain to complete Brian Holt’s workshop on developing a comprehensive Fullstack Next.js application. You may review it on Frontendmasters. I intend to enhance the application by integrating comprehensive full-text search capabilities. I plan to systematically record the procedure for future reference.

Based on this, I assume the:

The Next.js full-stack app is completed.
It includes a PostgreSQL database.
and it contains some data to search for.

The processes below are the steps I followed and researched to implement the functionality. We will build:

Full-text search using Postgres
Powered by Neon
The query will be done through Drizzle ORM.
accessed through Next.js API route
used on the search page UI

Since the application is a blog app, we will add:

Full-text search index by running it inside Neon SQL Editor (this would have been set up while building the app).
Connection to Drizzle Database

CREATE INDEX articles_search_idx
 ON articles
 USING GIN (
   to_tsvector(
     'english',
     title || ' ' || summary || ' ' || content
   )
 );

this (articles_search_idx) creates a search index on the article, you can use any other name you prefer. This intends to make the search fast and sort by relevance.

Connection to Drizzle Database

It is expected that the database would have been connected while building the fullstack application. However, if not done, use the sample below:

📁 db/index.ts

 import { drizzle } from "drizzle-orm/neon-http";
 import { neon } from "@neondatabase/serverless";
 import * as schema from "./schema";

 const sql = neon(process.env.DATABASE_URL!);

 export const db = drizzle(sql, { schema });

Create the Search API Folder/Routes for Articles

📁 app/api/search/route.ts

import { NextResponse } from "next/server";
 import { db } from "@/db";
 import { sql } from "drizzle-orm";

 export async function GET(req: Request) {
   const { searchParams } = new URL(req.url);
   const query = searchParams.get("q");

   if (!query) {
     return NextResponse.json([]);
   }

   const results = await db.execute(sql`
     SELECT 
       id,
       title,
       slug,
       summary,
       image_url,
       created_at,
       ts_rank(
         to_tsvector('english', title || ' ' || COALESCE(summary, '') || ' ' || content),
         plainto_tsquery('english', ${query})
       ) AS rank
     FROM articles
     WHERE published = true
       AND to_tsvector(
         'english',
         title || ' ' || COALESCE(summary, '') || ' ' || content
       )
       @@ plainto_tsquery('english', ${query})
     ORDER BY rank DESC
     LIMIT 20
   `);

   return NextResponse.json(results.rows);
 }

the easy way I use to understand this is:

I type a search criterion in the box.
It calls /api/search?q=term from the frontend.

On the backend, it: - turns the character into searchable form

            -finds matching articles

            -score them based on relevance

It returns the best matches and displays results.

Install Shadcn components

I used Shadcn and Tailwind for the application.

npx shadcn@latest init
 npx shadcn@latest add input
 npx shadcn@latest add button
 npx shadcn@latest add card
 npx shadcn@latest add separator

Creation of UI for Searches (Articles)

📁 app/search/page.tsx

"use client";

 import { useState } from "react";
 import Link from "next/link";

 import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent } from "@/components/ui/card";
 import { Separator } from "@/components/ui/separator";

 type Article = {
   id: number;
   title: string;
   slug: string;
   summary: string | null;
   created_at: string;
 };

 export default function ArticleSearchPage() {
   const [query, setQuery] = useState("");
   const [results, setResults] = useState<Article[]>([]);
   const [loading, setLoading] = useState(false);

   async function handleSearch() {
     if (!query.trim()) return;

     setLoading(true);

     const res = await fetch(
       `/api/search?q=${encodeURIComponent(query)}`
     );

     const data = await res.json();
     setResults(data);
     setLoading(false);
   }

   return (
     <div className="mx-auto max-w-3xl px-4 py-10">
       {/* Page Header */}
       <div className="mb-8 space-y-2 text-center">
         <h1 className="text-3xl font-bold tracking-tight">
           Search Articles
         </h1>
         <p className="text-muted-foreground">
           Find articles by title, summary, or content
         </p>
       </div>

       {/* Search Input */}
       <div className="flex gap-2">
         <Input
           value={query}
           onChange={(e) => setQuery(e.target.value)}
           placeholder="Search articles..."
           className="flex-1"
         />
         <Button onClick={handleSearch} disabled={loading}>
           {loading ? "Searching..." : "Search"}
         </Button>
       </div>

       <Separator className="my-8" />

       {/* Results */}
       <div className="space-y-4">
         {results.length === 0 && !loading && query && (
           <p className="text-center text-sm text-muted-foreground">
             No articles found.
           </p>
         )}

         {results.map((article) => (
           <Card key={article.id} className="hover:shadow-md transition">
             <CardContent className="p-6 space-y-2">
               <Link href={`/articles/${article.slug}`}>
                 <h3 className="text-lg font-semibold hover:underline">
                   {article.title}
                 </h3>
               </Link>

               {article.summary && (
                 <p className="text-sm text-muted-foreground line-clamp-3">
                   {article.summary}
                 </p>
               )}

               <p className="text-xs text-muted-foreground">
                 {new Date(article.created_at).toDateString()}
               </p>
             </CardContent>
           </Card>
         ))}
       </div>
     </div>
   );
 }

It links as follows:

When a user searches, the frontend updates the query.

After clicking search, handleSearch() runs, then the API runs /api/search?q=...

backend runs Postgres full-text search

Results are returned as JSON, and the UI is updated.

Optional: live search

We can make search behave like Google search. It starts searching immediately a user starts by typing.

"use client";

 import { useState } from "react";
 import Link from "next/link";

 import { Input } from "@/components/ui/input";
 import { Button } from "@/components/ui/button";
 import { Card, CardContent } from "@/components/ui/card";
 import { Separator } from "@/components/ui/separator";

 type Article = {
   id: number;
   title: string;
   slug: string;
   summary: string | null;
   created_at: string;
 };

 export default function ArticleSearchPage() {
   const [query, setQuery] = useState("");
   const [results, setResults] = useState<Article[]>([]);
   const [loading, setLoading] = useState(false);

   async function handleSearch() {
     if (!query.trim()) return;

     setLoading(true);

     const res = await fetch(
       `/api/search?q=${encodeURIComponent(query)}`
     );

     const data = await res.json();
     setResults(data);
     setLoading(false);
   }

   return (
     <div className="mx-auto max-w-3xl px-4 py-10">
       {/* Page Header */}
       <div className="mb-8 space-y-2 text-center">
         <h1 className="text-3xl font-bold tracking-tight">
           Search Articles
         </h1>
         <p className="text-muted-foreground">
           Find articles by title, summary, or content
         </p>
       </div>

       {/* Search Input */}
       <div className="flex gap-2">
         <Input
           value={query}
           onChange={(e) => setQuery(e.target.value)}
           placeholder="Search articles..."
           className="flex-1"
         />
         <Button onClick={handleSearch} disabled={loading}>
           {loading ? "Searching..." : "Search"}
         </Button>
       </div>

       <Separator className="my-8" />

       {/* Results */}
       <div className="space-y-4">
         {results.length === 0 && !loading && query && (
           <p className="text-center text-sm text-muted-foreground">
             No articles found.
           </p>
         )}

         {results.map((article) => (
           <Card key={article.id} className="hover:shadow-md transition">
             <CardContent className="p-6 space-y-2">
               <Link href={`/articles/${article.slug}`}>
                 <h3 className="text-lg font-semibold hover:underline">
                   {article.title}
                 </h3>
               </Link>

               {article.summary && (
                 <p className="text-sm text-muted-foreground line-clamp-3">
                   {article.summary}
                 </p>
               )}

               <p className="text-xs text-muted-foreground">
                 {new Date(article.created_at).toDateString()}
               </p>
             </CardContent>
           </Card>
         ))}
       </div>
     </div>
   );
 }

It links as follows:

When a user searches, the frontend updates the query.
After clicking search, handleSearch() runs, then the API runs /api/search?q=...
backend runs Postgres full-text search
Results are returned as JSON, and the UI is updated.

Optional: live search

We can make search behave like Google search. It starts searching immediately a user starts by typing.

<Input
  value={query}
  onChange={async (e) => {
    const value = e.target.value;
    setQuery(value);

    if (!value.trim()) {
      setResults([]);
      return;
    }

    setLoading(true);
    const res = await fetch(
      `/api/search?q=${encodeURIComponent(value)}`
    );
    const data = await res.json();
    setResults(data);
    setLoading(false);
  }}
  placeholder="Search articles..."
/>

Check a live demo here

This search can also be expanded to use Algolia/Typesense.

Thank you for taking time to go through the article.