DEV Community: Noah Chen

Deduplicating feature requests with pgvector: the threshold is a trap

Noah Chen — Wed, 12 Aug 2026 13:14:28 +0000

Two of our users asked for the same thing last month. One wrote "please add a way to export the report as a spreadsheet." The other wrote "CSV download for reports?" I filed them as separate requests, because I read them three weeks apart and did not connect them.

That is the whole problem with a feedback board. Duplicates do not announce themselves. They arrive slowly, in different words, and by the time you notice, the votes are split three ways and the one thing everybody wants looks like three things nobody cares much about.

I spent a weekend building semantic dedup for this, mostly to understand how it works before deciding whether to adopt something that already does it. Here is what I got wrong.

String matching does not survive contact with real users

The obvious first attempt is trigram similarity, which Postgres gives you for free:

CREATE EXTENSION IF NOT EXISTS pg_trgm;

SELECT title, similarity(title, 'CSV download for reports')
FROM feature_request
ORDER BY similarity(title, 'CSV download for reports') DESC
LIMIT 5;

On my two examples this scores about 0.13. They share almost no characters. Meanwhile "export report to PDF" scores higher than either, because it shares the words export and report while asking for something completely different.

Lexical similarity measures how things are spelled. Duplicate feature requests are duplicated in meaning and almost never in spelling, because two people describing the same frustration will reliably reach for different words.

Embeddings, and the setup that actually matters

The fix is to compare meaning, which means embeddings and pgvector.

CREATE EXTENSION IF NOT EXISTS vector;

ALTER TABLE feature_request ADD COLUMN embedding vector(1536);

CREATE INDEX ON feature_request
  USING hnsw (embedding vector_cosine_ops);

Two notes on that index, both of which cost me time.

HNSW builds slower and eats more memory than IVFFlat, but it does not need training data to be present before you build it. On a table that starts empty and grows one request at a time, IVFFlat's list centroids are computed from whatever happens to be there at build time, which for a new board is nothing useful. Use HNSW unless you are backfilling a large corpus in one shot.

The operator has to match the index. vector_cosine_ops pairs with <=>. If you build a cosine index and then query with <-> (L2 distance), Postgres will not error. It will silently do a sequential scan and you will conclude that pgvector is slow.

Embedding both the title and the body is worth it, but truncate:

const input = [title, body ?? ""].join("\n\n").slice(0, 8000);

const res = await openai.embeddings.create({
  model: "text-embedding-3-small",
  input,
});

Titles alone are too short to carry much signal. "Dark mode" and "Night theme" embed close together, but "Export" and "Download" do not, because a bare verb has almost no context to work with.

The threshold is a trap

Here is the part every tutorial skips. You will search for a cutoff, find someone saying 0.85 cosine similarity means duplicate, and hardcode it. It will not work, for two independent reasons.

Similarity scores are not comparable across text lengths. A pair of three-word titles and a pair of three-paragraph descriptions do not live on the same scale. Short texts cluster high, because there is less content to disagree about. If you tune your threshold on short requests, long ones will never trip it, and vice versa. In my data the same conceptual distance landed around 0.91 for title-only pairs and around 0.74 once bodies were included.

High similarity does not mean same request. This one is worse, because it fails in the direction that damages trust:

Pair	Cosine	Same request?
"Export to CSV" / "Export to Excel"	very high	No. Different file format, different work
"Dark mode" / "The UI burns my eyes at night"	moderate	Yes
"Add SSO" / "Add SAML login"	very high	Probably, but not certainly
"Slack integration" / "Discord integration"	very high	No. Not even close

Anything with a named entity in it breaks the assumption badly. Slack and Discord occupy nearly the same region of embedding space, and they are completely different pieces of work. A pure threshold merges them and you have just told two sets of users their request is the other one's request.

What I ended up with

Two changes, and the second matters more than the first.

Do not auto-merge. Suggest. Retrieve neighbours, show them to a human, let the human decide:

SELECT id, title, 1 - (embedding <=> $1) AS similarity
FROM feature_request
WHERE status <> 'merged'
ORDER BY embedding <=> $1
LIMIT 5;

No WHERE similarity > x clause at all. Rank, take the top handful, and put a person in the loop. The cost of a missed merge is a duplicate. The cost of a wrong merge is a user being told their idea is something it isn't.

