Quality management system for inspection and exceptions

This was a quality workstream inside the same broader internal operations platform as the shipping and visibility work. The transferable full-stack problem was state modeling: turn an ambiguous operational decision into a product boundary that downstream users could trust.

The old process was fragile because quality status was not just a quality-team detail. A hold could block shipment. A release could make inventory available. A rejection could create production follow-up. If the latest decision lived in a paper note, a spreadsheet cell, a message thread, or somebody's memory, the rest of the operation had to keep asking for confirmation.

Artifact note: screenshots, data examples, and code seams below are public-safe reconstructions of the production workflow. Actual UI, identifiers, customer data, and private table names are redacted; the state transitions, role boundaries, and current/history model reflect the implementation I owned.

What changed

Before:

1. A quality issue or inspection result was written on paper or sent through messenger/email.
2. Office users copied the result into Excel or checked with another person.
3. Inventory and shipment decisions depended on whether someone had the latest update.
4. Later questions required reconstructing who changed the status and why.

After:

1. A user opened the quality screen for the item, lot, box, or inspection context.
2. The React UI showed the current state, available actions, and required fields.
3. NestJS validated the transition, role, and required reason before save.
4. PostgreSQL updated the current record and appended a history event in the same transaction.
5. Production, inventory, and shipping users saw the updated state on the website instead of waiting for another Excel/email cycle.

Operational story

A typical failure case was a lot that looked physically ready but still had a quality exception. Before this module, someone might check the latest spreadsheet, ask the quality team, then message shipping to hold the item. The system changed that into a visible state: the record stayed blocked, the reason was attached to the item/lot/box, and the release path required a valid transition rather than another informal update.

The engineering value was not “CRUD for quality.” It was making hold, release, reject, and rework decisions explicit enough that the UI could guide the user, the API could reject invalid transitions, and the database could preserve both the current answer and the history behind it.

My ownership

I helped lead the work from process discovery through implementation. My scope included:

• mapping the quality process with operational users;
• co-designing the status model with the broader platform architecture;
• implementing React quality screens and API-connected flows;
• defining role-aware validation for allowed and blocked transitions;
• connecting quality records to PostgreSQL current/history data;
• supporting the system after launch when real use exposed unclear states or edge cases.

Artifact: state transition and record model

Artifact: implementation boundary

Simplified from the production service layer; names and identifiers are changed.

type QualityStatus =
  | "awaiting_inspection"
  | "passed"
  | "quality_hold"
  | "rework_required"
  | "rejected"
  | "released_to_shipping";

type QualityTransitionCommand = {
  entityType: "item" | "lot" | "box";
  entityId: string;
  nextStatus: QualityStatus;
  reasonCode?: "scratch" | "dimension" | "missing_label" | "customer_hold";
  note?: string;
  actorId: string;
  actorRole: "quality" | "supervisor" | "admin";
};

async function applyQualityTransition(command: QualityTransitionCommand) {
  return db.transaction(async (tx) => {
    const current = await tx.qualityCurrent.lockForUpdate(command.entityId);

    assertTransitionAllowed({
      from: current.status,
      to: command.nextStatus,
      actorRole: command.actorRole,
      reasonCode: command.reasonCode,
    });

    await tx.qualityCurrent.update(command.entityId, {
      status: command.nextStatus,
      activeException: command.nextStatus === "quality_hold",
      updatedBy: command.actorId,
    });

    return tx.qualityHistory.insert({
      entityId: command.entityId,
      fromStatus: current.status,
      toStatus: command.nextStatus,
      reasonCode: command.reasonCode,
      note: command.note,
      changedBy: command.actorId,
    });
  });
}

The frontend helped users choose valid actions, but the backend owned the transition. That kept the screen, the API, and the database record aligned.

Outcome

This module became part of daily production software serving office and factory-floor users.

• Quality status moved out of paper notes, messenger threads, Excel files, and email updates.
• Inspection, hold, release, and exception state became visible in the web system instead of depending on someone asking for the latest update.
• Inventory and shipping decisions had a clearer quality signal because state changes went through backend validation and durable current/history records.
• The reusable full-stack pattern was role-aware state transitions plus an audit trail, not just a data-entry screen.