Forem: Abdullah Jan

Carific.ai: Building an AI Resume Tailor with Multi-Step Agents - Vercel AI SDK 6 and ToolLoopAgent

Abdullah Jan — Tue, 13 Jan 2026 15:42:27 +0000

Eighth post in the Carific.ai series. Previous posts: Auth System, AI Resume Analyzer, Structured AI Output, Profile Editor Type Safety, Domain Model Architecture, Flicker-Free PDF Viewer, and Production Hardening.

The resume analyzer I built in post #2 had a problem: it told users what was wrong but didn't help them fix it.

"Add more metrics to your bullet points" is great advice. But which bullet points? What metrics? Users were left staring at a score card, unsure what to do next.

So I rebuilt the entire feature. Instead of analyzing and walking away, the new system tailors the resume step-by-step - rewriting the summary, optimizing each experience entry, reorganizing skills - with the user approving every change before it's applied.

This is the story of building an AI agent with human-in-the-loop approvals using the Vercel AI SDK 6.

The Stack (Actual Versions)

{
  "next": "16.1.1",
  "react": "19.2.3",
  "ai": "6.0.20",
  "@ai-sdk/react": "3.0.20",
  "@react-pdf/renderer": "4.3.1",
  "zod": "4.2.1",
  "@prisma/client": "7.1.0"
}

Chapter 1: Why the Analyzer Wasn't Enough

The original resume analyzer used generateObject to return structured feedback:

// ❌ The old approach - analyze and done
const { object } = await generateObject({
  model: RESUME_ANALYZER_MODEL,
  schema: ResumeAnalysisOutputSchema,
  prompt: `Analyze this resume against the job description...`,
});

return object; // Score, missing keywords, suggestions... now what?

Users got a score card with bullet fixes like:

Original: "Responsible for managing team projects"
Improved: "Led cross-functional team of 8 engineers to deliver React dashboard"

But they couldn't actually apply these changes. They had to manually copy suggestions, find the right section in their resume, and paste. Most didn't bother.

The feedback was good. The workflow was broken.

I also needed a way to manage multiple resumes - one tailored for each job application. The old analyzer had no concept of "resumes" at all. It just analyzed whatever PDF you uploaded and forgot about it.

Chapter 2: The Agent Architecture

The fix wasn't better analysis - it was guided execution. Instead of dumping suggestions, the AI should:

Create a plan based on the user's resume
Collect job details
Tailor each section one at a time
Wait for user approval before moving on
Apply approved changes to the actual resume

This is a multi-step agent with human-in-the-loop control.

ToolLoopAgent from AI SDK 6

The Vercel AI SDK 6 introduced ToolLoopAgent - an agent that executes tools in a loop until a stop condition is met. Perfect for this use case.

// ai/agent/resume-tailor.ts
import { ToolLoopAgent, stepCountIs } from "ai";

export const createResumeTailorAgent = (chatId: string) =>
  new ToolLoopAgent({
    model: RESUME_CHAT_MODEL,
    instructions: RESUME_TAILOR_SYSTEM_PROMPT,
    tools: {
      createTailoringPlan: createTailoringPlanTool(chatId),
      collectJobDetails: collectJobDetailsTool,
      tailorSummary: tailorSummaryTool,
      approveSummary: approveSummaryTool,
      tailorExperienceEntry: tailorExperienceEntryTool,
      approveExperienceEntry: approveExperienceEntryTool,
      tailorSkills: tailorSkillsTool,
      approveSkills: approveSkillsTool,
    },
    stopWhen: stepCountIs(30),
  });

The agent has 8 tools, each with a specific job:

Tool	Purpose
`createTailoringPlan`	Generate a step-by-step plan based on user's profile
`collectJobDetails`	Show a form to collect job title and description
`tailorSummary`	AI generates a tailored professional summary
`approveSummary`	User reviews and approves/edits the summary
`tailorExperienceEntry`	AI optimizes bullets for one work experience
`approveExperienceEntry`	User approves the optimized bullets
`tailorSkills`	AI reorganizes skills by relevance
`approveSkills`	User approves the skill changes

The key insight: tailor tools generate suggestions, approval tools wait for user input. The agent can't proceed until the user responds.

Each tailoring tool also returns a match score (0-100) with analysis. For summaries, it's how well the summary matches the job. For experiences, it's a relevance score - how related that role is to the target job:

// ai/tool/resume-tailor/schemas.ts
export const TailoredExperienceOutputSchema = z.object({
  experienceId: z.string(),
  relevanceScore: z
    .number()
    .min(0)
    .max(100)
    .describe(
      "How relevant this role is to the target job. 90+: Directly related, 70-89: Transferable skills, 50-69: Some relevance, <50: Limited"
    ),
  suggestedBullets: z.array(z.string()).min(2).max(6),
  improvements: z.array(z.string()).describe("What was improved"),
  // ...
});

This helps users understand which experiences matter most for the job they're applying to.

Chapter 3: Human-in-the-Loop with Approval Tools

The magic happens in how approval tools work. They have no execute function - they just define a schema and wait:

// ai/tool/resume-tailor/tailor-summary.ts

// This tool DOES work - generates the suggestion
export const tailorSummaryTool = tool({
  description: "Generate a tailored professional summary",
  inputSchema: z.object({
    jobTitle: z.string(),
    jobDescription: z.string(),
  }),
  outputSchema: TailoredSummaryOutputSchema,
  execute: async ({ jobTitle, jobDescription }) => {
    // AI generates the tailored summary
    const { output } = await generateText({
      model: RESUME_ANALYZER_MODEL,
      output: Output.object({ schema: TailoredSummaryOutputSchema }),
      system: TAILOR_SUMMARY_PROMPT,
      prompt: `...`,
    });
    return output;
  },
});

// This tool has NO execute - it waits for user input
export const approveSummaryTool = tool({
  description: "Show the approval form for the tailored summary",
  inputSchema: z.object({}),
  outputSchema: SummaryApprovalSchema,
  // No execute! The frontend provides the output
});

When approveSummary is called, the AI SDK marks it as approval-requested. The frontend renders an approval card. When the user clicks "Approve" or "Edit", we send the result back:

// Frontend: components/dashboard/resume-tailor/resume-tailor-page.tsx
const handleSummaryApproval = useCallback(
  async (toolCallId: string, data: SummaryApproval) => {
    addToolOutput({
      tool: "approveSummary",
      toolCallId,
      output: data, // { approved: true, customText: null }
    });
  },
  [addToolOutput]
);

The agent receives the approval and continues to the next step. No polling, no webhooks - just streaming.

Chapter 4: The Plan System

Every tailoring session starts with a plan. The plan is dynamic - it depends on what's in the user's profile:

// ai/tool/resume-tailor/create-plan.ts
export const createTailoringPlanTool = (chatId: string) =>
  tool({
    description: "Create a tailoring plan for the user's resume",
    inputSchema: z.object({}),
    outputSchema: TailoringPlanSchema,
    execute: async () => {
      const profile = await getFullProfile(session.user.id);

      const steps: PlanStep[] = [
        { id: "collect_jd", type: "collect_jd", label: "Collect Job Details" },
        {
          id: "tailor_summary",
          type: "tailor_summary",
          label: "Tailor Summary",
        },
        {
          id: "approve_summary",
          type: "approve_summary",
          label: "Review Summary",
        },
      ];

      // Add steps for EACH work experience
      profile.workExperiences.forEach((exp) => {
        steps.push({
          id: `tailor_exp_${exp.id}`,
          type: "tailor_experience",
          label: `Tailor: ${exp.position} @ ${exp.company}`,
          context: { experienceId: exp.id },
        });
        steps.push({
          id: `approve_exp_${exp.id}`,
          type: "approve_experience",
          label: `Review: ${exp.position}`,
          context: { experienceId: exp.id },
        });
      });

      // Skills if present
      if (profile.skills?.length > 0) {
        steps.push({
          id: "tailor_skills",
          type: "tailor_skills",
          label: "Tailor Skills",
        });
        steps.push({
          id: "approve_skills",
          type: "approve_skills",
          label: "Review Skills",
        });
      }

      // Persist to database
      await savePlanSteps(chatId, steps);

      return { steps, targetJob: { title: null, description: null } };
    },
  });

A user with 5 work experiences gets 15 steps. A user with no experience and no skills gets 3 steps. The plan adapts.

DB-Backed Plan State

Initially, I derived plan progress from chat messages. Bad idea. If the stream disconnected mid-step, the UI showed the wrong state.

The fix: store plan steps in the database with explicit status:

// lib/db/tailoring-chat.ts
export async function savePlanSteps(chatId: string, steps: PlanStep[]) {
  await prisma.tailoringPlanStep.createMany({
    data: steps.map((step, index) => ({
      chatId,
      stepId: step.id,
      stepType: step.type,
      label: step.label,
      description: step.description,
      order: index,
      status: "pending", // pending | in_progress | completed | skipped
      context: step.context,
    })),
  });
}

export async function completeStep(chatId: string, stepId: string) {
  await prisma.tailoringPlanStep.update({
    where: { chatId_stepId: { chatId, stepId } },
    data: { status: "completed" },
  });
}

Now the UI always shows accurate progress, even after page refresh.

Chapter 5: Message Persistence & Type Mapping

Here's a problem I didn't anticipate: the AI SDK's UI message format doesn't match what you'd want to store in a database.

UI messages have deeply nested parts with different shapes per tool. Storing them as raw JSON works, but querying becomes painful. I needed a mapping layer.

// lib/utils/tailoring-message-mapping.ts
export function mapUIMessagePartsToDBParts(
  parts: ResumeTailorAgentUIMessage["parts"],
  messageId: string
): DBPartInsert[] {
  const result: DBPartInsert[] = [];

  parts.forEach((part, index) => {
    switch (part.type) {
      case "step-start":
        result.push({ messageId, order: index, type: "step-start" });
        break;

      case "text":
        result.push({ messageId, order: index, type: "text", text: part.text });
        break;

      // Tool parts use generic JSONB columns
      default:
        if (part.type.startsWith("tool-")) {
          result.push({
            messageId,
            order: index,
            type: "tool-invocation",
            toolCallId: part.toolCallId,
            toolName: part.type.replace("tool-", ""),
            toolState: part.state,
            toolInput: part.input,
            toolOutput:
              part.state === "output-available" ? part.output : undefined,
          });
        }
    }
  });

  return result;
}

The reverse mapping (mapDBPartToUIMessagePart) reconstructs the typed parts when loading chat history. This keeps the database schema clean while preserving full type safety in the UI.

Chapter 6: Streaming with createUIMessageStream

The agent streams its output to the frontend. But there's a trick: we need to persist messages AND update plan status as tools complete.

// app/api/resume-tailor/route.ts
const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    if (message.role === "user") {
      writer.write({ type: "start", messageId: generateId() });
    }

    const agent = createResumeTailorAgent(chatId);
    const result = await agent.stream({
      messages: await convertToModelMessages(messages),
    });

    result.consumeStream();
    writer.merge(result.toUIMessageStream({ sendStart: false }));
  },
  originalMessages: messages,
  onFinish: async ({ responseMessage }) => {
    // Persist the response using our mapping layer
    await upsertMessage({
      chatId,
      id: responseMessage.id,
      message: responseMessage,
    });

    // Update step status based on completed tools
    for (const part of responseMessage.parts) {
      if (!("state" in part) || part.state !== "output-available") continue;

      if (part.type === "tool-tailorSummary") {
        await completeStep(chatId, "tailor_summary");
      } else if (part.type === "tool-approveExperienceEntry") {
        await completeStep(chatId, `approve_exp_${part.output.experienceId}`);
      }
      // ... other tools
    }

    // Apply approved changes to the actual resume
    await applyApprovedChanges(chat.resumeId, responseMessage, allMessages);
  },
});

The onFinish callback is critical. It runs after the stream completes, persisting everything to the database.

Chapter 7: Live PDF Preview

As users approve changes, they see their resume update in real-time. The preview panel shows a live PDF:

// components/dashboard/resume-tailor/resume-tailor-page.tsx
const previewData = useMemo((): ResumeData => {
  const preview = { ...initialProfile };

  // Apply approved summary
  if (approvedChanges.summary?.approved && approvedChanges.summary.text) {
    preview.bio = approvedChanges.summary.text;
  }

  // Apply approved experience changes
  if (approvedChanges.experiences) {
    preview.workExperiences = preview.workExperiences.map((exp) => {
      const change = approvedChanges.experiences[exp.id];
      if (change?.approved && change.bullets) {
        return { ...exp, bullets: change.bullets };
      }
      return exp;
    });
  }

  return preview;
}, [initialProfile, approvedChanges]);

// Render with @react-pdf/renderer
<PDFPreview data={previewData} />

Every approval triggers a re-render of the PDF. Users see exactly what their resume will look like before committing.

Chapter 8: The step-start Bug That Broke Everything

This one took hours to debug.

Users would click "Start Tailoring" and... nothing. The chat showed their message, but no response. The UI looked completely broken.

The problem: when a user sends a message, the API immediately writes a step-start event to signal "processing has begun":

// app/api/resume-tailor/route.ts
if (message.role === "user") {
  writer.write({ type: "start", messageId: generateId() });
}

This creates an assistant message with a single step-start part. If the stream disconnects before the agent responds, you're left with:

User message: "Start tailoring my resume"
Assistant message: { parts: [{ type: "step-start" }] } - empty!

My initial stuck detection only checked if the last message was from the user. It completely missed this case.

The Fix

Check for assistant messages that have no meaningful content:

// components/dashboard/resume-tailor/resume-tailor-page.tsx
const stuckState = useMemo(() => {
  if (messages.length === 0) return null;
  if (status === "streaming" || status === "submitted") return null;

  const lastMessage = messages[messages.length - 1];

  // Case 1: Last message is from user - no response at all
  if (lastMessage.role === "user") {
    return { messageId: lastMessage.id, messageText: extractText(lastMessage) };
  }

  // Case 2: Assistant message with no meaningful content (just step-start)
  if (lastMessage.role === "assistant") {
    const hasMeaningfulContent = lastMessage.parts.some(
      (p) =>
        p.type === "text" ||
        p.type === "reasoning" ||
        p.type.startsWith("tool-")
    );

    if (!hasMeaningfulContent && messages.length >= 2) {
      const userMessage = messages[messages.length - 2];
      return {
        messageId: userMessage.id,
        messageText: extractText(userMessage),
      };
    }
  }

  return null;
}, [messages, status]);

The RetryCard Component

When stuck, we show a friendly card with animated icons:

// components/dashboard/resume-tailor/retry-card.tsx
export function RetryCard({
  failedMessage,
  onRetry,
  isRetrying,
}: RetryCardProps) {
  const [isHovered, setIsHovered] = useState(false);

  return (
    <Card
      className="border-amber-500/30 bg-linear-to-br from-amber-500/5 to-orange-500/10"
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
    >
      <CardContent className="pt-6">
        <div className="flex items-start gap-4">
          <div className="rounded-full bg-amber-500/10 p-3 relative">
            <WifiOffIcon
              className={`h-6 w-6 text-amber-600 transition-opacity ${isHovered ? "opacity-0" : "opacity-100"}`}
            />
            <RefreshCwIcon
              className={`h-6 w-6 text-amber-600 absolute inset-0 m-auto transition-all ${isHovered ? "opacity-100 rotate-180" : "opacity-0"} ${isRetrying ? "animate-spin" : ""}`}
            />
          </div>
          <div className="flex-1 space-y-4">
            <h3 className="font-semibold text-amber-800">
              Connection Interrupted
            </h3>
            <p className="text-sm text-muted-foreground">
              The connection was lost before I could respond.
            </p>
            {failedMessage && (
              <div className="p-3 bg-muted/50 rounded-lg">
                <p className="text-xs text-muted-foreground">Your message:</p>
                <p className="text-sm italic">
                  "{failedMessage.slice(0, 100)}..."
                </p>
              </div>
            )}
            <Button onClick={onRetry} disabled={isRetrying}>
              {isRetrying ? "Retrying..." : "Try Again"}
            </Button>
            <span className="text-xs">Don't worry, your progress is saved</span>
          </div>
        </div>
      </CardContent>
    </Card>
  );
}

The retry handler re-sends the last user message:

const handleRetry = useCallback(() => {
  if (!stuckState) return;
  // Find the original user message and re-send it
  const userMessage = messages.find((m) => m.id === stuckState.messageId);
  if (userMessage) {
    handleSubmit({ preventDefault: () => {} } as React.FormEvent);
  }
}, [stuckState, messages, handleSubmit]);

Simple recovery, no Redis required. Users forgive network issues if recovery is easy.

The Final Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    Resume Tailor Flow                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  User clicks "Start Tailoring"                                       │
│           ↓                                                          │
│  Agent calls createTailoringPlan → Plan saved to DB                  │
│           ↓                                                          │
│  Agent calls collectJobDetails → Form shown to user                  │
│           ↓                                                          │
│  User submits job details → Agent receives input                     │
│           ↓                                                          │
│  Agent calls tailorSummary → AI generates suggestion                 │
│           ↓                                                          │
│  Agent calls approveSummary → Approval card shown                    │
│           ↓                                                          │
│  User approves → Agent continues to next experience                  │
│           ↓                                                          │
│  [Loop for each experience]                                          │
│           ↓                                                          │
│  Agent calls tailorSkills → AI reorganizes skills                    │
│           ↓                                                          │
│  User approves → Changes applied to resume in DB                     │
│           ↓                                                          │
│  PDF preview updates in real-time                                    │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

TL;DR

Problem	Solution
Analyzer gave advice but didn't help apply it	Agent tailors step-by-step with user approval
No control over AI changes	Human-in-the-loop with approval tools
Plan progress lost on refresh	DB-backed plan state with explicit status
Stream disconnects left UI broken	Stuck state detection with retry mechanism
Users couldn't preview changes	Live PDF preview updates on each approval
Generic bullet suggestions	AI tailors each experience entry individually
No way to manage multiple resumes	Resume dashboard with per-job tailoring
UI/DB message type mismatch	Mapping layer for clean persistence
`step-start` bug left chat empty	Check for meaningful content, not just role

Key Lessons

1. Agents > Analyzers for actionable features.

Analysis tells users what's wrong. Agents help them fix it. If your AI feature ends with "here's what you should do," you've only done half the job.

2. Human-in-the-loop is easier than you think.

Approval tools with no execute function + addToolOutput on the frontend = full user control. The AI SDK handles all the state management.