Run it at submission time, not as a cleanup job. This is the actual insight, and it took me embarrassingly long to see. If you dedupe nightly, you are cleaning up a mess. If you run the same query while the user is still typing, and show "3 people asked for something similar" with the existing requests listed, a good fraction of them will click the existing one and upvote it instead of creating a new one.

The dedup problem is much easier to prevent than to solve. The same vector search, moved earlier by thirty seconds, changes from a fuzzy classification problem into a UI affordance.

On not building this

Having built it, I am not going to run it. It is a solved problem, my products are not feedback boards, and the maintenance is real: embeddings need backfilling when you change models, and model changes are not optional forever.

So I have been looking at what already implements it. Canny and Featurebase both do dedup, but their pricing scales with tracked users or admin seats. Fider is open source but is a feedback board only, with no roadmap or changelog attached. FeedLog is the closest to what I described here: MIT licensed, self-hostable, and it runs the similarity search at input time rather than as a batch job, which is the part I care about. Its hard dependency is Postgres 17 with pgvector, which will be unsurprising if you read this far. The AI features are optional; without an API key the board and voting still work, they just stop suggesting merges.

I am a few weeks into evaluating it, not a year, so treat that as a pointer rather than a recommendation.

The takeaway I would actually defend: if you are building this yourself, skip the threshold. Rank, show, and let a person press the button. And move it to the moment of submission, where it stops being a machine learning problem.

Designing a Reliable PDF Translation Job Pipeline in TypeScript

Noah Chen — Wed, 05 Aug 2026 03:57:55 +0000

Uploading a PDF and calling a translation model looks like a two-step feature. In production, it is a job pipeline with untrusted input, two different extraction paths, several expensive stages, and an output that can be fluent while still being wrong.

That distinction matters for a small SaaS team. The translation request may come from support, sales, or an internal operations task. Nobody wants to operate a document platform, but the workflow still needs to answer basic questions:

Was the upload actually a PDF?
Does the file contain selectable text or scanned page images?
Can a retry create a second charge or a conflicting result?
What happens when page 37 fails after the first 36 pages succeed?
How do we know the translated PDF is not blank or visually broken?
When are the source and result deleted?

The translation model is one component. Reliability comes from the system around it.

Define the Job Contract First

I would not let a file reach an extractor until the API has established a narrow contract.

For example, a translation request might include:

type TranslationStyle = "general" | "technical" | "academic";

interface CreateTranslationJob {
  uploadId: string;
  sourceLanguage: string | "auto";
  targetLanguage: string;
  style: TranslationStyle;
  idempotencyKey: string;
  containsRestrictedData: boolean;
}

The request should be rejected when the source and target languages are identical, the upload is missing, the target language is unsupported, or policy says the document cannot leave an approved environment.

File validation should also be explicit. Do not trust the filename or browser-supplied MIME type. Check at least:

the actual byte size;
the file signature;
whether the parser can open the document;
whether the PDF is encrypted;
the page count;
whether the job fits the account or product limit.

A 20 MB limit is simple to explain in a user interface, but size alone is not a good predictor of work. A compressed 200-page text PDF can be smaller than a six-page scan. Page count, image area, and extracted character count are better inputs for estimating processing time.

Treat Preflight as Its Own Stage

The first useful result is not a translation. It is a document profile.

interface DocumentProfile {
  pageCount: number;
  encrypted: boolean;
  extractedCharacters: number;
  pagesWithText: number;
  pagesWithLargeImages: number;
  likelyScanned: boolean;
  estimatedOcrPages: number;
}

This profile controls routing. A PDF where nearly every page has substantial selectable text can go directly to extraction. A document made of page-sized images needs OCR. Mixed documents need a page-level decision rather than a single flag for the entire file.

A crude scan heuristic could look like this:

function needsOcr(profile: DocumentProfile): boolean {
  if (profile.pageCount === 0) return false;

  const textCoverage = profile.pagesWithText / profile.pageCount;
  const imageCoverage = profile.pagesWithLargeImages / profile.pageCount;

  return textCoverage < 0.25 && imageCoverage > 0.6;
}

The thresholds are product decisions, not universal constants. A form can contain a small amount of real text over a scanned background. A research paper may include image-heavy appendix pages. Store the measurements that led to the route so a failed job can be explained later.

Model the Pipeline as States, Not Progress Percentages

A single processing: true field hides too much.

I would rather expose a finite set of states:

