So here's the slightly unglamorous truth about how event-driven architecture actually entered this project: the part of the system that most obviously sounds like it should be event-driven — moderation, the thing that decides whether your review goes live — flatly isn't. It runs in a single Postgres transaction, synchronously, in-process, and it has stayed that way on purpose since early on. Kafka showed up later, for a completely different reason, and it took me writing this post to admit out loud that the reason was "I wanted the practice."

I think that's a more useful story than pretending I had the whole distributed-systems diagram in my head on day one. So let's do it in the order it actually happened.

The part that stayed boring, deliberately

When a candidate submits a rating, RoundRatingsService.create() inserts the rating and a moderation_queue row in the same database transaction. No queue, no broker, no "eventually" — either both rows exist or neither does. The original plan sketched moderation as a separate async worker reacting to events. That version never got built, and the reason is worth sitting with: nothing was asking for it. There was no load problem a synchronous write couldn't handle, and moderation decisions are exactly the kind of thing you don't want living in "probably arrives within a few seconds" land. A transactional write is a promise. A queue is a suggestion.

This is the least exciting sentence in the whole post and also, I'd argue, the most important system-design decision in this section: knowing where not to add a message broker is worth more than knowing how to configure one.

Then I wanted a broker anyway

Kafka/Redpanda showed up in a later phase for a reason that has nothing to do with moderation needing to be decoupled — it still doesn't. It showed up because I wanted real distributed-systems practice: a message broker two independent services could subscribe to, consumer groups, at-least-once delivery, the whole "now go build things that don't fall over when a message gets redelivered" problem set. That's an honest reason to add infrastructure. It's just not the reason system-design folklore usually cites, and I'd rather say that plainly than back into a more flattering story later.

Redpanda won over full Kafka for the boring, practical reason: it speaks the same wire protocol my Node client already expected, and running it locally means one container instead of a JVM plus a coordination layer. Nothing downstream of it cares which broker is underneath, which is the entire point of building against a protocol instead of a vendor.

Once the broker existed, every moderation-relevant write — a rating created, a status changed to approved or rejected — started publishing a versioned event, still safely after its own transaction had already committed. The synchronous write path never became dependent on the broker being up. Nobody's review submission should ever fail because a message queue is having a bad day.

The first two people who showed up to the party

Two services subscribe to those events, and they demonstrate two completely different lessons about building on top of an at-least-once broker.

notification-service exists to send one email: "your submission is pending review." The interesting part isn't the email, it's that Redpanda makes no promise about delivering that event exactly once — only at least once — which means the same event can show up twice, and a candidate should never get the same email twice because a network blip caused a redelivery. The fix is a NotificationLog table with a unique constraint on (entityType, entityId, eventType), checked once as a fast-path read and enforced for real by catching the database's own duplicate-key error on insert. The lock isn't a clever distributed algorithm — it's just Postgres doing what Postgres has always done, which is often the correct answer to "how do I make this idempotent" before you reach for anything fancier.

Building this also surfaced a real schema gap that had nothing to do with Kafka: the service had a candidateId and needed an email address, and the only thing on file was an HMAC hash designed to be unreversible — useful for "does this email already have an account," useless for "send this address a message." That's what a reversible, separately-keyed encrypted copy of the address is for, added specifically because a background consumer, unlike a synchronous request, can't rely on already having the plaintext address sitting in scope.

review-analyzer is the more interesting story, because it started as the setup for a joke about async infrastructure and ended up as a lesson about write authority. Its job is to run LLM-based triage on every submission and decide whether it looks concerning — but for a while, an identical version of that logic still lived inside api itself, running synchronously on the same write path. Porting the async version in and leaving the old one running would have looked like a careful, incremental migration. It would also have meant two independent code paths were each capable of auto-approving the same submission — a real double-approval bug waiting for a Tuesday to happen, not a style nitpick. The old in-process version had to be deleted outright, not just bypassed, the same day the new one shipped. review-analyzer computes and publishes a verdict; it never touches the moderation table directly. api remains the only thing on Earth allowed to actually approve or reject a submission — the event is an opinion, not a permission slip.

The bug that would have failed silently, forever

Here's my favorite kind of bug: the one that isn't a bug yet. A design review — not a production incident — noticed that the service publishing all these events connected to the broker exactly once, at boot. If the broker wasn't up yet when the app started (a routine local-dev race), or if a healthy connection later dropped for any reason, every subsequent publish call would just quietly return early forever. No crash, no error log anyone would notice, no retry. The app would keep serving requests, moderation would keep working, and it would look completely fine — right up until someone eventually asked "wait, why has nobody gotten a notification email in three days?"

