Credit Deduction Lifecycle & Auto-Refunds

Centralized Transactional Ledger

BestShots manages credit accounting through a centralized transactional ledger pattern (ADR 0001) implemented in @bestshots/shared/CreditService.

This architecture prevents race conditions, double-charging, and balance discrepancies during concurrent batch operations.

---

The Credit Deduction Lifecycle

1. Email Verification Guard: New accounts receive 100 free credits. The credit ledger enforces email verification before allowing credit consumption to prevent abuse.
2. Atomic Deduction on Queue: When a photographer triggers AI analysis, credits are atomically deducted in a PostgreSQL transaction (CreditTransactionType.ANALYSIS_DEDUCT).
3. Idempotency Guarantees: Enqueue requests carry unique job UUIDs. If a client retries a submission due to network latency, duplicate deductions are rejected at the database constraint level.

---

Automated Failure Reconciliation & Refunds

If an analysis job encounters an unrecoverable worker crash (e.g., corrupt RAW payload or cloud API timeout):

• Automatic Failure Detection: The Azure worker detects the fatal error and transitions the photo status to FAILED.
• Instant Credit Refund: The credit engine immediately initiates a compensating transaction (CreditTransactionType.REFUND), crediting the exact deducted amount back to the user balance.
• Audit Logging: An immutable record is appended to audit_logs detailing the refund reason and referenced job ID.