The Suppliers Service manages the complete supplier database with performance tracking, quality ratings, and price comparison capabilities. It enables data-driven supplier selection, tracks delivery performance, manages supplier contracts, and provides scorecards for supplier evaluation. This service is essential for maintaining strong supplier relationships while optimizing costs and ensuring consistent ingredient quality.

Key Features

Supplier Management

Complete Supplier Database - Contact details, payment terms, delivery schedules
Supplier Categories - Flour mills, dairy, packaging, equipment, services
Multi-Contact Management - Sales reps, delivery coordinators, accounts
Contract Management - Track agreements, pricing contracts, terms
Supplier Status - Active, inactive, preferred, blacklisted
Document Storage - Contracts, certificates, insurance documents
Geographic Data - Location, delivery zones, distance calculations

Performance Tracking

Delivery Performance - On-time delivery rate, lead time accuracy
Quality Metrics - Product quality ratings, defect rates
Reliability Score - Overall supplier reliability assessment
Order Fulfillment - Order accuracy, complete shipment rate
Communication Score - Responsiveness, issue resolution
Compliance Tracking - Food safety certifications, insurance validity

Price Management

Price Lists - Current pricing per product
Price History - Track price changes over time
Volume Discounts - Tiered pricing based on order size
Contract Pricing - Fixed prices for contract duration
Price Comparison - Compare prices across suppliers
Price Alerts - Notify on significant price changes
Cost Trend Analysis - Identify price trends and seasonality

Quality Assurance

Quality Ratings - 1-5 star ratings per supplier
Quality Reviews - Detailed quality assessments
Defect Tracking - Record quality issues and resolution
Product Certifications - Organic, fair trade, origin certifications
Lab Results - Store test results and analysis
Corrective Actions - Track quality improvement measures
Quality Trends - Monitor quality over time

Supplier Scorecards

Multi-Dimensional Scoring - Price, quality, delivery, service
Weighted Metrics - Customize scoring based on priorities
Trend Analysis - Improve/decline over time
Ranking System - Top suppliers by category
Performance Reports - Monthly/quarterly scorecards
Benchmarking - Compare against category averages

Communication & Collaboration

Contact Log - Track all supplier interactions
Email Integration - Send POs and communications
Order History - Complete purchase history per supplier
Issue Tracking - Log and resolve supplier problems
Notes & Reminders - Internal notes about suppliers
Calendar Integration - Delivery schedules, contract renewals

Business Value

For Bakery Owners

Cost Optimization - Data-driven supplier negotiations
Quality Assurance - Track and improve supplier quality
Risk Management - Identify unreliable suppliers early
Supplier Leverage - Performance data strengthens negotiations
Compliance - Track certifications and documentation
Strategic Relationships - Focus on best-performing suppliers

Quantifiable Impact

Cost Savings: 5-10% through data-driven negotiations
Quality Improvement: 15-25% fewer ingredient defects
Delivery Reliability: 20-30% improvement in on-time delivery
Time Savings: 3-5 hours/week on supplier management
Risk Reduction: Avoid €500-5,000 in spoiled ingredients
Supplier Consolidation: 20-30% fewer suppliers, better terms

For Procurement Staff

Supplier Selection - Clear data for choosing suppliers
Performance Visibility - Know which suppliers excel
Price Comparison - Quickly compare options
Issue Resolution - Track problems to completion
Contract Management - Never miss renewal dates

Technology Stack

Framework: FastAPI (Python 3.11+) - Async web framework
Database: PostgreSQL 17 - Supplier data
Caching: Redis 7.4 - Supplier data cache
Messaging: RabbitMQ 4.1 - Event publishing
ORM: SQLAlchemy 2.0 (async) - Database abstraction
Validation: Pydantic 2.0 - Schema validation
Logging: Structlog - Structured JSON logging
Metrics: Prometheus Client - Supplier metrics

API Endpoints (Key Routes)

Supplier Management

GET /api/v1/suppliers - List suppliers with filters
POST /api/v1/suppliers - Create new supplier
GET /api/v1/suppliers/{supplier_id} - Get supplier details
PUT /api/v1/suppliers/{supplier_id} - Update supplier
DELETE /api/v1/suppliers/{supplier_id} - Delete supplier (soft delete)
GET /api/v1/suppliers/{supplier_id}/contacts - Get supplier contacts

Performance Tracking