type JobState =
  | "queued"
  | "validating"
  | "extracting"
  | "ocr"
  | "translating"
  | "rendering"
  | "verifying"
  | "ready"
  | "failed"
  | "expired";

Each state should have a clear owner and output:

State	Responsibility	Durable output
`validating`	inspect the upload and policy	document profile
`extracting`	recover text and geometry	page blocks
`ocr`	recognize image-only pages	OCR blocks and confidence
`translating`	translate normalized blocks	translated segments
`rendering`	rebuild the destination PDF	candidate output
`verifying`	run structural checks	verification report
`ready`	expose a time-limited download	signed result reference

The state machine makes several bugs harder to create. A rendering worker cannot start before translation output exists. An expired job cannot silently return to ready. A retry can resume from the last durable stage instead of repeating the entire workflow.

Transitions should be enforced rather than implied:

const allowed: Record<JobState, JobState[]> = {
  queued: ["validating", "failed"],
  validating: ["extracting", "ocr", "failed"],
  extracting: ["ocr", "translating", "failed"],
  ocr: ["translating", "failed"],
  translating: ["rendering", "failed"],
  rendering: ["verifying", "failed"],
  verifying: ["ready", "failed"],
  ready: ["expired"],
  failed: [],
  expired: [],
};

function canTransition(from: JobState, to: JobState): boolean {
  return allowed[from].includes(to);
}

In a real system I would also record attempt, updatedAt, failureCode, and the worker version that produced each stage. That is enough to distinguish a bad document from a deployment regression.

Put Retry Boundaries Around Durable Work

Retries are necessary, but “retry the job” is too broad.

Uploading, OCR, translation, and rendering have different failure modes. A network timeout while writing the final PDF should not trigger OCR again. A transient translation-provider error should not require another upload. A user pressing the submit button twice should not create two independent jobs.

The idempotency key belongs at job creation. Stage-specific keys can be derived from the job and input version:

function stageKey(
  jobId: string,
  stage: JobState,
  inputVersion: number,
): string {
  return `${jobId}:${stage}:${inputVersion}`;
}

Workers should write their result before advancing the state. If the process stops between those operations, the next worker can see the existing stage output and continue safely.

Retries also need limits. OCR on a malformed image is unlikely to improve on attempt 12. Use stable failure codes such as PDF_ENCRYPTED, OCR_LOW_CONFIDENCE, TRANSLATION_TIMEOUT, and RENDER_OVERFLOW. They are more useful to support than a stack trace alone.

Translation Units Need Stable Identity

Sending one entire document as a string loses layout relationships. Sending every line independently loses context.

A practical middle ground is a collection of blocks with stable IDs:

interface TextBlock {
  id: string;
  page: number;
  role: "heading" | "paragraph" | "caption" | "table-cell" | "footer";
  sourceText: string;
  translatedText?: string;
  bounds: { x: number; y: number; width: number; height: number };
  ocrConfidence?: number;
}

Stable IDs make it possible to retry one segment, preserve repeated headers, compare source and translation, and point a human reviewer to a specific page and region.

Context can be supplied by grouping adjacent blocks or attaching a document glossary. The glossary should protect product names, UI labels, units, and phrases that must remain unchanged. It is also the right place to keep reviewer-approved terminology between versions.

Verification Is More Than “The File Opens”

A translated PDF can be syntactically valid and unusable.

Automated verification should look for structural signals:

output page count differs unexpectedly from the source;
pages contain no text or images;
translated blocks are missing;
text extends outside its assigned bounds;
a table has a different number of rows or cells;
a required font lacks glyphs for the target language;
hyperlinks disappeared;
OCR confidence is below a review threshold;
numbers present in the source are absent from the translated block.

These checks do not prove semantic accuracy. They decide whether the result is safe to show as an ordinary completion or should be flagged for review.

For customer-facing, legal, medical, financial, or safety-related documents, a human review is not an optional fallback. The workflow should make that requirement visible instead of letting a fluent result imply certification.

Retention Is Part of the Data Model

Document pipelines tend to become accidental archives.

The source upload, extracted text, OCR images, model inputs, intermediate render, and final file may all exist in different systems. Deleting only the public download does not remove the job data.

Every artifact should carry a retention class and expiry:

interface StoredArtifact {
  key: string;
  kind: "source" | "extracted" | "ocr" | "translated" | "result";
  deleteAfter: string;
  encrypted: boolean;
}

