sboulahtit/orion
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
11dcfdad73bb84c332f59d481c704ff8ca53d1b0
orion/docs/index.md
Samir Boulahtit f141cc4e6a docs: migrate module documentation to single source of truth 
Move 39 documentation files from top-level docs/ into each module's
docs/ folder, accessible via symlinks from docs/modules/. Create
data-model.md files for 10 modules with full schema documentation.
Replace originals with redirect stubs. Remove empty guide stubs.

Modules migrated: tenancy, billing, loyalty, marketplace, orders,
messaging, cms, catalog, inventory, hosting, prospecting.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-08 23:38:37 +01:00

448 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/storefront/store1 → Store 1 Shop
platform.com/storefront/store2 → 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
- [**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