dss/.dss/PLUGIN_MARKETPLACE_ARCHITECTURE.md

# Plugin Marketplace Architecture Analysis

**Date**: 2025-12-06
**Status**: ✅ Analysis Complete - Hybrid Architecture Recommended
**Confidence**: Very High (90%+)
**Validated By**: Gemini 3 Pro Preview (6-step thinkdeep analysis)

---

## Executive Summary

**Question**: Should we build a plugin marketplace on our DSS server for plugin distribution?

**Answer**: **NO** to full marketplace. **YES** to lightweight hybrid architecture.

**Recommendation**: GitHub hosting + DSS Registry API (Hybrid Model)

---

## Analysis Results

### 🔍 Key Discovery

Claude Code already supports **multiple GitHub-based plugin marketplaces** via the `extraKnownMarketplaces` setting in `.claude/settings.json`:

```json
{
  "extraKnownMarketplaces": [
    {
      "name": "My Marketplace",
      "url": "https://github.com/user/repo",
      "description": "Custom plugins"
    }
  ]
}
```

**Implication**: The infrastructure for plugin distribution already exists. We don't need to reinvent it.

---

## Architecture Comparison

| Aspect | Full Marketplace | Hybrid (Recommended) |
|--------|------------------|---------------------|
| **Implementation Time** | 5-7 weeks | 2-3 days |
| **Maintenance Burden** | ~40 hrs/month | ~2 hrs/month |
| **Security Risk** | High | Low |
| **Infrastructure Needed** | File hosting, CDN, backups, versioning | Simple REST API |
| **GitHub Integration** | Manual sync | Direct consumption |
| **Development Cost** | $20-30K equivalent | ~$1K equivalent |

---

## Recommended Architecture: Hybrid Model

### Components

**1. GitHub (File Hosting & Distribution)**
- Hosts actual plugin files (`.py`, `.json`, etc.)
- Provides version control, code review, audit trail
- Handles security scanning, access control
- Free infrastructure (GitHub Pages, Releases)

**2. DSS Registry API (Discovery & Analytics)**
- Lightweight REST API on DSS server
- Provides plugin discovery, search, categories
- Tracks download/usage analytics per team
- Enables private plugin sharing within organizations

**3. Claude Code (Installation)**
- Users add GitHub URLs to `extraKnownMarketplaces`
- Existing Claude Code plugin system handles installation
- Zero changes needed to Claude Code itself

### Data Flow

```
┌──────────────┐
│   GitHub     │  Hosts: plugin files, metadata, releases
│  (Storage)   │
└──────┬───────┘
       │
       │ ① Fetch metadata
       │
┌──────▼───────┐
│ DSS Registry │  Provides: search, analytics, team features
│     API      │
└──────┬───────┘
       │
       │ ② Query available plugins
       │
┌──────▼───────┐
│ Claude Code  │  Displays: plugin browser, install instructions
│     UI       │
└──────┬───────┘
       │
       │ ③ Install: Add to extraKnownMarketplaces
       │
┌──────▼───────┐
│     User     │
└──────────────┘
```

---

## Implementation Plan

### Phase 1: Registry API (2-3 days)

**API Endpoints**:
```
GET  /api/plugins/registry          - List all registered plugins
GET  /api/plugins/search?q={query}  - Search plugins
GET  /api/plugins/{id}              - Get plugin details + analytics
POST /api/plugins/register          - Register new plugin (GitHub URL)
POST /api/plugins/{id}/analytics    - Track download/usage event
```

**Database Schema**:
```sql
-- plugins table
CREATE TABLE plugins (
  id VARCHAR(50) PRIMARY KEY,
  name VARCHAR(200) NOT NULL,
  description TEXT,
  github_url VARCHAR(500) NOT NULL,
  author VARCHAR(100),
  category VARCHAR(50),
  tags TEXT[],
  version VARCHAR(20),
  downloads_count INTEGER DEFAULT 0,
  rating_avg DECIMAL(3,2),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- plugin_analytics table
CREATE TABLE plugin_analytics (
  id SERIAL PRIMARY KEY,
  plugin_id VARCHAR(50) REFERENCES plugins(id),
  team_id VARCHAR(50),
  event_type VARCHAR(20), -- install, uninstall, usage
  timestamp TIMESTAMP DEFAULT NOW()
);
```

**GitHub Integration**:
```python
async def sync_plugin_metadata(plugin_id: str, github_url: str):
    """Fetch plugin.json from GitHub and update registry."""
    # Parse GitHub URL
    # Fetch raw content of .claude-plugin/plugin.json
    # Validate schema
    # Update database with metadata
    # Cache for 1 hour
```

### Phase 2: Dynamic Plugin Loader ⚠️ CRITICAL

**Current Problem**:
- Plugins are hardcoded in `tools/dss_mcp/tools/project_tools.py`
- Adding a new plugin requires manual code changes
- No auto-discovery mechanism

