📜 Project Changelog
A reverse-chronological log of major features, architectural changes, and bug fixes for Project Arceus.
Blank Spaces in Digital Binders
Decided on hybrid approach for handling blank spaces from physical binders in digital views.
- Analyzed JTBD: Balance physical authenticity with digital efficiency
- Pros of mirroring blanks: Mental model match, wishlist potential
- Cons: Wasted screen space, UX friction on mobile
- Recommendation: Default to optimized (remove blanks) with toggle for "Physical View"
- Implementation plan: Store positions in DB, add view toggle in binder component
Smart Training System & CircuitDS Button Consistency
Revolutionized the training feedback system with categorized data collection and achieved full CircuitDS design system compliance across all buttons. Fixed Next.js 15 async cookies compatibility.
- Replaced binary "add to training" with smart feedback: "🚫 Not a Card", "📚 Missing from DB", "❌ Wrong ID", and "✅ Correct".
- Implemented organized training data collection in `training_data/card_crops/{type}/` folders for better ML retraining.
- Achieved 100% CircuitDS Button component usage - replaced all custom button CSS with proper design system variants.
- Fixed Next.js 15 async cookies compatibility by updating `supabaseServer()` and all API route params.
- Resolved RLS permission issues by simplifying database queries and removing complex joins.
- Added comprehensive error logging and user feedback for training data collection.
- Successfully collected real "not a card" training examples (social media logos, reflective surfaces) for YOLO retraining.
Vision Pipeline Stability & Enrichment
Resolved a persistent and elusive database error (42P10) that was blocking card creation. Fully stabilized the end-to-end vision pipeline, enabling successful enrichment from the pokemontcg.io API.
- Diagnosed the root cause of the 42P10 "no unique constraint" error: the worker was attempting to upsert records with NULL values in the conflict key columns (`set_code`, `card_number`).
- Added a UNIQUE constraint to `cards(set_code, card_number)` to enforce data integrity and enable upserts.
- Corrected the `dequeue_and_start_job` function multiple times to fix alias-related SQL errors (42P01 and 42702).
- Patched the worker to safely handle enrichment data and prevent NULLs from being passed to the database.
- Confirmed the `pokemontcg.io` API integration is working, pulling official card images into the collection UI.
The Great Migration & API Refactor
A deep-dive debugging session that fixed a series of cascading failures, from a corrupted database migration history to a broken rename API. The result is a fully functional, stable system with a modernized, useful handbook.
- Manually repaired a corrupted Supabase migration history after the CLI failed repeatedly.
- Fixed a critical bug in the rename functionality caused by a frontend/backend data mismatch (`scan_title` vs `binder_title`).
- Implemented user-facing toast notifications for all major CRUD actions (rename, delete).
- Refactored the entire project handbook, deleting 9 outdated pages and creating a new, streamlined changelog and patterns directory.
- Diagnosed and fixed the final permission issue on the `command_queue` table by manually applying the RLS policy.
- Achieved a fully working end-to-end user flow for scanning, reviewing, and managing items.
Optimistic CRUD Pipeline & Handbook Refactor
Replaced slow, synchronous deletes with a modern, Factorio-style command queue pattern for instant UI feedback. Refactored the handbook into a streamlined changelog and patterns directory.
- Implemented soft deletes by adding a `deleted_at` column to `scan_uploads`.
- Created a `command_queue` table to handle asynchronous background tasks.
- Developed a Supabase Edge Function to process delete commands (hard delete, storage cleanup).
- Updated frontend to use optimistic UI for deletes, providing instant feedback and rollback on error.
- Refactored the project handbook, deleting outdated pages and creating a new changelog.
The Great Debugging & Refactoring Campaign
A massive effort to fix a completely broken system. Addressed dozens of bugs across the stack, from database migrations to frontend rendering, worker logic, and API endpoints.
- Repaired a corrupted Supabase migration history that prevented schema changes.
- Fixed the `local_worker.py` to correctly fetch and process jobs from the queue.
- Resolved multiple frontend/backend data mismatches (e.g., `binder_title` vs. `scan_title`).
- Implemented real-time polling on the scan review page for live updates.
- Added comprehensive toast notifications for user actions.
Scan-to-Collection Workflow Implemented
Built the end-to-end user flow for processing a scanned image and adding the identified cards to a user's permanent collection.
- Integrated a mock Pokemon TCG API into the Python worker for card identification.
- The worker now enriches detected cards with names, sets, and values.
- Created an `/api/collections` endpoint to add verified cards to the `user_cards` table.
- Updated the review page to display enriched card data and allow adding to collection.
Fixed dequeue_and_start_job Function
Resolved a critical bug where the Python worker would hang because the database function returned the wrong data structure.
- Identified that `dequeue_and_start_job` was returning `job_type` instead of the expected `payload`.
- Updated the PostgreSQL function to return the correct `payload` containing the image `storage_path`.
- This fix unblocked the entire processing pipeline.
🏆 The Breakthrough Moment: Whole-Image Detection
The definitive solution that solved persistent card detection failures by abandoning artificial 3x3 tiling and running YOLO on complete binder images.
- Identified the root cause of detection failures: a mismatch between the model (trained on whole cards) and the input (tiled fragments).
- Simplified the Python worker to use a single `model.predict()` call on the entire, resized image.
- Achieved near-perfect detection confidence (1.000, 0.999...) and eliminated threshold-tuning hell.
- This architectural change made the vision pipeline production-ready and reliable.