orion/3.vertical_slice_roadmap.md

Multi-Tenant Ecommerce Platform - Vertical Slice Development Plan

Overview

This document outlines a vertical slice development approach for the multi-tenant ecommerce platform. Each slice delivers a complete, working user workflow that validates core architectural decisions and provides immediate value.

Development Philosophy

Vertical Slice Benefits:

• Working software at each milestone
• Early validation of architecture decisions
• Immediate stakeholder feedback
• Reduced risk through incremental delivery
• Clear progress demonstration

Technology Stack Updates

Frontend Framework: Alpine.js (v3.x)

• Lightweight (15KB), no build step required
• Perfect integration with Jinja2 templates
• Reactive state management without complexity
• CDN-based, works seamlessly with vanilla HTML/CSS/JS approach

Why Alpine.js:

• Minimal learning curve - feels like inline JavaScript
• No conflicts with Jinja2 template syntax
• Scoped reactivity - perfect for multi-tenant isolation
• Progressive enhancement - works even if JS fails
• Ideal for AJAX-heavy applications

Slice Development Order

Slice 1: Admin Creates Vendor → Vendor Owner Logs In (Week 1)

Core Value: Establish multi-tenant foundation and vendor isolation

User Stories:

• ✅ As a Super Admin, I can create vendors through the admin interface
• ✅ As a Super Admin, I can manage vendor accounts
• ✅ As a Vendor Owner, I can log into my vendor-specific admin interface
• ✅ The system correctly isolates vendor contexts

Technical Implementation:

Backend Components (Days 1-3) ✅

# Essential Models
class Vendor:
    id, name, subdomain, owner_email, is_active, created_at, updated_at

class User:
    id, email, hashed_password, role, vendor_id, is_active, created_at, updated_at

# Core Services
class VendorService:
    - create_vendor(vendor_data) -> Creates vendor + owner user
    - get_vendor_by_subdomain(subdomain) -> For context detection

class AuthService:
    - authenticate_admin(email, password) -> Admin login
    - authenticate_vendor(email, password, vendor_id) -> Vendor login

# API Endpoints
POST /api/v1/admin/vendors              # Create vendor
POST /api/v1/admin/auth/login           # Admin authentication
POST /api/v1/vendor/auth/login          # Vendor authentication (context-aware)
GET /api/v1/vendor/dashboard/stats      # Basic vendor dashboard

_#### Frontend Components (Days 4-5)

Admin Interface (Vanilla JS)

• admin/login.html # Super admin login
• admin/vendors.html # Vendor creation form
• admin/dashboard.html # Admin overview with stats

Vendor Interface (Vanilla JS)

• vendor/login.html # Vendor owner login
• vendor/dashboard.html # Basic vendor dashboard (Alpine.js)

Shared Components

• js/shared/api-client.js # API communication utilities
• css/shared/base.css # Base styling system
• css/shared/auth.css # Authentication page styles
• css/admin/admin.css # Admin interface styles
• css/vendor/vendor.css # Vendor interface styles

Acceptance Criteria:

• Admin can log into admin interface
• Admin can create new vendors
• System generates vendor owner credentials
• Vendor owner can log into vendor-specific interface
• Vendor context detection works in dev and production modes
• Database properly isolates vendor data

Deliverables:

• Working admin interface
• Working vendor login system
• Vendor context detection
• Basic database schema with migrations

---

Slice 2: Vendor Imports Products from Letzshop (Week 2)

Core Value: Establish marketplace integration foundation

User Stories:

• As a Vendor Owner, I can configure my Letzshop CSV URL
• As a Vendor Owner, I can trigger product imports from Letzshop
• As a Vendor Owner, I can view import job status and results
• The system processes CSV data in the background

Technical Implementation:

Backend Components (Days 1-3)

# Additional Models
class ImportJob:
    id, vendor_id, marketplace, csv_url, status, total_products, 
    imported_at, created_at, updated_at

class ImportedProduct:
    id, vendor_id, import_job_id, external_sku, raw_data, 
    is_selected, created_at, updated_at

# Enhanced Services
class MarketplaceService:
    - create_import_job(vendor_id, csv_url) -> Creates import job
    - process_csv_import(job_id) -> Background processing
    - get_import_jobs(vendor_id) -> Import history

