Updated documentation to cover all work completed today:
## Database Setup (docs/getting-started/database-setup.md)
- Added data seeding section with all three scripts
- Documented inventory creation requirement
- Added complete setup workflow
- Included common issues and solutions
- Added database reset instructions
## New Troubleshooting Guide (docs/troubleshooting/shop-frontend.md)
Comprehensive troubleshooting for:
### Cart and Product Issues
- Products cannot be added to cart (inventory = 0)
- Cart is empty after adding products (session ID issue)
- Root causes and solutions with code examples
### Styling and Layout Issues
- Pages with no styling (not extending base template)
- Images not loading (placeholder SVG implementation)
- Detailed before/after examples
### Navigation and Routing Issues
- Product detail 404 (duplicate /shop prefix)
- Missing /shop/ in links
- Breadcrumb navigation patterns
### Landing Page Issues
- Vendor root 404 (no landing page)
- Breadcrumb home link configuration
- Auto-redirect behavior
### Alpine.js Issues
- Component data not available (parent init not called)
- Product ID undefined (window globals solution)
- Debugging tips and console commands
All issues encountered today are now documented with:
- Clear symptoms
- Root cause explanation
- How the system works
- Step-by-step solutions
- Code examples
- Verification steps
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Created script to populate inventory table for products that have 0 inventory.
Issue:
- Products had 0 available_inventory because inventory table was empty
- available_inventory is calculated from inventory_entries relationship
- Empty inventory table = 0 inventory for all products
- Add to cart fails when inventory is 0
Solution:
- Create inventory entries for all products
- Each product gets 100 units in 'Main Warehouse'
- Script can be run multiple times (only creates missing entries)
Usage:
python scripts/create_inventory.py
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added comprehensive console logging to track:
- Cart eligibility checks
- API request URL and payload
- Response status and data
- Error details
This will help identify why items aren't being added to cart.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Issue:
- sessionId was undefined when cart/product pages loaded
- Parent shopLayoutData init() was being overridden, not called
- Session ID setup in parent wasn't running
Solution:
- Store reference to baseData before spreading
- Explicitly call baseData.init() in child component init
- This ensures sessionId is initialized before cart/product logic runs
- Add session ID logging for debugging
Now the session ID is properly initialized and cart functionality works.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Issue:
- Cart was empty after adding products
- Product and cart pages reference this.sessionId but it wasn't defined
- Session ID was being created separately in each page component
Solution:
- Add sessionId property to shopLayoutData base component
- Add getOrCreateSessionId() method to manage session across all pages
- Initialize sessionId in init() so it's available to all child components
- Session ID stored in localStorage as 'cart_session_id'
Now the cart session is shared across all shop pages and cart items
persist correctly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Issue:
- Cart page was standalone HTML without proper styling
- Referenced non-existent CSS files (/static/css/shared/base.css, /static/css/vendor/vendor.css)
- Missing header, footer, and navigation
- Not integrated with shop layout system
Changes:
- Extend shop/base.html for consistent styling and layout
- Remove hardcoded CSS references (now inherited from base)
- Add proper breadcrumbs with landing page navigation
- Integrate with shopLayoutData() for cart and toast functionality
- Use Tailwind classes consistent with other shop pages
- Add @error handler for broken product images
- Update all URLs to use {{ base_url }} for multi-tenant support
- Modernize layout with responsive grid system
The cart page now has proper styling, navigation, and integrates
seamlessly with the rest of the shop frontend.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Issue:
- Product images in database have fake URLs (wizamart.example.com) that don't exist
- Browser shows broken image icons instead of placeholder
Solution:
- Add @error handler to all product images to fallback to placeholder.svg
- When any image fails to load, automatically switch to placeholder
- Applies to: product detail page, products list, related products
Now all broken/invalid image URLs will automatically show the placeholder
instead of broken image icons.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Issues fixed:
- placeholder.jpg contained SVG content but browsers won't render SVG in .jpg files
- Multiple templates referenced wrong placeholder paths
Changes:
- Rename placeholder.jpg to placeholder.svg with proper SVG file
- Update product.html to use /static/shop/img/placeholder.svg
- Update products.html to use /static/shop/img/placeholder.svg
- Update cart.html to use /static/shop/img/placeholder.svg (was /static/images/)
All shop pages now correctly display placeholder images when products
have no image_link set.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Issues fixed:
- Product ID was undefined - Alpine.js couldn't access data-product-id from nested div
- Missing placeholder image caused 404 errors
Changes:
- Pass product_id and vendor.id through window globals instead of dataset
- Initialize productId and vendorId directly from window variables
- Add placeholder.jpg SVG for products without images
- Add debug logging to track initialization
The product detail page now correctly loads products and handles missing images.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Issues resolved:
- Product detail page was standalone HTML without proper styling
- Referenced non-existent CSS files (/static/css/shared/base.css, /static/css/vendor/vendor.css)
- Used wrong image path (/static/images/ instead of /static/shop/img/)
- Missing header, footer, and navigation
- Not integrated with shop layout system
Changes:
- Extend shop/base.html for consistent styling and layout
- Remove hardcoded CSS references (now inherited from base)
- Update image paths to /static/shop/img/placeholder.jpg
- Integrate with shopLayoutData() for cart and toast functionality
- Add proper breadcrumbs with landing page navigation
- Use Tailwind classes consistent with other shop pages
- Use theme CSS variables from base template
The product detail page now has proper styling, navigation, and
integrates seamlessly with the rest of the shop frontend.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Major improvements to shop URL routing and vendor landing page system:
## Landing Page System
- Add template field to ContentPage model for flexible landing page designs
- Create 4 landing page templates: default, minimal, modern, and full
- Implement smart root handler to serve landing pages or redirect to shop
- Add create_landing_page.py script for easy landing page management
- Support both domain/subdomain and path-based vendor access
- Add comprehensive landing page documentation
## Route Fixes
- Fix duplicate /shop prefix in shop_pages.py routes
- Correct product detail page routing (was /shop/shop/products/{id})
- Update all shop routes to work with router prefix mounting
- Remove unused public vendor endpoints (/api/v1/public/vendors)
## Template Link Corrections
- Fix all shop template links to include /shop/ prefix
- Update breadcrumb 'Home' links to point to vendor root (landing page)
- Update header navigation 'Home' link to point to vendor root
- Correct CMS page links in footer navigation
- Fix account, cart, and error page navigation links
## Navigation Architecture
- Establish two-tier navigation: landing page (/) and shop (/shop/)
- Document complete navigation flow and URL hierarchy
- Support for vendors with or without landing pages (auto-redirect fallback)
- Consistent breadcrumb and header navigation behavior
## Documentation
- Add vendor-landing-pages.md feature documentation
- Add navigation-flow.md with complete URL hierarchy
- Update shop architecture docs with error handling section
- Add orphaned docs to mkdocs.yml navigation
- Document multi-access routing patterns
## Database
- Migration f68d8da5315a: add template field to content_pages table
- Support template values: default, minimal, modern, full
This establishes a complete landing page system allowing vendors to have
custom marketing homepages separate from their e-commerce shop, with
flexible template options and proper navigation hierarchy.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Added comprehensive documentation for:
- Error page templates (10 templates)
- Error renderer base_url calculation
- Multi-access aware error links
- Template usage examples (bad vs good)
- How error pages work across domain/subdomain/path access
This documents the error page improvements made during shop API migration.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix MkDocs build error by removing markdown link to source code file.
Change from [API Dependencies](../app/api/deps.py) to plain text
reference to avoid strict mode warning about non-documentation files.
Fixes: Doc file contains a link to 'app/api/deps.py' not in docs
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive guide explaining when to use each authentication
dependency:
- get_current_admin_from_cookie_or_header vs get_current_admin_api
- get_current_vendor_from_cookie_or_header vs get_current_vendor_api
- get_current_customer_from_cookie_or_header vs get_current_customer_api
Key distinctions:
- HTML pages (templates) → use _from_cookie_or_header (accepts cookies)
- API endpoints (JSON) → use _api (header-only, no cookies, CSRF-safe)
- Login pages → use _optional (returns None instead of exception)
Includes:
- Complete reference table
- When to use which dependency
- Migration guide from old names
- Code examples for each scenario
- Quick reference cheat sheet
This clarifies the naming change from get_current_admin_user to the
more specific variants and helps developers choose the right dependency.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix ImportError by using correct authentication dependency names:
- Use get_current_admin_api instead of get_current_admin_user
- Use get_current_vendor_api instead of get_current_vendor_user
These are the correct dependency names for API endpoints that require
Authorization header authentication (no cookie support).
Fixes: ImportError: cannot import name 'get_current_admin_user'
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Ignore TODO file from version control as it's used for
temporary task tracking during development.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update troubleshooting guide with latest fixes and solutions for
common development issues encountered during CMS implementation
and shop frontend development.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add automated script to generate platform default content pages:
Script (create_default_content_pages.py):
- Creates 7 platform default pages (vendor_id=NULL)
- Content: About, Contact, FAQ, Shipping, Returns, Privacy, Terms
- Comprehensive, production-ready content for each page
- Idempotent - safe to run multiple times (skips existing)
- SEO metadata included for all pages
- Proper navigation flags (footer/header visibility)
Makefile Integration:
- Add 'create-cms-defaults' command
- Integrate into 'db-setup' workflow
- Update help documentation with CMS commands
- Update both 'help' and 'help-db' sections
Workflow:
make db-setup now runs:
migrate-up → init-prod → create-cms-defaults → seed-demo
This ensures all new developers get:
- Database schema (migrations)
- Admin user (init-prod)
- Default content pages (create-cms-defaults)
- Demo data (seed-demo)
All in one command: make db-setup
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement dynamic CMS content rendering in shop frontend:
Route Handler (shop_pages.py):
- Add generic /{slug} route for all CMS pages
- Load content from database with vendor override fallback
- Update get_shop_context() to load footer/header navigation
- Pass db session to all route handlers for navigation loading
- Return 404 if page not found
Template (content-page.html):
- Generic template for rendering CMS content
- Display page title, content, and metadata
- Show vendor override badge when applicable
- Support for HTML and Markdown content formats
- SEO meta tags from database
Footer Navigation (base.html):
- Dynamic footer links loaded from database
- Automatic two-column layout based on page count
- Fallback to static links if no CMS pages configured
- Filter pages by show_in_footer flag
This completes the CMS frontend integration, enabling:
- /about, /contact, /faq, etc. to load from database
- Vendors inherit platform defaults automatically
- Vendor-specific overrides take priority
- Dynamic footer navigation from CMS
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement complete CMS business logic and REST API:
Service Layer (content_page_service.py):
- get_page_for_vendor() - Two-tier lookup with fallback
- list_pages_for_vendor() - Merge vendor + platform pages
- create_page(), update_page(), delete_page() - CRUD operations
- Support for published/draft workflow
- Footer/header navigation filtering
API Endpoints:
Admin API (/api/v1/admin/content-pages):
- POST /platform - Create platform defaults
- GET /platform - List platform defaults
- GET / - List all pages with vendor filtering
- PUT /{id} - Update any page
- DELETE /{id} - Delete any page
Vendor API (/api/v1/vendor/{code}/content-pages):
- GET / - List available pages (vendor + platform merged)
- GET /overrides - List only vendor overrides
- POST / - Create vendor override
- PUT /{id} - Update vendor page
- DELETE /{id} - Delete vendor page
Shop API (/api/v1/shop/content-pages):
- GET /navigation - Get footer/header navigation pages
- GET /{slug} - Get specific page (public, with fallback)
All endpoints include proper authentication, authorization,
and validation using Pydantic schemas.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implement Content Management System database layer:
Database Model:
- ContentPage model with two-tier architecture
- Platform defaults (vendor_id=NULL)
- Vendor-specific overrides (vendor_id=123)
- SEO fields (meta_description, meta_keywords)
- Publishing workflow (is_published, published_at)
- Navigation flags (show_in_footer, show_in_header)
- Display ordering and timestamps
Migrations:
- Create content_pages table with all columns
- Add indexes for performance (vendor_id, slug, published status)
- Add unique constraint on (vendor_id, slug)
- Add foreign key relationships with cascade delete
Model Registration:
- Add ContentPage to Vendor relationship
- Import model in alembic/env.py for migration detection
This provides the foundation for managing static content pages
(About, FAQ, Contact, etc.) with platform defaults and vendor overrides.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Fix shop frontend links to work correctly across all three access methods:
- Custom domain (wizamart.shop)
- Subdomain (wizamart.localhost)
- Path-based (/vendor/wizamart/)
Changes:
- Update get_shop_context() to calculate base_url based on access method
- Update all shop templates to use {{ base_url }} for links
- Add base_url to shop-layout.js Alpine.js component
- Document multi-access routing in shop architecture docs
This ensures links work correctly regardless of how the shop is accessed,
solving broken navigation issues with path-based access.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add shared template infrastructure and static assets:
- Shared Jinja2 templates for reusable components
- Favicon for branding
- Local Tailwind CSS fallback
- Shop CSS styles directory
This provides the foundation for consistent UI components across
admin, vendor, and shop frontends with CDN fallback support.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Add comprehensive documentation for CDN fallback strategy used across
the platform's frontend. Documents the pattern for loading external
libraries (Alpine.js, Tailwind CSS, etc.) with automatic fallback to
local copies when CDN is unavailable.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