**Solution**: Create plugin auto-loader

**File**: `tools/dss_mcp/plugin_loader.py`
```python
"""Dynamic plugin loader for DSS MCP server."""
import importlib
import pkgutil
import logging
from pathlib import Path
from typing import List, Dict, Any

logger = logging.getLogger(__name__)

def load_plugins(plugin_dirs: List[str] = None) -> List[Dict[str, Any]]:
    """
    Dynamically load all plugins from specified directories.

    Plugin Contract:
    - Must be a Python module (.py file)
    - Must expose EXPORT_TOOLS variable (list of MCP tool definitions)
    - Optional: PLUGIN_METADATA dict with name, version, author

    Args:
        plugin_dirs: List of directories to scan. Defaults to ['tools'].

    Returns:
        List of MCP tool definitions from all discovered plugins.
    """
    if plugin_dirs is None:
        plugin_dirs = ['tools']

    registry = []

    for plugin_dir in plugin_dirs:
        plugin_path = Path(plugin_dir)
        if not plugin_path.exists():
            logger.warning(f"Plugin directory not found: {plugin_dir}")
            continue

        # Scan for Python modules
        for module_file in plugin_path.glob('*.py'):
            if module_file.name.startswith('_'):
                continue  # Skip __init__.py, __pycache__, etc.

            module_name = module_file.stem

            try:
                # Dynamically import the module
                spec = importlib.util.spec_from_file_location(
                    f"plugins.{module_name}",
                    module_file
                )
                module = importlib.util.module_from_spec(spec)
                spec.loader.exec_module(module)

                # Check for plugin contract compliance
                if hasattr(module, 'EXPORT_TOOLS'):
                    tools = module.EXPORT_TOOLS
                    registry.extend(tools)

                    metadata = getattr(module, 'PLUGIN_METADATA', {})
                    logger.info(
                        f"Loaded plugin: {metadata.get('name', module_name)} "
                        f"({len(tools)} tools)"
                    )
                else:
                    logger.debug(
                        f"Skipping {module_name} (no EXPORT_TOOLS variable)"
                    )

            except Exception as e:
                logger.error(f"Failed to load plugin {module_name}: {e}")

    return registry
```

**Plugin Contract Example**:
```python
# tools/network_logger.py - Example plugin

PLUGIN_METADATA = {
    "name": "Network Logger",
    "version": "1.0.0",
    "author": "DSS Team",
    "description": "Captures and analyzes browser network traffic"
}

EXPORT_TOOLS = [
    {
        "name": "get_network_requests",
        "description": "Get browser network requests",
        "inputSchema": {
            "type": "object",
            "properties": {
                "filter_type": {
                    "type": "string",
                    "enum": ["xhr", "fetch", "all"]
                }
            }
        }
    }
]

# Implementation class would go here
```

**Update MCP Server**:
```python
# tools/dss_mcp/server.py
from .plugin_loader import load_plugins

# Instead of hardcoded imports:
# from .tools.project_tools import PROJECT_TOOLS
# from .tools.debug_tools import DEBUG_TOOLS

# Use dynamic loading:
all_tools = load_plugins(['tools/dss_mcp/tools'])

# Register with MCP
for tool in all_tools:
    mcp.tool()(tool)
```

### Phase 3: Discovery UI (1-2 days)

**Location**: `admin-ui/plugins.html`

**Features**:
- Browse plugins by category (Design Tools, Testing, Debugging, etc.)
- Search functionality
- Plugin details page with:
  - Description, author, version
  - Download count, ratings
  - GitHub repository link
  - Installation instructions
- "Install" button → copies to clipboard:
  ```json
  {
    "name": "Network Logger",
    "url": "https://github.com/overbits/dss-plugins/tree/main/network-logger",
    "description": "Network traffic analyzer"
  }
  ```

**User Flow**:
1. Browse/search plugins at `https://dss.overbits.luz.uy/plugins`
2. Click "Install" → copies GitHub URL
3. Add to `.claude/settings.json` → `extraKnownMarketplaces`
4. Claude Code auto-discovers and installs plugin

### Phase 4: Team Features (Optional, 1-2 days)

- **Private Plugins**: Team-specific plugin repos
- **Usage Analytics**: Which plugins are most used by your team
- **Recommendations**: "Teams like yours also use..."
- **Admin Dashboard**: Manage approved plugins for organization

---

## What We DON'T Need ❌

- ❌ File hosting/storage infrastructure
- ❌ CDN (Content Delivery Network)
- ❌ Backup systems for plugin files
- ❌ Version management (GitHub handles this)
- ❌ Code security scanning (GitHub handles this)
- ❌ User authentication for downloads (GitHub handles access control)
- ❌ Payment processing (free plugins, GitHub Sponsors for premium)

---

## Security Implications

### GitHub-Based (Recommended) ✅

