Samir Boulahtit
0d204f39a8
- Update Makefile help sections with correct target names (platform-install) - Add Celery infrastructure section to background-tasks.md - Update installation.md with Celery setup instructions and environment vars - Update index.md with comprehensive development commands including Celery - Add Flower monitoring and task queue commands to docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
15 KiB
Wizamart Platform Documentation
Welcome to the complete documentation for Wizamart - a production-ready, multi-tenant, multi-theme e-commerce platform that enables vendors to operate independent webshops while integrating with external marketplaces.
What is Wizamart?
Wizamart is a comprehensive multi-tenant e-commerce platform built with FastAPI and Alpine.js, designed to support multiple vendors with complete data isolation, custom theming, and flexible deployment modes.
Key Capabilities
- 🏪 Multi-Vendor Marketplace: Complete vendor isolation with independent webshops
- 🎨 Multi-Theme System: Vendor-specific branding and customization
- 🔗 Marketplace Integration: Import and curate products from external marketplaces
- 📦 Product Catalog Management: Vendor-scoped product publishing
- 📊 Inventory Management: Real-time stock tracking with location-based inventory
- 🛒 Shopping Cart: Session-based cart with real-time Alpine.js updates
- 👥 Customer Management: Vendor-scoped customer accounts with order history
- 👨💼 Team Management: Role-based access control with granular permissions
- 📱 Order Management: Complete order lifecycle with status tracking
Platform Architecture
Wizamart operates on a multi-tenant architecture with three distinct interfaces:
┌─────────────────────────────────────────────────────────────┐
│ Wizamart Platform │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ADMIN │ │ VENDOR │ │ SHOP │ │
│ │ Interface │ │ Dashboard │ │ Storefront │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ Middleware │ │
│ │ Stack │ │
│ └───────┬────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ FastAPI │ │
│ │ Backend │ │
│ └───────┬────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ PostgreSQL │ │
│ │ Database │ │
│ └────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Three Deployment Modes
1. Custom Domain Mode
customdomain.com → Vendor 1 Shop
anothershop.com → Vendor 2 Shop
2. Subdomain Mode
vendor1.platform.com → Vendor 1 Shop
vendor2.platform.com → Vendor 2 Shop
admin.platform.com → Admin Interface
3. Path-Based Mode (Development Only)
platform.com/vendors/vendor1/shop → Vendor 1 Shop
platform.com/vendors/vendor2/shop → Vendor 2 Shop
platform.com/admin → Admin Interface
Learn more: Multi-Tenant System
Quick Navigation
🚀 Getting Started
-
:material-download:{ .lg .middle } Installation
Set up your development environment
-
:material-rocket-launch:{ .lg .middle } Quick Start
Get running in 5 minutes
-
:material-database:{ .lg .middle } Database Setup
Initialize database and run migrations
-
:material-cog:{ .lg .middle } Configuration
Environment and settings configuration
🏛️ Architecture
-
:material-floor-plan:{ .lg .middle } System Overview
High-level architecture and design
-
:material-store-multiple:{ .lg .middle } Multi-Tenant System
Three routing modes explained
-
:material-layers:{ .lg .middle } Middleware Stack
Complete middleware documentation
-
:material-lock:{ .lg .middle } Authentication & RBAC
Security and access control
💻 Development
-
:material-code-braces:{ .lg .middle } Backend Development
Services, APIs, and patterns
-
:material-api:{ .lg .middle } API Reference
Technical API documentation
-
:material-database-cog:{ .lg .middle } Database Migrations
Alembic migration guide
-
:material-electron-framework:{ .lg .middle } PyCharm Setup
IDE configuration and troubleshooting
📚 User Guides
- User Management - Managing users and roles
- Product Management - Working with products
- Shop Setup - Configuring vendor shops
- CSV Import - Bulk product import
- Marketplace Integration - External marketplace setup
🧪 Testing
- Testing Guide - Testing standards and practices
- Test Maintenance - Maintaining the test suite
🚢 Deployment
- Docker Deployment - Containerized deployment
- Production Setup - Production best practices
- Environment Variables - Configuration reference
Technology Stack
Backend
- Framework: FastAPI (Python 3.13+)
- Database: PostgreSQL with SQLAlchemy ORM
- Authentication: JWT tokens with bcrypt
- Async: Uvicorn ASGI server
- Migrations: Alembic
- Testing: pytest with comprehensive coverage
Frontend
- Templates: Jinja2 server-side rendering
- JavaScript: Alpine.js for reactive components (CDN-based, no build step)
- CSS: Tailwind CSS with custom themes
- Icons: Lucide Icons
- Zero Build Step: Works directly without compilation
Infrastructure
- Web Server: Uvicorn (ASGI)
- Middleware: Custom stack for multi-tenancy
- Static Files: FastAPI StaticFiles
- Documentation: MkDocs Material + mkdocstrings
Key Features
Multi-Tenancy
- Complete Data Isolation: Chinese wall between vendor data
- Flexible Routing: Custom domains, subdomains, or path-based
- Vendor Context Detection: Automatic tenant identification
- Scoped Queries: All database queries vendor-scoped by default
Learn more: Multi-Tenant System
Multi-Theme Support
- Vendor Branding: Custom colors, logos, and styling
- CSS Variables: Dynamic theming with CSS custom properties
- Theme Inheritance: Base themes with vendor overrides
- Real-time Updates: Theme changes apply instantly
Security & Authentication
- JWT-based Authentication: Secure token-based auth
- Role-Based Access Control: Admin, Vendor, Customer roles
- Team Permissions: Granular permissions for vendor team members
- Input Validation: Pydantic models for all requests
- Rate Limiting: API protection with sliding window algorithm
Learn more: Authentication & RBAC
Alpine.js Reactive UI
- Lightweight: 15KB framework for reactive components
- No Build Step: Works directly in HTML
- Reactive State: Modern UX without complexity
- Perfect Integration: Seamless with Jinja2 templates
- Scoped Components: Natural vendor isolation
Service Layer Architecture
- Clean Separation: Business logic isolated from routes
- Reusable Services: Shared across API and page routes
- Exception-First: Consistent error handling
- Testable: Easy unit and integration testing
Learn more: Backend Development
Request Flow
Understanding how a request flows through Wizamart:
graph LR
A[Client Request] --> B[LoggingMiddleware]
B --> C[VendorContextMiddleware]
C --> D[ContextDetectionMiddleware]
D --> E[ThemeContextMiddleware]
E --> F[FastAPI Router]
F --> G{Request Type}
G -->|API| H[JSON Response]
G -->|Page| I[HTML Template]
Learn more: Request Flow
Live Documentation
When running the application locally:
- Swagger UI: http://localhost:8000/docs - Interactive API testing
- ReDoc: http://localhost:8000/redoc - Alternative API docs
- Admin Panel: http://localhost:8000/admin - Platform administration
- Health Check: http://localhost:8000/health - System status
First Steps
For Developers
-
Set up your environment
-
Understand the architecture
-
Start developing
For Operations
-
Deploy the platform
-
Configure and manage
For Team Members
-
Get your IDE ready
-
Learn the workflow
Development Commands
Quick reference for common development tasks:
# Setup
make install # Install production dependencies
make install-all # Install all dependencies (dev + test + docs)
make platform-install # First-time setup wizard (validates config)
make setup # Complete setup (install + migrate + seed)
# Development
make dev # Start development server (port 8000)
make docs-serve # Start documentation server (port 9991)
# Database
make migrate-up # Run migrations
make migrate-create message="description" # Create new migration
make seed-demo # Seed demo data
make db-setup # Complete database setup
# Background Tasks (Celery)
make celery-worker # Start Celery worker
make celery-beat # Start Celery scheduler
make celery-dev # Start worker + beat together (dev)
make flower # Start Flower monitoring (port 5555)
# Testing
make test # Run all tests
make test-unit # Run unit tests only
make test-coverage # Run with coverage report
# Code Quality
make format # Format code (ruff)
make lint # Run linters (ruff + mypy)
make arch-check # Validate architecture patterns
make check # Format + lint + verify imports
# Documentation
make docs-build # Build documentation
make docs-serve # Serve documentation locally
Documentation Structure
This documentation is organized into logical sections:
- Getting Started: Installation, configuration, and setup
- Architecture: System design and multi-tenancy
- Backend Development: Services, APIs, and patterns
- API Documentation: For API consumers
- User Guides: Feature-specific guides
- Testing: Testing practices and standards
- Development: Tools, workflows, and troubleshooting
- Deployment: Production deployment guides
Getting Help
- GitHub Issues: Report bugs and request features
- API Documentation: Interactive Swagger UI at
/docs - Architecture Docs: System Overview
- Troubleshooting: PyCharm Troubleshooting
Contributing
We welcome contributions! Please see our Contributing Guide for:
- Development workflow
- Code quality standards
- Testing requirements
- Pull request process
Project Status
Current Version: Production-ready multi-tenant platform
Completed Features:
- ✅ Multi-tenant architecture with 3 routing modes
- ✅ Complete vendor data isolation
- ✅ Multi-theme system
- ✅ JWT authentication & RBAC
- ✅ Product catalog management
- ✅ Order processing
- ✅ Shopping cart with Alpine.js
- ✅ Marketplace integration
- ✅ Team management
In Development:
- 🚧 Payment integration (Stripe-ready)
- 🚧 Email notifications
- 🚧 Advanced analytics
Ready to get started? Head over to the Installation Guide or explore the Architecture Overview!
Built with ❤️ using FastAPI, PostgreSQL, Alpine.js, and modern Python patterns for a scalable, maintainable multi-tenant e-commerce platform.