Service architecture

Recommended service architecture

Start simple, but keep production boundaries clean.

Frontend / Discord / TCGMarketPulse
  → API layer
    → analysis_jobs table
    → artifact store
    → worker queue
      → image quality module
      → card detector
      → rectifier
      → layout classifier
      → measurement module
      → rules evaluator
      → overlay renderer
  → report endpoint / PulseLine reply

The browser should never call the vision worker directly with privileged paths or credentials. Frontend uploads go through an API layer that validates, stores, enqueues, and returns a job id.

Model strategy

Avoid premature ML complexity.

MVP: OpenCV contour + homography + manual handles.
Beta: card layout classifier for Pokémon card families.
V1: segmentation model for inner-boundary detection on complex cards.
V2: calibration by card era, finish, language, and capture device.

Result state machine

Important for user trust and clean UX.

Status	Meaning	User-facing behavior
received	Image accepted and job created	Show queued/processing state.
needs_retake	Quality gate failed	Give specific retake instructions.
needs_manual_adjustment	Outer or inner boundary uncertain	Show overlay handles or request operator review.
measured	Ratios calculated successfully	Show measurements, overlay, and confidence.
interpreted	Rules engine completed	Show grader eligibility matrix.
failed	Unexpected processing error	Friendly retry message; log debug detail internally.