SCA Grading System Documentation

Complete guide for using the catalytic converter grading system

Quick Start

For Graders (End Users)

  1. Click on the grading link provided to you
  2. Wait for images to load (this may take a moment)
  3. A guided tour will appear on your first visit — follow it or skip to start grading
  4. Review each catalytic converter image carefully
  5. Select your grading decision using the grade buttons on each card, or tap the image to open a larger view
  6. Use keyboard shortcuts (1-5) in the expanded view for faster grading
  7. Submit your grades when complete using the bottom action bar

For Administrators

  1. Access the Admin Panel
  2. Generate grading sessions for users (single or bulk)
  3. Share the generated links with graders
  4. Monitor session status, approve or request regrades
  5. Review grading results in Reports

System Overview

The SCA Grading Confirmation System is a web-based application for reviewing and grading catalytic converter images. It uses session-based authentication to provide secure, temporary access to grading interfaces. ML models (King and Dente) provide automated predictions that graders can reference during manual review.

Key Features

  • Session-based authentication (no passwords needed)
  • Mobile-responsive grading interface
  • Multiple grading categories (AM, OEM, Foil, Diesel, LOT, Unit)
  • ML predictions from King and Dente models
  • Keyboard shortcuts for fast grading
  • Auto-save progress with local storage
  • Batch grade submission with optimistic updates
  • Real-time progress tracking
  • Interactive product tour for onboarding
  • Dark mode support
  • CSV export for reports

Security

  • UUID-based session tokens
  • Configurable session expiration
  • Session deactivation capability
  • No sensitive data in client storage
  • Input validation and sanitization
  • API request timeouts with AbortSignal
  • Error boundaries on all routes

User Guide

Grading Interface

The grading page has four main areas:

Sticky Header

Shows your session ID, category, and a progress bar. Tap the chevron to expand details including ML model accuracy scores and prediction summaries.

Image Grid

Thumbnail cards arranged in a responsive grid. Each card shows the image, grade buttons, and any existing grade. Tap the image to open it in a larger modal view.

Image Modal

Expanded view with zoom, pan, and rotate controls. Navigate between images with arrow keys. Grade with number keys. Close with Escape.

Bottom Action Bar

Always-visible bar showing graded count, submit button, and actions like Clear, Regrade, and Approve.

Tips for Accurate Grading

  • Take time to examine each image carefully
  • Look for manufacturer markings and part numbers
  • Consider the overall condition and appearance
  • Reference the ML predictions (King/Dente) when available, but use your own judgment
  • Use “?” when uncertain rather than guessing
  • Use the expanded image modal for difficult images — zoom and rotate as needed
  • Your progress auto-saves, so you can close and return later

Session Behavior

  • Sessions are temporary and will expire based on administrator settings
  • Your progress is automatically saved to local storage as you work
  • You can close and reopen your session link to continue where you left off
  • A warning dialog appears if you try to leave the page with unsaved changes
  • Once submitted, grades are sent for review
  • Contact your administrator if you encounter any issues

Dark Mode

Toggle between light and dark themes using the sun/moon icon in the navigation bar. Your preference is saved and persists across sessions. The system also respects your OS-level color scheme preference.

Grading Categories

The system supports multiple grading categories. The buttons shown during grading depend on the session's category setting.

Aftermarket (AM)

AMNot AM?Not CatBad Pic

OEM

OEMAM?Not CatBad Pic

Foil

FoilNot Foil?

Diesel

DieselNot Diesel?

IR LOT & Unit

Used for IR Grade sessions. LOT sessions show ML prediction data (King and Dente models) alongside each image for reference.

AMOEMDieselFoil?Not CatBad Pic

Keyboard Shortcuts

Keyboard shortcuts are available when the image modal is open, allowing fast grading without using the mouse.

KeyAction
1 - 5Select grade (corresponds to the grade button order)
← →Navigate to previous / next image
EscClose the image modal

Session Management

Creating Sessions

Single Session

  1. Click “+ Generate New Link” in the admin panel
  2. Enter user identifier (email recommended)
  3. Select a grading category
  4. Set expiration period (1-30 days)
  5. Click “Generate Link”
  6. Copy and share the generated link

Bulk Sessions

  1. Enter multiple user identifiers (one per line)
  2. Select category and expiration period
  3. Click “Generate Bulk Links”
  4. Copy individual links from the generated list

IR LOT Sessions

IR LOT sessions are created by searching for a 4-character LOT code. The system fetches all units in that LOT and creates a grading session with ML predictions from King and Dente models.

  1. Click “IR Grade” in the admin panel
  2. Enter a 4-character LOT code
  3. Review the category breakdown
  4. Generate grading links for specific categories or all units

Session Statuses

PendingSession is active and awaiting grading
For ReviewGrades submitted, awaiting admin review
ApprovedGrades reviewed and approved by admin
RegradeSession sent back for regrading

Managing Sessions

  • Search: Filter the sessions table by session ID, email, category, or LOT code
  • Copy Links: Copy session UUIDs or grading links to share with users
  • Delete Sessions: Remove sessions that are no longer needed
  • Refresh: Reload the sessions list to see the latest status changes

Reports

The Reports page provides a comprehensive view of all graded images across sessions, with ML predictions and grader-level detail.

Summary Cards