# New API Endpoints
POST /api/v1/marketplace/import          # Trigger Letzshop import
GET /api/v1/marketplace/imports          # Import job history
GET /api/v1/marketplace/imports/{id}/status  # Job status

Frontend Components (Days 4-5)

# Vendor Interface Extensions
- vendor/imports.html                    # Import management
- vendor/imports/letzshop.html          # Letzshop configuration
- vendor/imports/history.html           # Import job history

# Enhanced JavaScript
- js/vendor/imports.js                  # Import management logic
- js/vendor/marketplace.js              # Marketplace interactions

Acceptance Criteria:

• Vendor can configure Letzshop CSV URL
• Vendor can trigger import jobs
• System downloads and processes CSV files
• Import status updates in real-time
• Import history is properly tracked
• Error handling for failed imports

Deliverables:

• Marketplace import system
• Background job processing
• Import management interface
• CSV processing capabilities

---

Slice 3: Vendor Selects and Publishes Products (Week 3)

Core Value: Complete the marketplace-to-catalog workflow

User Stories:

• As a Vendor Owner, I can browse imported products
• As a Vendor Owner, I can select which products to publish
• As a Vendor Owner, I can customize product information
• As a Vendor Owner, I can manage my product catalog

Technical Implementation:

Backend Components (Days 1-3)

# Additional Models
class Product:
    id, vendor_id, sku, name, price, imported_product_id, 
    custom_description, custom_price, is_active, created_at, updated_at

# Enhanced Services
class ProductService:
    - get_imported_products(vendor_id, import_job_id) -> Browse imports
    - publish_product(vendor_id, imported_product_id) -> Publish to catalog
    - update_product(vendor_id, product_id, updates) -> Customize products
    - get_vendor_catalog(vendor_id) -> Published products

# New API Endpoints
GET /api/v1/marketplace/imports/{id}/products    # Browse imported products
POST /api/v1/products/from-import/{id}           # Publish imported product
GET /api/v1/products                             # Vendor catalog
PUT /api/v1/products/{id}                        # Update product
DELETE /api/v1/products/{id}                     # Remove product

Frontend Components (Days 4-5)

# Vendor Interface Extensions
- vendor/products.html                   # Product catalog management
- vendor/products/browse-imports.html   # Browse imported products
- vendor/products/edit.html             # Product editing
- vendor/products/create.html           # Manual product creation

# Enhanced JavaScript
- js/vendor/products.js                 # Product management logic
- js/vendor/catalog.js                  # Catalog operations

Acceptance Criteria:

• Vendor can browse all imported products
• Vendor can select products to publish
• Published products appear in vendor catalog
• Vendor can customize product details
• Vendor can manually create products
• Product operations are properly isolated by vendor

Deliverables:

• Complete product management system
• Import-to-catalog workflow
• Product customization capabilities
• Vendor catalog interface

---

Slice 4: Customer Shops on Vendor Store (Week 4)

Core Value: Enable customer-facing ecommerce functionality

User Stories:

• As a Customer, I can browse products on a vendor's shop
• As a Customer, I can view product details
• As a Customer, I can register for a vendor-specific account
• As a Customer, I can add products to my cart

Technical Implementation:

Backend Components (Days 1-3)

# Additional Models
class Customer:
    id, vendor_id, email, hashed_password, first_name, last_name,
    customer_number, preferences, total_orders, total_spent,
    created_at, updated_at

class Cart:
    id, vendor_id, customer_id, session_id, items, 
    created_at, updated_at

# New Services
class CustomerService:
    - register_customer(vendor_id, customer_data) -> Vendor-scoped registration
    - authenticate_customer(vendor_id, email, password) -> Customer login
    - get_customer_profile(vendor_id, customer_id) -> Customer data

class CartService:
    - get_cart(vendor_id, session_id) -> Cart contents
    - add_to_cart(vendor_id, session_id, product_id, quantity) -> Add item
    - update_cart_item(vendor_id, session_id, item_id, quantity) -> Update

# Public API Endpoints
GET /api/v1/public/vendors/{vendor_id}/products     # Public product catalog
GET /api/v1/public/vendors/{vendor_id}/products/{id} # Product details
POST /api/v1/public/vendors/{vendor_id}/customers/register # Customer registration
POST /api/v1/public/vendors/{vendor_id}/customers/login    # Customer login
GET/POST/PUT /api/v1/public/vendors/{vendor_id}/cart/{session_id} # Cart operations