3. Persist plan state to the database.

Deriving state from chat messages is fragile. Explicit status columns (pending, in_progress, completed, skipped) make the UI predictable.

4. Stream disconnects happen. Plan for them.

Detect stuck states (user message with no response, or empty assistant message) and offer a retry button. Users forgive network issues if recovery is easy.

5. Live preview builds trust.

Users are hesitant to let AI modify their resume. Showing changes in real-time before committing makes them confident to approve.

6. The step-start trap is real.

If your streaming API writes a "processing started" event, you can end up with empty assistant messages on disconnect. Always check for meaningful content, not just message role.

What's Next

Resume templates - Multiple PDF layouts to choose from
Cover letter generation - Use the same agent pattern for cover letters
Job application tracking - Track which resumes were sent to which jobs
ATS compatibility scoring - Analyze PDF structure, not just content

Why Open Source?

Building an AI agent with human-in-the-loop approvals took weeks of iteration. The streaming, the state management, the edge cases - it's all in the repo.

If you're building something similar, you don't have to start from scratch. Fork it, learn from it, improve on it.

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If you find this useful, consider starring the repo - it helps others discover the project!

Key files from this post:

ai/agent/resume-tailor.ts - The ToolLoopAgent definition
ai/tool/resume-tailor/ - All 8 tools with schemas
app/api/resume-tailor/route.ts - Streaming API with persistence
components/dashboard/resume-tailor/ - UI components for approvals
lib/db/tailoring-chat.ts - Plan state management
lib/utils/tailoring-message-mapping.ts - UI ↔ DB message conversion

Your Turn

I'd love feedback:

On the code: See something that could be better? Open an issue or PR.
On the post: Too long? Missing something? Tell me.
On AI agents: How do you handle human-in-the-loop in your projects?

Building in public only works if there's a public to build with.

If this post helped you, drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan - ⭐ Star the repo if you found this helpful!
🐦 Twitter/X: @abdullahjan - Follow for more dev content
👥 LinkedIn: abdullahjan - Let's connect

Eighth post of many. See you in the next one.

Carific.ai: Building an AI Resume Tailor with Multi-Step Agents - Vercel AI SDK 6 and ToolLoopAgent

Abdullah Jan — Tue, 13 Jan 2026 15:42:26 +0000

The resume analyzer I built in post #2 had a problem: it told users what was wrong but didn't help them fix it.

"Add more metrics to your bullet points" is great advice. But which bullet points? What metrics? Users were left staring at a score card, unsure what to do next.

This is the story of building an AI agent with human-in-the-loop approvals using the Vercel AI SDK 6.

The Stack (Actual Versions)

{
  "next": "16.1.1",
  "react": "19.2.3",
  "ai": "6.0.20",
  "@ai-sdk/react": "3.0.20",
  "@react-pdf/renderer": "4.3.1",
  "zod": "4.2.1",
  "@prisma/client": "7.1.0"
}

Chapter 1: Why the Analyzer Wasn't Enough

The original resume analyzer used generateObject to return structured feedback:

// ❌ The old approach - analyze and done
const { object } = await generateObject({
  model: RESUME_ANALYZER_MODEL,
  schema: ResumeAnalysisOutputSchema,
  prompt: `Analyze this resume against the job description...`,
});

return object; // Score, missing keywords, suggestions... now what?

Users got a score card with bullet fixes like:

Original: "Responsible for managing team projects"
Improved: "Led cross-functional team of 8 engineers to deliver React dashboard"

But they couldn't actually apply these changes. They had to manually copy suggestions, find the right section in their resume, and paste. Most didn't bother.

The feedback was good. The workflow was broken.

Chapter 2: The Agent Architecture

The fix wasn't better analysis - it was guided execution. Instead of dumping suggestions, the AI should:

Create a plan based on the user's resume
Collect job details
Tailor each section one at a time
Wait for user approval before moving on
Apply approved changes to the actual resume

This is a multi-step agent with human-in-the-loop control.

ToolLoopAgent from AI SDK 6

The Vercel AI SDK 6 introduced ToolLoopAgent - an agent that executes tools in a loop until a stop condition is met. Perfect for this use case.

// ai/agent/resume-tailor.ts
import { ToolLoopAgent, stepCountIs } from "ai";

export const createResumeTailorAgent = (chatId: string) =>
  new ToolLoopAgent({
    model: RESUME_CHAT_MODEL,
    instructions: RESUME_TAILOR_SYSTEM_PROMPT,
    tools: {
      createTailoringPlan: createTailoringPlanTool(chatId),
      collectJobDetails: collectJobDetailsTool,
      tailorSummary: tailorSummaryTool,
      approveSummary: approveSummaryTool,
      tailorExperienceEntry: tailorExperienceEntryTool,
      approveExperienceEntry: approveExperienceEntryTool,
      tailorSkills: tailorSkillsTool,
      approveSkills: approveSkillsTool,
    },
    stopWhen: stepCountIs(30),
  });

The agent has 8 tools, each with a specific job:

Tool	Purpose
`createTailoringPlan`	Generate a step-by-step plan based on user's profile
`collectJobDetails`	Show a form to collect job title and description
`tailorSummary`	AI generates a tailored professional summary
`approveSummary`	User reviews and approves/edits the summary
`tailorExperienceEntry`	AI optimizes bullets for one work experience
`approveExperienceEntry`	User approves the optimized bullets
`tailorSkills`	AI reorganizes skills by relevance
`approveSkills`	User approves the skill changes

The key insight: tailor tools generate suggestions, approval tools wait for user input. The agent can't proceed until the user responds.

// ai/tool/resume-tailor/schemas.ts
export const TailoredExperienceOutputSchema = z.object({
  experienceId: z.string(),
  relevanceScore: z
    .number()
    .min(0)
    .max(100)
    .describe(
      "How relevant this role is to the target job. 90+: Directly related, 70-89: Transferable skills, 50-69: Some relevance, <50: Limited"
    ),
  suggestedBullets: z.array(z.string()).min(2).max(6),
  improvements: z.array(z.string()).describe("What was improved"),
  // ...
});

This helps users understand which experiences matter most for the job they're applying to.

Chapter 3: Human-in-the-Loop with Approval Tools

The magic happens in how approval tools work. They have no execute function - they just define a schema and wait:

// ai/tool/resume-tailor/tailor-summary.ts

// This tool DOES work - generates the suggestion
export const tailorSummaryTool = tool({
  description: "Generate a tailored professional summary",
  inputSchema: z.object({
    jobTitle: z.string(),
    jobDescription: z.string(),
  }),
  outputSchema: TailoredSummaryOutputSchema,
  execute: async ({ jobTitle, jobDescription }) => {
    // AI generates the tailored summary
    const { output } = await generateText({
      model: RESUME_ANALYZER_MODEL,
      output: Output.object({ schema: TailoredSummaryOutputSchema }),
      system: TAILOR_SUMMARY_PROMPT,
      prompt: `...`,
    });
    return output;
  },
});

// This tool has NO execute - it waits for user input
export const approveSummaryTool = tool({
  description: "Show the approval form for the tailored summary",
  inputSchema: z.object({}),
  outputSchema: SummaryApprovalSchema,
  // No execute! The frontend provides the output
});

When approveSummary is called, the AI SDK marks it as approval-requested. The frontend renders an approval card. When the user clicks "Approve" or "Edit", we send the result back:

// Frontend: components/dashboard/resume-tailor/resume-tailor-page.tsx
const handleSummaryApproval = useCallback(
  async (toolCallId: string, data: SummaryApproval) => {
    addToolOutput({
      tool: "approveSummary",
      toolCallId,
      output: data, // { approved: true, customText: null }
    });
  },
  [addToolOutput]
);

The agent receives the approval and continues to the next step. No polling, no webhooks - just streaming.

Chapter 4: The Plan System

Every tailoring session starts with a plan. The plan is dynamic - it depends on what's in the user's profile:

// ai/tool/resume-tailor/create-plan.ts
export const createTailoringPlanTool = (chatId: string) =>
  tool({
    description: "Create a tailoring plan for the user's resume",
    inputSchema: z.object({}),
    outputSchema: TailoringPlanSchema,
    execute: async () => {
      const profile = await getFullProfile(session.user.id);

      const steps: PlanStep[] = [
        { id: "collect_jd", type: "collect_jd", label: "Collect Job Details" },
        {
          id: "tailor_summary",
          type: "tailor_summary",
          label: "Tailor Summary",
        },
        {
          id: "approve_summary",
          type: "approve_summary",
          label: "Review Summary",
        },
      ];

      // Add steps for EACH work experience
      profile.workExperiences.forEach((exp) => {
        steps.push({
          id: `tailor_exp_${exp.id}`,
          type: "tailor_experience",
          label: `Tailor: ${exp.position} @ ${exp.company}`,
          context: { experienceId: exp.id },
        });
        steps.push({
          id: `approve_exp_${exp.id}`,
          type: "approve_experience",
          label: `Review: ${exp.position}`,
          context: { experienceId: exp.id },
        });
      });

      // Skills if present
      if (profile.skills?.length > 0) {
        steps.push({
          id: "tailor_skills",
          type: "tailor_skills",
          label: "Tailor Skills",
        });
        steps.push({
          id: "approve_skills",
          type: "approve_skills",
          label: "Review Skills",
        });
      }

      // Persist to database
      await savePlanSteps(chatId, steps);

      return { steps, targetJob: { title: null, description: null } };
    },
  });

A user with 5 work experiences gets 15 steps. A user with no experience and no skills gets 3 steps. The plan adapts.

DB-Backed Plan State

Initially, I derived plan progress from chat messages. Bad idea. If the stream disconnected mid-step, the UI showed the wrong state.

The fix: store plan steps in the database with explicit status:

// lib/db/tailoring-chat.ts
export async function savePlanSteps(chatId: string, steps: PlanStep[]) {
  await prisma.tailoringPlanStep.createMany({
    data: steps.map((step, index) => ({
      chatId,
      stepId: step.id,
      stepType: step.type,
      label: step.label,
      description: step.description,
      order: index,
      status: "pending", // pending | in_progress | completed | skipped
      context: step.context,
    })),
  });
}

export async function completeStep(chatId: string, stepId: string) {
  await prisma.tailoringPlanStep.update({
    where: { chatId_stepId: { chatId, stepId } },
    data: { status: "completed" },
  });
}

Now the UI always shows accurate progress, even after page refresh.

Chapter 5: Message Persistence & Type Mapping

Here's a problem I didn't anticipate: the AI SDK's UI message format doesn't match what you'd want to store in a database.

UI messages have deeply nested parts with different shapes per tool. Storing them as raw JSON works, but querying becomes painful. I needed a mapping layer.

// lib/utils/tailoring-message-mapping.ts
export function mapUIMessagePartsToDBParts(
  parts: ResumeTailorAgentUIMessage["parts"],
  messageId: string
): DBPartInsert[] {
  const result: DBPartInsert[] = [];

  parts.forEach((part, index) => {
    switch (part.type) {
      case "step-start":
        result.push({ messageId, order: index, type: "step-start" });
        break;

      case "text":
        result.push({ messageId, order: index, type: "text", text: part.text });
        break;

      // Tool parts use generic JSONB columns
      default:
        if (part.type.startsWith("tool-")) {
          result.push({
            messageId,
            order: index,
            type: "tool-invocation",
            toolCallId: part.toolCallId,
            toolName: part.type.replace("tool-", ""),
            toolState: part.state,
            toolInput: part.input,
            toolOutput:
              part.state === "output-available" ? part.output : undefined,
          });
        }
    }
  });

  return result;
}

The reverse mapping (mapDBPartToUIMessagePart) reconstructs the typed parts when loading chat history. This keeps the database schema clean while preserving full type safety in the UI.

Chapter 6: Streaming with createUIMessageStream

The agent streams its output to the frontend. But there's a trick: we need to persist messages AND update plan status as tools complete.

// app/api/resume-tailor/route.ts
const stream = createUIMessageStream({
  execute: async ({ writer }) => {
    if (message.role === "user") {
      writer.write({ type: "start", messageId: generateId() });
    }

    const agent = createResumeTailorAgent(chatId);
    const result = await agent.stream({
      messages: await convertToModelMessages(messages),
    });

    result.consumeStream();
    writer.merge(result.toUIMessageStream({ sendStart: false }));
  },
  originalMessages: messages,
  onFinish: async ({ responseMessage }) => {
    // Persist the response using our mapping layer
    await upsertMessage({
      chatId,
      id: responseMessage.id,
      message: responseMessage,
    });

    // Update step status based on completed tools
    for (const part of responseMessage.parts) {
      if (!("state" in part) || part.state !== "output-available") continue;

      if (part.type === "tool-tailorSummary") {
        await completeStep(chatId, "tailor_summary");
      } else if (part.type === "tool-approveExperienceEntry") {
        await completeStep(chatId, `approve_exp_${part.output.experienceId}`);
      }
      // ... other tools
    }

    // Apply approved changes to the actual resume
    await applyApprovedChanges(chat.resumeId, responseMessage, allMessages);
  },
});

The onFinish callback is critical. It runs after the stream completes, persisting everything to the database.

Chapter 7: Live PDF Preview

As users approve changes, they see their resume update in real-time. The preview panel shows a live PDF:

// components/dashboard/resume-tailor/resume-tailor-page.tsx
const previewData = useMemo((): ResumeData => {
  const preview = { ...initialProfile };

  // Apply approved summary
  if (approvedChanges.summary?.approved && approvedChanges.summary.text) {
    preview.bio = approvedChanges.summary.text;
  }

  // Apply approved experience changes
  if (approvedChanges.experiences) {
    preview.workExperiences = preview.workExperiences.map((exp) => {
      const change = approvedChanges.experiences[exp.id];
      if (change?.approved && change.bullets) {
        return { ...exp, bullets: change.bullets };
      }
      return exp;
    });
  }

  return preview;
}, [initialProfile, approvedChanges]);

// Render with @react-pdf/renderer
<PDFPreview data={previewData} />

Every approval triggers a re-render of the PDF. Users see exactly what their resume will look like before committing.

Chapter 8: The step-start Bug That Broke Everything

This one took hours to debug.

Users would click "Start Tailoring" and... nothing. The chat showed their message, but no response. The UI looked completely broken.

The problem: when a user sends a message, the API immediately writes a step-start event to signal "processing has begun":

// app/api/resume-tailor/route.ts
if (message.role === "user") {
  writer.write({ type: "start", messageId: generateId() });
}

This creates an assistant message with a single step-start part. If the stream disconnects before the agent responds, you're left with:

User message: "Start tailoring my resume"
Assistant message: { parts: [{ type: "step-start" }] } - empty!

My initial stuck detection only checked if the last message was from the user. It completely missed this case.

The Fix

Check for assistant messages that have no meaningful content:

// components/dashboard/resume-tailor/resume-tailor-page.tsx
const stuckState = useMemo(() => {
  if (messages.length === 0) return null;
  if (status === "streaming" || status === "submitted") return null;

  const lastMessage = messages[messages.length - 1];

  // Case 1: Last message is from user - no response at all
  if (lastMessage.role === "user") {
    return { messageId: lastMessage.id, messageText: extractText(lastMessage) };
  }

  // Case 2: Assistant message with no meaningful content (just step-start)
  if (lastMessage.role === "assistant") {
    const hasMeaningfulContent = lastMessage.parts.some(
      (p) =>
        p.type === "text" ||
        p.type === "reasoning" ||
        p.type.startsWith("tool-")
    );

    if (!hasMeaningfulContent && messages.length >= 2) {
      const userMessage = messages[messages.length - 2];
      return {
        messageId: userMessage.id,
        messageText: extractText(userMessage),
      };
    }
  }

  return null;
}, [messages, status]);

The RetryCard Component

When stuck, we show a friendly card with animated icons:

// components/dashboard/resume-tailor/retry-card.tsx
export function RetryCard({
  failedMessage,
  onRetry,
  isRetrying,
}: RetryCardProps) {
  const [isHovered, setIsHovered] = useState(false);

  return (
    <Card
      className="border-amber-500/30 bg-linear-to-br from-amber-500/5 to-orange-500/10"
      onMouseEnter={() => setIsHovered(true)}
      onMouseLeave={() => setIsHovered(false)}
    >
      <CardContent className="pt-6">
        <div className="flex items-start gap-4">
          <div className="rounded-full bg-amber-500/10 p-3 relative">
            <WifiOffIcon
              className={`h-6 w-6 text-amber-600 transition-opacity ${isHovered ? "opacity-0" : "opacity-100"}`}
            />
            <RefreshCwIcon
              className={`h-6 w-6 text-amber-600 absolute inset-0 m-auto transition-all ${isHovered ? "opacity-100 rotate-180" : "opacity-0"} ${isRetrying ? "animate-spin" : ""}`}
            />
          </div>
          <div className="flex-1 space-y-4">
            <h3 className="font-semibold text-amber-800">
              Connection Interrupted
            </h3>
            <p className="text-sm text-muted-foreground">
              The connection was lost before I could respond.
            </p>
            {failedMessage && (
              <div className="p-3 bg-muted/50 rounded-lg">
                <p className="text-xs text-muted-foreground">Your message:</p>
                <p className="text-sm italic">
                  "{failedMessage.slice(0, 100)}..."
                </p>
              </div>
            )}
            <Button onClick={onRetry} disabled={isRetrying}>
              {isRetrying ? "Retrying..." : "Try Again"}
            </Button>
            <span className="text-xs">Don't worry, your progress is saved</span>
          </div>
        </div>
      </CardContent>
    </Card>
  );
}

The retry handler re-sends the last user message:

const handleRetry = useCallback(() => {
  if (!stuckState) return;
  // Find the original user message and re-send it
  const userMessage = messages.find((m) => m.id === stuckState.messageId);
  if (userMessage) {
    handleSubmit({ preventDefault: () => {} } as React.FormEvent);
  }
}, [stuckState, messages, handleSubmit]);

Simple recovery, no Redis required. Users forgive network issues if recovery is easy.