Three KPI cards at the top show: Total Images (all graded images), Unique Graders (number of people who have graded), and Grade Categories (distinct grade values used).

Filtering & Search

  • Search: Free-text search across unit codes, grader emails, and grade values
  • Grader filter: Show only images graded by a specific person
  • Grade filter: Show only images with a specific grade value
  • View toggle: Switch between Table and Grid layouts

Data Table

The table shows each image with its unit code, King and Dente ML predictions with confidence scores, Master Tag (consensus grade), grader count, and individual grader columns. Click column headers to sort.

Click any image thumbnail to open a detail modal with zoom/pan/rotate controls, full prediction data, and grader details.

CSV Export

Click “Export Excel” to download the report as a CSV file. The export includes all columns visible in the table. When filters or sorting are active, the export reflects the filtered/sorted data.

Grade Changes

Authorized graders can change grades directly from the reports page by clicking on a grade badge. A popover appears with all available grade options. Changes are saved immediately.

Product Tour

Each major section of the application includes an interactive guided tour that highlights key features and explains how to use them.

Available Tours

  • Grading Tour (4 steps) — Covers the session header, progress bar, image grid, and submit bar
  • Admin Tour (3 steps) — Covers sessions overview, link generation, and session monitoring
  • Reports Tour (6 steps) — Covers the reports header, summary cards, filters, data table, pagination, and CSV export

How It Works

  • First visit: The tour automatically appears after a short delay
  • Navigation: Use Next/Back buttons, arrow keys, or Enter to navigate steps
  • Skip: Press Skip or Escape to close the tour at any time
  • Replay: Click the “How It Works” button in the page header to restart the tour
  • Persistence: Tour completion is saved in your browser — it won't auto-start again after you finish or skip it

API Reference

Session Endpoints

# Create Grading Pad
POST /api/ir-grading-pad
Content-Type: application/json

{
  "user_identifier": "user@example.com",
  "expires_in_days": 7,
  "category": "am",
  "metadata": {
    "created_by": "admin-interface"
  }
}

# Validate Session
GET /api/ir-grading-pad/{sessionId}

# Update Session Status
POST /api/ir-grading-pad/{sessionId}/status
Content-Type: application/json

{
  "status": "approved",
  "password": "..."
}

Grading Endpoints

# Submit Batch Grades
POST /api/ir-grading-pad/{sessionId}/grade
Content-Type: application/json

{
  "grades": [
    {
      "image_name": "catalytic_001.jpg",
      "box_uid": "12345",
      "grade": "AM",
      "catalytic_id": 1
    }
  ]
}

Reports Endpoint

# Fetch Report Page
GET /api/ir-grading-pad/report?page=1&limit=50

# Response includes:
# - total_images, total_pages, has_more
# - images[] with unit_code, king/dente predictions,
#   master_tag, graders[], image_url

Troubleshooting

Common Issues

“Session not found” Error

  • Check that the session URL is complete and unmodified
  • Verify the session hasn't expired
  • Contact administrator to check session status

Images Not Loading

  • Check internet connection
  • Try the “Reload Failed Images” button in the session header
  • Clear browser cache and cookies
  • Try a different browser or device

Grade Submission Failed

  • Check network connection
  • Your progress is auto-saved locally — try submitting again
  • If the session status is not “Pending”, you may need a regrade
  • Contact administrator if problem persists

Reports Not Loading

  • The first load may take a moment as data is fetched
  • Applying filters requires fetching all data — be patient on large datasets
  • Try clearing filters and refreshing the page

Getting Help

If you need assistance:

  • Click “How It Works” on any page to replay the interactive tour
  • Contact your system administrator
  • Provide your session ID when reporting issues
  • Include any error messages you see
  • Note the time when the issue occurred

System Architecture

Technology Stack

Frontend

  • Next.js 16 (App Router)
  • TypeScript (Type Safety)
  • Tailwind CSS 4 (Styling with CSS custom properties)
  • React Query / TanStack Query (Server State)
  • Vitest (Testing)

Backend & Infrastructure

  • IRML API (Grading pads, predictions)
  • SCA API (Image lookup, lot units)
  • MySQL 8.0+ (Database)
  • CDN (Image Storage)
  • Next.js API Routes (Proxy Layer)

ML Predictions

Two ML models provide automated classification predictions:

  • King: Primary classification model with confidence scores
  • Dente: Secondary classification model for cross-validation

Predictions are polled every 15 seconds during grading sessions and include category labels with confidence percentages.

Data Flow

1. Admin creates grading pad → IRML API → Database
2. User accesses grading link → Session validation via IRML API
3. Catalytic data loaded → Images served from CDN
4. ML predictions fetched → King & Dente models polled
5. Grades saved locally → Auto-save to localStorage
6. Grades submitted → IRML API → Database
7. Admin reviews → Approve / Regrade / Export

Frontend Architecture

  • Design System: CSS custom properties for surfaces, borders, text, semantic colors, typography, and radii — with full dark mode support
  • Component Library: Modal (with focus trap), Toast notifications, ProductTour, NavBar, ThemeProvider
  • State Management: React Query for server state, React state + localStorage for client state
  • Error Handling: Error boundaries on all routes, structured API error responses, user-friendly error messages
  • Testing: Vitest with jsdom environment, unit tests for constants, API handlers, and transform functions
SCA Grading Confirmation System Documentation
Last updated: September 2026