Use short-lived signed URLs for downloads. Run deletion as an observable job. Record completion without keeping the deleted content. If business users need a permanent copy, make them move it into the approved system of record rather than silently extending temporary storage.

Make Operations Visible

A progress bar is useful to the person waiting, but it is not enough for the team operating the workflow.

I would track metrics by stage and route:

validation failures by reason;
percentage of pages sent to OCR;
median and high-percentile duration for extraction, OCR, translation, and rendering;
retries and terminal failures by worker version;
output files flagged for human review;
deletion jobs completed after their deadline;
jobs abandoned before download.

These measurements answer different questions. A sudden increase in OCR pages may indicate a change in customer inputs. Longer rendering time after a deployment points toward layout code, not the translation provider. A high completion rate with a low download rate may mean results expire too quickly or the notification step is unreliable.

Logs should carry the job ID, stage, attempt, and block or page range, but not extracted document text by default. Document contents make debugging tempting and data handling much harder. Store diagnostic metadata first; collect a redacted sample only through an explicit support path.

Build, Run Locally, or Use a Hosted Workflow?

Not every team should build this pipeline.

Building makes sense when translation is part of the product, jobs repeat at scale, restricted documents are involved, or the team needs precise control over models, audit logs, and retention. Local tools are attractive when a technical operator can process sensitive files without uploading them.

For an occasional public or synthetic document, a hosted interface can remove a lot of setup. PDFTranslator is one example: it supports OCR, more than 100 languages, and translation styles, with a 20 MB upload limit and a stated free allowance of 1,000 pages per calendar month. It is still a cloud workflow. Its homepage says task files are deleted within 24 hours, which is useful operational information but not a reason to upload restricted material without an approved policy.

That tradeoff is the important part. Convenience changes who operates the pipeline; it does not remove the need to classify the document or review the result.

A Production-Readiness Checklist

Before calling a PDF translation workflow reliable, I would want clear answers to these questions:

Do we validate file contents rather than extensions?
Can we route text, scanned, and mixed PDFs differently?
Are job states and legal transitions explicit?
Are retries idempotent and limited to the failed stage?
Can we trace translated blocks back to source regions?
Do we verify page structure, overflow, fonts, tables, links, and numbers?
Can the system require human review instead of merely suggesting it?
Does every stored artifact have a deletion rule?
Can support explain a failure without reading worker logs?
Have we decided which documents are allowed to leave the device?

The model call may be the most visible part of translation, but it is not the system. The system is the set of boundaries that keeps an untrusted document, a long-running process, and a persuasive-looking output from creating a quiet operational failure.

Compressing Video to a Target File Size: The Bitrate Math in TypeScript

Noah Chen — Mon, 03 Aug 2026 09:39:39 +0000

A practical calculator for turning an upload limit into a video bitrate, with enough margin for audio and container overhead.

“Make this video smaller” is an open-ended request. “Make this three-minute video fit under 10 MB” is an engineering constraint.

The second version sounds more precise, but a quality slider alone cannot solve it. A quality setting tells an encoder how aggressively to preserve detail. It does not directly tell us how many bytes the final file may contain. If the destination has a hard upload limit, the useful starting point is a bit budget.

This article builds that calculation in TypeScript, then looks at the assumptions that make the answer less exact than the formula first appears.

File Size Is Bitrate Multiplied by Time

A video file contains several streams plus a container. For a simple MP4, the largest pieces are usually:

the video stream;
the audio stream;
container metadata and indexing overhead.

If we ignore overhead for a moment, the relationship is straightforward:

file size in bits = total bitrate in bits per second × duration in seconds

Rearranging it gives us the total bitrate available for a target size:

total bitrate = target size in bits / duration in seconds

That total must cover both video and audio. The approximate video budget is therefore:

video bitrate = total bitrate - audio bitrate - overhead allowance

The result is not a promise. It is a budget that an encoder can aim at.

Be Explicit About MB and MiB

Before writing code, decide what “10 MB” means.

Storage vendors and many web services use decimal megabytes:

1 MB = 1,000,000 bytes

Operating systems and developer tools often display binary mebibytes:

1 MiB = 1,048,576 bytes

The difference is about 4.9%. That is large enough to turn a file that looks safe locally into a rejected upload. For a hard external limit, I prefer to calculate with decimal MB and keep an additional safety margin. For an internal tool where the unit is clearly MiB, I make that choice explicit in the function name or input type.

A Small TypeScript Calculator