The Final Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    Resume Tailor Flow                                │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  User clicks "Start Tailoring"                                       │
│           ↓                                                          │
│  Agent calls createTailoringPlan → Plan saved to DB                  │
│           ↓                                                          │
│  Agent calls collectJobDetails → Form shown to user                  │
│           ↓                                                          │
│  User submits job details → Agent receives input                     │
│           ↓                                                          │
│  Agent calls tailorSummary → AI generates suggestion                 │
│           ↓                                                          │
│  Agent calls approveSummary → Approval card shown                    │
│           ↓                                                          │
│  User approves → Agent continues to next experience                  │
│           ↓                                                          │
│  [Loop for each experience]                                          │
│           ↓                                                          │
│  Agent calls tailorSkills → AI reorganizes skills                    │
│           ↓                                                          │
│  User approves → Changes applied to resume in DB                     │
│           ↓                                                          │
│  PDF preview updates in real-time                                    │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

TL;DR

Problem	Solution
Analyzer gave advice but didn't help apply it	Agent tailors step-by-step with user approval
No control over AI changes	Human-in-the-loop with approval tools
Plan progress lost on refresh	DB-backed plan state with explicit status
Stream disconnects left UI broken	Stuck state detection with retry mechanism
Users couldn't preview changes	Live PDF preview updates on each approval
Generic bullet suggestions	AI tailors each experience entry individually
No way to manage multiple resumes	Resume dashboard with per-job tailoring
UI/DB message type mismatch	Mapping layer for clean persistence
`step-start` bug left chat empty	Check for meaningful content, not just role

Key Lessons

1. Agents > Analyzers for actionable features.

Analysis tells users what's wrong. Agents help them fix it. If your AI feature ends with "here's what you should do," you've only done half the job.

2. Human-in-the-loop is easier than you think.

Approval tools with no execute function + addToolOutput on the frontend = full user control. The AI SDK handles all the state management.

3. Persist plan state to the database.

Deriving state from chat messages is fragile. Explicit status columns (pending, in_progress, completed, skipped) make the UI predictable.

4. Stream disconnects happen. Plan for them.

Detect stuck states (user message with no response, or empty assistant message) and offer a retry button. Users forgive network issues if recovery is easy.

5. Live preview builds trust.

Users are hesitant to let AI modify their resume. Showing changes in real-time before committing makes them confident to approve.

6. The step-start trap is real.

If your streaming API writes a "processing started" event, you can end up with empty assistant messages on disconnect. Always check for meaningful content, not just message role.

What's Next

Resume templates - Multiple PDF layouts to choose from
Cover letter generation - Use the same agent pattern for cover letters
Job application tracking - Track which resumes were sent to which jobs
ATS compatibility scoring - Analyze PDF structure, not just content

Why Open Source?

Building an AI agent with human-in-the-loop approvals took weeks of iteration. The streaming, the state management, the edge cases - it's all in the repo.

If you're building something similar, you don't have to start from scratch. Fork it, learn from it, improve on it.

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If you find this useful, consider starring the repo - it helps others discover the project!

Key files from this post:

ai/agent/resume-tailor.ts - The ToolLoopAgent definition
ai/tool/resume-tailor/ - All 8 tools with schemas
app/api/resume-tailor/route.ts - Streaming API with persistence
components/dashboard/resume-tailor/ - UI components for approvals
lib/db/tailoring-chat.ts - Plan state management
lib/utils/tailoring-message-mapping.ts - UI ↔ DB message conversion

Your Turn

I'd love feedback:

On the code: See something that could be better? Open an issue or PR.
On the post: Too long? Missing something? Tell me.
On AI agents: How do you handle human-in-the-loop in your projects?

Building in public only works if there's a public to build with.

If this post helped you, drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan - ⭐ Star the repo if you found this helpful!
🐦 Twitter/X: @abdullahjan - Follow for more dev content
👥 LinkedIn: abdullahjan - Let's connect

Eighth post of many. See you in the next one.

Carific.ai: The Last 10% - Production Hardening with React 19, Privacy Safeguards, and Memory Leak Fixes

Abdullah Jan — Wed, 24 Dec 2025 06:43:57 +0000

Seventh post in the Carific.ai series. Previous posts: Auth System, AI Resume Analyzer, Structured AI Output, Profile Editor Type Safety, Domain Model Architecture, and Flicker-Free PDF Viewer.

Building a feature to "it works" usually takes 20% of the time. The remaining 80% is spent on the "it's bulletproof" part.

I thought Carific.ai's profile editor was feature complete. The profile editor worked, the PDF preview was smooth, and users could see the initial version of their resumes. Then code review happened.

What I discovered: memory leaks from rapid typing, React key bugs that broke focus, missing privacy safeguards for sensitive data, and accessibility gaps that screen readers couldn't handle.

This post is about the "Last 10%" - the hardening phase where we fix race conditions, implement GDPR-compliant consent flows, add array reordering with stable keys, and plug memory leaks in PDF rendering.

The Stack (Actual Versions)

{
  "next": "16.1.1",
  "react": "19.2.3",
  "@react-pdf/renderer": "4.3.1",
  "@tanstack/react-form": "1.27.1",
  "zod": "4.1.13"
}

Chapter 1: Array Reordering with TanStack Form

Users needed to reorder resume sections move work experiences up and down, rearrange education entries. Sounds simple, but implementing it properly with TanStack Form revealed several traps.

The Feature Request

I needed to add up/down/delete buttons to every array field in the profile editor:

Work Experience bullets
Education highlights
Skills, Languages, Certifications
Projects, Achievements, Social Links

The naive approach? Add three buttons to each section and call it done. But code review caught issues I completely missed.

The DRY Violation

My first implementation copy-pasted the same button group across 8+ sections:

// ❌ Duplicated everywhere
<ButtonGroup>
  <Button onClick={() => field.moveValue(index, index - 1)}>
    <ChevronUp />
  </Button>
  <Button onClick={() => field.moveValue(index, index + 1)}>
    <ChevronDown />
  </Button>
  <Button onClick={() => field.removeValue(index)}>
    <Trash2 />
  </Button>
</ButtonGroup>

Code review flagged this immediately: "Extract this into a reusable component."

The Solution: ArrayFieldActions Component

I created a generic component that works with any array field:

// components/form/form-components.tsx
import { useFieldContext } from "@/hooks/form-context";

export function ArrayFieldActions<T = unknown>({
  index,
  className,
}: ArrayFieldActionsProps) {
  const field = useFieldContext<T[]>();
  const total = field.state.value?.length ?? 0;

  return (
    <ButtonGroup className={className}>
      <Button
        type="button"
        variant="outline"
        size="sm"
        onClick={() => field.moveValue(index, index - 1)}
        disabled={index === 0}
        title="Move Up"
        aria-label="Move item up"
      >
        <ChevronUp className="h-4 w-4" />
      </Button>
      <Button
        type="button"
        variant="outline"
        size="sm"
        onClick={() => field.moveValue(index, index + 1)}
        disabled={index === total - 1}
        title="Move Down"
        aria-label="Move item down"
      >
        <ChevronDown className="h-4 w-4" />
      </Button>
      <Button
        type="button"
        variant="outline"
        size="sm"
        onClick={() => field.removeValue(index)}
        title="Remove"
        aria-label="Remove item"
      >
        <Trash2 className="h-4 w-4 text-destructive" />
      </Button>
    </ButtonGroup>
  );
}

Key decisions:

Generic type parameter (<T = unknown>) - works with string[], WorkExperience[], any array type
useFieldContext - reads the parent field automatically, no prop drilling
Boundary checks - disable up/down buttons at edges
Accessibility - aria-label for screen readers, title for tooltips

Now every section just uses:

<ArrayFieldActions index={index} />

One component, 8+ sections, zero duplication.

Chapter 2: The "Index" Trap

With reordering implemented, code review caught a critical bug: I was using array indices as React keys.

The Problem

When you use an array index as a React key, React assumes the identity of a component is tied to its position. If you move "Experience A" from position 0 to 1, React thinks position 0 now holds a "new" item and position 1 is just the "old" item updated.

This leads to:

Lost Focus: If you're typing in a field and reorder the list, you lose focus.
State Ghosting: Local component state (like collapsed/expanded) stays at the index, not with the data.
Animation Bugs: CSS transitions fire on the wrong elements.

The Bug in Action

// ❌ The trap: components/profile-editor/sections/work-experience-section.tsx
{
  field.state.value.map((_, index) => (
    <Card key={index}>
      {/* User types in position 0, clicks "Move Down" */}
      {/* React thinks position 0 is a NEW card, loses focus */}
    </Card>
  ));
}

The Fix: Stable IDs from Factory Functions

I moved to a factory pattern where every new item gets a unique ID immediately:

// lib/validations/profile-update.ts
import { randomUUID } from "crypto";

export const createEmptyWorkExperience = (): WorkExperience => ({
  id: randomUUID(), // Generated once, never changes
  company: "",
  position: "",
  startDate: null,
  endDate: null,
  current: false,
  bullets: [],
  order: 0,
});

Now the keys follow the data:

// ✅ The fix: using stable IDs
{
  field.state.value.map((exp) => (
    <Card key={exp.id}>
      {/* Focus stays with the data, not the position */}
    </Card>
  ));
}

I applied this pattern to all array fields:

createEmptyEducation()
createEmptyProject()
createEmptySkill()
createEmptyLanguage()
createEmptyCertification()
createEmptyAchievement()
createEmptySocialLink()

The Lesson: Never use index as a key for lists that can be reordered, deleted, or inserted. Generate a UUID on the client the moment the "Add" button is clicked, and store it in your form state.

Chapter 3: Privacy Safeguards for Sensitive PII

Code review flagged a legal risk I hadn't considered: the profile editor was collecting sensitive personal information without consent or privacy notices.

The Compliance Issue

The basic info section collected:

Date of birth
Gender
Nationality
Marital status
Visa status

These are protected characteristics under GDPR, CCPA, and anti-discrimination laws in many jurisdictions. Collecting them without:

Explicit consent
Privacy notices
Legitimate business purpose
Proper data handling

...is a legal liability.

The Problem

Users in the US, UK, and EU are often discouraged or prohibited from including this data on resumes. But users in other regions (Middle East, Asia) may need it for visa requirements or local customs.

I needed a solution that:

✅ Warns users about discrimination risks
✅ Requires explicit consent before enabling fields
✅ Stores consent in the database
✅ Conditionally renders fields in PDF based on consent

The Implementation

Step 1: Database Schema

Added a privacyConsent field to track user consent:

// prisma/schema.prisma
model UserProfile {
  // ... other fields

  // Optional Personal Details (region-specific)
  dateOfBirth   DateTime?
  gender        String?
  nationality   String?
  maritalStatus String?
  visaStatus    String?

  privacyConsent Boolean @default(false) // NEW: tracks consent
}

Migration:

-- prisma/migrations/20251223143639_add_privacy_consent/migration.sql
ALTER TABLE "user_profile"
ADD COLUMN "privacyConsent" BOOLEAN NOT NULL DEFAULT false;

Step 2: Privacy Warning UI

Added an accordion with a prominent warning:

// components/profile-editor/sections/basic-info-section.tsx
import { AlertTriangle } from "lucide-react";
import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";

<Accordion type="single" collapsible>
  <AccordionItem value="personal-details">
    <AccordionTrigger>
      <span className="text-sm font-medium">Personal Details (Optional)</span>
    </AccordionTrigger>
    <AccordionContent>
      <Alert variant="destructive" className="mb-6">
        <AlertTriangle className="h-4 w-4" />
        <AlertTitle>Privacy & Discrimination Risk</AlertTitle>
        <AlertDescription>
          Including protected characteristics (gender, nationality, etc.) is
          discouraged or illegal in many regions (e.g., US, UK). Only include
          these if strictly required for your target location or visa
          requirements.
        </AlertDescription>
      </Alert>

      {/* Consent checkbox + fields */}
    </AccordionContent>
  </AccordionItem>
</Accordion>;

Step 3: Consent Checkbox

Fields are disabled until the user explicitly consents:

<form.AppField name="privacyConsent">
  {(consentField) => (
    <>
      <div className="flex items-center space-x-2 mb-6 p-3 bg-muted/50 rounded-lg border">
        <Checkbox
          id="privacy-consent"
          checked={consentField.state.value}
          onCheckedChange={(checked) =>
            consentField.handleChange(checked === true)
          }
        />
        <Label htmlFor="privacy-consent" className="text-xs">
          I understand these details are optional and I consent to providing
          this sensitive information for my resume.
        </Label>
      </div>

      <div
        className={cn(
          "space-y-4 transition-opacity duration-200",
          !consentField.state.value && "opacity-50 pointer-events-none"
        )}
      >
        {/* Sensitive fields here, disabled until consent */}
        <form.AppField name="dateOfBirth">
          {(field) => (
            <field.DateField
              label="Date of Birth"
              disabled={!consentField.state.value}
            />
          )}
        </form.AppField>
        {/* ... more fields */}
      </div>
    </>
  )}
</form.AppField>

Step 4: Conditional PDF Rendering

The resume template only shows sensitive data if consent was given:

// components/pdf/resume-template.tsx
{
  data.privacyConsent && data.dateOfBirth && (
    <Text>DOB: {formatDate(data.dateOfBirth)}</Text>
  );
}

{
  data.privacyConsent && data.nationality && (
    <Text>Nationality: {data.nationality}</Text>
  );
}

The Result

✅ Users see a clear warning about discrimination risks
✅ Fields are disabled by default
✅ Consent is stored in the database
✅ PDF respects user privacy choices
✅ Legal compliance for GDPR/CCPA

The Lesson: When collecting sensitive PII, always implement explicit consent flows with clear warnings. Don't assume users understand the legal implications of including protected characteristics on resumes.

Chapter 4: The Rapid-Fire Memory Leak

The PDF viewer uses URL.createObjectURL(blob) to render previews. In my previous iteration, I revoked the old URL after 1 second to allow for a smooth transition.

The Bug

If a user is a fast typer, they might trigger 5 renders in 500ms. My code was only tracking the current timeout. When a new render finished, it cleared the previous timeout, but it never revoked the URL that timeout was supposed to clean up.

I was essentially abandoning blobs in the browser's memory with every keystroke.

The Breakthrough: Tracking the "Pending" URL

During code review, we realized we needed a way to revoke the "previously scheduled for revocation" URL if a new one came in early.

// components/pdf/pdf-viewer-client.tsx

const pendingRevokeUrlRef = useRef<string | null>(null);
const revokeTimeoutRef = useRef<NodeJS.Timeout | null>(null);

const handleRenderSuccess = () => {
  // 1. If there's a pending cleanup, do it NOW
  if (revokeTimeoutRef.current) {
    clearTimeout(revokeTimeoutRef.current);
    if (pendingRevokeUrlRef.current) {
      URL.revokeObjectURL(pendingRevokeUrlRef.current);
      pendingRevokeUrlRef.current = null;
    }
  }

  // 2. Schedule the next cleanup
  if (previousPdfUrl && previousPdfUrl !== pdfUrl) {
    pendingRevokeUrlRef.current = previousPdfUrl;
    revokeTimeoutRef.current = setTimeout(() => {
      if (pendingRevokeUrlRef.current) {
        URL.revokeObjectURL(pendingRevokeUrlRef.current);
        pendingRevokeUrlRef.current = null;
      }
    }, 1000);
  }
};

The Lesson: When working with manual memory management (like Blob URLs), always think about the "Rapid Update" scenario. If your cleanup is async (via setTimeout), you must ensure that no "in-flight" cleanups get discarded.

Chapter 5: Accessibility & UX Polish

With the core functionality working, code review flagged several accessibility and UX issues.

Issue 1: Missing ARIA Labels

The reorder buttons had title attributes for tooltips, but no aria-label for screen readers:

// ❌ Screen readers can't describe these buttons
<Button title="Move Up">
  <ChevronUp />
</Button>

The fix:

// ✅ Both visual and screen reader support
<Button title="Move Up" aria-label="Move item up">
  <ChevronUp />
</Button>

Issue 2: End Date Fields Not Disabled

When users checked "Currently work here" or "Currently studying here", the end date field stayed enabled. Confusing UX.

The fix: watch the current field and disable endDate accordingly:

// components/profile-editor/sections/work-experience-section.tsx
{
  field.state.value.map((exp, index) => (
    <Card key={exp.id}>
      {/* ... other fields */}

      <form.AppField name={`workExperiences[${index}].current`}>
        {(currentField) => (
          <currentField.CheckboxField label="Currently work here" />
        )}
      </form.AppField>

      <form.AppField name={`workExperiences[${index}].endDate`}>
        {(dateField) => (
          <dateField.DateField
            label="End Date"
            disabled={exp.current} // Disabled when current = true
          />
        )}
      </form.AppField>
    </Card>
  ));
}

Applied the same pattern to:

Education section
Volunteer Experience section

Issue 3: Type Safety in Form Fields

The disabled prop was added inline with type intersections:

// ❌ Inconsistent pattern
export function TextField({
  label,
  placeholder,
  disabled,
}: TextFieldProps & { disabled?: boolean }) {
  // ...
}

Code review suggested moving disabled into the interface:

// ✅ Consistent, maintainable
interface TextFieldProps extends FormControlProps {
  placeholder?: string;
  type?: "text" | "email" | "password";
  autoComplete?: string;
  disabled?: boolean; // Now part of the interface
}

export function TextField({
  label,
  placeholder,
  type = "text",
  autoComplete,
  disabled,
}: TextFieldProps) {
  // ...
}

Applied to all form field components:

TextFieldProps
TextAreaFieldProps
SelectFieldProps
DateFieldProps

The Lesson: Accessibility isn't an afterthought. Add aria-label to icon-only buttons, disable fields that shouldn't be editable, and keep type definitions consistent.

Chapter 6: The Ghost of Transitions Past

I had a 300ms CSS transition for the PDF cross-fade. But it wasn't playing. The "Previous" document just vanished instantly.

Why?

I was updating the previousPdfUrl state immediately in handleRenderSuccess. React would see the update, re-render, and since the IDs didn't match the "previous" slot anymore, the old DOM elements were unmounted instantly.

An element that is unmounted cannot animate its fade-out.

The Fix: Coordination via Delay

I had to coordinate the React state update with the CSS transition duration.

// Delay updating the state to allow for the 300ms CSS transition
setTimeout(() => {
  previousPdfUrlRef.current = pdfUrl;
  setPreviousPdfUrl(pdfUrl);
}, 300); // Perfectly matches transition-opacity duration

The Lesson: Smooth transitions require the element to stay in the DOM for the duration of the animation. Sometimes, a tiny setTimeout in your state logic is the cleanest way to bridge the gap between "logical state" and "visual state."

TL;DR: From MVP to Production

