Samir Boulahtit
d648c921b7
- Add Development URL Quick Reference section to url-routing overview with all login URLs, entry points, and full examples - Replace /shop/ path segments with /storefront/ across 50 docs files - Update file references: shop_pages.py → storefront_pages.py, templates/shop/ → templates/storefront/, api/v1/shop/ → api/v1/storefront/ - Preserve domain references (orion.shop) and /store/ staff dashboard paths - Archive docs left unchanged (historical) 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/storefront/store1 → Store 1 Shop
platform.com/storefront/store2 → 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.