The function below accepts a decimal target size, duration, audio bitrate, container allowance, and safety margin. It returns the video bitrate to pass to an encoder.

type BitrateBudgetInput = {
  targetMB: number;
  durationSeconds: number;
  audioKbps?: number;
  containerOverheadFraction?: number;
  safetyMarginFraction?: number;
};

type BitrateBudget = {
  totalKbps: number;
  usableKbps: number;
  audioKbps: number;
  videoKbps: number;
};

export function calculateVideoBitrate({
  targetMB,
  durationSeconds,
  audioKbps = 96,
  containerOverheadFraction = 0.02,
  safetyMarginFraction = 0.03,
}: BitrateBudgetInput): BitrateBudget {
  if (!Number.isFinite(targetMB) || targetMB <= 0) {
    throw new RangeError("targetMB must be greater than zero");
  }

  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
    throw new RangeError("durationSeconds must be greater than zero");
  }

  const targetBits = targetMB * 1_000_000 * 8;
  const totalKbps = targetBits / durationSeconds / 1_000;

  const reservedFraction =
    containerOverheadFraction + safetyMarginFraction;

  if (reservedFraction < 0 || reservedFraction >= 1) {
    throw new RangeError("reserved fractions must total less than one");
  }

  const usableKbps = totalKbps * (1 - reservedFraction);
  const videoKbps = Math.floor(usableKbps - audioKbps);

  if (videoKbps <= 0) {
    throw new RangeError(
      "The target is too small for this duration and audio bitrate",
    );
  }

  return {
    totalKbps: Math.floor(totalKbps),
    usableKbps: Math.floor(usableKbps),
    audioKbps,
    videoKbps,
  };
}

For a three-minute video with a 10 MB limit:

const budget = calculateVideoBitrate({
  targetMB: 10,
  durationSeconds: 180,
  audioKbps: 96,
});

console.log(budget);

The raw total is roughly 444 kbps. After reserving 5% for overhead and safety, then allocating 96 kbps to audio, the video stream receives about 326 kbps.

That is a tight budget. It may be acceptable for a mostly static 720p screen recording. It will probably look rough for fast camera movement at 1080p. The calculator can tell us whether the numbers fit. It cannot decide whether the visual result is useful.

Add Tests Around the Boundary Conditions

The arithmetic is simple enough that the most valuable tests are about invalid or unrealistic inputs.

import { describe, expect, it } from "vitest";
import { calculateVideoBitrate } from "./bitrate-budget";

describe("calculateVideoBitrate", () => {
  it("returns a positive video budget", () => {
    const result = calculateVideoBitrate({
      targetMB: 25,
      durationSeconds: 120,
      audioKbps: 96,
    });

    expect(result.videoKbps).toBeGreaterThan(0);
    expect(result.videoKbps).toBeLessThan(result.totalKbps);
  });

  it("rejects a zero duration", () => {
    expect(() =>
      calculateVideoBitrate({ targetMB: 10, durationSeconds: 0 }),
    ).toThrow(RangeError);
  });

  it("rejects an impossible audio allocation", () => {
    expect(() =>
      calculateVideoBitrate({
        targetMB: 1,
        durationSeconds: 600,
        audioKbps: 128,
      }),
    ).toThrow(RangeError);
  });
});

An impossible result is useful information. It means at least one constraint must change: shorten the video, increase the file limit, lower the audio bitrate, remove audio, reduce resolution, or accept visibly lower quality.

Why Two-Pass Encoding Gets Closer

A constant bitrate is easy to reason about, but real video does not have constant complexity. A static product screen needs fewer bits than a transition, scrolling page, or camera pan.

Two-pass encoding uses the first pass to analyze where complexity occurs. The second pass spends more of the fixed budget on difficult sections and less on easy ones. It is therefore a sensible choice when file size matters more than encoding speed.

A simplified FFmpeg flow looks like this:

ffmpeg -y -i input.mp4 \
  -c:v libx264 -b:v 326k -pass 1 -an \
  -f mp4 /dev/null

ffmpeg -i input.mp4 \
  -c:v libx264 -b:v 326k -pass 2 \
  -c:a aac -b:a 96k output.mp4

On Windows, the first command uses NUL instead of /dev/null. A production wrapper should also remove the pass-log files and handle failed processes.

Even two-pass encoding can miss an exact target because of muxing overhead, encoder behavior, subtitles, metadata, and rounding. That is why the calculator keeps a safety margin instead of aiming at the final byte.

