- Rewrite pagination.md for server-side pagination approach
- Update quick-start guide with new implementation pattern
- Document shared pattern across Vendors, Companies, Users pages
- Add examples for filters, search, and API integration
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add arch-check, arch-check-file, arch-check-object Makefile targets
- Include arch-check in QA target for CI integration
- Update architecture-rules.md with CLI usage examples
- Update code-quality.md with validation commands
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Document all admin UI pages (list, detail, edit)
- Document transfer ownership modal with user search
- Add user management API endpoints section
- Update ownership transfer description
- Fix encoding issue in marketplace-integration.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Document 221 remaining violations (down from 239)
- Explain intentional transaction control at API layer
- Categorize violations by priority and impact
- Create refactoring roadmap for legacy code
- Establish architecture validation philosophy
Categories:
1. Transaction control (intentional, documented)
2. Raw dict responses (legacy, low priority)
3. Service patterns (legacy, medium priority)
4. Simple queries in endpoints (case-by-case)
5. Template inline styles (accepted)
Result: Codebase in good architectural health with clear improvement path
- Create comprehensive seed scripts audit document
- Inventory of all seed/create scripts
- Analysis of current vs intended workflow
- Identification of duplicates and orphaned scripts
- Refactoring recommendations
- Create Makefile refactoring completion document
- Summary of architecture decisions
- Before/after comparison
- Updated workflows for production and development
- Script classification (production, demo, utility, test)
- New developer onboarding workflow
- Production deployment workflow
Documentation provides clear guidance on:
- Which scripts to run in production vs development
- How init-prod differs from seed-demo
- When to use utility commands
- Proper setup workflow for new developers
Problem:
- Ruff removed 'from app.core.database import Base' from models/database/base.py
- Import appeared "unused" (F401) but was actually a critical re-export
- Caused ImportError: cannot import name 'Base' at runtime
- Re-export pattern: import in one file to export from package
Solution:
1. Added F401 ignore for models/database/base.py in pyproject.toml
2. Created scripts/verify_critical_imports.py verification script
3. Integrated verification into make check and CI pipeline
4. Updated documentation with explanation
New Verification Script:
- Checks all critical re-export imports exist
- Detects import variations (parentheses, 'as' clauses)
- Handles SQLAlchemy declarative_base alternatives
- Runs as part of make check automatically
Protected Files:
- models/database/base.py - Re-exports Base for all models
- models/__init__.py - Exports Base for Alembic
- models/database/__init__.py - Exports Base from package
- All __init__.py files (already protected)
Makefile Changes:
- make verify-imports - Run import verification
- make check - Now includes verify-imports
- make ci - Includes verify-imports in pipeline
Documentation Updated:
- Code quality guide explains re-export protection
- Pre-commit workflow includes verification
- Examples of why re-exports matter
This prevents future issues where linters remove seemingly
"unused" imports that are actually critical for application structure.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Add detailed Code Quality guide covering Ruff, mypy, and pytest
- Add Contributing Guide with workflow, standards, and best practices
- Update mkdocs.yml navigation to include new documentation
- Successfully build documentation without errors
New Documentation:
- docs/development/code-quality.md - Complete guide to code quality tools
- docs/development/contributing.md - Contributing guidelines and workflow
- Added Code Quality Dashboard implementation to navigation
Documentation includes:
- Ruff usage and configuration
- mypy type checking
- pytest testing guidelines
- Makefile command reference
- Pre-commit workflow
- IDE integration instructions
- Migration guide from old tools
- Best practices and common issues
Documentation builds cleanly with mkdocs build.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
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>
