Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
287 lines (236 loc) · 9.01 KB

ARCHITECTURE.md

File metadata and controls

287 lines (236 loc) · 9.01 KB
Raw

Nike Search Widget - System Architecture

🏗️ System Overview

The Nike Search Widget is a comprehensive system that enables intelligent Nike product search and comparison through multiple interfaces. It's built as a Model Context Protocol (MCP) server with custom UI components, designed to integrate seamlessly with ChatGPT's Apps SDK.

graph TB
    subgraph "Frontend Layer"
        UI[React UI Widget]
        HTML[Test Interface]
    end
    
    subgraph "API Layer"
        MCP[MCP Server]
        REST[REST API Server]
        SSE[SSE Endpoint]
    end
    
    subgraph "Data Layer"
        NIKE[Nike.com API]
        CACHE[Response Cache]
    end
    
    subgraph "Integration Layer"
        CHATGPT[ChatGPT Apps SDK]
        CLIENT[MCP Client]
    end
    
    UI --> MCP
    HTML --> REST
    MCP --> NIKE
    REST --> MCP
    SSE --> MCP
    CHATGPT --> UI
    CLIENT --> SSE
    MCP --> CACHE
Loading

🔧 Core Components

1. Nike Search MCP Server (nikesearch.py)

Primary component - Full-featured MCP server with advanced Nike API integration.

Key Features:

  • 🔍 Product Search - Multi-parameter search with filters
  • 🆚 Product Comparison - Side-by-side product analysis
  • 🖼️ Image Processing - Product image extraction and optimization
  • 📊 Smart Caching - Response caching for performance
  • 🛡️ Error Handling - Robust error recovery and fallbacks

Architecture:

class NikeSearchMCPServer:
    ├── NikeSearchClient          # Core API client
    ├── search_products()         # Main search functionality
    ├── get_product_details()     # Detailed product info
    ├── compare_products()        # Product comparison
    └── get_product_images()      # Image extraction

2. REST API Server (nikesearch_rest.py)

Bridge component - FastAPI wrapper providing REST and SSE endpoints.

Endpoints:

  • GET /search - Product search via REST
  • GET /compare - Product comparison via REST
  • POST /sse - Server-Sent Events for MCP communication
  • GET /health - Health check endpoint

Integration Pattern:

FastAPI App
├── CORS Support           # Cross-origin requests
├── MCP Server Instance    # Embedded MCP server
├── SSE Transport Layer    # Real-time communication
└── Request Validation     # Pydantic models

3. React UI Components (web/)

Presentation layer - Modern React widgets following OpenAI Apps SDK patterns.

Component Hierarchy:

App.tsx (Main Container)
├── ProductCard.tsx       # Individual product display
├── hooks.ts             # OpenAI SDK integration hooks
├── types.ts             # TypeScript definitions
└── component.tsx        # Entry point and mounting

Key Features:

  • 🌓 Theme Support - Light/dark mode switching
  • 📱 Responsive Design - Mobile-first responsive layout
  • ⚡ Real-time Updates - Live data synchronization
  • 🎨 Nike Branding - Official Nike design system
  • 🔗 External Links - Direct Nike.com integration

4. Test Infrastructure (test_mcp_client.py)

Development tool - Comprehensive testing client for MCP endpoints.

📊 Data Flow Architecture

Search Flow

sequenceDiagram
    participant U as User
    participant UI as React Widget
    participant MCP as MCP Server
    participant N as Nike API
    
    U->>UI: Enter search query
    UI->>MCP: search_products(query, filters)
    MCP->>N: HTTP request with headers
    N->>MCP: Product JSON response
    MCP->>MCP: Parse & validate data
    MCP->>UI: Structured product list
    UI->>U: Rendered product cards
Loading

Comparison Flow

sequenceDiagram
    participant U as User
    participant UI as React Widget
    participant MCP as MCP Server
    participant N as Nike API
    
    U->>UI: Select products to compare
    UI->>MCP: compare_products(product_ids)
    par Parallel API Calls
        MCP->>N: Get product 1 details
        MCP->>N: Get product 2 details
    end
    MCP->>MCP: Compare specifications
    MCP->>UI: Comparison matrix
    UI->>U: Side-by-side comparison
Loading

🛠️ Technology Stack