Codec Choice Changes the Quality, Not the Budget

If the target size and duration are fixed, the total bitrate is fixed too. Switching from H.264 to H.265 does not create a larger bit budget. It tries to produce better visual quality with the same budget.

That tradeoff includes compatibility and encoding cost:

H.264 is widely supported and usually encodes faster.
H.265 can preserve more detail at low bitrates, especially at higher resolutions.
Older browsers, devices, or editing workflows may not handle H.265 as predictably.
Re-encoding an already compressed file can introduce additional artifacts regardless of codec.

For a file that must play everywhere, H.264 may be the safer result. For a controlled playback environment and a severe size limit, H.265 may be worth testing.

Resolution Is Often the Most Honest Lever

At some point, there are not enough bits to describe every pixel well.

Trying to keep 4K resolution at a few hundred kilobits per second usually produces a file that is technically 4K but visually worse than a clean 720p version. Downscaling reduces the number of pixels the encoder must describe and can improve perceived quality at the same file size.

For product videos, I use a simple decision order:

Remove dead time and unnecessary scenes.
Keep only the audio quality the content needs.
Calculate the available video bitrate.
Choose a resolution appropriate for that bitrate and viewing context.
Encode with a safety margin.
Inspect text, cursor movement, transitions, and other high-risk frames.

The final inspection matters. A passing file-size check does not mean small interface text remains readable.

When Not to Build the Pipeline

The TypeScript function is useful when compression is part of a repeatable system: an upload service, media queue, desktop tool, or CI job. In that situation, controlling the encoder and recording the exact settings are worth the engineering effort.

For an occasional file, maintaining that pipeline may cost more time than it saves. A browser-based tool such as VideoCompress exposes target-size and advanced controls without requiring a local FFmpeg workflow. The tradeoff is that processing happens in the cloud, so upload time and data sensitivity matter. Its free account also uses monthly credits rather than offering unlimited processing.

That distinction is the practical one: automate recurring workloads; use a focused interface for one-off work; keep sensitive media local.

Treat the Formula as a Constraint, Not a Quality Score

Target-size compression becomes easier to reason about once the upload limit is translated into a bit budget. The arithmetic tells us what is possible. The encoder decides how to distribute those bits. Human inspection determines whether the result is acceptable.

Those are three separate jobs.

A small calculator prevents impossible settings from reaching the encoder and makes tradeoffs visible before a long job starts. It also replaces the vague instruction to “compress it more” with better questions: Can we shorten it? Can we reduce resolution? Is the audio budget too high? Does compatibility require H.264? Is this recurring enough to automate?

That is usually where a reliable video workflow begins.

Modeling Product Feedback as a State Machine in TypeScript

Noah Chen — Tue, 28 Jul 2026 10:11:04 +0000

A small domain model for keeping feedback status, roadmap visibility, release events, and customer notifications consistent.

Product feedback looks like a list until people begin making decisions about it.

A new request is reviewed. A reviewed problem may be planned, declined, or left open for more evidence. Planned work becomes active. A shipped change needs a release note and a notification to the people who cared about it.

If these transitions are implemented as arbitrary string updates, contradictory states appear quickly:

a declined request remains on the “In Progress” roadmap;
an item moves from shipped back to new without explanation;
users are notified before a release is public;
two processes write different statuses for the same request;
a popular request is treated as automatically planned.

A small state machine makes those rules explicit. This article builds one in TypeScript without adding a state-machine library.

Define States Around Decisions

The first temptation is to mirror every UI label. A better starting point is to model meaningful product decisions.

export type FeedbackStatus =
  | "new"
  | "reviewing"
  | "planned"
  | "in_progress"
  | "shipped"
  | "declined";

These states answer different questions:

new: captured but not triaged;
reviewing: understood well enough to evaluate;
planned: accepted as intended work, without necessarily promising a date;
in_progress: active delivery work exists;
shipped: a released change addresses the problem;
declined: the team made a decision not to pursue it.

The names are less important than their meaning. If two teammates interpret planned differently, TypeScript cannot save the roadmap.

Document the contract first: which decision each state communicates internally and publicly.

Make Legal Transitions Explicit

Not every move should be allowed.

const allowedTransitions: Record<
  FeedbackStatus,
  readonly FeedbackStatus[]
> = {
  new: ["reviewing", "declined"],
  reviewing: ["planned", "declined"],
  planned: ["reviewing", "in_progress", "declined"],
  in_progress: ["planned", "shipped"],
  shipped: [],
  declined: ["reviewing"],
};

