revamping documentation
This commit is contained in:
356
docs/architecture/overview.md
Normal file
356
docs/architecture/overview.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# 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
|
||||
```
|
||||
platform.com/vendor/vendor1/shop → Vendor 1 Shop
|
||||
platform.com/vendor/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. Request Flow
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
A[Client Request] --> B[Logging Middleware]
|
||||
B --> C[Vendor Context Middleware]
|
||||
C --> D[Path Rewrite Middleware]
|
||||
D --> E[Context Detection Middleware]
|
||||
E --> F[Theme Context Middleware]
|
||||
F --> G{Request Type?}
|
||||
|
||||
G -->|API /api/*| H[API Router]
|
||||
G -->|Admin /admin/*| I[Admin Page Router]
|
||||
G -->|Vendor /vendor/*| J[Vendor Page Router]
|
||||
G -->|Shop /shop/*| K[Shop Page Router]
|
||||
|
||||
H --> L[JSON Response]
|
||||
I --> M[Admin HTML]
|
||||
J --> N[Vendor HTML]
|
||||
K --> O[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
|
||||
│
|
||||
├─── 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
|
||||
│ └── 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
|
||||
|
||||
### Logging
|
||||
|
||||
- Structured logging with Python logging module
|
||||
- Request/response logging via middleware
|
||||
- Error tracking with stack traces
|
||||
- Audit logging for admin actions
|
||||
|
||||
### Performance Monitoring
|
||||
|
||||
- Request timing headers (`X-Process-Time`)
|
||||
- Database query monitoring (SQLAlchemy echo)
|
||||
- Slow query identification
|
||||
- Memory usage tracking
|
||||
|
||||
## 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
|
||||
- [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/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)
|
||||
Reference in New Issue
Block a user