Problem	Symptoms	Solution
DRY Violation	Duplicated button groups everywhere	Generic `ArrayFieldActions<T>` component
Index Keys	Focus loss & state bugs on reorder	Stable `id` generated in factory functions
Privacy Compliance	Collecting PII without consent	Consent checkbox + database flag + warnings
Accessibility	Screen readers can't describe buttons	`aria-label` on all icon-only buttons
Disabled State	End date editable when "current"	Watch `current` field, disable `endDate`
Type Safety	Inconsistent `disabled` prop pattern	Add `disabled` to interface, not inline
Uncaptured Refs	Cleanup not running on unmount	Capture values inside `useEffect` with refs
Rapid Blob Revocation	Memory leaks during typing	`pendingRevokeUrlRef` tracking
Instant Unmount	Transitions feel "janky"	Synchronize state updates with CSS durations

The Complete Commit History

For those who want to see the actual implementation:

78469bb - Add pendingRevokeUrlRef to track URLs scheduled for revocation
a9521c6 - Upgrade Next.js from 16.0.10 to 16.1.1
57bfef5 - Add revokeTimeoutRef to track pending URL revocations
f73b32b - Improve PDF viewer transition effects and fix cleanup
7d256f6 - Use item property for disabled state consistency
e1c05ca - Change Card keys from index to item.id for stable identity
7b145f9 - Add privacyConsent field to ResumeExtractionSchema
202e53c - Disable end date when current checkbox is checked
036daeb - Add privacy consent checkbox with disabled state
c456ebc - Replace type assertion with explicit default values
7bc6cbc - Add volunteer experience and hobbies sections
712977a - Refactor to use single AppField wrapper
3fb67fd - Extract ArrayFieldActions component
32de976 - Add reordering controls to all sections
405fc18 - Refactor StringArrayField to use TanStack Form helpers
2e3539e - Add reordering controls to StringArrayField

Every line of code is in the repo: github.com/ImAbdullahJan/carific.ai

Why Open Source?

This post covers 15+ commits over several hours of work. Array reordering, privacy compliance, accessibility fixes, memory leak debugging-none of it was straightforward.

If this post (or the code in Carific.ai) saves you even 30 minutes of debugging React keys, implementing GDPR consent flows, or fixing Blob URL race conditions, then the "Build in Public" experiment is working.

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If this helped you, consider starring the repo. It's the best way to support the project!

What's Next

🤖 Resume Intelligence: AI-powered bullet point optimization with industry-specific feedback
🎨 Theme Engine: Customizable fonts, colors, and layout templates
📊 ATS Scoring: Real-time compatibility checks for applicant tracking systems
🔐 Privacy Controls: Fine-grained control over which data is shared with AI models

Your Turn

I'd love feedback:

On array reordering: How do you handle reorderable lists in React? Any better patterns than TanStack Form's moveValue?
On privacy compliance: Have you implemented GDPR consent flows? What challenges did you face?
On memory leaks: Ever dealt with Blob URL race conditions? How did you debug them?
On accessibility: What accessibility tools do you use for testing?

Drop your thoughts in the comments. Let's learn together.

If this post helped you, drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan
🐦 Twitter/X: @Mr_AbdullahJan
👥 LinkedIn: abdullahjan

Seventh post of many. See you in the next one.

Carific.ai: Building a Flicker-Free PDF Viewer with React - The Dual-Document Pattern

Abdullah Jan — Sun, 21 Dec 2025 14:08:31 +0000

Sixth post in the Carific.ai series. Previous posts: Auth System, AI Resume Analyzer, Structured AI Output, Profile Editor Type Safety, and Domain Model Architecture.

The PDF preview flickered every time I typed. Not a subtle flicker - a full white flash that made the whole interface feel broken. Users would be editing their resume on the right, and the preview on the left would flash repeatedly like a broken fluorescent light.

This is the story of how I built a PDF viewer for Carific.ai using the dual-document pattern from react-pdf's official REPL, and how code review caught memory leaks I completely missed.

The entire codebase is MIT licensed. Every line of code in this post is live in the repo.

The Mission

I needed a live PDF preview that:

✅ Updates in real-time as users edit their resume
✅ No flickering during updates
✅ Zoom controls (50% to 300%)
✅ Multi-page navigation for longer resumes
✅ No memory leaks (blob URLs properly cleaned up)
✅ Production-ready performance

Sounds straightforward, right? The flickering alone took me down a rabbit hole that taught me more about React rendering than I expected.

The Stack (Actual Versions)

{
  "next": "16.0.10",
  "react": "19.2.3",
  "@react-pdf/renderer": "4.3.1",
  "react-pdf": "10.2.0",
  "pdfjs-dist": "5.4.449",
  "use-debounce": "10.0.6"
}

Chapter 1: The Flicker Problem

The Naive Approach

My first implementation was the obvious one-use @react-pdf/renderer's <PDFViewer> component:

// ❌ This flickers on every update
export function PDFViewerClient({ data }: PDFViewerClientProps) {
  const [debouncedData] = useDebounce(data, 500);

  const document = useMemo(
    () => <ResumeTemplate data={debouncedData} />,
    [debouncedData]
  );

  const viewerKey = JSON.stringify(debouncedData);

  return (
    <PDFViewer
      key={viewerKey} // Force remount on data changes
      style={{ width: "100%", height: "100%" }}
      showToolbar={false}
    >
      {document}
    </PDFViewer>
  );
}

The problem: Every time debouncedData changed, the entire PDFViewer component remounted. Full white screen, then the new PDF appeared. Terrible UX.

Why Force Remount?

I was using key={viewerKey} because without it, @react-pdf/renderer threw cryptic errors when the document structure changed:

Error: Minified React error #130
Eo is not a function

Not helpful. After digging through GitHub issues, I learned that @react-pdf/renderer's <PDFViewer> doesn't handle dynamic document updates well. The workaround? Force a complete remount with a changing key prop.

It worked, but the flicker was unacceptable. There had to be a better way.

Chapter 2: The Dual-Document Pattern

I found the solution in react-pdf's own REPL source code. They use a clever pattern: render two documents simultaneously during transitions.

How It Works

Keep the old PDF visible (at 50% opacity)
Render the new PDF invisibly (absolute positioned)
Wait for the new PDF to fully render
Swap atomically when ready

No white flash. No flicker. Just a smooth fade transition.

The Implementation

"use client";

import { useState, useEffect, useRef } from "react";
import { pdf } from "@react-pdf/renderer";
import { Document, Page, pdfjs } from "react-pdf";
import { useDebounce } from "use-debounce";

pdfjs.GlobalWorkerOptions.workerSrc = `//unpkg.com/pdfjs-dist@${pdfjs.version}/build/pdf.worker.min.mjs`;

export function PDFViewerClient({ data }: PDFViewerClientProps) {
  const [debouncedData] = useDebounce(data, 300);

  const [pdfUrl, setPdfUrl] = useState<string | null>(null);
  const [previousPdfUrl, setPreviousPdfUrl] = useState<string | null>(null);
  const [isRendering, setIsRendering] = useState(false);

  const pdfUrlRef = useRef<string | null>(null);
  const previousPdfUrlRef = useRef<string | null>(null);

  // Generate PDF blob URL
  useEffect(() => {
    let cancelled = false;
    let generatedUrl: string | null = null;
    let urlSetToState = false;

    const generatePdf = async () => {
      setIsRendering(true);
      setError(null);

      try {
        const blob = await pdf(
          <ResumeTemplate data={debouncedData} />
        ).toBlob();
        const objectUrl = URL.createObjectURL(blob);
        generatedUrl = objectUrl;

        if (!cancelled) {
          urlSetToState = true;
          setPdfUrl(() => {
            pdfUrlRef.current = objectUrl;
            return objectUrl;
          });
        } else {
          URL.revokeObjectURL(objectUrl);
        }
      } catch (err) {
        if (!cancelled) {
          console.error("PDF generation error:", err);
          setError(
            err instanceof Error ? err.message : "Failed to generate PDF"
          );
          setIsRendering(false);
        }
      }
    };

    generatePdf();

    return () => {
      cancelled = true;
      // Only revoke if URL was created but never set to state
      if (generatedUrl && !urlSetToState) {
        URL.revokeObjectURL(generatedUrl);
      }
    };
  }, [debouncedData]);

  const handleRenderSuccess = () => {
    setPreviousPdfUrl((prev) => {
      if (prev && prev !== pdfUrl) {
        setTimeout(() => URL.revokeObjectURL(prev), 500);
      }
      previousPdfUrlRef.current = pdfUrl;
      return pdfUrl;
    });
    setIsRendering(false);
  };

  const isFirstRender = !previousPdfUrl;
  const shouldShowPrevious =
    !isFirstRender && isRendering && previousPdfUrl !== pdfUrl;

  return (
    <div className="relative w-full h-full">
      {/* Previous PDF (faded) */}
      {shouldShowPrevious && previousPdfUrl && (
        <div className="opacity-50 transition-opacity duration-200">
          <Document file={previousPdfUrl} loading={null} error={null}>
            <Page
              pageNumber={currentPage}
              width={containerWidth * zoom}
              renderTextLayer={false}
              renderAnnotationLayer={false}
            />
          </Document>
        </div>
      )}

      {/* New PDF (invisible until ready) */}
      <div
        className={shouldShowPrevious ? "absolute top-0 left-0 right-0" : ""}
      >
        {pdfUrl && (
          <Document
            file={pdfUrl}
            loading={null}
            error={null}
            onLoadSuccess={handleDocumentLoadSuccess}
          >
            <Page
              pageNumber={currentPage}
              width={containerWidth * zoom}
              onRenderSuccess={handleRenderSuccess}
              renderTextLayer={true}
              renderAnnotationLayer={true}
            />
          </Document>
        )}
      </div>
    </div>
  );
}

The Magic Moment

The key is onRenderSuccess. This callback fires only when the new page is fully rendered. That's when we:

Move the current pdfUrl to previousPdfUrl
Set isRendering = false
The old document disappears, new one becomes visible

Zero flicker. Smooth as butter.

Chapter 3: Adding Zoom Controls

With the flicker solved, I added zoom functionality using shadcn/ui components:

import { Button } from "@/components/ui/button";
import { ButtonGroup } from "@/components/ui/button-group";
import { ZoomIn, ZoomOut, RotateCcw } from "lucide-react";

const [zoom, setZoom] = useState<number>(1);

const onZoomIn = () => setZoom((prev) => Math.min(prev + 0.25, 3));
const onZoomOut = () => setZoom((prev) => Math.max(prev - 0.25, 0.5));
const onResetZoom = () => setZoom(1);

return (
  <div className="flex items-center justify-between h-16 px-5 gap-3 bg-background border-t w-full">
    <ButtonGroup>
      <Button
        onClick={onZoomOut}
        disabled={zoom <= 0.5}
        title="Zoom Out"
        variant="outline"
        size="icon-sm"
      >
        <ZoomOut />
      </Button>

      <div className="flex items-center justify-center px-3 text-sm font-medium border-y bg-background min-w-[60px]">
        {Math.round(zoom * 100)}%
      </div>

      <Button
        onClick={onZoomIn}
        disabled={zoom >= 3}
        title="Zoom In"
        variant="outline"
        size="icon-sm"
      >
        <ZoomIn />
      </Button>

      <Button
        onClick={onResetZoom}
        disabled={zoom === 1}
        title="Reset Zoom"
        variant="outline"
        size="icon-sm"
      >
        <RotateCcw />
      </Button>
    </ButtonGroup>
  </div>
);

The zoom applies to both documents during transitions, maintaining the smooth effect.

Adding Page Navigation

For multi-page resumes, I added pagination controls:

const [numPages, setNumPages] = useState<number>(1);
const [currentPage, setCurrentPage] = useState<number>(1);

const handleDocumentLoadSuccess = ({ numPages }: { numPages: number }) => {
  setNumPages(numPages);
  setCurrentPage((prev) => Math.min(prev, numPages));
};

const onPreviousPage = () => {
  setCurrentPage((prev) => Math.max(prev - 1, 1));
};

const onNextPage = () => {
  setCurrentPage((prev) => Math.min(prev + 1, numPages));
};

return (
  <div className="flex items-center justify-between h-16 px-5 gap-3 bg-background border-t w-full">
    {/* Zoom controls */}
    <ButtonGroup>{/* ... zoom buttons ... */}</ButtonGroup>

    {/* Page navigation - only show for multi-page PDFs */}
    {numPages > 1 && (
      <ButtonGroup>
        <Button
          onClick={onPreviousPage}
          disabled={currentPage === 1}
          variant="outline"
          size="sm"
        >
          ← Previous
        </Button>

        <div className="flex items-center justify-center px-3 text-sm font-medium border-y bg-background">
          Page {currentPage} / {numPages}
        </div>

        <Button
          onClick={onNextPage}
          disabled={currentPage >= numPages}
          variant="outline"
          size="sm"
        >
          Next →
        </Button>
      </ButtonGroup>
    )}
  </div>
);

The onLoadSuccess callback from react-pdf gives us the total page count, and we track the current page in state.

Making It Responsive

The PDF needs to adapt to different screen sizes. I used ResizeObserver to dynamically adjust the width:

const containerRef = useRef<HTMLDivElement>(null);
const [containerWidth, setContainerWidth] = useState<number>(600);

useEffect(() => {
  if (!containerRef.current) return;

  const resizeObserver = new ResizeObserver((entries) => {
    for (const entry of entries) {
      const width = entry.contentRect.width;
      // Subtract padding, enforce minimum width
      setContainerWidth(Math.max(width - 40, 400));
    }
  });

  resizeObserver.observe(containerRef.current);
  return () => resizeObserver.disconnect();
}, []);

return (
  <div ref={containerRef} className="relative w-full h-full">
    {/* PDF renders at containerWidth * zoom */}
    <Page width={containerWidth * zoom} />
  </div>
);

Now the PDF scales smoothly when users resize their browser or switch between desktop and mobile.

Chapter 4: The Memory Leaks I Missed

After implementing the dual-document pattern, I thought I was done. Then code review happened.

Issue #1: Component Unmount Cleanup

The problem: When the component unmounts, pdfUrl and previousPdfUrl blob URLs aren't revoked.

// ❌ State values in cleanup capture initial values (null)
useEffect(() => {
  return () => {
    if (pdfUrl) URL.revokeObjectURL(pdfUrl); // Always null!
    if (previousPdfUrl) URL.revokeObjectURL(previousPdfUrl); // Always null!
  };
}, []);

Why this fails: Cleanup functions capture values from when the effect runs. Since the effect runs once on mount (empty dependency array), pdfUrl and previousPdfUrl are both null.

The fix: Use refs to track the latest URLs:

const pdfUrlRef = useRef<string | null>(null);
const previousPdfUrlRef = useRef<string | null>(null);

// Update refs whenever URLs change
setPdfUrl(() => {
  pdfUrlRef.current = objectUrl;
  return objectUrl;
});

// Cleanup with refs
useEffect(() => {
  return () => {
    if (pdfUrlRef.current) {
      URL.revokeObjectURL(pdfUrlRef.current);
    }
    if (previousPdfUrlRef.current) {
      URL.revokeObjectURL(previousPdfUrlRef.current);
    }
  };
}, []);

Refs always contain the latest value, making them perfect for cleanup.

Issue #2: Effect Cleanup Race Condition

The problem: When debouncedData changes rapidly, the effect cleanup revokes generatedUrl which might be the same URL that's now previousPdfUrl.

// ❌ Race condition
return () => {
  cancelled = true;
  if (generatedUrl) {
    URL.revokeObjectURL(generatedUrl); // Might still be in use!
  }
};

Timeline of the bug:

Generate PDF → generatedUrl = "blob:abc"
Set to state → pdfUrl = "blob:abc"
User types → effect cleanup runs
Cleanup revokes "blob:abc" ❌
But "blob:abc" is now previousPdfUrl and still rendering!
Error: ResponseException: Unexpected server response (0)

The Debugging Journey

This bug was tricky. I initially tried increasing the cleanup delay:

// ❌ First attempt - didn't work
setTimeout(() => URL.revokeObjectURL(prev), 500);

Still got errors. The problem wasn't timing-it was that I was revoking URLs that were actively in use. The error appeared randomly during rapid typing because it depended on the exact timing of effect cleanups vs. render cycles.

After adding console logs to track URL lifecycles, I realized the issue: the effect cleanup was running before the transition completed, revoking a URL that previousPdfUrl still needed.

The fix: Only revoke if the URL was never set to state:

let urlSetToState = false;

if (!cancelled) {
  urlSetToState = true;
  setPdfUrl(() => {
    pdfUrlRef.current = objectUrl;
    return objectUrl;
  });
}

return () => {
  cancelled = true;
  // Only revoke if URL was created but never used
  if (generatedUrl && !urlSetToState) {
    URL.revokeObjectURL(generatedUrl);
  }
};

This flag ensures we never revoke URLs that are actively being used in component state.

The Complete Memory Management Strategy

URL	Lifecycle	Cleanup Trigger	Delay
`generatedUrl` (unused)	Effect scope	Effect cleanup	Immediate
`generatedUrl` (used)	Effect scope	Never by effect	-
`pdfUrl`	Current render	Never during render	-
`previousPdfUrl`	Transition	After render success	500ms
All URLs	Component unmount	Unmount cleanup	Immediate

The Final Architecture

components/pdf/
├── pdf-preview.tsx          # Wrapper with download button
├── pdf-viewer-client.tsx    # Main viewer (284 lines)
└── resume-template.tsx      # PDF document template

Key Features:
✅ Dual-document rendering (no flicker)
✅ Zoom controls (50% - 300%)
✅ Multi-page navigation
✅ Responsive width with ResizeObserver
✅ Memory leak protection
✅ Error handling with user-friendly messages
✅ Loading states
✅ shadcn/ui integration

TL;DR - What I Learned

Problem	Solution
PDF flickers on updates	Dual-document pattern: render new PDF invisibly, swap when ready
When to show previous document	`!isFirstRender && isRendering && previousPdfUrl !== pdfUrl`
Blob URL cleanup on unmount	Use refs, not state values (closures capture initial values)
Effect cleanup race condition	Track `urlSetToState` flag, only revoke unused URLs
Smooth transitions	500ms delay before revoking old URLs
Debounce timing	300ms is optimal for typing without lag

Production Readiness Checklist

Before deploying, I verified:

