revamping documentation
This commit is contained in:
501
docs/index.md
501
docs/index.md
@@ -1,118 +1,437 @@
|
||||
# Letzshop Import Documentation
|
||||
# Wizamart Platform Documentation
|
||||
|
||||
Welcome to the complete documentation for the Letzshop Import application - a comprehensive marketplace product import and management system built with FastAPI.
|
||||
Welcome to the complete documentation for **Wizamart** - a production-ready, multi-tenant, multi-theme e-commerce platform that enables vendors to operate independent webshops while integrating with external marketplaces.
|
||||
|
||||
## What is Letzshop Import?
|
||||
## What is Wizamart?
|
||||
|
||||
Letzshop Import is a powerful web application that enables:
|
||||
Wizamart is a comprehensive multi-tenant e-commerce platform built with **FastAPI** and **Alpine.js**, designed to support multiple vendors with complete data isolation, custom theming, and flexible deployment modes.
|
||||
|
||||
- **MarketplaceProduct Management**: Create, update, and manage product catalogs
|
||||
- **Shop Management**: Multi-shop support with individual configurations
|
||||
- **CSV Import**: Bulk import products from various marketplace formats
|
||||
- **Inventory Management**: Track inventory across multiple locations
|
||||
- **User Management**: Role-based access control for different user types
|
||||
- **Marketplace Integration**: Import from various marketplace platforms
|
||||
### Key Capabilities
|
||||
|
||||
- **🏪 Multi-Vendor Marketplace**: Complete vendor isolation with independent webshops
|
||||
- **🎨 Multi-Theme System**: Vendor-specific branding and customization
|
||||
- **🔗 Marketplace Integration**: Import and curate products from external marketplaces
|
||||
- **📦 Product Catalog Management**: Vendor-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**: Vendor-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
|
||||
|
||||
Wizamart operates on a **multi-tenant architecture** with three distinct interfaces:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Wizamart Platform │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ ADMIN │ │ VENDOR │ │ SHOP │ │
|
||||
│ │ Interface │ │ Dashboard │ │ Storefront │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └──────────────────┴──────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────▼────────┐ │
|
||||
│ │ Middleware │ │
|
||||
│ │ Stack │ │
|
||||
│ └───────┬────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────▼────────┐ │
|
||||
│ │ FastAPI │ │
|
||||
│ │ Backend │ │
|
||||
│ └───────┬────────┘ │
|
||||
│ │ │
|
||||
│ ┌───────▼────────┐ │
|
||||
│ │ PostgreSQL │ │
|
||||
│ │ Database │ │
|
||||
│ └────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Three Deployment Modes
|
||||
|
||||
**1. Custom Domain Mode**
|
||||
```
|
||||
customdomain.com → Vendor 1 Shop
|
||||
anothershop.com → Vendor 2 Shop
|
||||
```
|
||||
|
||||
**2. Subdomain Mode**
|
||||
```
|
||||
vendor1.platform.com → Vendor 1 Shop
|
||||
vendor2.platform.com → Vendor 2 Shop
|
||||
admin.platform.com → Admin Interface
|
||||
```
|
||||
|
||||
**3. Path-Based Mode**
|
||||
```
|
||||
platform.com/vendor/vendor1/shop → Vendor 1 Shop
|
||||
platform.com/vendor/vendor2/shop → Vendor 2 Shop
|
||||
platform.com/admin → Admin Interface
|
||||
```
|
||||
|
||||
**Learn more**: [Multi-Tenant System](architecture/multi-tenant.md)
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
### 🚀 Get Started
|
||||
- [**Installation Guide**](getting-started/installation.md) - Set up the application
|
||||
- [**Quick Start**](getting-started/quickstart.md) - Get running in minutes
|
||||
- [**Configuration**](getting-started/configuration.md) - Environment setup
|
||||
### 🚀 Getting Started
|
||||
|
||||
### 📚 API Documentation
|
||||
- [**Interactive API Docs**](http://localhost:8000/docs) - Swagger UI for live testing
|
||||
- [**Alternative API Docs**](http://localhost:8000/redoc) - ReDoc interface
|
||||
- [**API Overview**](api/index.md) - High-level API concepts
|
||||
- [**Authentication Guide**](api/authentication.md) - Security and auth flows
|
||||
<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/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 Guides
|
||||
- [**User Management**](guides/user-management.md) - Managing users and roles
|
||||
- [**MarketplaceProduct Management**](guides/product-management.md) - Working with products
|
||||
- [**CSV Import**](guides/csv-import.md) - Bulk import workflows
|
||||
- [**Shop Setup**](guides/shop-setup.md) - Configuring shops
|
||||
- [**Product Management**](guides/product-management.md) - Working with products
|
||||
- [**Shop Setup**](guides/shop-setup.md) - Configuring vendor 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) - Our testing standards and how to run tests
|
||||
- [**Test Maintenance**](testing/test-maintenance.md) - Test suite maintenance
|
||||
|
||||
### 🔧 Development
|
||||
- [**Architecture**](development/architecture.md) - System design overview
|
||||
- [**Database Schema**](development/database-schema.md) - Data model documentation
|
||||
- [**Troubleshooting**](development/troubleshooting.md) - How to troubleshoot
|
||||
- [**Contributing**](development/contributing.md) - How to contribute
|
||||
- [**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
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
Client[Web Client/API Consumer]
|
||||
API[FastAPI Application]
|
||||
Auth[Authentication Service]
|
||||
Products[MarketplaceProduct Service]
|
||||
Shops[Shop Service]
|
||||
Import[Import Service]
|
||||
DB[(PostgreSQL Database)]
|
||||
|
||||
Client --> API
|
||||
API --> Auth
|
||||
API --> Products
|
||||
API --> Shops
|
||||
API --> Import
|
||||
Auth --> DB
|
||||
Products --> DB
|
||||
Shops --> DB
|
||||
Import --> DB
|
||||
```
|
||||
|
||||
## Key Features
|
||||
|
||||
=== "MarketplaceProduct Management"
|
||||
- CRUD operations for products
|
||||
- GTIN validation and normalization
|
||||
- Price management with currency support
|
||||
- Category and attribute management
|
||||
- Bulk operations support
|
||||
|
||||
=== "Import System"
|
||||
- CSV file processing
|
||||
- Multiple marketplace format support
|
||||
- Validation and error reporting
|
||||
- Batch processing for large files
|
||||
- Import job tracking and status
|
||||
|
||||
=== "Multi-Shop Support"
|
||||
- Independent shop configurations
|
||||
- Shop-specific product associations
|
||||
- Inventory tracking per shop
|
||||
- Role-based shop access
|
||||
|
||||
=== "Security"
|
||||
- JWT-based authentication
|
||||
- Role-based access control (RBAC)
|
||||
- API key management
|
||||
- Input validation and sanitization
|
||||
- Rate limiting
|
||||
- [**Environment Variables**](deployment/environment.md) - Configuration reference
|
||||
|
||||
## Technology Stack
|
||||
|
||||
- **Backend**: FastAPI, Python 3.10+
|
||||
### Backend
|
||||
|
||||
- **Framework**: FastAPI (Python 3.13+)
|
||||
- **Database**: PostgreSQL with SQLAlchemy ORM
|
||||
- **Authentication**: JWT tokens
|
||||
- **Testing**: pytest with comprehensive test suite
|
||||
- **Documentation**: MkDocs Material + FastAPI auto-docs
|
||||
- **Deployment**: Docker, Docker Compose
|
||||
- **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 vendor data
|
||||
- **Flexible Routing**: Custom domains, subdomains, or path-based
|
||||
- **Vendor Context Detection**: Automatic tenant identification
|
||||
- **Scoped Queries**: All database queries vendor-scoped by default
|
||||
|
||||
**Learn more**: [Multi-Tenant System](architecture/multi-tenant.md)
|
||||
|
||||
### Multi-Theme Support
|
||||
|
||||
- **Vendor Branding**: Custom colors, logos, and styling
|
||||
- **CSS Variables**: Dynamic theming with CSS custom properties
|
||||
- **Theme Inheritance**: Base themes with vendor overrides
|
||||
- **Real-time Updates**: Theme changes apply instantly
|
||||
|
||||
### Security & Authentication
|
||||
|
||||
- **JWT-based Authentication**: Secure token-based auth
|
||||
- **Role-Based Access Control**: Admin, Vendor, Customer roles
|
||||
- **Team Permissions**: Granular permissions for vendor 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 vendor 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 Wizamart:
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
A[Client Request] --> B[LoggingMiddleware]
|
||||
B --> C[VendorContextMiddleware]
|
||||
C --> D[PathRewriteMiddleware]
|
||||
D --> E[ContextDetectionMiddleware]
|
||||
E --> F[ThemeContextMiddleware]
|
||||
F --> G[FastAPI Router]
|
||||
G --> H{Request Type}
|
||||
H -->|API| I[JSON Response]
|
||||
H -->|Page| J[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/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-all # Install all dependencies
|
||||
make setup # Complete setup (install + migrate + seed)
|
||||
|
||||
# Development
|
||||
make dev # Start development server
|
||||
make docs-serve # Start documentation server
|
||||
|
||||
# Database
|
||||
make migrate-up # Run migrations
|
||||
make seed-demo # Seed demo data
|
||||
make db-setup # Complete database setup
|
||||
|
||||
# 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
|
||||
make check # Format + lint
|
||||
|
||||
# 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
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/yourusername/letzshop-import/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/letzshop-import/discussions)
|
||||
- **API Testing**: Use the [Swagger UI](http://localhost:8000/docs) for interactive testing
|
||||
- **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 vendor data isolation
|
||||
- ✅ Multi-theme system
|
||||
- ✅ JWT authentication & RBAC
|
||||
- ✅ Product catalog management
|
||||
- ✅ Order processing
|
||||
- ✅ Shopping cart with Alpine.js
|
||||
- ✅ Marketplace integration
|
||||
- ✅ Team management
|
||||
|
||||
**In Development**:
|
||||
- 🚧 Payment integration (Stripe-ready)
|
||||
- 🚧 Email notifications
|
||||
- 🚧 Advanced analytics
|
||||
|
||||
---
|
||||
|
||||
Ready to get started? Head over to the [Installation Guide](getting-started/installation.md)!
|
||||
**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
Block a user