The fix is almost insultingly simple: listen for the broker client's own DISCONNECT event to know the connection is actually dead (a try/catch around one send tells you nothing about the next one), and run a self-healing reconnect check every 30 seconds forever, whether the failure was "never connected" or "connected, then dropped." It's a few lines of code guarding against an entire category of "everything looks fine, nothing is happening" failure — the kind of gap that never shows up in a demo, because a demo doesn't run long enough for a connection to quietly die.

Teaching a free local model to grade a paid one

The newest chapter of this story is the one I like most, because it's a small, honest lesson about evaluating AI systems without either trusting them blindly or spending real money to check your own homework. Once the LLM-triage pipeline existed, a natural question showed up: is it actually good, or does it just look good in the three examples I happened to glance at? Building a real evaluation harness against the same paid model doing the triage would cost tokens every single run — which quietly discourages ever running it. So the harness runs entirely against a free local model instead, checked live end to end at 14/14 correct on a hand-labeled test set, with an average "does this reasoning actually make sense" score of 4.79 out of 5 from a second local model acting as judge.

That second number comes with an asterisk I think is worth keeping in the post rather than editing out: on one run, the judge's lowest score flagged a verdict as inventing a detail that "wasn't in the source." Reading the actual text by hand, it was in the source — the judge was wrong, not the model under test. A single small model's opinion is a prompt to go look closer, not a number to report on a dashboard and walk away from. That distinction — between "I ran an eval" and "I know what my eval can and can't actually tell me" — is, I'd argue, most of what separates a real evaluation practice from eval-shaped theater.

Why this is the part I actually wanted to write about

"Event-driven" is an easy phrase to say and a much harder architecture to actually justify, verify, and keep honest once at-least-once delivery, silent disconnects, and double-write races enter the picture. The interesting engineering here was never "we added Kafka" — it's the decision not to add it to the one place that most wanted it, and then, once it existed for a good reason, taking idempotency, connection health, and write authority as seriously as the happy path.

Next up in this series: the least glamorous part of the entire system — moderation queue SLAs, claim logic, and the plumbing nobody claps for that's actually what separates a trust-and-safety feature from a trust-and-safety demo.

Here's the uncomfortable version of the product I didn't build: candidates log in, rate "John from Engineering" a 1/5, write "he was condescending and clearly didn't read my resume," and that goes live to the internet under John's actual name, searchable, permanent, and produced by a system with zero verification that John was even having a bad day versus being systematically unfair. That system would get someone sued — the platform, probably, and possibly the candidate too. It would also, deservedly, deserve it.

So this post is about the three things that actually stand between "review platform" and "liability engine," and why all three had to be architectural decisions, not UI features you could accidentally ship without.

1. Anonymize identity, not accountability

Interviewers and recruiters are stored as real entities in this system — that's not a contradiction, it's the whole trick. An interviewers row exists so that ratings can roll up correctly ("this interviewer's fluency score across 40 rounds") and so the same person doesn't get treated as forty different strangers across forty different candidate submissions. But the row has no name column. It has internal_identifier_hash (for de-duplication) and display_label, a generated string like "Interviewer A" or "Round 2 Interviewer."

The point isn't that a UI layer hides the name from you. The point is that the name was never captured in the first place — there is nothing to leak, because there is nothing stored to leak. A bug in a future API endpoint, a careless SELECT *, a debug log statement someone forgets to remove — none of those can expose a real name, because the schema makes it structurally impossible. That's a materially different, and much stronger, guarantee than "we redact this in the response serializer," which is one missed code review away from an incident.

2. Nothing is public until a human — or a sufficiently confident model — says so

Every rating and review table in this system ships with a status column defaulting to pending, and it's been there since the very first database migration, before a single line of moderation logic existed to act on it. That ordering matters: the column wasn't added in response to a fraud incident. It was there from day zero because the plan was never "launch open, add moderation later." Every public read path filters on status = 'approved'. There is no code path that serves an unmoderated submission to a stranger.

The write path and the moderation enqueue happen in the same database transaction:

create(roundId: string, dto: CreateRoundRatingDto) {
  return this.prisma.$transaction(async (tx) => {
    const flagReason = await this.fraudChecksService.detectFlagReason(dto, tx);
    const rating = await tx.roundRating.create({ data: { ...dto, roundId } });
    await this.moderationService.enqueue('round_rating', rating.id, tx, flagReason);
    return rating; // one transaction: the write and the enqueue, atomic
  });
}

