Samir Boulahtit
e9253fbd84
Replace all ~1,086 occurrences of Wizamart/wizamart/WIZAMART/WizaMart with Orion/orion/ORION across 184 files. This includes database identifiers, email addresses, domain references, R2 bucket names, DNS prefixes, encryption salt, Celery app name, config defaults, Docker configs, CI configs, documentation, seed data, and templates. Renames homepage-wizamart.html template to homepage-orion.html. Fixes duplicate file_pattern key in api.yaml architecture rule. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
15 KiB
Orion Platform Documentation
Welcome to the complete documentation for Orion - a production-ready, multi-tenant, multi-theme e-commerce platform that enables stores to operate independent webshops while integrating with external marketplaces.
What is Orion?
Orion is a comprehensive multi-tenant e-commerce platform built with FastAPI and Alpine.js, designed to support multiple stores with complete data isolation, custom theming, and flexible deployment modes.
Key Capabilities
- 🏪 Multi-Store Marketplace: Complete store isolation with independent webshops
- 🎨 Multi-Theme System: Store-specific branding and customization
- 🔗 Marketplace Integration: Import and curate products from external marketplaces
- 📦 Product Catalog Management: Store-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: Store-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
Orion operates on a multi-tenant architecture with three distinct interfaces:
┌─────────────────────────────────────────────────────────────┐
│ Orion Platform │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ ADMIN │ │ STORE │ │ SHOP │ │
│ │ Interface │ │ Dashboard │ │ Storefront │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ └──────────────────┴──────────────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ Middleware │ │
│ │ Stack │ │
│ └───────┬────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ FastAPI │ │
│ │ Backend │ │
│ └───────┬────────┘ │
│ │ │
│ ┌───────▼────────┐ │
│ │ PostgreSQL │ │
│ │ Database │ │
│ └────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Three Deployment Modes
1. Custom Domain Mode
customdomain.com → Store 1 Shop
anothershop.com → Store 2 Shop
2. Subdomain Mode
store1.platform.com → Store 1 Shop
store2.platform.com → Store 2 Shop
admin.platform.com → Admin Interface
3. Path-Based Mode (Development Only)
platform.com/stores/store1/shop → Store 1 Shop
platform.com/stores/store2/shop → Store 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 store 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 store data
- Flexible Routing: Custom domains, subdomains, or path-based
- Store Context Detection: Automatic tenant identification
- Scoped Queries: All database queries store-scoped by default
Learn more: Multi-Tenant System
Multi-Theme Support
- Store Branding: Custom colors, logos, and styling
- CSS Variables: Dynamic theming with CSS custom properties
- Theme Inheritance: Base themes with store overrides
- Real-time Updates: Theme changes apply instantly
Security & Authentication
- JWT-based Authentication: Secure token-based auth
- Role-Based Access Control: Admin, Store, Customer roles
- Team Permissions: Granular permissions for store 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 store 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 Orion:
graph LR
A[Client Request] --> B[LoggingMiddleware]
B --> C[StoreContextMiddleware]
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 store data isolation
- ✅ Multi-theme system
- ✅ JWT authentication & RBAC
- ✅ Product catalog management
- ✅ Order processing
- ✅ Shopping cart with Alpine.js
- ✅ Marketplace integration
- ✅ Team management
Production Ready:
- ✅ Error tracking (Sentry integration)
- ✅ Cloud storage (Cloudflare R2)
- ✅ CDN & WAF (CloudFlare)
In Development:
- 🚧 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.