sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9c60989f1d26a237c6f3db60023e9a1b02399d33
orion/docs/index.md
Samir Boulahtit dd51df7b31 docs: reorganize migration docs into dedicated subfolder 
- Create docs/development/migration/ directory
- Move database-migrations.md to migration subfolder
- Move svc-006-migration-plan.md to migration subfolder
- Update all cross-references in:
  - mkdocs.yml nav configuration
  - docs/index.md
  - docs/architecture/overview.md
  - docs/backend/overview.md
  - docs/development/contributing.md
  - docs/development/troubleshooting.md
  - docs/getting-started/database-setup.md

This separates migration plans from core documentation.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-03 22:16:05 +01:00

15 KiB
Raw Blame History

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

🏛️ Architecture

💻 Development

📚 User Guides

🧪 Testing

🚢 Deployment

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:

First Steps

For Developers

  1. Set up your environment

  2. Understand the architecture

  3. Start developing

For Operations

  1. Deploy the platform

  2. Configure and manage

For Team Members

  1. Get your IDE ready

  2. Learn the workflow

Development Commands

Quick reference for common development tasks:

# Setup
make install-all          # Install all dependencies
make setup               # Complete setup (install + migrate + seed)

# Development
make dev                 # Start development server
make docs-serve          # Start documentation server

# Database
make migrate-up          # Run migrations
make seed-demo           # Seed demo data
make db-setup            # Complete database setup

# Testing
make test                # Run all tests
make test-coverage       # Run with coverage report

# Code Quality
make format              # Format code (black + isort)
make lint                # Run linters
make check               # Format + lint

# 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

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.

Reference in New Issue View Git Blame Copy Permalink