Frontend Components (Days 4-5)

# Customer Shop Interface
- shop/home.html                        # Shop homepage
- shop/products.html                    # Product catalog
- shop/product.html                     # Product detail page
- shop/cart.html                        # Shopping cart
- shop/account/register.html            # Customer registration
- shop/account/login.html               # Customer login

# Shop JavaScript
- js/shop/catalog.js                    # Product browsing
- js/shop/cart.js                       # Cart functionality
- js/shop/auth.js                       # Customer authentication

Acceptance Criteria:

• Customers can browse products without authentication
• Customers can register vendor-specific accounts
• Customers can log into their vendor-specific accounts
• Customers can add products to cart
• Cart persists across sessions
• Customer data is properly isolated by vendor

Deliverables:

• Complete customer shop interface
• Customer registration and authentication
• Shopping cart functionality
• Public product browsing

---

Slice 5: Customer Places Orders (Week 5)

Core Value: Complete the ecommerce transaction workflow

User Stories:

• As a Customer, I can proceed to checkout with my cart
• As a Customer, I can place orders
• As a Customer, I can view my order history
• As a Vendor Owner, I can view and manage customer orders

Technical Implementation:

Backend Components (Days 1-3)

# Additional Models
class Order:
    id, vendor_id, customer_id, order_number, status, total_amount,
    shipping_address, billing_address, items, created_at, updated_at

class OrderItem:
    id, order_id, product_id, quantity, unit_price, total_price,
    created_at, updated_at

# Enhanced Services
class OrderService:
    - create_order_from_cart(vendor_id, customer_id, cart_id) -> Process checkout
    - get_customer_orders(vendor_id, customer_id) -> Order history
    - get_vendor_orders(vendor_id) -> All vendor orders
    - update_order_status(vendor_id, order_id, status) -> Order management

# New API Endpoints
POST /api/v1/public/vendors/{vendor_id}/orders      # Place order
GET /api/v1/public/vendors/{vendor_id}/customers/orders # Customer order history
GET /api/v1/orders                                   # Vendor order management
PUT /api/v1/orders/{id}/status                       # Update order status

Frontend Components (Days 4-5)

# Customer Interface Extensions
- shop/checkout.html                    # Checkout process
- shop/account/orders.html              # Customer order history
- shop/order-confirmation.html          # Order confirmation

# Vendor Interface Extensions
- vendor/orders.html                    # Order management
- vendor/orders/detail.html             # Order details

# Enhanced JavaScript
- js/shop/checkout.js                   # Checkout process
- js/vendor/orders.js                   # Order management

Acceptance Criteria:

• Customers can complete checkout process
• Orders are created with proper vendor isolation
• Customers can view their order history
• Vendors can view all their orders
• Vendors can update order status
• Order confirmation is sent to customers

Deliverables:

• Complete order processing system
• Checkout workflow
• Order management for vendors and customers
• Order status tracking

---

Deployment Strategy

Environment Setup

Each slice should be deployable to:

• Development: localhost:3000 with path-based routing
• Staging: Subdomain-based testing (vendor.staging.platform.com)
• Production: Full subdomain + custom domain support

Continuous Integration

• Automated testing for each slice
• Database migration scripts
• Environment configuration validation
• Deployment verification

Quality Gates

Slice Completion Criteria

Each slice must pass:

• All acceptance criteria met
• Manual testing complete
• Security validation (vendor isolation)
• Performance testing (basic load)
• Documentation updated
• Stakeholder demo successful

Testing Strategy

• Unit Tests: Service layer functionality
• Integration Tests: API endpoint behavior
• End-to-End Tests: Complete user workflows
• Security Tests: Vendor isolation validation

Success Metrics

Week 1 (Slice 1)

• Admin can create vendors
• Vendor owners can log in
• Vendor context detection works

Week 2 (Slice 2)

• Letzshop imports work correctly
• Background job processing functional
• Import status tracking operational

Week 3 (Slice 3)

• Product selection workflow complete
• Vendor catalog management functional
• Product customization working

Week 4 (Slice 4)

• Customer shop browsing works
• Customer registration/login functional
• Shopping cart operations working

Week 5 (Slice 5)

• Complete order workflow functional
• Order management for vendors working
• System ready for production use

This approach delivers working software weekly while building toward a complete platform. Each slice validates core assumptions and provides immediate value to stakeholders.