costco-grocery-list/docs

Documentation Index

This directory contains all project documentation organized by category.

📁 Directory Structure

/architecture - System Design & Structure

• component-structure.md - Frontend component organization and patterns
• multi-household-architecture-plan.md - Multi-household system architecture design

/features - Feature Implementation Details

• classification-implementation.md - Item classification system (zones, types, groups)
• image-storage-implementation.md - Image storage and handling (bytea, MIME types)

/guides - How-To & Reference Guides

• api-documentation.md - REST API endpoints and usage
• frontend-readme.md - Frontend development guide
• MOBILE_RESPONSIVE_AUDIT.md - Mobile-first design guidelines and audit checklist
• setup-checklist.md - Development environment setup steps

/migration - Database Migrations & Updates

• MIGRATION_GUIDE.md - Multi-household migration instructions (also in backend/migrations/)
• POST_MIGRATION_UPDATES.md - Required updates after migration

/archive - Completed Implementation Records

Historical documentation of completed features. Useful for reference but not actively maintained.

• ACCOUNT_MANAGEMENT_IMPLEMENTATION.md - Phase 4: Display name and password change
• code-cleanup-guide.md - Code cleanup checklist (completed)
• HOUSEHOLD_MANAGEMENT_IMPLEMENTATION.md - Household management UI implementation
• IMPLEMENTATION_STATUS.md - Multi-household migration sprint status
• settings-dark-mode.md - Dark mode implementation notes
• TEST_SUITE_README.md - Testing infrastructure documentation

---

📄 Root-Level Documentation

These files remain at the project root for easy access:

• ../README.md - Project overview and quick start
• ../PROJECT_INSTRUCTIONS.md - Canonical project constraints and delivery contract
• ../AGENTS.md - Agent behavior and guardrails
• ../DEBUGGING_INSTRUCTIONS.md - Required bugfix workflow
• ../.github/copilot-instructions.md - Copilot compatibility shim to root instructions

---

🔍 Quick Reference

Setting up the project? → Start with setup-checklist.md

Understanding the API? → See api-documentation.md

Working on mobile UI? → Check MOBILE_RESPONSIVE_AUDIT.md

Need architecture context? → Read AGENTIC_CONTRACT_MAP.md and ../PROJECT_INSTRUCTIONS.md

Running migrations? → Follow DB_MIGRATION_WORKFLOW.md

---

📝 Contributing to Documentation

When adding new documentation:

1. Guides (/guides) - General how-to, setup, reference
2. Features (/features) - Specific feature implementation details
3. Architecture (/architecture) - System design, patterns, structure
4. Migration (/migration) - Database migrations and upgrade guides
5. Archive (/archive) - Completed implementation records (for reference only)

Keep documentation:

• ✅ Up-to-date with code changes
• ✅ Concise and scannable
• ✅ Linked to relevant files (use relative paths)
• ✅ Organized by category