sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1cb659e3a59c51444ea8a2105ce9db75f3922d21
orion/docs/index.md
Samir Boulahtit e9253fbd84 refactor: rename Wizamart to Orion across entire codebase 
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>
2026-02-14 16:46:56 +01:00

451 lines
15 KiB
Markdown
Raw Blame History

# 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](architecture/multi-tenant.md)
## Quick Navigation
### 🚀 Getting Started
<div class="grid cards" markdown>
- :material-download:{ .lg .middle } __Installation__
---
Set up your development environment
[:octicons-arrow-right-24: Installation Guide](getting-started/installation.md)
- :material-rocket-launch:{ .lg .middle } __Quick Start__
---
Get running in 5 minutes
[:octicons-arrow-right-24: Quick Start](getting-started/quickstart.md)
- :material-database:{ .lg .middle } __Database Setup__
---
Initialize database and run migrations
[:octicons-arrow-right-24: Database Setup](getting-started/database-setup.md)
- :material-cog:{ .lg .middle } __Configuration__
---
Environment and settings configuration
[:octicons-arrow-right-24: Configuration](getting-started/configuration.md)
</div>
### 🏛️ Architecture
<div class="grid cards" markdown>
- :material-floor-plan:{ .lg .middle } __System Overview__
---
High-level architecture and design
[:octicons-arrow-right-24: Overview](architecture/overview.md)
- :material-store-multiple:{ .lg .middle } __Multi-Tenant System__
---
Three routing modes explained
[:octicons-arrow-right-24: Multi-Tenancy](architecture/multi-tenant.md)
- :material-layers:{ .lg .middle } __Middleware Stack__
---
Complete middleware documentation
[:octicons-arrow-right-24: Middleware](architecture/middleware.md)
- :material-lock:{ .lg .middle } __Authentication & RBAC__
---
Security and access control
[:octicons-arrow-right-24: Auth & RBAC](architecture/auth-rbac.md)
</div>
### 💻 Development
<div class="grid cards" markdown>
- :material-code-braces:{ .lg .middle } __Backend Development__
---
Services, APIs, and patterns
[:octicons-arrow-right-24: Backend Guide](backend/overview.md)
- :material-api:{ .lg .middle } __API Reference__
---
Technical API documentation
[:octicons-arrow-right-24: API Reference](backend/middleware-reference.md)
- :material-database-cog:{ .lg .middle } __Database Migrations__
---
Alembic migration guide
[:octicons-arrow-right-24: Migrations](development/migration/database-migrations.md)
- :material-electron-framework:{ .lg .middle } __PyCharm Setup__
---
IDE configuration and troubleshooting
[:octicons-arrow-right-24: PyCharm Guide](development/troubleshooting.md)
</div>
### 📚 User Guides
- [**User Management**](guides/user-management.md) - Managing users and roles
- [**Product Management**](guides/product-management.md) - Working with products
- [**Shop Setup**](guides/shop-setup.md) - Configuring store shops
- [**CSV Import**](guides/csv-import.md) - Bulk product import
- [**Marketplace Integration**](guides/marketplace-integration.md) - External marketplace setup
### 🧪 Testing
- [**Testing Guide**](testing/testing-guide.md) - Testing standards and practices
- [**Test Maintenance**](testing/test-maintenance.md) - Maintaining the test suite
### 🚢 Deployment
- [**Docker Deployment**](deployment/docker.md) - Containerized deployment
- [**Production Setup**](deployment/production.md) - Production best practices
- [**Environment Variables**](deployment/environment.md) - 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](architecture/multi-tenant.md)
### 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](architecture/auth-rbac.md)
### 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](backend/overview.md)
## Request Flow
Understanding how a request flows through Orion:
```mermaid
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](architecture/request-flow.md)
## Live Documentation
When running the application locally:
- **Swagger UI**: [http://localhost:8000/docs](http://localhost:8000/docs) - Interactive API testing
- **ReDoc**: [http://localhost:8000/redoc](http://localhost:8000/redoc) - Alternative API docs
- **Admin Panel**: [http://localhost:8000/admin](http://localhost:8000/admin) - Platform administration
- **Health Check**: [http://localhost:8000/health](http://localhost:8000/health) - System status
## First Steps
### For Developers
1. **Set up your environment**
- [Installation Guide](getting-started/installation.md)
- [Database Setup](getting-started/database-setup.md)
- [Configuration](getting-started/configuration.md)
2. **Understand the architecture**
- [System Overview](architecture/overview.md)
- [Multi-Tenant System](architecture/multi-tenant.md)
- [Middleware Stack](architecture/middleware.md)
3. **Start developing**
- [Backend Development](backend/overview.md)
- [Database Migrations](development/migration/database-migrations.md)
- [Testing Guide](testing/testing-guide.md)
### For Operations
1. **Deploy the platform**
- [Docker Deployment](deployment/docker.md)
- [Production Setup](deployment/production.md)
- [Environment Variables](deployment/environment.md)
2. **Configure and manage**
- [Configuration Guide](getting-started/configuration.md)
- [Database Setup](getting-started/database-setup.md)
### For Team Members
1. **Get your IDE ready**
- [PyCharm Setup](development/pycharm-configuration-make.md)
- [Troubleshooting Guide](development/troubleshooting.md)
2. **Learn the workflow**
- [Contributing Guide](development/contributing.md)
- [Testing Standards](testing/testing-guide.md)
## Development Commands
Quick reference for common development tasks:
```bash
# 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](architecture/overview.md)
- **Troubleshooting**: [PyCharm Troubleshooting](development/troubleshooting.md)
## Contributing
We welcome contributions! Please see our [Contributing Guide](development/contributing.md) 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](getting-started/installation.md) or explore the [Architecture Overview](architecture/overview.md)!
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