# 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
- [**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.