orion/docs/architecture/overview.md

# System Architecture

High-level overview of the Wizamart multi-tenant e-commerce platform architecture.

## Overview

Wizamart is a **multi-tenant e-commerce platform** that supports three distinct interfaces:
- **Admin** - Platform administration and vendor management
- **Vendor** - Vendor dashboard for managing shops
- **Shop** - Customer-facing storefronts

## Technology Stack

### Backend
- **Framework**: FastAPI (Python)
- **Database**: PostgreSQL with SQLAlchemy ORM
- **Authentication**: JWT-based with bcrypt password hashing
- **API**: RESTful JSON APIs

### Frontend
- **Templates**: Jinja2 server-side rendering
- **JavaScript**: Alpine.js for reactive components
- **CSS**: Tailwind CSS
- **Icons**: Lucide Icons

### Infrastructure
- **Web Server**: Uvicorn (ASGI)
- **Middleware**: Custom middleware stack for multi-tenancy
- **Static Files**: FastAPI StaticFiles

## System Components

### 1. Multi-Tenant Routing

The platform supports three deployment modes:

#### Custom Domain Mode
```
customdomain.com → Vendor 1 Shop
anotherdomain.com → Vendor 2 Shop
```

#### Subdomain Mode
```
vendor1.platform.com → Vendor 1 Shop
vendor2.platform.com → Vendor 2 Shop
admin.platform.com → Admin Interface
```

#### Path-Based Mode (Development Only)
```
platform.com/vendors/vendor1/shop → Vendor 1 Shop
platform.com/vendors/vendor2/shop → Vendor 2 Shop
platform.com/admin                → Admin Interface
```

**See:** [Multi-Tenant System](multi-tenant.md) for detailed implementation

### 2. Middleware Stack

Custom middleware handles:
- Vendor detection and context injection
- Request context detection (API/Admin/Vendor/Shop)
- Theme loading for vendor shops
- Request/response logging
- Path rewriting for multi-tenant routing

**See:** [Middleware Stack](middleware.md) for complete documentation

### 3. Authentication & Authorization

- JWT-based authentication
- Role-based access control (RBAC)
- Three user roles: Admin, Vendor, Customer
- Hierarchical permissions system

**See:** [Authentication & RBAC](auth-rbac.md) for details

### 4. Module System

The platform uses a modular architecture with three-tier classification:

```
┌─────────────────────────────────────────────────────────────┐
│                    FRAMEWORK LAYER                          │
│  (Infrastructure - always available, not modules)           │
│  Config │ Database │ Auth │ Permissions │ Observability     │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                     MODULE LAYER                            │
│                                                             │
│  CORE (Always Enabled)     OPTIONAL (Per-Platform)         │
│  ├── core                  ├── payments                    │
│  ├── tenancy               ├── billing                     │
│  ├── cms                   ├── inventory                   │
│  └── customers             ├── orders                      │
│                            ├── marketplace                 │
│  INTERNAL (Admin-Only)     ├── analytics                   │
│  ├── dev-tools             └── messaging                   │
│  └── monitoring                                            │
└─────────────────────────────────────────────────────────────┘
```

**Module Features:**
- Enable/disable modules per platform
- Module dependencies (billing requires payments)
- Health checks and lifecycle hooks
- Self-contained modules with own services, models, migrations

**See:** [Module System](module-system.md) for complete documentation

### 5. Request Flow

```mermaid
graph TB
    A[Client Request] --> B[Logging Middleware]
    B --> C[Vendor Context Middleware]
    C --> D[Context Detection Middleware]
    D --> E[Theme Context Middleware]
    E --> F{Request Type?}

    F -->|API /api/*| G[API Router]
    F -->|Admin /admin/*| H[Admin Page Router]
    F -->|Vendor /vendor/*| I[Vendor Page Router]
    F -->|Shop /shop/*| J[Shop Page Router]

    G --> K[JSON Response]
    H --> L[Admin HTML]
    I --> M[Vendor HTML]
    J --> N[Shop HTML]
```

**See:** [Request Flow](request-flow.md) for detailed journey

## Application Areas

### Admin Interface (`/admin/*`)

**Purpose**: Platform administration

**Features**:
- Vendor management
- User management
- System settings
- Audit logs
- Analytics dashboard

**Access**: Admin users only

### Vendor Dashboard (`/vendor/*`)

**Purpose**: Vendor shop management

**Features**:
- Product management
- Inventory tracking
- Order processing
- Shop settings
- Team member management
- Analytics

**Access**: Vendor users (owners and team members)

### Shop Interface (`/shop/*` or custom domains)

**Purpose**: Customer-facing storefront

**Features**:
- Product browsing
- Shopping cart
- Checkout
- Order tracking
- Customer account

**Access**: Public + registered customers

### API (`/api/*`)

**Purpose**: RESTful JSON API for all operations

**Features**:
- All CRUD operations
- Authentication endpoints
- Data export/import
- Webhook support

**Access**: Authenticated users based on role

## Data Architecture

### Database Schema

```
┌─────────────────┐
│     vendors     │ ← Multi-tenant root
└────────┬────────┘
         │
         ├─── vendor_domains
         ├─── vendor_themes
         ├─── vendor_settings
         │
         ├─── products ────┬─── product_variants
         │                 ├─── product_images
         │                 └─── product_categories
         │
         ├─── cart_items (session-based shopping cart)
         │
         ├─── orders ──────┬─── order_items
         │                 └─── order_status_history
         │
         └─── customers ───┬─── customer_addresses
                           └─── customer_sessions
```

### Key Design Patterns

1. **Tenant Isolation**: All data scoped to vendor_id
2. **Soft Deletes**: Records marked as deleted, not removed
3. **Audit Trail**: All changes tracked with user and timestamp
4. **JSON Fields**: Flexible metadata storage