Why does this matter? Because the alternative failure modes are both bad: a rating that gets written but never enqueued would be content that can never become visible, since nothing would ever review it. A queue entry pointing at a rating that failed to insert would be a review task for nothing. Wrapping both in one transaction means neither failure mode can happen — a rating either fully exists with a pending review task, or neither exists at all.

A confidence-scored LLM pass (an Anthropic model, evaluated against the exact same criteria a human moderator uses) now handles the obviously-clean tail of this queue automatically — but notice the design constraint that survived the AI layer's introduction unchanged: the model doesn't get a bypass, it gets a confidence threshold. Below that threshold, or on anything flagged concerning, a human still reviews it, exactly as before. The system's fail-safe direction has stayed pointed the same way through every phase: when in doubt, a human decides, never the reverse.

3. A raw average is a lie you tell with math

Here's a scenario: a company has exactly one review, and that reviewer had a genuinely bad day and gave every score a 1. Do you show that company a 1.0-star rating? Obviously not — that's not "this company is bad," that's "n=1 and noise dominates." But where's the actual cutoff? Hide everything below n=5? Then a company with 4 reviews shows nothing, and the moment review #5 lands, you show a raw average that's still barely more meaningful than the one you were hiding a second ago. That's a misleading cliff, not a fix.

The actual approach is shrinkage — pull small samples toward the platform-wide average, and let them converge to the company's true average as real signal accumulates:

With k (a tunable confidence constant, starting around 8–10) and a company with only 1 review, the formula pulls that score heavily toward the global average — one bad-day reviewer can't tank a company's displayed number by themselves. As real reviews accumulate, the weight shifts naturally toward the company's own true signal. And there's still one hard floor underneath all of it: below n = 3, the score isn't shown at all — the API returns null, and the frontend shows "not enough reviews yet" instead of a number. Sample size is always shown alongside the score, never hidden — the goal is honest uncertainty, not a false sense of precision.

The lifecycle, end to end

Put it all together, and a single rating's life looks like this:

Every box in that diagram exists because leaving it out creates a specific, describable harm — a name leak, a permanently-public unreviewed accusation, or a misleading score. None of them are decorative.

The part I'm actually proud of: finding my own bug

None of the above is worth much if the implementation has races in it, so here's an honest one. An internal audit later found that ModerationService.review() — the method behind every approve/reject/flag action, including the AI auto-approval path — had a check-then-act race: it read a queue entry, checked whether it was already reviewed, and then wrote the decision, as two separate round trips with no lock held between them. Two moderators clicking "approve" within milliseconds of each other (or a moderator racing the AI auto-approval consumer) could both pass the "not yet reviewed" check before either committed — and both proceed to flip the same entity's status, in the worst case sending a candidate an "approved" email and a "rejected" email for the same submission.

The fix is a small, specific pattern worth knowing regardless of what you're building: fold the check into the write's own WHERE clause, so the database's row lock does the serializing instead of application code racing itself.

const { count } = await tx.moderationQueueEntry.updateMany({
  where: { id, reviewedAt: null },   // the check IS the write now
  data: { reviewedAt: new Date(), reviewedBy: dto.reviewedBy, flagReason },
});
if (count === 0) throw new ConflictException('Already reviewed.');

I'd rather tell you about the race condition I found and fixed than pretend the first version was perfect. A system that claims to be trustworthy and then hides its own bugs is a worse system than one that's honest about having found and closed one.

Why this matters

Every one of these decisions has a name behind it on both sides of the transaction — a candidate whose honest account of a bad interview shouldn't get buried under legal risk, and an interviewer who shouldn't have their name permanently attached to an unverified, un-reviewable accusation. Trust isn't a feature you add once the "real" product works. In a system like this, it is the product — the schema either protects both of those people by construction, or it doesn't, and no amount of nice UI afterward fixes a bad answer to that question.

Next up: why the write path stayed a plain, synchronous Postgres transaction even after a Kafka-style message broker showed up in this system — and the very specific, very honest reason a broker got added anyway.

I have no idea what happened in that interview. Neither do you. Neither, six months later, does the person who wrote it. Was the interviewer rude? Was the problem hard, or was the interviewer hard to understand? Did "fair" mean "unbiased" or just "not a trick question"? A number from 1 to 5 collapsed an hour of another human being's working life into a piece of information roughly as useful as a fortune cookie.

This is the problem I actually set out to solve before I wrote a single line of backend code: an interview loop isn't one experience, it's a sequence of them — a phone screen, a system design round, a behavioral round, a recruiter who either ghosts you or doesn't — and a single aggregate rating throws away exactly the information you'd want if you were the next candidate walking in.

