Auth Flows, Onboarding Traps, and Why AI Still Needs a Human to Think

#nextjs #typescript #webdev #buildinpublic

So this week was one of those weeks where you go in thinking you'll fix one small thing and come out three days later having redesigned half the app's architecture.

Worth it though. Here's what actually happened.

The Problem I Was Ignoring

My invoice PDF templates were broken. Not broken like crashing, broken like useless. The generated PDFs had placeholder company info, no real sender details, nothing a freelancer could actually send to a client. Just four templates sitting there looking pretty and being completely non-functional.

The fix was obvious: capture the user's company details somewhere and use them in the PDF.

But that opened a whole other question: where in the flow do you capture this? You can't just shove a form in front of someone before they've even seen the product. That's the fastest way to kill your conversion rate.

So I decided to redesign the auth and onboarding flow entirely.

The New Flow

Old flow: sign up → land on dashboard → stare at an empty page.

New flow: create your invoice first, auth later.

The user hits the app, clicks "Create Invoice," fills in the form, sees a live preview of their PDF, all without signing up. When they hit submit, that's when we ask for auth. And immediately after auth, if they haven't gone through onboarding, we collect their company details before anything else.

It sounds simple but it required rethinking quite a bit of how the middleware works.

The logic being: let people see value before asking them to commit. Once they've built something they actually want to send, they're invested. That's the moment to ask for an account. Not before.

The Onboarding Status Problem (and Why the AI Kept Getting It Wrong)

This is the part that actually frustrated me the most this week, and I want to be honest about it because I think it's important.

Once you have an onboarding flow, you need to check: has this user gone through it or not? Seems simple. It isn't.

Option 1: Hit the database every time. Check for a row. If it's there, they're onboarded.

This is the obvious answer. It's also terrible. You'd be doing an unnecessary DB read on every single protected route, every middleware call, every page load. That's a lot of wasted reads for information that barely changes.

Option 2: Use Clerk's user metadata. After onboarding, write onboarded: true to the user's public metadata. From then on, you read it from the JWT, no DB call needed.

This is the right answer. But it's harder to implement correctly, and the JWT update isn't instant, which creates a brief window where the token still shows the old state.

Here's the frustrating part: I was using AI to help me through the bugs I hit with option 2. And multiple times, when I got stuck and asked "can we try a simpler approach?", the AI would just... give me database middleware code. Every time. Just casually suggest checking the DB on every request like it wasn't a problem.

It doesn't know your scale concerns. It doesn't know you're trying to keep reads low. It optimises for "working code" not "well-architected code." And if you don't push back, you end up with the wrong solution wrapped in a green checkmark.

This is something I keep coming back to: AI is a powerful tool but it needs someone who knows what they're trying to build. If you don't have the mental model of what good looks like, the AI will lead you somewhere technically correct and architecturally wrong.

Bug Fixes That Were Quietly Breaking Everything

While I was in there, I caught a few bugs that had been hiding:

user was undefined in ModernInvoice.tsx because InvoicePDFButton wasn't receiving or passing user down to InvoicePDFDialog. Classic prop drilling miss.
There was a hardcoded "Your Company" string that was a leftover from early dev. It had been sitting there, overriding real data, the whole time.
InvoiceData type in InvoicePDFButton was missing customerId, causing a mismatch with InvoiceForPDF. Fixed by dropping the local type and just reusing InvoiceForPDF directly.

None of these were glamorous. But fixing them made the PDF output actually correct for the first time.

A Shift in How I'm Thinking About This

Somewhere in the middle of all this, I stopped thinking like a developer and started thinking like a product person.

I've been asking myself a lot of "should this even be here?" questions. What does the user actually need to see first? What am I making them do that they shouldn't have to? What am I hiding that they need?

The create invoice flow is a good example. I spent a while thinking about whether to use a stepper (step 1 → step 2 → step 3) or a single split-panel view with the form on the left and a live PDF preview on the right.

Steppers feel clean but they're wrong for this. Invoice fields are deeply interdependent: change the line items and the total changes, change the currency and the format changes, change the due date and the payment terms might need to update. A stepper forces you to pretend those dependencies don't exist. A split panel lets you see everything at once and makes the relationships obvious.

I'm also thinking more carefully about what to reveal and when. The template picker, for example, should be a modal that opens when you click "Create Invoice", not a separate page, not a step in a form. Each template card should have a "Preview sample" link that opens a fullscreen overlay. Once you pick one, you land on the builder with that template already applied.

Small decisions. But they compound into an experience that either feels thoughtful or feels like someone just strung features together.

What's Next

The onboarding flow captures company name, address, and basic details for now. No logo yet, because that would mean setting up S3 or Uploadthing and that's a whole project in itself. It's on the list but not the priority.

Next up is getting the create invoice flow to its final form. The split-panel builder with live preview, a template switcher pill in the header so you can swap templates without losing your form data, and the success animation: button morphs to a checkmark, then confetti, then redirect to the invoice detail page.

Also planning to add auto-save to localStorage every 30 seconds as a safety net. Nothing worse than filling in an invoice, your browser hiccups, and you lose everything.

I'll keep posting updates as things come together. If you've been following along, thank you genuinely, it helps more than you'd think. This the detailed post on my personal blog

And if you've hit the "AI keeps suggesting the wrong architecture" wall before, I'd love to hear how you dealt with it. Drop it in the comments.