## Security Architecture

### Authentication Flow

```
1. User submits credentials
2. Server validates against database
3. JWT token generated with user info
4. Token returned to client
5. Client includes token in subsequent requests
6. Server validates token on each request
```

### Authorization Layers

1. **Route-level**: Middleware checks user authentication
2. **Role-level**: Decorators enforce role requirements
3. **Resource-level**: Services check ownership/permissions
4. **Tenant-level**: All queries scoped to vendor

**See:** [Authentication & RBAC](auth-rbac.md)

## Scalability Considerations

### Current Architecture
- **Single server**: Suitable for small to medium deployments
- **In-memory rate limiting**: Per-process limits
- **Session state**: Stateless JWT tokens

### Future Enhancements
- **Horizontal scaling**: Load balancer + multiple app servers
- **Redis integration**: Distributed rate limiting and caching
- **Database replication**: Read replicas for scaling
- **CDN integration**: Static asset distribution
- **Message queue**: Async task processing (Celery + Redis)

## Development Workflow

### Local Development

```bash
# Setup
make install-all
make db-setup

# Development
make dev          # Start FastAPI server
make docs-serve   # Start documentation server

# Testing
make test         # Run all tests
make test-coverage  # Run with coverage report

# Code Quality
make format       # Format code (black + isort)
make lint         # Run linters (ruff + mypy)
```

### Project Structure

```
project/
├── app/                    # Application code
│   ├── api/               # API routes
│   ├── routes/            # Page routes (HTML)
│   ├── services/          # Business logic
│   ├── core/              # Core functionality (config, db, observability)
│   ├── modules/           # Module definitions and self-contained modules
│   │   ├── base.py       # ModuleDefinition class
│   │   ├── registry.py   # Module registry (CORE, OPTIONAL, INTERNAL)
│   │   ├── service.py    # Module enablement service
│   │   ├── events.py     # Module event bus
│   │   ├── cms/          # Self-contained CMS module
│   │   ├── payments/     # Self-contained payments module
│   │   └── ...           # Other modules
│   └── exceptions/        # Custom exceptions
│
├── middleware/            # Custom middleware
│   ├── auth.py           # Authentication
│   ├── vendor_context.py # Tenant detection
│   ├── context_middleware.py  # Context detection
│   └── theme_context.py  # Theme loading
│
├── models/               # Data models
│   ├── database/        # SQLAlchemy models
│   └── schema/          # Pydantic schemas
│
├── static/              # Static files
│   ├── admin/          # Admin assets
│   ├── vendor/         # Vendor assets
│   └── shop/           # Shop assets
│
├── templates/           # Jinja2 templates
│   ├── admin/
│   ├── vendor/
│   └── shop/
│
├── tests/              # Test suite
│   ├── unit/
│   └── integration/
│
└── docs/               # Documentation
    ├── architecture/   # System architecture
    ├── frontend/       # Frontend guides
    ├── backend/        # Backend development
    └── api/            # API documentation
```

## Monitoring & Observability

The platform includes a comprehensive observability framework:

### Health Checks

- Aggregated health endpoint (`/health`)
- Kubernetes probes (`/health/live`, `/health/ready`)
- Module health check integration
- External tool links (`/health/tools`)

### Metrics

- Prometheus metrics endpoint (`/metrics`)
- Request latency histograms
- Counter and gauge support

### Error Tracking

- Sentry integration for production
- Exception capture with context
- Environment-aware configuration

### Logging

- Structured logging with Python logging module
- Request/response logging via middleware
- Error tracking with stack traces
- Audit logging for admin actions

**See:** [Observability](observability.md) for complete documentation

## Deployment Architecture

### Production Deployment

```
                    ┌─────────────┐
Internet ───────────│ Load Balancer│
                    └──────┬───────┘
                           │
            ┌──────────────┼──────────────┐
            │              │              │
       ┌────▼────┐    ┌────▼────┐   ┌────▼────┐
       │ App     │    │ App     │   │ App     │
       │ Server 1│    │ Server 2│   │ Server 3│
       └────┬────┘    └────┬────┘   └────┬────┘
            │              │              │
            └──────────────┼──────────────┘
                           │
                    ┌──────▼───────┐
                    │  PostgreSQL  │
                    │  (Primary +  │
                    │   Replicas)  │
                    └──────────────┘
```

**See:** [Deployment Documentation](../deployment/index.md)

## Related Documentation

- [Multi-Tenant System](multi-tenant.md) - Detailed multi-tenancy implementation
- [Module System](module-system.md) - Module architecture and classification
- [Menu Management](menu-management.md) - Sidebar and menu configuration
- [Observability](observability.md) - Health checks, metrics, error tracking
- [Middleware Stack](middleware.md) - Complete middleware documentation
- [Authentication & RBAC](auth-rbac.md) - Security and access control
- [Request Flow](request-flow.md) - Detailed request processing
- [Frontend Architecture](../frontend/overview.md) - Frontend development guides
- [Backend Development](../backend/overview.md) - Backend development guides
- [API Documentation](../api/index.md) - API reference

## Quick Links

### For Developers
- [Creating a New Admin Page](../frontend/admin/page-templates.md)
- [Backend Development Guide](../backend/overview.md)
- [Database Migrations](../development/migration/database-migrations.md)

### For Operations
- [Deployment Guide](../deployment/production.md)
- [Environment Configuration](../deployment/environment.md)
- [Database Setup](../getting-started/database-setup.md)

### For Team Members
- [Contributing Guide](../development/contributing.md)
- [PyCharm Setup](../development/pycharm-configuration-make.md)
- [Troubleshooting](../development/troubleshooting.md)