✅ Test on different screen sizes (mobile, tablet, desktop)
✅ Test with large PDFs (10+ pages, complex layouts)
✅ Test error scenarios (invalid data, network issues)
✅ Verify zoom functionality (50% to 300% range)
✅ Check browser compatibility (Chrome, Firefox, Safari, Edge)
✅ Test rapid typing (debounce prevents excessive renders)
✅ Monitor memory usage (blob URLs cleaned up properly)
✅ Verify dark mode support

Why Open Source?

Building in public means showing the messy parts. The bugs I missed. The code review feedback that caught memory leaks. The refactors that made the code better.

Carific.ai is MIT licensed. That means:

✅ Use it in your projects
✅ Fork it and make it your own
✅ Learn from the code (and my mistakes)
✅ Contribute back if you want

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If you find this useful, consider starring the repo - it helps others discover the project!

What's Next for Carific.ai

The PDF viewer is just one piece. Here's what's coming:

🤖 AI-powered resume analysis - Actionable feedback on content, formatting, ATS compatibility
📊 Resume scoring - Industry-specific scoring with improvement suggestions
🎨 Multiple templates - Professional, creative, ATS-optimized designs
💾 Version history - Track changes and revert to previous versions

I'll be documenting each feature as I build it. Follow along if you want to see how an open-source project evolves.

Your Turn

I'd genuinely love feedback:

On the code: See something that could be better? Open an issue or PR.
On the post: Too technical? Missing something? Tell me.
On PDF rendering: What's your approach? Any war stories with blob URLs?

Building in public only works if there's a public to build with. Let's learn together.

If this post helped you, drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan - ⭐ Star the repo if you found this helpful!
🐦 Twitter/X: @abdullahjan - Follow for more dev content and project updates
👥 LinkedIn: abdullahjan - Let's connect

Sixth post of many. See you in the next one.

Carific.ai: Breaking the Type Hammer - Domain Model Architecture for Live PDF Preview

Abdullah Jan — Sat, 20 Dec 2025 05:52:20 +0000

This is my fifth dev.to post. Previous posts: Auth System, AI Resume Analyzer, Structured AI Output, and Profile Editor Type Safety.

const liveProfile = mergeFormValuesWithProfile(
  profile,
  values
) as unknown as FullProfile;

I stared at that line. as unknown as FullProfile. The "type hammer."

It worked. The PDF preview updated when users typed. But TypeScript had given up. I was lying to the compiler, and deep down, I knew this would bite me.

This is the story of how I refactored a working feature into something actually maintainable - introducing a Domain Model that decouples my PDF templates from both Prisma and TanStack Form. And a code review that taught me about React 19's stricter rules.

The Stack

Package	Version	Purpose
Next.js	16.0.10	App framework
React	19.2.3	UI library
TanStack Form	1.27.1	Type-safe form state
Zod	4.1.13	Schema validation & type source
@react-pdf/renderer	4.3.1	Live PDF generation
use-debounce	10.0.6	Debounce for performance

Chapter 1: The Problem with Coupling

The Mess I Had

My live PDF preview worked, but the architecture was fragile. The ResumeTemplate component expected a FullProfile - a type derived from Prisma:

// ❌ Tightly coupled to database structure
type FullProfile = NonNullable<Awaited<ReturnType<typeof getFullProfile>>>;

interface ResumeTemplateProps {
  profile: FullProfile;
}

This type included database metadata: id, createdAt, updatedAt, profileId. My templates didn't need any of that. But because the type demanded it, I had to fake it:

// ❌ The type hammer in action
const liveProfile = {
  ...profile,
  ...values,
  workExperiences: values.workExperiences.map((exp) => ({
    ...exp,
    startDate: exp.startDate ? new Date(exp.startDate) : null,
    endDate: exp.endDate ? new Date(exp.endDate) : null,
  })),
  // ... repeat for 6 more sections
} as unknown as FullProfile;

That as unknown as FullProfile was a red flag. I was telling TypeScript, "Trust me, this is a FullProfile" - even though it wasn't. Missing fields, wrong types, runtime crashes waiting to happen.

Why This Matters

No type safety - TypeScript couldn't catch missing or wrong fields
Tight coupling - Templates knew about database structure
Scaling nightmare - Adding new templates meant copying the same casting logic
Maintenance hell - Change the database schema, and who knows what breaks

Chapter 2: The Domain Model Solution

The Insight

The PDF template doesn't care where data comes from. It just needs to know:

What's the person's name?
What jobs did they have?
What skills do they have?

That's it. No id, no createdAt, no profileId. Just content.

Creating the Domain Model

I created a new file: lib/types/resume.ts. This defines what a "Resume" actually is in my application:

// lib/types/resume.ts

import { z } from "zod/v4";

// Define the schema FIRST
export const ResumeDataSchema = z.object({
  displayName: z.string(),
  headline: z.string().nullable(),
  email: z.string().nullable(),
  phone: z.string().nullable(),
  website: z.string().nullable(),
  location: z.string().nullable(),
  bio: z.string().nullable(),

  socialLinks: z.array(
    z.object({
      platform: z.string(),
      url: z.string(),
      label: z.string().nullable(),
    })
  ),

  workExperiences: z.array(
    z.object({
      company: z.string(),
      position: z.string(),
      location: z.string().nullable(),
      startDate: z.date().nullable(),
      endDate: z.date().nullable(),
      current: z.boolean(),
      bullets: z.array(z.string()),
    })
  ),

  // ... educations, projects, skills, etc.
});

// Derive the type FROM the schema
export type ResumeData = z.infer<typeof ResumeDataSchema>;

Key insight: No id fields. No database metadata. Just the content that appears on a resume.

The Transformation Layer

Now I needed functions to convert data sources to this domain model:

// lib/profile-transformation.ts

/**
 * Database Profile → Resume Domain Data
 */
export function profileToResume(profile: FullProfile): ResumeData {
  return {
    displayName: profile.displayName || "",
    headline: profile.headline,
    email: profile.email,
    // ... map all fields, stripping database metadata
    workExperiences: profile.workExperiences.map((exp) => ({
      company: exp.company,
      position: exp.position,
      // Notice: no id, no createdAt, no updatedAt
      startDate: exp.startDate,
      endDate: exp.endDate,
      current: exp.current,
      bullets: exp.bullets,
    })),
  };
}

/**
 * Form Values → Resume Domain Data
 */
export function formToResume(formValues: ProfileFormValues): ResumeData {
  return {
    displayName: formValues.displayName,
    headline: formValues.headline || null,
    // ... map all fields, converting strings to Dates
    workExperiences: formValues.workExperiences.map((exp) => ({
      company: exp.company,
      position: exp.position,
      startDate: exp.startDate ? new Date(exp.startDate) : null,
      endDate: exp.endDate ? new Date(exp.endDate) : null,
      current: exp.current,
      bullets: exp.bullets,
    })),
  };
}

Two data sources. One common output. No type hammers.

Refactoring the Template

Now the template only cares about ResumeData:

// components/pdf/resume-template.tsx

import type { ResumeData } from "@/lib/types/resume";

interface ResumeTemplateProps {
  data: ResumeData;  // ✅ Clean domain type, not database type
}

export function ResumeTemplate({ data }: ResumeTemplateProps) {
  return (
    <Document>
      <Page size="A4" style={styles.page}>
        <Text style={styles.name}>{data.displayName}</Text>
        {data.workExperiences.map((exp, index) => (
          <View key={index} style={styles.experienceItem}>
            {/* Notice: key={index} because ResumeData has no IDs */}
            <Text>{exp.position} at {exp.company}</Text>
          </View>
        ))}
      </Page>
    </Document>
  );
}

Why key={index}? The domain model doesn't have IDs because IDs are a database concern. In a PDF document (which is static and remounts on every change), index-based keys are perfectly safe.

The Profile Editor Update

Now the live preview is beautifully simple:

// components/profile-editor/profile-editor.tsx

<form.Subscribe selector={(state) => [state.values]}>
  {([values]) => {
    const resumeData = formToResume(values);  // ✅ Clean transformation
    return <PDFPreview profile={resumeData} />;
  }}
</form.Subscribe>

No more as unknown as FullProfile. TypeScript is happy. I'm happy.

Chapter 3: The Three-Layer Architecture

Here's what I ended up with:

┌─────────────────────────────────────────────────────────────┐
│                       DATA SOURCES                          │
├─────────────────────────────┬───────────────────────────────┤
│     Database (Prisma)       │      Form (TanStack)          │
│     FullProfile type        │      ProfileFormValues type   │
│     Has: id, createdAt...   │      Has: string dates        │
└──────────────┬──────────────┴───────────────┬───────────────┘
               │                              │
               ▼                              ▼
        profileToResume()              formToResume()
               │                              │
               └──────────────┬───────────────┘
                              ▼
               ┌──────────────────────────────┐
               │        DOMAIN MODEL          │
               │         ResumeData           │
               │   No IDs, no DB metadata     │
               │   Just content               │
               └──────────────┬───────────────┘
                              │
                              ▼
               ┌──────────────────────────────┐
               │         TEMPLATES            │
               │      ResumeTemplate          │
               │      FutureTemplate1         │
               │      FutureTemplate2         │
               └──────────────────────────────┘

Benefits:

Add 10 new templates without touching Prisma or form code
Change database schema without breaking templates
Form validation and template rendering are completely decoupled
TypeScript catches errors at compile time, not runtime

Chapter 4: The Code Review That Almost Broke Everything

The Performance Suggestion

During code review, I got feedback about a performance concern in the PDF viewer:

"Using JSON.stringify on the entire resume data object can be expensive. Consider using a revision counter instead."

The suggestion:

// Code review suggestion
const revisionRef = useRef(0);

useEffect(() => {
  revisionRef.current += 1;
}, [debouncedData]);

const viewerKey = `viewer-${revisionRef.current}`;

Smart thinking! JSON.stringify on every render does seem wasteful. I merged it.

React 19 Said No

Immediately hit this error:

Error: Cannot access refs during render

React refs are values that are not needed for rendering.
Refs should only be accessed outside of render...

React 19 enforces stricter rules. Reading revisionRef.current during render is now forbidden.

The Fix That Didn't Work

I tried moving to state:

const [revision, setRevision] = useState(0);

useEffect(() => {
  setRevision((r) => r + 1);
}, [debouncedData]);

const viewerKey = `viewer-${revision}`;

TypeScript was happy. React was happy. But the PDF crashed:

TypeError: Eo is not a function
    at PDFViewerClient

Why? The useEffect runs after render. So on the first render after data changes:

Data changes
Component renders with OLD key
@react-pdf/renderer tries to update with new data
💥 Internal reconciler crashes
THEN useEffect runs and updates the key
Too late

The Lesson: Correctness Over Micro-Optimization

I reverted to JSON.stringify:

// components/pdf/pdf-viewer-client.tsx

export function PDFViewerClient({ data }: PDFViewerClientProps) {
  const [debouncedData] = useDebounce(data, 500);

  const document = useMemo(
    () => <ResumeTemplate data={debouncedData} />,
    [debouncedData]
  );

  // Note: JSON.stringify on resume data (~50KB max) is acceptable;
  // more complex hashing would add unnecessary complexity.
  const viewerKey = JSON.stringify(debouncedData);

  return (
    <PDFViewer key={viewerKey} style={styles.viewer}>
      {document}
    </PDFViewer>
  );
}

For a resume-sized object (~10-50KB), JSON.stringify takes microseconds. The performance "problem" didn't exist. But the bugs from "optimizing" it did.

Sometimes the "slower" solution is the right one.

Chapter 5: Other Code Review Wins

Not all the suggestions broke things. Some were genuinely good:

1. Redundant `new Date()` Wrapper

// ❌ Before - redundant
export function formatDateForInput(date: Date | null): string {
  if (!date) return "";
  return new Date(date).toISOString().split("T")[0];
}

// ✅ After - simplified
export function formatDateForInput(date: Date | null): string {
  if (!date) return "";
  return date.toISOString().split("T")[0];
}

TypeScript already guarantees date is a Date. No need to wrap it again.

2. Explicit Defensive Date Handling

// ❌ Before - implicit defense
function formatDate(date: Date | null): string {
  if (!date) return "";
  const d = new Date(date);
  if (isNaN(d.getTime())) return "";
  return new Intl.DateTimeFormat("en-US", {
    month: "short",
    year: "numeric",
  }).format(d);
}

// ✅ After - explicit defense with comment
function formatDate(date: Date | null): string {
  if (!date) return "";
  // Defensive: handle string dates from API/JSON that may bypass type system at runtime
  const d = date instanceof Date ? date : new Date(date);
  if (isNaN(d.getTime())) return "";
  return new Intl.DateTimeFormat("en-US", {
    month: "short",
    year: "numeric",
  }).format(d);
}

The instanceof check makes the defensive intent explicit. Future developers will know why this code exists.

TL;DR

Problem	Solution
Type hammer (`as unknown as FullProfile`)	Domain Model (`ResumeData`) with transformation functions
Templates coupled to database types	Templates only know about `ResumeData`
Database IDs in PDF template keys	Use `index` - domain model has no IDs
`JSON.stringify` performance concern	Keep it - correctness > micro-optimization
React 19 ref access during render	Don't access refs during render, use state with `useEffect`
Redundant `new Date()` wrapper	Trust TypeScript, remove the wrapper

Key Lessons

1. Domain Models are worth the effort.

Creating a separate type for "what the resume contains" (vs "what Prisma returns") eliminated an entire category of bugs and made the codebase ready for multiple templates.

2. The "as unknown as" pattern is a code smell.

If you're casting through unknown, you've lost type safety. Step back and redesign.

3. React 19 is stricter about refs.

You can't read refs during render anymore. Use state if you need values during render.

4. Performance intuition can be wrong.

JSON.stringify on a small object is fast. Premature optimization introduced real bugs.

5. Code reviews are valuable, even when they're wrong.

The suggestion didn't work, but the discussion led to documenting why we use JSON.stringify and understanding React 19's new rules.

6. Make defensive code explicit.

If you're guarding against runtime type mismatches, add a comment. Future you will thank present you.

What's Next

Multiple resume templates - The domain model makes this trivial
Template preview gallery - Show all templates side by side
AI-powered suggestions - Use the resume analyzer to improve content inline
Public portfolio pages - Share resumes via URL

Why Open Source?

Every refactor, every bug fix, every "I can't believe that didn't work" moment - it's all in the repo.

If this post saves you from the "type hammer" pattern or helps you understand domain models, it was worth writing. Architecture decisions are the hardest to learn from tutorials - they need context and mistakes.

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If you find this useful, consider starring the repo - it helps others discover the project!

Key files from this post:

lib/types/resume.ts - The domain model
lib/profile-transformation.ts - Transformation functions
components/pdf/resume-template.tsx - Template using domain model
components/pdf/pdf-viewer-client.tsx - PDF viewer with debounce

Your Turn

I'd love feedback:

On the architecture: Is domain model overkill for your projects? When would you use it?
On the post: Did the diagrams help? Too much code?
On React 19: Have you hit the stricter ref rules?

Building in public only works if there's a public to build with.

If this post helped you, drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan - ⭐ Star the repo if you found this helpful!
🐦 Twitter/X: @abdullahjan - Follow for more dev content
👥 LinkedIn: abdullahjan - Let's connect

Fifth post of many. See you in the next one.

Building in public 4th post. Love to see feedback from the community.

Abdullah Jan — Thu, 18 Dec 2025 12:04:43 +0000

Abdullah Jan

Dec 18 '25

Carific.ai: Building a Type-Safe Profile Editor with TanStack Form, Zod, and Live PDF Preview

#typescript #react #nextjs #opensource

Comments 1

12 min read

Carific.ai: Building a Type-Safe Profile Editor with TanStack Form, Zod, and Live PDF Preview

Abdullah Jan — Thu, 18 Dec 2025 12:02:50 +0000

This is my fourth dev.to post. Previous posts: Auth System, AI Resume Analyzer, and Structured AI Output.

"TypeError: Cannot read properties of undefined (reading 'company')"

I stared at the error. The form worked fine with basic fields. But the moment I added dynamic arrays for work experience, education, and projects, TypeScript lost its mind.

The problem? I had types defined in three places: Prisma schema, Zod validation, and a manual types.ts file. They were already drifting apart.

This is the story of how I built a profile editor with 10+ dynamic sections, live PDF preview, and zero type duplication — using Zod as the single source of truth.

The Stack

Package	Version	Purpose
Next.js	16.0.10	App framework
React	19.2.3	UI library
TanStack Form	1.27.1	Type-safe form state
Zod	4.1.13	Schema validation & type source
@react-pdf/renderer	4.3.1	Live PDF generation
date-fns	4.1.0	Date formatting
react-day-picker	9.11.3	Calendar component

Chapter 1: The Type Duplication Problem

The Mess I Started With

When I first built the profile editor, I had types everywhere:

// ❌ types.ts - Manual type definitions
export interface WorkExperience {
  id?: string;
  company: string;
  position: string;
  // ... 8 more fields
}

// ❌ profile-update.ts - Zod schema (different structure!)
export const WorkExperienceSchema = z.object({
  id: z.string().optional(),
  company: z.string().min(1),
  position: z.string().min(1),
  // ... slightly different validation
});

// ❌ Prisma schema - Yet another definition
model WorkExperience {
  id        String @id
  company   String
  position  String
  // ... database-specific fields
}

Three sources of "truth." When I added location to the Prisma schema, I forgot to add it to types.ts. The form silently dropped the field. Two hours of debugging later, I found it.

The Fix: Zod as Single Source of Truth

The solution was obvious in hindsight: derive all types from Zod schemas.

// lib/validations/profile-update.ts

// Define the schema ONCE
export const WorkExperienceSchema = z.object({
  id: z.string().optional(),
  company: z.string().min(1, "Company name is required"),
  position: z.string().min(1, "Position is required"),
  location: z.string().optional(),
  startDate: z.string().optional(),
  endDate: z.string().optional(),
  current: z.boolean().default(false),
  bullets: z.array(z.string()).default([]),
});

// Derive the type FROM the schema
export type WorkExperienceInput = z.infer<typeof WorkExperienceSchema>;

Now there's exactly one place to update. Add a field to the schema, and TypeScript immediately tells you everywhere that needs updating.

I deleted the redundant types.ts file entirely. One less thing to maintain.

The Form Values Type

For the form, I needed a slightly different type — one where all optional fields have default values (empty strings, not undefined):

