Created detailed implementation guide for remaining phases (2-4):
Phase 2 - Service Layer:
- CodeQualityService class specification
- Scan management methods
- Violation CRUD operations
- Statistics and metrics calculation
- Integration with validator script
Phase 3 - API Endpoints:
- REST API specification for code quality
- Pydantic request/response models
- Endpoint documentation (/admin/code-quality/*)
Phase 4 - Frontend:
- Dashboard layout and components
- Alpine.js component structure
- Violations table with filtering
- Charts and visualizations
- Navigation integration
Implementation Details:
- Database schema documentation
- JSON output format for validator
- Testing checklist
- Priority order for next session
- Time estimates (3-4 hours)
Additional Features:
- Background job support considerations
- Email notifications
- GitHub/GitLab PR integration
- Historical trend analysis
This document serves as a complete blueprint for completing
the code quality dashboard in the next development session.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Implemented automated architecture validation to enforce design decisions:
Architecture Validation System:
- Created .architecture-rules.yaml with comprehensive rule definitions
- Implemented validate_architecture.py script with AST-based validation
- Added pre-commit hook configuration for automatic validation
- Comprehensive documentation in docs/architecture/architecture-patterns.md
Key Design Rules Enforced:
- API-001 to API-004: API endpoint patterns (Pydantic models, no business logic, exception handling, auth)
- SVC-001 to SVC-004: Service layer patterns (domain exceptions, db session params, no HTTP concerns)
- MDL-001 to MDL-002: Model separation (SQLAlchemy vs Pydantic)
- EXC-001 to EXC-002: Exception handling (custom exceptions, no bare except)
- JS-001 to JS-003: JavaScript patterns (apiClient, logger, Alpine components)
- TPL-001: Template patterns (extend base.html)
Features:
- Validates separation of concerns (routes vs services vs models)
- Enforces proper exception handling (domain exceptions in services, HTTP in routes)
- Checks database session patterns and Pydantic model usage
- JavaScript and template validation
- Detailed error reporting with suggestions
- Integration with pre-commit hooks and CI/CD
UI Fix:
- Fixed icon names in content-pages.html (pencil→edit, trash→delete)
Documentation:
- Added architecture patterns guide with examples
- Created scripts/README.md for validator usage
- Updated mkdocs.yml with architecture documentation
- Built and verified documentation successfully
Usage:
python scripts/validate_architecture.py # Validate all
python scripts/validate_architecture.py --verbose # With details
python scripts/validate_architecture.py --errors-only # Errors only
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Updated API reference, error handling, and architecture docs to reflect
the new persistent cart system with database storage.
API Reference Updates (shop-api-reference.md):
- Updated last modified date to 2025-11-23
- Updated cart response schemas to match CartResponse/CartItemResponse models
- Added detailed schema tables for all cart endpoints
- Documented all cart exceptions with examples (CART_ITEM_NOT_FOUND, INSUFFICIENT_INVENTORY_FOR_CART, etc.)
- Added implementation notes about cart persistence and duplicate prevention
- Updated all endpoint documentation with proper request/response schemas
- Added CartOperationResponse and ClearCartResponse documentation
Error Handling Updates (error-handling.md):
- Added Shopping Cart Exceptions section with 6 cart-specific exceptions
- Added Product Exceptions section
- Added Inventory Exceptions section
- Updated error response format to show structured WizamartException format
- Added examples with error_code, message, status_code, and details fields
- Documented the difference between structured and generic error formats
Architecture Updates (overview.md):
- Added cart_items table to database schema diagram
- Documented session-based shopping cart in data model hierarchy
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
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>
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>
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 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>