So the very first decision I made on this project wasn't a framework or a database. It was a data model. And the data model is, honestly, most of the product.

Start with the shape of the thing you're actually modeling

Here's the entity hierarchy the entire system is built around:

Notice what this is not: it's not a Review table with a stars column and a text field. It's a tree. A Company has many InterviewProcesses (one per candidate's application loop). A process has many Rounds in sequence, and separately, RecruiterInteractions. Each round can carry exactly one rating from the candidate who sat it. There's also one OverallReview per process — a summary, but a summary that sits alongside the granular data, never a replacement for it.

Getting this hierarchy right on day one mattered more than almost anything else in the project, for a boring but important reason: five phases of feature work later — moderation, analytics, search, an AI triage pipeline — nothing has ever needed a breaking schema change to this core tree. Only additive changes. That's not luck. It's the payoff of spending real time on the data model before writing a single API endpoint.

The rating fields are an argument, encoded as columns

The most interesting design decision isn't the hierarchy, it's what's inside a RoundRating. Early on, a round rating had five fields: difficulty, fairness, communication_fluency, attentiveness, bias_signal. It read like a survey designed by committee, because early on, it kind of was.

A later UX pass killed two of those fields outright and renamed the rest, landing on the four that ship today:

• difficulty — an axis about the round, not the interviewer. How hard was the problem.

• fluency — an axis about the interviewer. Could they actually communicate.

• clarity — was the problem statement itself clear, or did you spend ten minutes decoding what was even being asked.

• focus — was the interviewer paying attention, or checking Slack under the table.

Why cut fairness and bias_signal? Because they don't hold up as self-reported, single-question ratings. "Was this interview fair" is a conclusion, not an observation — it's the thing you'd derive from a pattern across many fluency/clarity/focus scores over time, not something one candidate can honestly rate about their own hour-long experience without just projecting their overall outcome onto the question. Asking directly just captures "did I get an offer," dressed up as a bias metric. It's a subtler trap than it sounds, and cutting it was the right call.

That's the kind of decision that never shows up in a demo, and it's exactly the kind of decision I want a hiring manager reading this to notice: the schema isn't just "what fields does the form have," it's a stance on what's actually measurable.

Type-specific data without a column explosion

A coding round wants to record which algorithms and data structures came up. A case study round wants to record which frameworks and what industry context. A behavioral round wants a framework used (STAR, etc.) and focus areas. None of those belong as top-level columns on rounds — that's a table that would grow a new nullable column every time someone adds a ninth interview format, and eventually look like a spreadsheet that gave up.

Instead, rounds.type_metadata is a single JSONB column, and its shape is defined by a round-type registry in code — a lookup table mapping round_type to an explicit list of expected fields and their kind (free text vs. a controlled, admin-managed vocabulary). Adding a ninth round type later is "add an enum value and a schema entry," not "write a migration."

// a coding round
{ "problemAlgorithms": ["DFS", "BFS"], "problemDataStructures": ["Graph"] }

// a leadership round
{ "principlesAsked": ["Ownership", "Deliver Results"] }

What Postgres enforces so the application never has to lie

A few constraints are worth calling out because they're the difference between "the API validates this" and "this cannot physically happen":

• Every 1–5 rating column has a real CHECK constraint at the database level. Prisma's schema language can't express CHECK directly, so these were hand-appended to the generated migration SQL — the one deliberate exception to an otherwise fully auto-generated schema.

• UNIQUE(round_id, candidate_id) means a candidate cannot insert a second rating for the same round. Not "the frontend disables the button" — the database rejects the insert.

• Every rating and review table has a status column, defaulting to pending, from the very first migration — before a moderation system existed to act on it. That's the subject of the next post in this series.

None of this is architecture for architecture's sake. It's what lets me say, honestly, that a company's aggregate score is built from real atomic rows that were never allowed to be malformed, duplicated, or invented — which turns out to matter enormously once you start asking "can I trust this number," which is exactly the question the next post is about.

Why this matters

A candidate who bombs a system design round because the interviewer couldn't articulate the problem deserves a system that can say that — separately from whether the algorithm question itself was hard, and separately from whatever their overall outcome was. A generic star rating erases that distinction entirely, which means it erases exactly the information a future candidate would find useful, and exactly the accountability a company would find uncomfortable. Building the schema to preserve that distinction from day one was the actual product decision. Everything else is implementation.

Next up: what happens to one of these ratings between the moment a candidate hits submit and the moment it's public — and why "never expose a real interviewer's name" had to be a schema decision, not a UI filter.