**Strengths**:
- Code review via Pull Requests
- Audit trail (Git history)
- GitHub's security scanning (Dependabot, CodeQL)
- Access control (public/private repos, teams)
- Trusted platform

**Risks**:
- Malicious plugins (mitigated by curated registry)
- Dependency vulnerabilities (mitigated by GitHub scanning)

**Mitigation Strategy**:
1. **Curated Registry**: All plugins require PR review before appearing in registry
2. **Checksum Validation**: Registry stores SHA256 checksums
3. **Dependency Whitelist**: Start with "standard library only" or pre-approved packages
4. **Sandbox Execution**: Future enhancement - run plugins in isolated environment

### Server-Hosted ❌

**Risks**:
- Code injection vulnerabilities
- File upload attacks
- Unvetted code execution
- No audit trail
- Maintenance nightmare

---

## Migration Path

### Existing Plugins

Current structure:
```
dss-claude-plugin/
├── .claude-plugin/
│   └── plugin.json
├── commands/
├── skills/
└── agents/
```

**Step 1**: Create GitHub repo structure
```
dss-plugins/
├── network-logger/
│   ├── .claude-plugin/plugin.json
│   └── network_logger.py
├── performance-analyzer/
│   ├── .claude-plugin/plugin.json
│   └── performance_analyzer.py
└── registry.json  # Central registry file
```

**Step 2**: Publish to GitHub
```bash
gh repo create overbits/dss-plugins --public
git push origin main
```

**Step 3**: Register in DSS API
```bash
POST /api/plugins/register
{
  "github_url": "https://github.com/overbits/dss-plugins/tree/main/network-logger"
}
```

**Step 4**: Users install
```json
// .claude/settings.json
{
  "extraKnownMarketplaces": [
    {
      "name": "DSS Official Plugins",
      "url": "https://github.com/overbits/dss-plugins",
      "description": "Official DSS design system plugins"
    }
  ]
}
```

---

## Success Metrics

### Phase 1 (Registry API)
- ✅ API endpoints functional
- ✅ Database schema created
- ✅ GitHub metadata sync working
- ✅ Basic search functional

### Phase 2 (Dynamic Loader)
- ✅ Plugins auto-discovered on server start
- ✅ No manual registration needed
- ✅ Error handling for broken plugins
- ✅ Plugin contract documented

### Phase 3 (Discovery UI)
- ✅ Plugin browser accessible
- ✅ Search & filter working
- ✅ Install flow documented
- ✅ Analytics tracking events

### Phase 4 (Team Features)
- ✅ Private plugin support
- ✅ Team usage dashboard
- ✅ Admin controls functional

---

## Timeline

| Phase | Component | Effort | Priority |
|-------|-----------|--------|----------|
| 2 | Dynamic Plugin Loader | 1 day | 🔴 CRITICAL |
| 1 | Registry API | 2 days | 🟡 High |
| 3 | Discovery UI | 1-2 days | 🟢 Medium |
| 4 | Team Features | 1-2 days | 🔵 Low |

**Total**: 5-7 days for full implementation
**Minimum Viable**: 3 days (Phases 1+2)

---

## Expert Validation Notes

From Gemini 3 Pro Preview analysis:

> "The proposed Hybrid Architecture (GitHub-hosted files + DSS Registry API) is the correct strategic choice. It avoids the 'marketplace antipattern' (building infrastructure for billing/hosting that already exists) while retaining control over discovery and curation."

**Critical Insight**:
> "For this to work practically, the underlying DSS MCP server must be refactored to support **dynamic tool loading**, otherwise 'installing' a plugin requires manual code changes."

**Security Warning**:
> "Code Injection Risk: Downloading Python files and executing them is high-risk. Mitigation: Registry must be curated (PR review required)."

**Dependency Management**:
> "Plugins might require conflicting Python packages. Mitigation: Start with 'standard library only' or pre-approved dependency list (like httpx, numpy)."

---

## Conclusion

**Recommendation**: Implement Hybrid Architecture (GitHub + DSS Registry API)

**Priority Order**:
1. **Phase 2 (Dynamic Loader)** - CRITICAL, blocks everything else
2. **Phase 1 (Registry API)** - Core discovery infrastructure
3. **Phase 3 (Discovery UI)** - Improves UX
4. **Phase 4 (Team Features)** - Nice-to-have

**Total Effort**: 5-7 days
**Maintenance**: ~2 hours/month
**Security Risk**: Low (GitHub handles file hosting)
**Cost**: Minimal (no infrastructure needed)

**Next Steps**:
1. Create `plugin_loader.py` with auto-discovery
2. Define plugin contract documentation
3. Test with example plugin
4. Implement Registry API
5. Create discovery UI
6. Launch with curated initial plugins

---

**Analysis validated by**: Gemini 3 Pro Preview
**Confidence**: Very High (90%+)
**Date**: 2025-12-06