// Form values type - matches actual form state
export type ProfileFormValues = {
  displayName: string;
  headline: string;
  email: string;
  // ... all strings, no undefined
  workExperiences: Required<WorkExperienceInput>[];
  educations: Required<EducationInput>[];
  // ... all arrays with Required<T>
};

This ensures the form always has values to work with. No more "cannot read property of undefined."

Chapter 2: Dynamic Array Fields That Don't Suck

The Problem with Array Forms

TanStack Form handles arrays beautifully with mode="array". But I kept writing the same boilerplate:

// ❌ Repetitive pattern in every section
<form.Field name="workExperiences" mode="array">
  {(field) => (
    <>
      <Button onClick={() => field.pushValue(createEmpty())}>Add</Button>
      {field.state.value.map((item, index) => (
        <div key={item.id}>
          <form.Field name={`workExperiences[${index}].company`}>
            {(subField) => <Input value={subField.state.value} ... />}
          </form.Field>
          {/* 10 more fields... */}
        </div>
      ))}
    </>
  )}
</form.Field>

The pattern was fine, but I had 10 sections: work experience, education, projects, skills, certifications, languages, achievements, social links, volunteer experience, and hobbies.

The Solution: `withForm` HOC + Card Headers with Item Numbers

TanStack Form's withForm higher-order component lets you create pre-typed section components. I also added card headers with item numbers for better UX — users can easily identify which experience they're editing:

// components/profile-editor/sections/work-experience-section.tsx

import { withForm } from "@/hooks/form";
import {
  type ProfileFormValues,
  createEmptyWorkExperience,
} from "@/lib/validations/profile-update";

export const WorkExperienceSection = withForm({
  defaultValues: {} as ProfileFormValues,
  render: function Render({ form }) {
    return (
      <div className="space-y-4">
        <div className="flex items-center justify-between">
          <h3 className="text-md font-medium">Work Experience</h3>
          <form.Field name="workExperiences" mode="array">
            {(field) => (
              <Button
                type="button"
                variant="outline"
                size="sm"
                onClick={() => field.pushValue(createEmptyWorkExperience())}
              >
                <Plus className="h-4 w-4 mr-1" />
                Add Experience
              </Button>
            )}
          </form.Field>
        </div>

        <form.Field name="workExperiences" mode="array">
          {(field) => (
            <div className="space-y-4">
              {field.state.value.map((workExperience, index) => (
                <Card key={workExperience.id}>
                  <CardHeader>
                    <div className="flex items-center justify-between">
                      <CardTitle className="text-sm font-medium">
                        Experience {index + 1}
                      </CardTitle>
                      <Button
                        type="button"
                        variant="ghost"
                        size="sm"
                        onClick={() => field.removeValue(index)}
                      >
                        <Trash2 className="h-4 w-4 text-destructive" />
                      </Button>
                    </div>
                  </CardHeader>
                  <CardContent>
                    {/* Fields here */}
                  </CardContent>
                </Card>
              ))}
            </div>
          )}
        </form.Field>
      </div>
    );
  },
});

The key insight: defaultValues: {} as ProfileFormValues gives TypeScript the type information it needs. Now form.AppField name="workExperiences[${index}].company" is fully typed.

Factory Functions for New Items

Each array type needs a factory function that returns a complete object with all required fields:

// lib/validations/profile-update.ts

export const createEmptyWorkExperience = (): Required<WorkExperienceInput> => ({
  id: crypto.randomUUID(),
  company: "",
  position: "",
  location: "",
  startDate: "",
  endDate: "",
  current: false,
  bullets: [],
});

Using crypto.randomUUID() for IDs ensures React's key prop is stable and unique, even for items that haven't been saved to the database yet.

Chapter 3: Custom Field Components

The StringArrayField Component

Work experience bullets, education highlights, project features — they're all arrays of strings. Instead of building custom UI for each, I created a reusable StringArrayField:

// components/form/form-fields.tsx

export function StringArrayField({
  label,
  description,
  placeholder = "Enter item...",
  addButtonText = "Add Item",
}: StringArrayFieldProps) {
  const field = useFieldContext<string[]>();
  const items = field.state.value ?? [];

  const addItem = () => {
    field.handleChange([...items, ""]);
  };

  const removeItem = (index: number) => {
    field.handleChange(items.filter((_, i) => i !== index));
  };

  const updateItem = (index: number, value: string) => {
    const newItems = [...items];
    newItems[index] = value;
    field.handleChange(newItems);
  };

  return (
    <Field>
      <FieldContent>
        <div className="flex items-center justify-between">
          <FieldLabel>{label}</FieldLabel>
          <Button type="button" variant="ghost" size="sm" onClick={addItem}>
            <Plus className="h-3 w-3 mr-1" />
            {addButtonText}
          </Button>
        </div>
      </FieldContent>
      <div className="space-y-2">
        {items.map((item, index) => (
          <div key={index} className="flex items-center gap-2">
            <span className="text-muted-foreground text-xs w-5">
              {index + 1}.
            </span>
            <Input
              value={item}
              onChange={(e) => updateItem(index, e.target.value)}
              onBlur={field.handleBlur}
              placeholder={placeholder}
              className="flex-1"
            />
            <Button
              type="button"
              variant="ghost"
              size="sm"
              onClick={() => removeItem(index)}
            >
              <Trash2 className="h-4 w-4 text-destructive" />
            </Button>
          </div>
        ))}
        {items.length === 0 && (
          <p className="text-sm text-muted-foreground italic">
            No items yet. Click "{addButtonText}" to add one.
          </p>
        )}
      </div>
    </Field>
  );
}

Now adding bullet points to work experience is one line:

<form.AppField name={`workExperiences[${index}].bullets`}>
  {(subField) => (
    <subField.StringArrayField
      label="Key Responsibilities & Achievements"
      placeholder="Describe a responsibility or achievement..."
      addButtonText="Add Bullet"
    />
  )}
</form.AppField>

The DateField with shadcn Calendar

Native date inputs are ugly and inconsistent across browsers. I replaced them with shadcn's Calendar component:

// components/form/form-fields.tsx

export function DateField({
  label,
  description,
  placeholder = "Pick a date",
}: DateFieldProps) {
  const field = useFieldContext<string>();

  // Convert string (yyyy-MM-dd) to Date for Calendar
  const dateValue = field.state.value
    ? parse(field.state.value, "yyyy-MM-dd", new Date())
    : undefined;
  const isValidDate = dateValue && !isNaN(dateValue.getTime());

  const handleSelect = (date: Date | undefined) => {
    if (date) {
      field.handleChange(format(date, "yyyy-MM-dd"));
    } else {
      field.handleChange("");
    }
  };

  return (
    <FormBase label={label} description={description}>
      <Popover>
        <PopoverTrigger asChild>
          <Button
            variant="outline"
            className={cn(
              "w-full justify-start text-left font-normal",
              !field.state.value && "text-muted-foreground"
            )}
          >
            <CalendarIcon className="mr-2 h-4 w-4" />
            {isValidDate ? format(dateValue, "PPP") : placeholder}
          </Button>
        </PopoverTrigger>
        <PopoverContent className="w-auto p-0" align="start">
          <Calendar
            mode="single"
            selected={dateValue}
            onSelect={handleSelect}
            autoFocus
          />
        </PopoverContent>
      </Popover>
    </FormBase>
  );
}

The isValidDate check is crucial. Without it, malformed date strings (from bad data or migrations) would crash the component with "Invalid Date."

Chapter 4: Consolidating PDF Preview Components

The Duplication Problem

I had two components doing similar things:

ResumeViewer — A standalone PDF viewer with download
ProfileEditor — Had its own PDF preview logic embedded

Both had duplicate code for the download button, loading states, and PDF rendering. When I fixed a bug in one, I'd forget to fix it in the other.

The Solution: Shared `PDFPreview` Component

I extracted the common logic into a reusable PDFPreview component:

// components/pdf/pdf-preview.tsx

const PDFViewerClient = dynamic(
  () => import("./pdf-viewer-client").then((mod) => mod.PDFViewerClient),
  {
    ssr: false,
    loading: () => (
      <div
        className="flex items-center justify-center bg-muted"
        style={{ height: "calc(100vh - 180px)" }}
      >
        <Loader2 className="h-8 w-8 animate-spin mx-auto text-muted-foreground" />
        <p className="text-muted-foreground">Loading PDF viewer...</p>
      </div>
    ),
  }
);

export function PDFPreview({
  profile,
  title = "Resume Preview",
  showDownload = true,
  height = "calc(100vh - 180px)",
}: PDFPreviewProps) {
  const [isDownloading, setIsDownloading] = useState(false);

  const handleDownload = async () => {
    setIsDownloading(true);
    try {
      const blob = await pdf(<ResumeTemplate profile={profile} />).toBlob();
      const url = URL.createObjectURL(blob);
      const link = document.createElement("a");
      link.href = url;
      link.download = `${profile.displayName?.replace(/\s+/g, "_") || "resume"}_resume.pdf`;
      document.body.appendChild(link);
      link.click();
      document.body.removeChild(link);
      URL.revokeObjectURL(url);
      toast.success("Resume downloaded successfully");
    } catch (error) {
      console.error("Failed to generate PDF:", error);
      toast.error("Failed to generate PDF. Please try again.");
    } finally {
      setIsDownloading(false);
    }
  };

  return (
    <div className="flex flex-col gap-4 h-full">
      <div className="flex items-center justify-between">
        <h2 className="text-lg font-semibold">{title}</h2>
        {showDownload && (
          <Button
            variant="outline"
            size="sm"
            onClick={handleDownload}
            disabled={isDownloading}
          >
            {isDownloading ? (
              <>
                <Loader2 className="h-4 w-4 mr-2 animate-spin" />
                Generating...
              </>
            ) : (
              <>
                <Download className="h-4 w-4 mr-2" />
                Download PDF
              </>
            )}
          </Button>
        )}
      </div>
      <Card className="flex-1 overflow-hidden py-1">
        <CardContent className="p-0" style={{ height }}>
          <PDFViewerClient profile={profile} />
        </CardContent>
      </Card>
    </div>
  );
}

Custom Download vs PDFDownloadLink

I considered using @react-pdf/renderer's built-in PDFDownloadLink component, but went with custom logic because:

Better UX — Custom loading states and toast notifications
Error handling — Graceful fallback when PDF generation fails
Filename control — Dynamic filename based on user's name
Consistent styling — Matches the rest of the UI

After consolidating, I deleted resume-viewer.tsx and moved EmptyProfileState to its own file in the profile-editor directory. One less component to maintain.

Chapter 5: Live PDF Preview (And the Bug That Almost Broke It)

The Architecture

The profile editor has a split-screen layout: form on the right, live PDF preview on the left. When you save changes, the PDF updates immediately.

// components/profile-editor/profile-editor.tsx

export function ProfileEditor({ profile }: ProfileEditorProps) {
  const router = useRouter();

  const form = useAppForm({
    defaultValues: profileToFormValues(profile),
    onSubmit: async ({ value }) => {
      const response = await fetch("/api/profile", {
        method: "PUT",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(value),
      });

      if (!response.ok) {
        throw new Error("Failed to update profile");
      }

      toast.success("Profile updated successfully");
      router.refresh(); // Revalidate server data
    },
  });

  return (
    <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
      {/* Left Side - PDF Preview */}
      <PDFPreview profile={profile} height="calc(100vh - 180px)" />

      {/* Right Side - Edit Form */}
      <div className="flex flex-col gap-4">{/* Form content */}</div>
    </div>
  );
}

The "Eo is not a function" Bug

After implementing router.refresh() to update the PDF preview, I hit a cryptic error:

TypeError: Eo is not a function
    at PDFViewerClient (components/pdf/pdf-viewer-client.tsx:15:5)

This is a known bug in @react-pdf/renderer. When the PDF document tree changes (sections added/removed), the internal reconciler crashes instead of gracefully updating. I found multiple GitHub issues describing the same problem.

The Fix: Force Remount on Data Change

The solution is to force the PDFViewer to completely remount when the profile changes, instead of trying to update in place:

// components/pdf/pdf-viewer-client.tsx

export function PDFViewerClient({ profile }: PDFViewerClientProps) {
  // Use updatedAt as a key to force remount on changes
  const profileKey = profile.updatedAt.toISOString();

  return (
    <PDFViewer
      key={profileKey}
      style={{
        width: "100%",
        height: "calc(100vh - 180px)",
        border: "none",
      }}
      showToolbar={false}
    >
      <ResumeTemplate key={profileKey} profile={profile} />
    </PDFViewer>
  );
}

By using profile.updatedAt as the key, React treats it as a completely new component when the timestamp changes. The old PDFViewer unmounts, a fresh one mounts, and the bug never triggers.

Why `router.refresh()` Instead of State

My first attempt used a previewKey state variable:

// ❌ Before - stale data
const [previewKey, setPreviewKey] = useState(0);

// In onSubmit:
setPreviewKey((prev) => prev + 1);

This re-rendered the component but with stale props. The profile data came from the server, and incrementing a key didn't fetch fresh data.

// ✅ After - fresh server data
router.refresh();

router.refresh() triggers Next.js to revalidate the page's server data, ensuring the PDF preview shows the actual saved values.

Chapter 6: Production Readiness Fixes

Before shipping, I did a thorough code review and caught several issues:

1. SelectField Missing `onBlur`

// ❌ Before - validation errors don't show
<Select
  value={field.state.value}
  onValueChange={(value) => field.handleChange(value)}
>

// ✅ After - triggers validation on change
<Select
  value={field.state.value}
  onValueChange={(value) => {
    field.handleChange(value);
    field.handleBlur(); // Mark as touched
  }}
>

Without handleBlur(), the field never gets marked as "touched," so validation errors don't appear until form submission. Users had no idea their selection was invalid.

2. DateField Crash on Malformed Data

// ❌ Before - crashes on invalid dates
const dateValue = parse(field.state.value, "yyyy-MM-dd", new Date());
return format(dateValue, "PPP"); // 💥 "Invalid Date"

// ✅ After - graceful fallback
const dateValue = field.state.value
  ? parse(field.state.value, "yyyy-MM-dd", new Date())
  : undefined;
const isValidDate = dateValue && !isNaN(dateValue.getTime());

return isValidDate ? format(dateValue, "PPP") : placeholder;

Edge cases matter. Bad data from imports or migrations shouldn't crash the entire form.

3. Missing Fields in Section Components

During the review, I found that some section components were missing fields that existed in the Zod schema:

EducationSection was missing the location field
CertificationsSection was missing credentialUrl

This is exactly why Zod as single source of truth matters — but you still have to render all the fields!

The Final Architecture

components/
├── form/
│   ├── form-base.tsx          # Field wrapper (label, error, description)
│   ├── form-fields.tsx        # TextField, DateField, StringArrayField, etc.
│   └── form-components.tsx    # SubmitButton
├── pdf/
│   ├── pdf-preview.tsx        # Shared wrapper with download button
│   ├── pdf-viewer-client.tsx  # PDFViewer with remount fix
│   └── resume-template.tsx    # ATS-compliant PDF template
└── profile-editor/
    ├── profile-editor.tsx     # Main component with tabs
    ├── empty-profile-state.tsx # Shown when no profile exists
    └── sections/
        ├── basic-info-section.tsx
        ├── work-experience-section.tsx
        ├── education-section.tsx
        ├── skills-section.tsx
        ├── projects-section.tsx
        ├── certifications-section.tsx
        ├── languages-section.tsx
        ├── achievements-section.tsx
        └── social-links-section.tsx

lib/
└── validations/
    └── profile-update.ts      # Zod schemas + inferred types + factory functions

hooks/
├── form.tsx                   # useAppForm, withForm
└── form-context.tsx           # TanStack Form contexts

TL;DR

Problem	Solution
Type definitions in 3 places	Zod schemas as single source, `z.infer<>` for types
Repetitive array field boilerplate	`withForm` HOC + reusable section components
String arrays (bullets, highlights)	Custom `StringArrayField` component
Ugly native date inputs	shadcn Calendar with Popover
Duplicate PDF preview code	Shared `PDFPreview` component
PDF crashes on data change	Force remount with `key={updatedAt}`
Stale PDF after save	`router.refresh()` for server revalidation
SelectField validation not showing	Add `handleBlur()` to `onValueChange`
DateField crash on bad data	`isValidDate` check before formatting

Key Lessons

1. Zod is more than validation.

Using z.infer<typeof Schema> eliminates an entire category of bugs. One schema, one type, zero drift. Delete your types.ts file.

2. Factory functions prevent undefined errors.

createEmptyWorkExperience() returns a complete object with all fields. No more "cannot read property of undefined."

3. @react-pdf/renderer has quirks.

The "Eo is not a function" error is a known issue with dynamic content. Force remounting with a key prop is the workaround.

4. Consolidate duplicate code early.

I had PDF preview logic in two places. When I fixed a bug in one, I forgot the other. Extract shared components before this happens.

5. router.refresh() is powerful.

It revalidates server data without a full page reload. Perfect for updating previews after mutations.

6. Edge cases crash production.

Invalid dates, missing fields, malformed data — test with bad inputs, not just happy paths.

What's Next

Form validation feedback — Show inline errors as users type
Autosave — Debounced saves to prevent data loss
Resume templates — Multiple PDF layouts to choose from
AI-powered suggestions — Use the resume analyzer to suggest improvements inline

Why Open Source?

Every refactor, every bug fix, every "I can't believe I missed that" moment — it's all in the repo.

Building forms with dynamic arrays is hard. Building them with type safety is harder. If this post saves you from the "Eo is not a function" rabbit hole or helps you structure your Zod schemas better, it was worth writing.

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If you find this useful, consider starring the repo — it helps others discover the project!

Key files from this post:

lib/validations/profile-update.ts — Zod schemas and factory functions
hooks/form.tsx — TanStack Form setup with custom components
components/form/form-fields.tsx — All reusable field components
components/profile-editor/ — The complete profile editor
components/pdf/pdf-preview.tsx — Shared PDF preview component
components/pdf/pdf-viewer-client.tsx — PDF viewer with remount fix

Your Turn

I'd love feedback:

On the code: See something that could be better? Open an issue or PR.
On the post: Too long? Missing something? Tell me.
On forms: How do you handle complex forms with dynamic arrays?

Building in public only works if there's a public to build with.

If this post helped you, drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan — ⭐ Star the repo if you found this helpful!
🐦 Twitter/X: @abdullahjan — Follow for more dev content
👥 LinkedIn: abdullahjan — Let's connect