export function canTransition(
  from: FeedbackStatus,
  to: FeedbackStatus,
): boolean {
  return allowedTransitions[from].includes(to);
}

This is deliberately conservative.

A declined request can reopen when new evidence appears. Planned work can return to review if assumptions change. Work in progress can return to planned if delivery pauses.

shipped is terminal in this model. That does not mean software can never regress. It means a shipped outcome remains historical fact. If a regression or new problem appears, create a new record rather than rewriting history.

Your product may need different rules. The important thing is to make exceptions deliberate instead of allowing any status string to replace any other.

A Transition Needs Context

Changing a status is a product decision, not only a database update.

export interface TransitionCommand {
  feedbackId: string;
  from: FeedbackStatus;
  to: FeedbackStatus;
  actorId: string;
  reason: string;
  occurredAt: Date;
  releaseId?: string;
}

The reason field preserves why the decision changed. It can feed an internal audit log and a shorter public explanation.

The optional releaseId becomes required when something moves to shipped. That rule can live in validation:

export class InvalidFeedbackTransition extends Error {}

export function validateTransition(command: TransitionCommand): void {
  if (!canTransition(command.from, command.to)) {
    throw new InvalidFeedbackTransition(
      `Cannot move feedback from ${command.from} to ${command.to}`,
    );
  }

  if (!command.reason.trim()) {
    throw new InvalidFeedbackTransition(
      "A status change requires a reason",
    );
  }

  if (command.to === "shipped" && !command.releaseId) {
    throw new InvalidFeedbackTransition(
      "Shipped feedback must reference a release",
    );
  }
}

Requiring a reason may feel strict for a small team. In practice, a single sentence is enough. The small cost now prevents a much larger reconstruction later.

Keep Votes Out of the Transition Rules

Votes are evidence, not authority.

This is an anti-pattern:

if (feedback.voteCount >= 20) {
  feedback.status = "planned";
}

The rule ignores customer segment, severity, strategy, cost, confidence, and the possibility that several high-vote requests describe the same underlying problem.

Votes belong in the decision context:

export interface FeedbackEvidence {
  voteCount: number;
  affectedAccountIds: string[];
  segments: string[];
  examples: Array<{
    source: "email" | "support" | "discord" | "github" | "board";
    summary: string;
  }>;
}

An application service can present this evidence to the decision-maker. It should not silently turn popularity into a roadmap promise.

Separate Persistence From Domain Logic

The state machine should not know whether data lives in Postgres, a document database, or an API.

export interface FeedbackRecord {
  id: string;
  status: FeedbackStatus;
  version: number;
}

export interface FeedbackRepository {
  getById(id: string): Promise<FeedbackRecord | null>;
  save(
    record: FeedbackRecord,
    expectedVersion: number,
  ): Promise<void>;
}

The version enables optimistic concurrency. Without it, two people can review the same request, make different decisions, and overwrite each other.

export interface DomainEvent {
  type: string;
  aggregateId: string;
  occurredAt: Date;
  payload: Record<string, unknown>;
}

export interface EventOutbox {
  append(event: DomainEvent): Promise<void>;
}

Now the application service can enforce transitions and record an event:

export async function transitionFeedback(
  command: Omit<TransitionCommand, "from">,
  repository: FeedbackRepository,
  outbox: EventOutbox,
): Promise<void> {
  const current = await repository.getById(command.feedbackId);

  if (!current) {
    throw new Error("Feedback record not found");
  }

  const transition: TransitionCommand = {
    ...command,
    from: current.status,
  };

  validateTransition(transition);

  await repository.save(
    {
      ...current,
      status: command.to,
      version: current.version + 1,
    },
    current.version,
  );

  await outbox.append({
    type: "feedback.status_changed",
    aggregateId: current.id,
    occurredAt: command.occurredAt,
    payload: {
      from: current.status,
      to: command.to,
      actorId: command.actorId,
      reason: command.reason,
      releaseId: command.releaseId,
    },
  });
}

In production, the record update and outbox insert should share one database transaction. Otherwise a process can save the new state and crash before creating the event.

Derive Roadmap Visibility Instead of Storing It Twice

If roadmap columns directly mirror feedback status, derive them from the state machine.

export type RoadmapColumn =
  | "open"
  | "planned"
  | "in_progress"
  | "shipped";