GET /api/v1/suppliers/{supplier_id}/performance - Get performance metrics
POST /api/v1/suppliers/{supplier_id}/performance/review - Add performance review
GET /api/v1/suppliers/{supplier_id}/performance/history - Performance history
GET /api/v1/suppliers/performance/rankings - Supplier rankings

Price Management

GET /api/v1/suppliers/{supplier_id}/pricing - Get supplier price list
POST /api/v1/suppliers/{supplier_id}/pricing - Add/update pricing
GET /api/v1/suppliers/{supplier_id}/pricing/history - Price history
POST /api/v1/suppliers/pricing/compare - Compare prices across suppliers

Quality Management

GET /api/v1/suppliers/{supplier_id}/quality - Get quality metrics
POST /api/v1/suppliers/{supplier_id}/quality/review - Add quality review
POST /api/v1/suppliers/{supplier_id}/quality/issue - Report quality issue
GET /api/v1/suppliers/{supplier_id}/quality/defects - Defect history

Scorecard & Analytics

GET /api/v1/suppliers/{supplier_id}/scorecard - Generate supplier scorecard
GET /api/v1/suppliers/analytics/dashboard - Supplier analytics dashboard
GET /api/v1/suppliers/analytics/top-performers - Top performing suppliers
GET /api/v1/suppliers/analytics/cost-analysis - Cost analysis by supplier

Communication

GET /api/v1/suppliers/{supplier_id}/communications - Communication log
POST /api/v1/suppliers/{supplier_id}/communications - Log communication
POST /api/v1/suppliers/{supplier_id}/send-email - Send email to supplier
GET /api/v1/suppliers/{supplier_id}/orders - Order history

Database Schema

Main Tables

suppliers

CREATE TABLE suppliers (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    supplier_name VARCHAR(255) NOT NULL,
    supplier_code VARCHAR(100),                  -- Internal supplier code
    supplier_type VARCHAR(100),                   -- flour_mill, dairy, packaging, equipment, service
    business_legal_name VARCHAR(255),
    tax_id VARCHAR(50),                          -- CIF/NIF for Spanish suppliers
    phone VARCHAR(50),
    email VARCHAR(255),
    website VARCHAR(255),
    address_line1 VARCHAR(255),
    address_line2 VARCHAR(255),
    city VARCHAR(100),
    state_province VARCHAR(100),
    postal_code VARCHAR(20),
    country VARCHAR(100) DEFAULT 'España',
    payment_terms VARCHAR(100),                   -- Net 30, Net 60, COD, etc.
    credit_limit DECIMAL(10, 2),
    currency VARCHAR(10) DEFAULT 'EUR',
    lead_time_days INTEGER DEFAULT 3,
    minimum_order_value DECIMAL(10, 2),
    delivery_days JSONB,                         -- ["Monday", "Wednesday", "Friday"]
    status VARCHAR(50) DEFAULT 'active',         -- active, inactive, preferred, blacklisted
    is_preferred BOOLEAN DEFAULT FALSE,
    notes TEXT,

    -- Performance metrics (cached)
    quality_rating DECIMAL(3, 2),                -- 1.00 to 5.00
    delivery_rating DECIMAL(3, 2),
    price_competitiveness DECIMAL(3, 2),
    overall_score DECIMAL(3, 2),
    total_orders INTEGER DEFAULT 0,
    on_time_deliveries INTEGER DEFAULT 0,
    on_time_delivery_percentage DECIMAL(5, 2),

    -- Compliance
    food_safety_cert_valid BOOLEAN DEFAULT FALSE,
    food_safety_cert_expiry DATE,
    insurance_valid BOOLEAN DEFAULT FALSE,
    insurance_expiry DATE,

    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(tenant_id, supplier_name)
);

supplier_contacts