Fourth post of many. See you in the next one.

Carific.ai: From AI Slop to Actionable Feedback - Structured Output with Zod and the AI SDK

Abdullah Jan — Thu, 11 Dec 2025 06:44:17 +0000

This is my third dev.to post. If you missed the previous ones: Building the Auth System and Building the AI Resume Analyzer.

"Spearheaded cross-functional initiatives to leverage synergies..."

That's what my AI resume analyzer suggested. I stared at the screen, realizing I'd built exactly what I was trying to help users avoid: generic, buzzword-filled nonsense.

The resume analyzer worked. It streamed markdown. It looked impressive. But when I asked myself "Would I actually use this feedback?" - the answer was no.

This is the story of how I rebuilt the entire output system to be genuinely useful.

The Stack

Package	Version	Purpose
Next.js	16.0.7	App framework
AI SDK	5.0.108	`generateObject` for structured output
Zod	4.1.13	Schema validation
Lucide React	0.555.0	Icons
Sonner	2.0.7	Toast notifications

Chapter 1: The Problem with Streaming Markdown

The first version of the resume analyzer used streamText from the AI SDK. It worked like this:

// ❌ The old approach
const result = await streamText({
  model: MODEL,
  system: SYSTEM_PROMPT,
  prompt: `Analyze this resume...`,
});

return result.toTextStreamResponse();

The frontend would receive chunks of markdown and render them progressively. Cool demo. Terrible UX.

Problems:

No structure - The AI could return anything. Sometimes bullet points, sometimes paragraphs, sometimes a mix.
No copy functionality - Users couldn't easily copy suggested improvements.
No persistence - Can't save unstructured markdown to a database meaningfully.
Generic advice - "Add more metrics to your bullet points" tells users nothing actionable.

The breaking point was when I tested it with my own resume. The AI suggested "Ready-to-Use Bullet Points" that had nothing to do with my actual experience. Where was I supposed to put them? The AI didn't say.

Chapter 2: The Switch to Structured Output

The AI SDK has a generateObject function that returns typed JSON validated against a Zod schema. This was the fix.

// ✅ The new approach
// lib/ai/resume-analyzer.ts

import { generateObject } from "ai";
import { ResumeAnalysisOutputSchema } from "@/lib/validations/resume-analysis";

export async function analyzeResume({ resumeText, jobDescription }) {
  const { object } = await generateObject({
    model: "google/gemini-2.5-flash-lite",
    schema: ResumeAnalysisOutputSchema,
    system: RESUME_ANALYSIS_SYSTEM_PROMPT,
    prompt: `Analyze this resume against the job description...`,
  });

  return object;
}

The schema defines exactly what the AI must return:

// lib/validations/resume-analysis.ts

export const ResumeAnalysisOutputSchema = z.object({
  score: z.number().min(0).max(100),
  scoreLabel: z.enum(["Poor", "Fair", "Good", "Strong", "Excellent"]),
  scoreSummary: z.string(),

  missingKeywords: z.array(MissingKeywordSchema).min(1),
  bulletFixes: z.array(BulletFixSchema),
  priorityActions: z.array(z.string()).min(1).max(3),
  sectionFeedback: z.array(SectionFeedbackSchema).length(5),
  lengthAssessment: z.object({
    currentLength: z.enum(["Too Short", "Appropriate", "Too Long"]),
    recommendation: z.string(),
  }),
});

Now the AI can't return random markdown. It must fill every field, and Zod validates the response before it reaches the frontend.

Chapter 3: Making Feedback Actually Actionable

Having structured output was step one. But the content still needed work.

The "Before/After" Bullet Fix

The old approach: "Here are some sample bullet points you could use."

The problem: Users don't know where to put them or how they relate to their actual resume.

The fix: Find weak bullets in the user's resume and show exactly how to improve them.

export const BulletFixSchema = z.object({
  location: z
    .string()
    .describe(
      "Where this bullet is, e.g. 'Experience → Acme Corp → 2nd bullet'"
    ),
  original: z.string().describe("The exact text from the user's resume"),
  improved: z.string().describe("The suggested replacement"),
  reason: z.string().describe("Why this helps - reference job requirements"),
  impact: z.enum(["High", "Medium"]),
});

The prompt enforces this:

### Bullet Fixes
- original: Exact text from the resume (must match verbatim)
- improved: Rewritten with action verb, metrics, and relevance to job

Rules:
- original must be text that exists in the resume
- Target vague phrases: "Responsible for", "Worked on", "Helped with"

Now users see their actual bullet point, the improved version, and a copy button. No guessing.

Killing AI Slop

The first improved bullet started with "Spearheaded." Classic AI resume speak.

I added explicit rules to the prompt:

- DO NOT use these overused words: Spearheaded, Leveraged, Synergy,
  Utilize, Facilitated, Orchestrated, Pioneered, Revolutionized,
  Streamlined, Championed
- Use plain, professional verbs: Led, Built, Created, Reduced,
  Increased, Managed, Designed, Developed, Improved, Launched

And for the overall tone:

## Writing Style
- Direct and concise
- No filler phrases ("I'd recommend", "You might consider")
- No exclamation marks
- State facts, not opinions

The output now reads like feedback from a senior colleague, not a chatbot.

Chapter 4: Skill Gap Categorization

Missing keywords were originally a flat list. "Docker, Leadership, HIPAA, Python" - all treated the same.

But these require completely different actions:

Docker - I can learn this in a weekend
Leadership - I need to reframe existing experience
HIPAA - Either I have compliance experience or I don't

So I added categorization:

export const MissingKeywordSchema = z.object({
  keyword: z.string(),
  category: z.enum(["Hard Skill", "Soft Skill", "Domain"]),
  importance: z.enum(["Critical", "Important", "Nice to Have"]),
  whereToAdd: z.string(),
});

The UI now groups keywords by category with actionable descriptions:

const CATEGORY_CONFIG = {
  "Hard Skill": {
    icon: Wrench,
    label: "Hard Skills",
    description: "Learnable, measurable skills you can add",
  },
  "Soft Skill": {
    icon: Users,
    label: "Soft Skills",
    description: "Reframe existing experience to highlight these",
  },
  Domain: {
    icon: BookOpen,
    label: "Domain Knowledge",
    description: "Industry-specific expertise",
  },
};

Users immediately understand: "I'm missing 3 hard skills I can learn, 1 soft skill I need to reframe, and 2 domain areas where I might not be a fit."

Chapter 5: Section Completeness & Length Assessment

Two more features that add real value:

Section Feedback

Check if standard resume sections exist and are complete:

export const SectionFeedbackSchema = z.object({
  section: z.enum(["Contact", "Summary", "Experience", "Education", "Skills"]),
  status: z.enum(["Present", "Missing", "Incomplete"]),
  feedback: z.string(),
});

The UI only shows sections with issues - if everything is present, this card doesn't appear.

Length Assessment

lengthAssessment: z.object({
  currentLength: z.enum(["Too Short", "Appropriate", "Too Long"]),
  recommendation: z.string(),
}),

The prompt includes context:

- Entry-level (0-2 years): 1 page ideal
- Mid-level (3-7 years): 1-2 pages
- Senior (8+ years): 2 pages acceptable

Again, only shown if there's an issue. No noise.

The Final Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Resume Analyzer Flow                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  1. User uploads PDF + pastes job description                │
│                    ↓                                         │
│  2. Zod validates input (ResumeAnalysisSchema)               │
│                    ↓                                         │
│  3. generateObject() calls AI with structured schema         │
│                    ↓                                         │
│  4. AI returns typed JSON (ResumeAnalysisOutputSchema)       │
│                    ↓                                         │
│  5. Frontend renders typed components                        │
│     - PriorityActions (what to do first)                     │
│     - BulletFixes (before/after with copy)                   │
│     - MissingKeywords (grouped by category)                  │
│     - SectionFeedback (only if issues)                       │
│     - LengthAssessment (only if issues)                      │
│     - ScoreCard (de-emphasized at bottom)                    │
│                                                              │
└─────────────────────────────────────────────────────────────┘

TL;DR

Problem	Solution
Unstructured markdown output	`generateObject` with Zod schema
Generic "sample bullets"	Before/after fixes on actual resume content
AI buzzwords ("Spearheaded")	Explicit banned word list in prompt
Flat keyword list	Categorized: Hard Skill / Soft Skill / Domain
Information overload	Only show sections with issues
Vague advice	Specific locations: "Add to Skills section"

Key Lessons

1. Structured output changes everything.

generateObject + Zod means the AI can't return garbage. Every field is validated. The frontend knows exactly what to expect.

2. "Actionable" means specific.

"Add more metrics" is useless. "Change your 2nd bullet at Acme Corp from X to Y because the job requires Z" is actionable.

3. Ban the slop explicitly.

LLMs default to resume-speak. You have to explicitly tell them not to use "Spearheaded" and friends.

4. Show less, not more.

If sections are complete, don't show the section feedback card. If length is appropriate, don't mention it. Every piece of UI should require action.

5. Categorization adds context.

A flat list of missing keywords is overwhelming. Grouping by Hard Skill / Soft Skill / Domain tells users what kind of gap they're dealing with.

What's Next

ATS compatibility check - Analyze the PDF structure, not just text
Save analysis history - Now that output is structured, we can persist it

Why Open Source?

Every iteration, every refactor - it's all in the repo. Not because I'm proud of the first "Spearheaded" output, but because someone else is probably fighting the same battle with AI slop right now.

If this post saves you from shipping generic AI advice to your users, it was worth writing.

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If you find this useful, consider starring the repo - it helps others discover the project!

Key files from this post:

lib/ai/resume-analyzer.ts - AI integration with structured output
lib/validations/resume-analysis.ts - Zod schemas
components/analysis/ - All the UI components

Your Turn

I'd love feedback:

On the code: See something that could be better? Open an issue or PR.
On the post: Too long? Missing something? Tell me.
On AI features: How do you handle structured output in your projects?

Building in public only works if there's a public to build with.

If this post helped you, drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan - ⭐ Star the repo if you found this helpful!
🐦 Twitter/X: @abdullahjan - Follow for more dev content
👥 LinkedIn: abdullahjan - Let's connect

Third post of many. See you in the next one.

Carific.ai: Building a Streaming AI Feature in Next.js 16 with the Vercel AI SDK

Abdullah Jan — Tue, 09 Dec 2025 16:30:49 +0000

This is my second dev.to post. If you missed the first one about building the auth system, check it out here.

Setting up fake worker failed: "Cannot read properties of undefined (reading 'WorkerMessageHandler')"

That was the error that greeted me when I tried to parse my first PDF. I'd installed pdfjs-dist, copied some code from a tutorial, and expected it to just work.

It did not just work.

This is the story of how I built the AI-powered resume analyzer for Carific.ai - and every rabbit hole I fell into along the way.

The entire codebase is MIT licensed. Every line of code in this post is live in the repo. Fork it, learn from it, improve it.

The Mission

I wanted users to:

📄 Upload a PDF resume or paste text directly
📝 Paste a job description they're applying for
🤖 Get AI-powered feedback on how to improve their resume for that specific role
⚡ See results stream in real-time - no waiting for a full response

Sounds straightforward, right? Spoiler: PDF.js had other plans.

The Stack (From package.json)

{
  "next": "^16.0.7",
  "react": "^19.2.1",
  "ai": "^5.0.108",
  "pdfjs-dist": "^5.4.449",
  "zod": "^4.1.13"
}

Yes, Zod v4. The one with the completely different API that broke all my validation code. More on that later.

Chapter 1: The PDF.js Worker Nightmare

I installed pdfjs-dist, copied some code from a tutorial, and tried to parse a PDF:

// ❌ This doesn't work in Next.js
import { getDocument } from "pdfjs-dist";

const pdfDoc = await getDocument({ data: arrayBuffer }).promise;

The error: Setting up fake worker failed: "Cannot read properties of undefined (reading 'WorkerMessageHandler')"

I tried setting up the worker the "normal" way:

// ❌ Also doesn't work
import { GlobalWorkerOptions } from "pdfjs-dist";
GlobalWorkerOptions.workerSrc = "/pdf.worker.min.js";

Still broken. The worker file wasn't being served correctly by Next.js.

The Legacy Build Saves the Day

After plenty of Googling, I found the magic combination:

// ✅ The fix that actually works
import {
  GlobalWorkerOptions,
  getDocument,
} from "pdfjs-dist/legacy/build/pdf.mjs";

GlobalWorkerOptions.workerSrc = new URL(
  "pdfjs-dist/legacy/build/pdf.worker.min.mjs",
  import.meta.url
).toString();

The key insights:

Use the legacy build (pdfjs-dist/legacy/build/pdf.mjs) - it has better compatibility with bundlers
Use import.meta.url to resolve the worker path - this works with Next.js's bundling
Use the .mjs extension - ESM modules play nicer with Next.js

One hour of Googling for three lines of code. Classic.

The Production Gotcha

A code review caught something I missed:

// ❌ This will fail in production
const standardFontDataUrl = "node_modules/pdfjs-dist/standard_fonts/";

node_modules doesn't exist in production deployments. The fix? I just removed the function that used it - it wasn't needed for my use case. Sometimes the best code is no code.

Chapter 2: Zod v4 Broke Everything

The Validation That Wasn't Validating

I added input validation to my API route. Copied the pattern from a tutorial:

// ❌ This doesn't work in Zod v4
const ResumeAnalysisSchema = z.object({
  resumeText: z
    .string({ required_error: "Resume is required" })
    .min(50, "Resume must be at least 50 characters"),
});

TypeScript screamed at me:

error TS2769: No overload matches this call.
Object literal may only specify known properties, and 'required_error' does not exist

The Zod v4 API Changes

Turns out Zod v4 changed the API. required_error is gone. So is the string shorthand for error messages:

// ✅ Zod v4 syntax
const ResumeAnalysisSchema = z.object({
  resumeText: z
    .string({ error: "Resume is required" })
    .min(50, { error: "Resume must be at least 50 characters" }),
});

And accessing validation errors? Also different:

// ❌ Zod v3
validation.error.errors[0].message;

// ✅ Zod v4
validation.error.issues[0].message;

30 minutes of debugging because I copied code from an outdated tutorial. Lesson learned: always check the version.

Single Source of Truth

A code review caught another issue - I had the same validation limits hardcoded in two places:

// ❌ Duplication that will drift
const schema = z.string().min(50).max(50000);
export const RESUME_MAX_LENGTH = 50000; // Will someone remember to update both?

The fix - constants as the single source of truth:

// ✅ lib/validations/resume-analysis.ts
export const RESUME_MIN_LENGTH = 50;
export const RESUME_MAX_LENGTH = 50_000;

export const ResumeAnalysisSchema = z.object({
  resumeText: z
    .string({ error: "Resume is required" })
    .min(RESUME_MIN_LENGTH, {
      error: `Resume must be at least ${RESUME_MIN_LENGTH} characters`,
    })
    .max(RESUME_MAX_LENGTH, {
      error: `Resume exceeds maximum length of ${RESUME_MAX_LENGTH.toLocaleString()} characters`,
    }),
});

Now changing a limit is a one-line change, and the error messages update automatically.

Chapter 3: Streaming AI Responses

The AI SDK Makes It Easy (Finally, Something That Just Works)

After the PDF.js and Zod nightmares, the AI integration was refreshingly simple:

// lib/ai/resume-analyzer.ts
import { streamText } from "ai";

const MODEL = "google/gemini-2.5-flash-lite";

export function analyzeResume({ resumeText, jobDescription }) {
  const userMessage = `Analyze this resume against the job description...`;

  return streamText({
    model: MODEL,
    system: RESUME_ANALYSIS_SYSTEM_PROMPT,
    messages: [{ role: "user", content: userMessage }],
  });
}

The API route streams the response directly:

// app/api/analyze-resume/route.ts
export async function POST(req: Request) {
  // ... auth and validation ...

  const result = analyzeResume({ resumeText, jobDescription });
  return result.toTextStreamResponse();
}

Client-Side Streaming

Reading a streaming response on the client:

const response = await fetch("/api/analyze-resume", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ resumeText, jobDescription }),
});

const reader = response.body?.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value, { stream: true });
  setAnalysisResult((prev) => prev + chunk);
}

Users see the AI response appear word by word. Much better UX than staring at a loading spinner for 10 seconds.

Chapter 4: The Little Bugs That Bite

Race Condition in File Upload

A code review caught a subtle bug - users could start multiple uploads simultaneously:

// ❌ Race condition waiting to happen
const handleDrop = (e: React.DragEvent) => {
  if (disabled) return;
  processFile(file);
};

If isProcessing is true, we should block new uploads:

// ✅ Guard against concurrent uploads
const processFile = async (file: File) => {
  if (disabled || isProcessing) return;
  // ...
};

const handleDrop = (e: React.DragEvent) => {
  if (disabled || isProcessing) return;
  // ...
};

Apply the same guard to drag handlers, file input, and the Card's disabled styling. Defensive programming saves debugging time later.

Browser Tab Freezing on Large PDFs

Another review comment - what happens if someone uploads a 500-page PDF?

// ❌ Will freeze the browser
for (let i = 1; i <= pageCount; i++) {
  const page = await pdfDoc.getPage(i);
  // Process every single page...
}

The fix - fail fast with limits:

// ✅ Protect the browser
const MAX_PAGES = 50;
const MAX_TEXT_LENGTH = 100_000;

if (pageCount > MAX_PAGES) {
  throw new Error(
    `PDF has ${pageCount} pages. Maximum allowed is ${MAX_PAGES} pages.`
  );
}

// Also check text length incrementally
totalLength += pageText.length;
if (totalLength > MAX_TEXT_LENGTH) {
  throw new Error(
    "PDF content exceeds maximum allowed length. Please use a shorter resume."
  );
}

String Concatenation Performance

One more optimization - repeated string concatenation is O(n²):

// ❌ Quadratic time complexity
let allText = "";
for (let i = 1; i <= pageCount; i++) {
  allText += pageText + "\n\n";
}

Array + join is O(n):

// ✅ Linear time complexity
const pageTexts: string[] = [];
for (let i = 1; i <= pageCount; i++) {
  pageTexts.push(pageText.trim());
}
return pageTexts.join("\n\n");

For a 2-page resume, it doesn't matter. For a 50-page document, it does.

The Final Architecture

app/
├── api/
│   └── analyze-resume/
│       └── route.ts          # Streaming API endpoint
├── dashboard/
│   └── page.tsx              # Server component with auth check