Backend

  • Python 3.9+ - Core runtime
  • MCP Protocol - Model Context Protocol for AI integration
  • FastAPI - Modern async web framework
  • aiohttp - Async HTTP client
  • Pydantic - Data validation and serialization

Frontend

  • React 18 - UI framework with hooks
  • TypeScript - Type-safe JavaScript
  • ESBuild - Fast bundling and compilation
  • CSS-in-JS - Component-scoped styling

Integration

  • OpenAI Apps SDK - ChatGPT custom app integration
  • Server-Sent Events - Real-time communication
  • CORS - Cross-origin resource sharing

📁 File Structure

nikesearch/
├── 🐍 Backend Services
│   ├── nikesearch.py          # Main MCP server (1554 lines)
│   ├── nikesearch_rest.py     # REST API wrapper (328 lines)
│   ├── test_mcp_client.py     # Testing utilities (151 lines)
│   └── main.py                # Entry point
│
├── ⚛️ Frontend Components  
│   └── web/
│       ├── src/
│       │   ├── App.tsx            # Main container (224 lines)
│       │   ├── ProductCard.tsx    # Product display (158 lines) 
│       │   ├── component.tsx      # Entry point (26 lines)
│       │   ├── hooks.ts           # SDK integration (100 lines)
│       │   └── types.ts           # Type definitions (57 lines)
│       ├── dist/
│       │   └── component.js       # Compiled bundle
│       ├── test-with-server.html  # Local testing interface
│       └── package.json           # Node.js dependencies
│
├── 📦 Configuration
│   ├── pyproject.toml        # Python project config
│   ├── requirements.txt      # Python dependencies  
│   ├── uv.lock              # Lock file
│   └── app-manifest.json     # OpenAI app manifest
│
└── 📚 Documentation
    ├── README.md
    ├── ARCHITECTURE.md       # This file
    ├── QUICK_START.md
    └── *.md                  # Additional docs

🔄 Integration Patterns

OpenAI Apps SDK Integration

// Hook-based state management
const toolOutput = useToolOutput();           // Get MCP results
const theme = useTheme();                     // UI theme sync
const displayMode = useDisplayMode();         // Layout mode
const [widgetState, setWidgetState] = useWidgetState({});

MCP Protocol Compliance

# Standard MCP server structure
server = Server("nike-search")

@server.call_tool()
async def search_products(query: str, **filters) -> CallToolResult:
    """Tool implementation following MCP standards"""
    return CallToolResult(content=[TextContent(type="text", text=result)])

Nike API Integration

# Robust API client with fallbacks
class NikeSearchClient:
    async def search_products(self, query: str) -> List[NikeProduct]:
        # Multiple endpoint strategies
        # Error handling and retries
        # Response caching
        # Data validation

🚀 Deployment Architecture

Development Environment

# Backend services
uv run python nikesearch.py          # MCP server (stdio)
uv run python nikesearch_rest.py     # REST API (port 8000)

# Frontend development  
cd web && npm run build              # Build React components
python3 -m http.server 8080          # Serve test interface

Production Considerations

  • Load Balancing - Multiple MCP server instances
  • Caching Layer - Redis for API response caching
  • Rate Limiting - Nike API usage optimization
  • Monitoring - Health checks and error tracking
  • Security - API key management and request validation

🔍 Key Design Patterns

1. Async/Await Throughout

All I/O operations use async patterns for optimal performance.

2. Type Safety

Pydantic models and TypeScript ensure data consistency.

3. Error Boundaries

Graceful degradation at every layer.

4. Caching Strategy

Smart caching to minimize Nike API calls.

5. Responsive Design

Mobile-first UI with adaptive layouts.

6. SDK Integration

Native OpenAI Apps SDK patterns for seamless ChatGPT integration.

🎯 Performance Optimizations

  • Parallel API Calls - Concurrent product fetching
  • Image Optimization - Lazy loading and fallbacks
  • Bundle Splitting - Optimized JavaScript delivery
  • Request Deduplication - Avoid redundant API calls
  • Memory Management - Efficient data structures

🔐 Security Considerations

  • Input Validation - All user inputs sanitized
  • Rate Limiting - Prevent API abuse
  • CORS Policy - Controlled cross-origin access
  • Error Sanitization - No sensitive data in error messages
  • API Key Management - Secure credential handling

This architecture supports both development testing and production deployment, providing a robust foundation for Nike product search and comparison capabilities.