export function roadmapColumnFor(
  status: FeedbackStatus,
): RoadmapColumn | null {
  switch (status) {
    case "reviewing":
      return "open";
    case "planned":
      return "planned";
    case "in_progress":
      return "in_progress";
    case "shipped":
      return "shipped";
    case "new":
    case "declined":
      return null;
  }
}

This prevents the roadmap and feedback record from disagreeing.

Some products need a separate visibility setting. A private customer request might be planned without appearing publicly. In that case, store visibility as an independent decision:

export interface PublicFeedbackView {
  isPublic: boolean;
  publicTitle?: string;
  publicExplanation?: string;
}

Do not overload status to represent privacy.

Notify on a Published Outcome, Not Just a Status

Moving feedback to shipped does not necessarily mean users should receive an email immediately. The team may still be preparing documentation or a changelog entry.

Model publication as a separate event:

export interface ChangelogPublished {
  type: "changelog.published";
  aggregateId: string;
  occurredAt: Date;
  payload: {
    releaseId: string;
    feedbackIds: string[];
  };
}

A notification worker can consume that event:

export async function handleChangelogPublished(
  event: ChangelogPublished,
  subscriptions: SubscriptionRepository,
  notifications: NotificationQueue,
): Promise<void> {
  const recipients = await subscriptions.listUniqueRecipients(
    event.payload.feedbackIds,
  );

  for (const recipient of recipients) {
    await notifications.enqueue({
      deduplicationKey:
        `${event.payload.releaseId}:${recipient.userId}`,
      userId: recipient.userId,
      releaseId: event.payload.releaseId,
    });
  }
}

The deduplication key matters when one person voted on several requests addressed by the same release. It also makes retrying the event consumer safer.

Add Invariants Before Adding More States

Tests should describe behavior, not merely lines of code.

import { describe, expect, it } from "vitest";

describe("feedback transitions", () => {
  it("does not let popularity create a commitment", () => {
    expect(canTransition("new", "planned")).toBe(false);
  });

  it("lets new evidence reopen a declined problem", () => {
    expect(canTransition("declined", "reviewing")).toBe(true);
  });

  it("preserves shipped outcomes as history", () => {
    expect(canTransition("shipped", "in_progress")).toBe(false);
  });

  it("requires a release before marking feedback shipped", () => {
    expect(() =>
      validateTransition({
        feedbackId: "fb_123",
        from: "in_progress",
        to: "shipped",
        actorId: "user_42",
        reason: "Released scheduled reports",
        occurredAt: new Date(),
      }),
    ).toThrow("must reference a release");
  });
});

Useful invariants include:

every status change records an actor and reason;
shipped feedback references a release;
a public roadmap view is derived consistently;
publishing one release sends at most one notification per person;
duplicate requests retain their original authors and evidence;
votes never trigger a product commitment automatically.

These rules provide more value than adding a dozen finely named states.

Build It or Adopt It?

This model is small enough to implement internally. The question is whether the surrounding workflow is also something your team wants to own.

A production feedback system eventually needs authentication, public and private boards, voting, comments, duplicate handling, roadmap views, changelog publishing, subscriptions, email delivery, moderation, and export.

If your requirements are narrow, building only the state machine may be the right choice. A spreadsheet may be even better when volume is low.

I have been evaluating FeedLog as one existing implementation of the broader workflow. It connects feedback boards, roadmap states, releases, and notifications, while keeping its AI-assisted duplicate detection optional.

The project is self-hostable, which is useful only if your team accepts the operational responsibility. You still need to manage PostgreSQL, backups, upgrades, authentication settings, storage, and an email provider for real notifications.

For developers, the better evaluation surface is FeedLog’s GitHub repository. The code and deployment configuration show what the application currently implements and which services it expects, rather than asking you to infer the architecture from a feature page.

Keep the Machine Smaller Than the Problem

A state machine is a tool for making decisions explicit. It should not become a substitute for product judgment.

Start with the few states that change what the team communicates or does next. Require context for transitions. Keep votes in the evidence layer. Derive public views where possible. Emit reliable events for the work that must follow a decision.

Most importantly, model the complete loop.

Capturing a request without preserving the decision creates a list. Recording a decision without connecting a release creates a roadmap. Shipping a release without notifying the original participants leaves the relationship unfinished.

The state machine earns its complexity when it helps the team move from evidence to decision to outcome without losing the people who supplied the evidence.