CREATE TABLE supplier_contacts (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    supplier_id UUID REFERENCES suppliers(id) ON DELETE CASCADE,
    contact_name VARCHAR(255) NOT NULL,
    job_title VARCHAR(255),
    contact_type VARCHAR(50),                    -- sales, delivery, accounts, technical
    phone VARCHAR(50),
    mobile VARCHAR(50),
    email VARCHAR(255),
    is_primary BOOLEAN DEFAULT FALSE,
    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

supplier_products

CREATE TABLE supplier_products (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    supplier_id UUID REFERENCES suppliers(id) ON DELETE CASCADE,
    ingredient_id UUID NOT NULL,                 -- Link to inventory ingredient
    supplier_product_code VARCHAR(100),
    supplier_product_name VARCHAR(255),
    unit_price DECIMAL(10, 2) NOT NULL,
    unit VARCHAR(50) NOT NULL,
    minimum_order_quantity DECIMAL(10, 2),
    packaging VARCHAR(100),                      -- "25kg bag", "1L bottle", etc.
    lead_time_days INTEGER DEFAULT 3,
    is_preferred BOOLEAN DEFAULT FALSE,
    quality_grade VARCHAR(50),                   -- A, B, C or Premium, Standard, Economy
    certifications JSONB,                        -- ["Organic", "Non-GMO", "Fair Trade"]
    valid_from DATE DEFAULT CURRENT_DATE,
    valid_until DATE,
    is_active BOOLEAN DEFAULT TRUE,
    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(tenant_id, supplier_id, ingredient_id)
);

supplier_performance_reviews

CREATE TABLE supplier_performance_reviews (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    supplier_id UUID REFERENCES suppliers(id) ON DELETE CASCADE,
    review_date DATE NOT NULL DEFAULT CURRENT_DATE,
    review_period_start DATE NOT NULL,
    review_period_end DATE NOT NULL,

    -- Performance scores (1-5)
    quality_score DECIMAL(3, 2) NOT NULL,
    delivery_score DECIMAL(3, 2) NOT NULL,
    price_score DECIMAL(3, 2) NOT NULL,
    service_score DECIMAL(3, 2) NOT NULL,
    overall_score DECIMAL(3, 2) NOT NULL,

    -- Metrics
    total_orders INTEGER DEFAULT 0,
    on_time_deliveries INTEGER DEFAULT 0,
    on_time_percentage DECIMAL(5, 2),
    quality_issues INTEGER DEFAULT 0,
    defect_rate DECIMAL(5, 2),
    average_delivery_time_days DECIMAL(5, 2),
    total_spend DECIMAL(10, 2) DEFAULT 0.00,

    -- Qualitative feedback
    strengths TEXT,
    weaknesses TEXT,
    recommendations TEXT,

    reviewed_by UUID NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

supplier_quality_issues

CREATE TABLE supplier_quality_issues (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    supplier_id UUID REFERENCES suppliers(id) ON DELETE CASCADE,
    purchase_order_id UUID,                      -- Link to specific PO if applicable
    ingredient_id UUID,
    issue_date DATE NOT NULL DEFAULT CURRENT_DATE,
    issue_type VARCHAR(100) NOT NULL,            -- defect, contamination, wrong_product, damaged, expired
    severity VARCHAR(50) NOT NULL,               -- critical, major, minor
    description TEXT NOT NULL,
    quantity_affected DECIMAL(10, 2),
    unit VARCHAR(50),
    financial_impact DECIMAL(10, 2),

    -- Resolution
    resolution_status VARCHAR(50) DEFAULT 'open', -- open, in_progress, resolved, closed
    corrective_action TEXT,
    supplier_response TEXT,
    credit_issued DECIMAL(10, 2) DEFAULT 0.00,
    resolved_date DATE,
    resolved_by UUID,

    reported_by UUID NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

supplier_price_history

CREATE TABLE supplier_price_history (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    supplier_id UUID REFERENCES suppliers(id) ON DELETE CASCADE,
    ingredient_id UUID NOT NULL,
    effective_date DATE NOT NULL,
    unit_price DECIMAL(10, 2) NOT NULL,
    unit VARCHAR(50) NOT NULL,
    previous_price DECIMAL(10, 2),
    price_change_percentage DECIMAL(5, 2),
    reason VARCHAR(255),                         -- "market_increase", "contract_renewal", etc.
    created_at TIMESTAMP DEFAULT NOW(),
    INDEX idx_price_history_date (tenant_id, ingredient_id, effective_date DESC)
);

supplier_communications

CREATE TABLE supplier_communications (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    supplier_id UUID REFERENCES suppliers(id) ON DELETE CASCADE,
    communication_date TIMESTAMP NOT NULL DEFAULT NOW(),
    communication_type VARCHAR(50) NOT NULL,     -- email, phone, meeting, visit
    subject VARCHAR(255),
    summary TEXT NOT NULL,
    participants JSONB,                          -- Array of names
    action_items TEXT,
    follow_up_date DATE,
    logged_by UUID NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

supplier_contracts

CREATE TABLE supplier_contracts (
    id UUID PRIMARY KEY,
    tenant_id UUID NOT NULL,
    supplier_id UUID REFERENCES suppliers(id) ON DELETE CASCADE,
    contract_number VARCHAR(100),
    contract_type VARCHAR(100),                  -- pricing, volume, exclusive, service
    start_date DATE NOT NULL,
    end_date DATE NOT NULL,
    auto_renew BOOLEAN DEFAULT FALSE,
    renewal_notice_days INTEGER DEFAULT 30,
    contract_terms TEXT,
    payment_terms VARCHAR(100),
    minimum_volume DECIMAL(10, 2),
    maximum_volume DECIMAL(10, 2),
    fixed_pricing BOOLEAN DEFAULT FALSE,
    contract_value DECIMAL(10, 2),
    status VARCHAR(50) DEFAULT 'active',         -- draft, active, expired, terminated
    document_url VARCHAR(500),
    notes TEXT,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

Indexes for Performance

CREATE INDEX idx_suppliers_tenant_status ON suppliers(tenant_id, status);
CREATE INDEX idx_suppliers_type ON suppliers(tenant_id, supplier_type);
CREATE INDEX idx_supplier_products_supplier ON supplier_products(supplier_id);
CREATE INDEX idx_supplier_products_ingredient ON supplier_products(tenant_id, ingredient_id);
CREATE INDEX idx_performance_reviews_supplier ON supplier_performance_reviews(supplier_id, review_date DESC);
CREATE INDEX idx_quality_issues_supplier ON supplier_quality_issues(supplier_id, issue_date DESC);
CREATE INDEX idx_quality_issues_status ON supplier_quality_issues(tenant_id, resolution_status);

Business Logic Examples

Supplier Scorecard Calculation

async def calculate_supplier_scorecard(
    supplier_id: UUID,
    start_date: date,
    end_date: date
) -> SupplierScorecard:
    """
    Calculate comprehensive supplier scorecard for period.
    Scoring: 30% Quality, 30% Delivery, 25% Price, 15% Service
    """
    # Get all purchase orders for period
    purchase_orders = await db.query(PurchaseOrder).filter(
        PurchaseOrder.supplier_id == supplier_id,
        PurchaseOrder.order_date >= start_date,
        PurchaseOrder.order_date <= end_date,
        PurchaseOrder.status == 'received'
    ).all()

    if not purchase_orders:
        return None

    # QUALITY SCORE (1-5 scale)
    quality_issues = await db.query(SupplierQualityIssue).filter(
        SupplierQualityIssue.supplier_id == supplier_id,
        SupplierQualityIssue.issue_date >= start_date,
        SupplierQualityIssue.issue_date <= end_date
    ).all()

    total_orders = len(purchase_orders)
    critical_issues = len([i for i in quality_issues if i.severity == 'critical'])
    major_issues = len([i for i in quality_issues if i.severity == 'major'])
    minor_issues = len([i for i in quality_issues if i.severity == 'minor'])

    # Defect rate
    defect_rate = (critical_issues * 3 + major_issues * 2 + minor_issues) / total_orders if total_orders > 0 else 0

    # Quality score: 5 stars minus penalties
    quality_score = 5.0 - min(defect_rate, 4.0)

    # DELIVERY SCORE (1-5 scale)
    on_time_deliveries = len([
        po for po in purchase_orders
        if po.actual_delivery_date and po.expected_delivery_date
        and po.actual_delivery_date <= po.expected_delivery_date
    ])

    on_time_percentage = (on_time_deliveries / total_orders * 100) if total_orders > 0 else 0

    # Delivery score based on on-time percentage
    if on_time_percentage >= 95:
        delivery_score = 5.0
    elif on_time_percentage >= 90:
        delivery_score = 4.5
    elif on_time_percentage >= 85:
        delivery_score = 4.0
    elif on_time_percentage >= 75:
        delivery_score = 3.0
    elif on_time_percentage >= 60:
        delivery_score = 2.0
    else:
        delivery_score = 1.0

    # PRICE SCORE (1-5 scale)
    # Compare supplier prices against market average
    supplier_products = await get_supplier_products(supplier_id)
    price_comparisons = []

    for sp in supplier_products:
        # Get all suppliers for this ingredient
        all_suppliers = await db.query(SupplierProduct).filter(
            SupplierProduct.tenant_id == sp.tenant_id,
            SupplierProduct.ingredient_id == sp.ingredient_id,
            SupplierProduct.is_active == True
        ).all()

        if len(all_suppliers) > 1:
            prices = [s.unit_price for s in all_suppliers]
            avg_price = sum(prices) / len(prices)
            price_ratio = sp.unit_price / avg_price if avg_price > 0 else 1.0
            price_comparisons.append(price_ratio)

    if price_comparisons:
        avg_price_ratio = sum(price_comparisons) / len(price_comparisons)
        # Lower ratio = better price = higher score
        if avg_price_ratio <= 0.90:
            price_score = 5.0  # 10%+ below market
        elif avg_price_ratio <= 0.95:
            price_score = 4.5  # 5-10% below market
        elif avg_price_ratio <= 1.00:
            price_score = 4.0  # At market
        elif avg_price_ratio <= 1.05:
            price_score = 3.0  # 5% above market
        elif avg_price_ratio <= 1.10:
            price_score = 2.0  # 10% above market
        else:
            price_score = 1.0  # 10%+ above market
    else:
        price_score = 3.0  # Default if no comparison available

    # SERVICE SCORE (1-5 scale)
    # Based on communication responsiveness and issue resolution
    communications = await db.query(SupplierCommunication).filter(
        SupplierCommunication.supplier_id == supplier_id,
        SupplierCommunication.communication_date >= start_date,
        SupplierCommunication.communication_date <= end_date
    ).all()

    resolved_issues = len([
        i for i in quality_issues
        if i.resolution_status == 'resolved'
    ])
    total_issues = len(quality_issues)

    resolution_rate = (resolved_issues / total_issues * 100) if total_issues > 0 else 100

    # Service score based on issue resolution
    if resolution_rate >= 90 and len(communications) >= 2:
        service_score = 5.0
    elif resolution_rate >= 80:
        service_score = 4.0
    elif resolution_rate >= 70:
        service_score = 3.0
    elif resolution_rate >= 50:
        service_score = 2.0
    else:
        service_score = 1.0

    # WEIGHTED OVERALL SCORE
    overall_score = (
        quality_score * 0.30 +
        delivery_score * 0.30 +
        price_score * 0.25 +
        service_score * 0.15
    )

    # Calculate total spend
    total_spend = sum(po.total_amount for po in purchase_orders)

    # Average lead time
    lead_times = [
        (po.actual_delivery_date - po.order_date).days
        for po in purchase_orders
        if po.actual_delivery_date and po.order_date
    ]
    avg_lead_time = sum(lead_times) / len(lead_times) if lead_times else 0

    # Create scorecard
    scorecard = SupplierScorecard(
        supplier_id=supplier_id,
        period_start=start_date,
        period_end=end_date,
        quality_score=round(quality_score, 2),
        delivery_score=round(delivery_score, 2),
        price_score=round(price_score, 2),
        service_score=round(service_score, 2),
        overall_score=round(overall_score, 2),
        total_orders=total_orders,
        on_time_deliveries=on_time_deliveries,
        on_time_percentage=round(on_time_percentage, 2),
        quality_issues_count=len(quality_issues),
        defect_rate=round(defect_rate, 4),
        total_spend=total_spend,
        average_lead_time_days=round(avg_lead_time, 1)
    )

    return scorecard

Supplier Recommendation Engine

async def recommend_supplier_for_ingredient(
    tenant_id: UUID,
    ingredient_id: UUID,
    quantity: float,
    urgency: str = 'normal'
) -> list[dict]:
    """
    Recommend best suppliers for ingredient based on multiple criteria.
    Returns ranked list with scores and reasoning.
    """
    # Get all suppliers for ingredient
    supplier_products = await db.query(SupplierProduct).filter(
        SupplierProduct.tenant_id == tenant_id,
        SupplierProduct.ingredient_id == ingredient_id,
        SupplierProduct.is_active == True
    ).all()

    if not supplier_products:
        return []

    recommendations = []

    for sp in supplier_products:
        supplier = await get_supplier(sp.supplier_id)

        # Get supplier performance
        scorecard = await get_latest_scorecard(sp.supplier_id)

        # Calculate recommendation score
        scores = {}

        # Price score (40% weight for normal urgency, 20% for urgent)
        price_weight = 0.20 if urgency == 'urgent' else 0.40
        scores['price'] = scorecard.price_score if scorecard else 3.0

        # Quality score (30% weight)
        scores['quality'] = scorecard.quality_score if scorecard else 3.0

        # Delivery score (30% for normal, 50% for urgent)
        delivery_weight = 0.50 if urgency == 'urgent' else 0.30
        scores['delivery'] = scorecard.delivery_score if scorecard else 3.0

        # Service score (10% weight)
        scores['service'] = scorecard.service_score if scorecard else 3.0

        # Calculate weighted score
        if urgency == 'urgent':
            weighted_score = (
                scores['price'] * 0.20 +
                scores['quality'] * 0.30 +
                scores['delivery'] * 0.50
            )
        else:
            weighted_score = (
                scores['price'] * 0.40 +
                scores['quality'] * 0.30 +
                scores['delivery'] * 0.20 +
                scores['service'] * 0.10
            )

        # Check if minimum order quantity is met
        meets_moq = quantity >= (sp.minimum_order_quantity or 0)

        # Check lead time
        lead_time_acceptable = sp.lead_time_days <= 3 if urgency == 'urgent' else True

        # Calculate total cost
        total_cost = sp.unit_price * quantity

        recommendations.append({
            'supplier_id': str(supplier.id),
            'supplier_name': supplier.supplier_name,
            'unit_price': float(sp.unit_price),
            'total_cost': float(total_cost),
            'lead_time_days': sp.lead_time_days,
            'minimum_order_quantity': float(sp.minimum_order_quantity) if sp.minimum_order_quantity else None,
            'meets_moq': meets_moq,
            'lead_time_acceptable': lead_time_acceptable,
            'quality_score': float(scores['quality']),
            'delivery_score': float(scores['delivery']),
            'price_score': float(scores['price']),
            'service_score': float(scores['service']),
            'weighted_score': float(weighted_score),
            'recommendation_reason': generate_recommendation_reason(
                scores, urgency, meets_moq, lead_time_acceptable
            )
        })

    # Sort by weighted score descending
    recommendations.sort(key=lambda x: x['weighted_score'], reverse=True)

    return recommendations

def generate_recommendation_reason(
    scores: dict,
    urgency: str,
    meets_moq: bool,
    lead_time_acceptable: bool
) -> str:
    """Generate human-readable recommendation reason."""
    reasons = []

    if urgency == 'urgent' and lead_time_acceptable:
        reasons.append("Fast delivery available")

    if scores['quality'] >= 4.5:
        reasons.append("Excellent quality rating")
    elif scores['quality'] >= 4.0:
        reasons.append("Good quality rating")

    if scores['price'] >= 4.5:
        reasons.append("Best price")
    elif scores['price'] >= 4.0:
        reasons.append("Competitive price")

    if scores['delivery'] >= 4.5:
        reasons.append("Excellent delivery record")
    elif scores['delivery'] >= 4.0:
        reasons.append("Reliable delivery")

    if not meets_moq:
        reasons.append("⚠️ Below minimum order quantity")

    if not lead_time_acceptable:
        reasons.append("⚠️ Lead time too long for urgent order")

    return ", ".join(reasons) if reasons else "Standard supplier"

Price Trend Analysis

async def analyze_price_trends(
    tenant_id: UUID,
    ingredient_id: UUID,
    months_back: int = 12
) -> dict:
    """
    Analyze price trends for ingredient across all suppliers.
    """
    start_date = date.today() - timedelta(days=months_back * 30)

    # Get price history
    price_history = await db.query(SupplierPriceHistory).filter(
        SupplierPriceHistory.tenant_id == tenant_id,
        SupplierPriceHistory.ingredient_id == ingredient_id,
        SupplierPriceHistory.effective_date >= start_date
    ).order_by(SupplierPriceHistory.effective_date.asc()).all()

    if not price_history:
        return None

    # Calculate statistics
    prices = [p.unit_price for p in price_history]
    current_price = prices[-1]
    min_price = min(prices)
    max_price = max(prices)
    avg_price = sum(prices) / len(prices)

    # Calculate trend (simple linear regression)
    import statistics
    if len(prices) > 2:
        # Calculate slope
        x = list(range(len(prices)))
        x_mean = sum(x) / len(x)
        y_mean = avg_price

        numerator = sum((x[i] - x_mean) * (prices[i] - y_mean) for i in range(len(prices)))
        denominator = sum((x[i] - x_mean) ** 2 for i in range(len(x)))

        slope = numerator / denominator if denominator != 0 else 0
        trend_direction = 'increasing' if slope > 0.01 else 'decreasing' if slope < -0.01 else 'stable'
    else:
        trend_direction = 'insufficient_data'

    # Calculate volatility (coefficient of variation)
    std_dev = statistics.stdev(prices) if len(prices) > 1 else 0
    volatility = (std_dev / avg_price * 100) if avg_price > 0 else 0

    # Identify best and worst suppliers
    supplier_avg_prices = {}
    for ph in price_history:
        if ph.supplier_id not in supplier_avg_prices:
            supplier_avg_prices[ph.supplier_id] = []
        supplier_avg_prices[ph.supplier_id].append(ph.unit_price)

    supplier_averages = {
        sid: sum(prices) / len(prices)
        for sid, prices in supplier_avg_prices.items()
    }

    best_supplier_id = min(supplier_averages, key=supplier_averages.get)
    worst_supplier_id = max(supplier_averages, key=supplier_averages.get)

    return {
        'ingredient_id': str(ingredient_id),
        'period_months': months_back,
        'data_points': len(price_history),
        'current_price': float(current_price),
        'min_price': float(min_price),
        'max_price': float(max_price),
        'average_price': float(avg_price),
        'price_range': float(max_price - min_price),
        'trend_direction': trend_direction,
        'volatility_percentage': round(volatility, 2),
        'price_change_percentage': round((current_price - prices[0]) / prices[0] * 100, 2),
        'best_supplier_id': str(best_supplier_id),
        'best_supplier_avg_price': float(supplier_averages[best_supplier_id]),
        'worst_supplier_id': str(worst_supplier_id),
        'worst_supplier_avg_price': float(supplier_averages[worst_supplier_id]),
        'price_difference_percentage': round(
            (supplier_averages[worst_supplier_id] - supplier_averages[best_supplier_id]) /
            supplier_averages[best_supplier_id] * 100, 2
        )
    }

Events & Messaging

Published Events (RabbitMQ)

Exchange: suppliers Routing Keys: suppliers.performance_alert, suppliers.price_change, suppliers.quality_issue, suppliers.contract_expiring

Supplier Performance Alert

{
    "event_type": "supplier_performance_alert",
    "tenant_id": "uuid",
    "supplier_id": "uuid",
    "supplier_name": "Harinas García",
    "alert_type": "poor_delivery",
    "on_time_delivery_percentage": 65.0,
    "threshold": 80.0,
    "period_days": 30,
    "recommendation": "Consider alternative suppliers or renegotiate terms",
    "timestamp": "2025-11-06T09:00:00Z"
}

Supplier Price Change Event

{
    "event_type": "supplier_price_change",
    "tenant_id": "uuid",
    "supplier_id": "uuid",
    "supplier_name": "Lácteos del Norte",
    "ingredient_id": "uuid",
    "ingredient_name": "Mantequilla",
    "old_price": 4.50,
    "new_price": 5.20,
    "change_percentage": 15.56,
    "effective_date": "2025-11-15",
    "reason": "market_increase",
    "timestamp": "2025-11-06T14:00:00Z"
}

Supplier Quality Issue Event

{
    "event_type": "supplier_quality_issue",
    "tenant_id": "uuid",
    "supplier_id": "uuid",
    "supplier_name": "Distribuidora Madrid",
    "issue_id": "uuid",
    "severity": "major",
    "issue_type": "contamination",
    "ingredient_name": "Harina Integral",
    "description": "Foreign material found in bag",
    "financial_impact": 125.00,
    "timestamp": "2025-11-06T11:30:00Z"
}

Contract Expiring Alert

{
    "event_type": "supplier_contract_expiring",
    "tenant_id": "uuid",
    "supplier_id": "uuid",
    "supplier_name": "Embalajes Premium",
    "contract_id": "uuid",
    "contract_type": "pricing",
    "expiry_date": "2025-11-30",
    "days_until_expiry": 24,
    "auto_renew": false,
    "action_required": "Review and renew contract",
    "timestamp": "2025-11-06T08:00:00Z"
}

Consumed Events

From Procurement: Purchase orders update supplier performance
From Inventory: Quality issues on received goods
From Accounting: Payment history affects supplier relationships

Custom Metrics (Prometheus)

# Supplier metrics
suppliers_total = Gauge(
    'suppliers_total',
    'Total suppliers',
    ['tenant_id', 'supplier_type', 'status']
)

supplier_performance_score = Histogram(
    'supplier_performance_score',
    'Supplier overall performance score',
    ['tenant_id', 'supplier_id'],
    buckets=[1.0, 2.0, 3.0, 3.5, 4.0, 4.5, 5.0]
)

supplier_quality_issues_total = Counter(
    'supplier_quality_issues_total',
    'Total quality issues',
    ['tenant_id', 'supplier_id', 'severity']
)

supplier_on_time_delivery_percentage = Histogram(
    'supplier_on_time_delivery_percentage',
    'Supplier on-time delivery rate',
    ['tenant_id', 'supplier_id'],
    buckets=[50, 60, 70, 80, 85, 90, 95, 98, 100]
)

supplier_price_changes_total = Counter(
    'supplier_price_changes_total',
    'Total price changes',
    ['tenant_id', 'supplier_id', 'direction']
)

Configuration

Environment Variables

Service Configuration:

PORT - Service port (default: 8012)
DATABASE_URL - PostgreSQL connection string
REDIS_URL - Redis connection string
RABBITMQ_URL - RabbitMQ connection string

Performance Configuration:

QUALITY_SCORE_WEIGHT - Quality scoring weight (default: 0.30)
DELIVERY_SCORE_WEIGHT - Delivery scoring weight (default: 0.30)
PRICE_SCORE_WEIGHT - Price scoring weight (default: 0.25)
SERVICE_SCORE_WEIGHT - Service scoring weight (default: 0.15)

Alert Configuration:

MIN_ON_TIME_DELIVERY_PERCENTAGE - Alert threshold (default: 80.0)
MAX_DEFECT_RATE_PERCENTAGE - Alert threshold (default: 5.0)
PRICE_CHANGE_ALERT_PERCENTAGE - Alert on price change (default: 10.0)
CONTRACT_EXPIRY_ALERT_DAYS - Days before expiry (default: 30)

Quality Configuration:

REQUIRE_FOOD_SAFETY_CERT - Require certifications (default: true)
CERT_EXPIRY_REMINDER_DAYS - Remind before expiry (default: 60)

Development Setup

Prerequisites

Python 3.11+
PostgreSQL 17
Redis 7.4
RabbitMQ 4.1

Local Development

cd services/suppliers
python -m venv venv
source venv/bin/activate

pip install -r requirements.txt

export DATABASE_URL=postgresql://user:pass@localhost:5432/suppliers
export REDIS_URL=redis://localhost:6379/0
export RABBITMQ_URL=amqp://guest:guest@localhost:5672/

alembic upgrade head
python main.py

Integration Points

Dependencies

Auth Service - User authentication
PostgreSQL - Supplier data
Redis - Caching
RabbitMQ - Event publishing

Dependents

Procurement Service - Supplier selection for purchase orders
Inventory Service - Quality tracking on receipts
AI Insights Service - Supplier optimization recommendations
Notification Service - Performance and contract alerts
Frontend Dashboard - Supplier management UI

Business Value for VUE Madrid

Problem Statement

Spanish bakeries struggle with:

No systematic supplier performance tracking
Manual price comparison across suppliers
No quality issue documentation
Lost supplier history when staff changes
No leverage in supplier negotiations
Missed contract renewals and price increases

Solution

Bakery-IA Suppliers Service provides:

Data-Driven Decisions: Performance scorecards guide supplier selection
Cost Control: Price tracking and comparison across suppliers
Quality Assurance: Document and resolve quality issues systematically
Relationship Management: Complete supplier history and communication log
Risk Management: Track certifications, contracts, and performance

Quantifiable Impact

Cost Savings:

€100-300/month from data-driven negotiations (5-10% procurement savings)
€150-500/month from reduced ingredient defects (15-25% quality improvement)
€50-200/month from avoiding expired contracts with price increases
Total: €300-1,000/month savings

Time Savings:

3-5 hours/week on supplier management and tracking
1-2 hours/week on price comparison
1-2 hours/week on quality issue documentation
Total: 5-9 hours/week saved

Operational Improvements:

20-30% improvement in on-time delivery through supplier accountability
15-25% fewer ingredient defects through quality tracking
100% contract renewal visibility (avoid surprise price increases)
20-30% supplier consolidation (focus on best performers)

Target Market Fit (Spanish Bakeries)

Supplier Relationships: Spanish business culture values long-term relationships
Quality Focus: Spanish consumers demand high-quality ingredients
Cost Pressure: SMBs need every cost advantage in competitive market
Compliance: Food safety certifications required by Spanish law

ROI Calculation

Investment: €0 additional (included in platform subscription) Monthly Savings: €300-1,000 Annual ROI: €3,600-12,000 value per bakery Payback: Immediate (included in subscription)