components/
├── dashboard/
│   ├── resume-analyzer-form.tsx  # Main form (client)
│   └── dashboard-header.tsx      # Header with logout
├── resume-upload.tsx         # PDF/text upload with drag-drop
├── job-description-input.tsx # Job description textarea
└── analysis-results.tsx      # Streaming markdown renderer

lib/
├── ai/
│   ├── index.ts              # Barrel export
│   └── resume-analyzer.ts    # AI streaming logic
├── pdf-parser.ts             # PDF text extraction
└── validations/
    └── resume-analysis.ts    # Shared Zod schema + constants

TL;DR - What I Learned

If you scrolled straight here (no judgment), here's the cheat sheet:

Problem	Solution
PDF.js worker fails in Next.js	Use legacy build + `import.meta.url` for worker path
`node_modules` path in production	Remove it or copy files to `public/`
Zod v4 `required_error` doesn't exist	Use `error` property instead
Zod v4 `errors` array	Use `issues` array instead
Validation limits duplicated	Constants as single source of truth
Race conditions in file upload	Guard with `isProcessing` flag everywhere
Large PDFs freeze browser	Add max page and text length limits
String concatenation is slow	Use array + join instead

Why Open Source?

Every bug I hit, every fix I found - it's all in the repo. Not because I'm proud of the bugs, but because someone else will hit the same issues.

If this post saves you even one hour of Googling "pdfjs-dist worker not working next.js", it was worth writing.

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If you find this useful, consider starring the repo - it helps others discover the project!

What's Next

The resume analyzer is live, but there's more to build:

🔐 OAuth providers - Google and GitHub sign-in
💾 Save analysis history - Review past analyses
📊 Resume scoring trends - Track improvement over time
🎯 ATS optimization - Specific keyword recommendations

I'll be documenting each feature as I build it. Follow along if you want to see how an open-source project evolves.

Your Turn

I'd love feedback:

On the code: See something that could be better? Open an issue or PR.
On the post: Too long? Missing something? Tell me.
On AI features: What would you want in a resume analyzer?

Building in public only works if there's a public to build with.

If this post helped you, drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan - ⭐ Star the repo if you found this helpful!
🐦 Twitter/X: @abdullahjan - Follow for more dev content
👥 LinkedIn: abdullahjan - Let's connect

Second post of many. See you in the next one.

Carific.ai: Building a Production-Ready Auth System with Next.js 16, Better Auth, and TanStack Form

Abdullah Jan — Mon, 08 Dec 2025 17:44:56 +0000

This is my first dev.to post. I'm starting my journey of building and learning in public.

It was 11 PM on a Tuesday. I had coffee #2 in hand, three browser tabs of Stack Overflow open, and a React Email component that refused to render. The error message mocked me: "Failed to render React component."

This is the story of how I built the authentication system for Carific.ai, my open-source, AI-powered career development platform, and every rabbit hole I fell into along the way.

The entire codebase is MIT licensed. Every line of code in this post is live in the repo. Fork it, learn from it, improve it. That's the whole point.

The Mission

I needed a complete auth system:

✉️ Email/password authentication with Better Auth
✅ Email verification that actually lands in inboxes (not spam)
📝 Type-safe forms with TanStack Form's new composition pattern
🔒 Server-side auth checks using Next.js App Router
🧩 Clean architecture separating server and client concerns

Sounds straightforward, right? Spoiler: it really wasn't.

The Stack (Actual Versions from My package.json)

{
  "next": "16.0.7",
  "react": "19.2.1",
  "better-auth": "1.4.5",
  "@tanstack/react-form": "1.27.1",
  "@react-email/components": "1.0.1",
  "resend": "6.5.2",
  "zod": "4.1.13"
}

Yes, I'm running Next.js 16 and React 19. Living on the edge. No regrets (mostly).

The Journey: 30 Commits Later

Before diving into the code, here's how this feature evolved. Building in public means showing the messy middle, not just the polished end result.

01c1695 Add authentication system with better-auth and Prisma
5ed22b0 Add initial Prisma migration for authentication database schema
a6fb7ba Add email verification system with Resend integration
4cae5f0 Refactor email system with Tailwind styling
8cdd67e Refine email template styling with inline styles (Outlook fix!)
c245401 Add authentication pages with sign in, sign up, and dashboard
54b2338 Refactor auth forms to use custom form hook
8f85a04 Refactor form components into separate modules
41b3005 Add remember me checkbox to sign-in form
e2643f2 Refactor auth pages to use shared AuthCard component
52cbe41 Refactor auth pages to server components (the big one!)
72c3393 Replace hardcoded route strings with centralized ROUTES constants
f6dcd9d Add welcome page for email verification flow

Notice the pattern? Build → Realize it's wrong → Refactor → Repeat.

That's 30 commits across 7 pull requests just for authentication. Each refactor taught me something. Let me share the biggest lessons.

Chapter 1: The Email That Wouldn't Send

11:47 PM - The Error That Started It All

When I first wired up React Email with Resend, I followed what seemed like the obvious pattern:

// ❌ This doesn't work
await resend.emails.send({
  from: process.env.EMAIL_FROM,
  to: email,
  subject: "Verify your email",
  react: <EmailVerification verificationUrl={url} />,
});

The error: Failed to render React component. Make sure to install @react-email/render or @react-email/components.

I checked my package.json. The packages were there. I ran npm ls @react-email/components. Installed. I cleared .next, restarted the dev server, and sacrificed a rubber duck to the debugging gods.

Nothing.

12:23 AM - The Breakthrough

After an embarrassing amount of Googling, I found it. The react prop in Resend doesn't play nice with Next.js server components. You need to manually render the component to HTML first:

// ✅ The fix that saved my sanity
import { render } from "@react-email/components";

const html = await render(
  <EmailVerification userName={userName} verificationUrl={url} />
);

await resend.emails.send({
  from: process.env.EMAIL_FROM!,
  to: email,
  subject: "Verify your email address",
  html, // Pass the rendered HTML string, not the component
});

One line. That's it. The render() function converts your React Email component to an HTML string. Two hours of my life for one function call.

If this saves you even 10 minutes, this blog post was worth writing.

The Outlook Problem (Because Of Course There's More)

With emails finally sending, I opened React Email's dev server to admire my work. Yellow warnings everywhere:

⚠️ border-radius - Not supported in Outlook
⚠️ text-decoration-line - Not supported in Outlook
⚠️ word-break - Not supported in Outlook, Yahoo! Mail

Outlook. The Internet Explorer of email clients. Still haunting us in 2024.

My pragmatic solution: Inline styles for the critical stuff, graceful degradation for the rest.

<Button
  href={verificationUrl}
  className="rounded-md bg-primary px-6 py-3 text-white"
  style={{ textDecoration: "none" }} // Inline style for Outlook
>
  Verify Email
</Button>

Will Outlook users see square buttons? Yes. Will they still be able to verify their email? Also yes. Ship it.

Chapter 2: TanStack Form Composition (Where Things Got Fun)

After the email saga, I needed a win. Enter TanStack Form v1 and its new createFormHook API.

I'd used TanStack Form before, but always ended up with repetitive boilerplate, the same label/error/input pattern copy-pasted across every form. The composition pattern changes everything.

Step 1: Create Form Contexts

// hooks/form-context.tsx
import { createFormHookContexts } from "@tanstack/react-form";

export const { fieldContext, useFieldContext, formContext, useFormContext } =
  createFormHookContexts();

Step 2: Build a Base Field Wrapper

This handles labels, descriptions, and error states for all field types:

// components/form/form-base.tsx
"use client";

import { ComponentProps, ReactNode } from "react";
import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldLabel,
} from "@/components/ui/field";
import { useFieldContext } from "@/hooks/form-context";

export type FormControlProps = {
  label: string;
  description?: string;
};

type FormBaseProps = FormControlProps & {
  children: ReactNode;
  orientation?: ComponentProps<typeof Field>["orientation"];
  controlFirst?: boolean;
};

export function FormBase({
  children,
  label,
  description,
  orientation,
  controlFirst,
}: FormBaseProps) {
  const field = useFieldContext();

  const isInvalid =
    field.state.meta.errors.length > 0 && field.state.meta.isTouched;

  const labelElement = (
    <>
      <FieldLabel htmlFor={field.name}>{label}</FieldLabel>
      {description && <FieldDescription>{description}</FieldDescription>}
    </>
  );

  return (
    <Field orientation={orientation} invalid={isInvalid}>
      {controlFirst ? (
        <>
          <FieldContent>{children}</FieldContent>
          {labelElement}
        </>
      ) : (
        <>
          {labelElement}
          <FieldContent>{children}</FieldContent>
        </>
      )}
      <FieldError />
    </Field>
  );
}

🚨 The Gotcha That Cost Me 30 Minutes

I initially used useFormContext() here. Bad idea. The error message was... unhelpful:

formContext only works when within a formComponent passed to createFormHook

Here's the mental model that finally clicked:

fieldComponents → Use useFieldContext() (you're inside a field)
formComponents → Use useFormContext() (you're at the form level)

FormBase wraps individual fields, so it needs useFieldContext(). Simple once you know it, maddening until you do.

Step 3: Create Pre-bound Field Components

// components/form/form-fields.tsx
"use client";

import { Input } from "@/components/ui/input";
import { Checkbox } from "@/components/ui/checkbox";
import { useFieldContext } from "@/hooks/form-context";
import { FormBase, FormControlProps } from "./form-base";

interface TextFieldProps extends FormControlProps {
  placeholder?: string;
  type?: "text" | "email" | "password";
  autoComplete?: string;
}

export function TextField({
  label,
  description,
  placeholder,
  type = "text",
  autoComplete,
}: TextFieldProps) {
  const field = useFieldContext<string>();

  return (
    <FormBase label={label} description={description}>
      <Input
        id={field.name}
        name={field.name}
        type={type}
        value={field.state.value}
        onBlur={field.handleBlur}
        onChange={(e) => field.handleChange(e.target.value)}
        placeholder={placeholder}
        autoComplete={autoComplete}
        aria-invalid={
          field.state.meta.errors.length > 0 && field.state.meta.isTouched
        }
      />
    </FormBase>
  );
}

export function CheckboxField({ label, description }: FormControlProps) {
  const field = useFieldContext<boolean>();

  return (
    <FormBase
      label={label}
      description={description}
      orientation="horizontal"
      controlFirst // Checkbox before label
    >
      <Checkbox
        id={field.name}
        checked={field.state.value}
        onCheckedChange={(checked) => field.handleChange(checked === true)}
        onBlur={field.handleBlur}
      />
    </FormBase>
  );
}

Step 4: Wire It All Together

// hooks/form.tsx
import { createFormHook } from "@tanstack/react-form";
import { fieldContext, formContext } from "./form-context";
import { TextField, CheckboxField } from "@/components/form/form-fields";
import { SubmitButton } from "@/components/form/form-components";

export const { useAppForm, withForm } = createFormHook({
  fieldContext,
  formContext,
  fieldComponents: {
    TextField,
    CheckboxField,
  },
  formComponents: {
    SubmitButton,
  },
});

The Payoff: Forms That Don't Make Me Cry

Remember the boilerplate I mentioned? Gone. Now my sign-in form looks like this:

const form = useAppForm({
  defaultValues: {
    email: "",
    password: "",
    rememberMe: false,
  },
  validators: { onSubmit: signInSchema },
  onSubmit: async ({ value }) => {
    // Handle sign in
  },
});

return (
  <form
    onSubmit={(e) => {
      e.preventDefault();
      form.handleSubmit();
    }}
  >
    <form.AppField name="email">
      {(field) => (
        <field.TextField
          label="Email"
          type="email"
          placeholder="you@example.com"
        />
      )}
    </form.AppField>

    <form.AppField name="password">
      {(field) => (
        <field.TextField
          label="Password"
          type="password"
          placeholder="••••••••"
        />
      )}
    </form.AppField>

    <form.AppField name="rememberMe">
      {(field) => <field.CheckboxField label="Remember me" />}
    </form.AppField>

    <form.AppForm>
      <form.SubmitButton label="Sign in" loadingLabel="Signing in..." />
    </form.AppForm>
  </form>
);

Every field is type-safe. Validation is declarative. Adding a new form takes minutes, not hours.

This is the kind of DX that makes you excited to build features instead of dreading them.

Chapter 3: The Server/Client Dance

Next.js App Router gives us a superpower: server components. But with great power comes great confusion about what goes where.

Here's the architecture I landed on after several refactors:

Server Component (Page)

// app/(auth)/signin/page.tsx
import { Metadata } from "next";
import { AuthCard } from "@/components/auth/auth-card";
import { SignInForm } from "@/components/auth/signin-form";
import { checkAuthAndRedirect } from "@/lib/auth-check";

export const metadata: Metadata = {
  title: "Sign In - Carific AI",
  description: "Sign in to your Carific AI account",
};

export default async function SignInPage() {
  // Redirect to dashboard if already authenticated
  await checkAuthAndRedirect({ disableCookieCache: true });

  return (
    <AuthCard
      title="Welcome back"
      description="Sign in to your account to continue"
      footer={{
        text: "Don't have an account?",
        linkText: "Sign up",
        linkHref: "/signup",
      }}
    >
      <SignInForm />
    </AuthCard>
  );
}

Client Component (Form)

// components/auth/signin-form.tsx
"use client";

export function SignInForm() {
  const router = useRouter();
  const form = useAppForm({
    // ... form config
  });

  return <form>{/* Just the form, no layout */}</form>;
}

Why This Split Matters

I initially had everything in client components. It worked, but:

No SEO metadata - export const metadata only works in server components
Flash of unauthenticated content - Auth checks happened client-side, so users saw the login form before being redirected
Larger JS bundle - The entire page was client-rendered

The new architecture:

✅ Metadata exports work (SEO-friendly)
✅ Auth checks happen server-side (no flash)
✅ Static layout stays on the server (smaller bundle)
✅ Interactive logic is isolated to the smallest possible client component

Server-Side Auth Check

// lib/auth-check.ts
import { headers } from "next/headers";
import { redirect } from "next/navigation";
import { auth } from "@/lib/auth";
import { ROUTES } from "@/lib/constants";

export async function checkAuth(disableCookieCache = false) {
  return auth.api.getSession({
    headers: await headers(),
    query: { disableCookieCache },
  });
}

export async function checkAuthAndRedirect({
  redirectUrl = ROUTES.DASHBOARD,
  disableCookieCache = false,
} = {}) {
  const session = await checkAuth(disableCookieCache);
  if (session) {
    redirect(redirectUrl);
  }
}

Chapter 4: The Little Things That Save Hours

Centralized Route Constants

After the third time I typo'd /dashbaord instead of /dashboard, I created this:

// lib/constants.ts
export const ROUTES = {
  DASHBOARD: "/dashboard",
  SIGN_IN: "/signin",
  SIGN_UP: "/signup",
  WELCOME: "/welcome",
} as const;

Now TypeScript yells at me before I ship broken links. ROUTES.DASHBOARD everywhere, string typos nowhere.

Bonus: When I eventually rename /dashboard to /app, it's a one-line change.

The Final Architecture

app/
├── (auth)/
│   ├── layout.tsx        # Logo + centered layout
│   ├── loading.tsx       # Skeleton loader
│   ├── signin/page.tsx   # Server component
│   ├── signup/page.tsx   # Server component
│   └── welcome/page.tsx  # Post-signup "check your email"
├── dashboard/page.tsx
└── layout.tsx            # Root layout with Toaster

components/
├── auth/
│   ├── auth-card.tsx     # Reusable card wrapper
│   ├── signin-form.tsx   # Client form
│   └── signup-form.tsx   # Client form
├── form/
│   ├── form-base.tsx     # Field wrapper
│   ├── form-fields.tsx   # TextField, CheckboxField
│   └── form-components.tsx
└── ui/                   # shadcn/ui

hooks/
├── form.tsx              # useAppForm
└── form-context.tsx

lib/
├── auth-check.ts         # Server auth utilities
├── constants.ts          # Route constants
├── transactional-email.tsx
└── validations/auth.ts   # Zod schemas

TL;DR - What I Learned

If you scrolled straight here (no judgment), here's the cheat sheet:

Problem	Solution
React Email won't render in Next.js	Use `render()` to convert to HTML string first
Outlook breaks your email styles	Inline styles for critical properties, accept graceful degradation
TanStack Form boilerplate	Use `createFormHook` composition pattern
`useFormContext` vs `useFieldContext`	Field components use `useFieldContext`, form components use `useFormContext`
Flash of unauthenticated content	Server-side auth checks in page components
Route string typos	Centralized `ROUTES` constant object

Why Open Source?

This is my first open-source project, and I'm learning that building in public is terrifying and liberating at the same time.

Terrifying because my code is out there. Every questionable variable name, every "I'll refactor this later" comment visible to anyone who clicks the repo.

Liberating because I'm no longer building alone. CodeRabbit reviews my PRs. Future contributors might catch bugs I missed. And maybe just maybe someone learning auth will find this codebase useful.

Carific.ai is MIT licensed. That means:

✅ Use it in your projects
✅ Fork it and make it your own
✅ Learn from the code (and my mistakes)
✅ Contribute back if you want

The repo: github.com/ImAbdullahJan/carific.ai

⭐ If you find this useful, consider starring the repo - it helps others discover the project!

What's Next for Carific.ai

This auth system is just the foundation. Here's the roadmap I'm building toward:

🔐 OAuth providers - Google and GitHub sign-in
🔑 Password reset flow - With rate limiting and secure tokens
👤 Session management - See and revoke active sessions
🤖 The actual AI features - Career coaching, resume analysis, interview prep

I'll be documenting each feature as I build it. Follow along if you want to see how an open-source project evolves from zero to (hopefully) something useful.

Your Turn

This is my first post, and I'd genuinely love feedback:

On the code: See something that could be better? Open an issue or PR.
On the post: Too long? Too short? Missing something? Tell me.
On auth in general: What's your stack? Any war stories?

Building in public only works if there's a public to build with. Let's learn together.

If this post helped you or if you just want to encourage a first-time poster or drop a ❤️. It means more than you know.

Let's connect:

🐙 GitHub: @ImAbdullahJan - ⭐ Star the repo if you found this helpful!
🐦 Twitter/X: @abdullahjan - Follow for more dev content and project updates
👥 LinkedIn: abdullahjan - Let's connect

First post of many. See you in the next one.