Marketplace Architecture

Overview

The ATOM marketplace ecosystem enables cross-tenant sharing and federation of AI capabilities across four distinct marketplaces:

Agent Marketplace - Share mature AI agents with pre-learned capabilities
Skill Marketplace - Distribute reusable AI skills and functions
Canvas Marketplace - Share UI canvas templates and visual components
Domain Marketplace - Exchange specialist domain expertise templates

Architecture Diagram

Data Flow Diagrams

Marketplace Ecosystem Data Flow

Federation Protocol Flow

Multi-Tenant Isolation Boundaries

Security Layers

System Components

1. Marketplace Services

AgentMarketplaceService

Location: core/agent_marketplace_service.py

Responsibilities:

Publish mature agents to marketplace
Install agents from marketplace
Anonymize experience memory for sharing
Track agent installations

Key Methods:

publish_agent(tenant_id, agent_id, user_id, name, description, price, category)
install_agent(tenant_id, template_id, user_id)
browse_agents(limit, offset)

Data Flow:

Multi-Tenant Isolation:

All queries scoped by tenant_id
Published agents marked with author_tenant_id
Installed agents belong to installer's tenant
Memory anonymized to prevent data leakage

PublicMarketplaceService

Location: core/public_marketplace_service.py

Responsibilities:

Browse public skills
Submit skills for approval
Rate and review skills
Search and discovery

Key Methods:

browse_skills(query, category, tags, skill_type, is_free, is_featured, sort_by, sort_order, limit, offset)
get_skill_details(skill_id)
get_categories()
get_tags(limit)
submit_skill(tenant_id, user_id, name, description, ...)
rate_skill(skill_id, tenant_id, user_id, rating, review)
get_reviews(skill_id, limit, offset)

Backward Compatibility:

Gracefully handles missing marketplace columns
Falls back to basic skill listing
Logs warnings for missing features

DomainMarketplaceService

Location: core/domain_marketplace_service.py

Responsibilities:

Submit specialist domains to marketplace
Admin approval workflow
Install domain templates
Search and discovery
Rating system

Key Methods:

submit_to_marketplace(domain_id, tenant_id, price_usd, license_type, tags)
approve_domain(domain_id, approved_by)
reject_domain(domain_id, rejected_by, reason)
install_domain_from_marketplace(template_domain_id, tenant_id, custom_name)
search_marketplace(search_query, category, tags, max_price, limit)
get_trending_domains(limit)
rate_domain(domain_id, rating, user_id)
list_submitted_domains(tenant_id)
get_marketplace_stats()

2. Data Models

AgentTemplate

Purpose: Represents a published agent available for installation

Key Fields:

id: UUID
tenant_id: UUID  # Author's tenant
author_id: UUID  # Publishing user
name: str
description: str
category: str
price: float
version: str
configuration: JSON  # Agent configuration
capabilities: List[UUID]  # Skill IDs
canvas_ui_schemas: List[JSON]  # UI definitions
anonymized_memory_bundle: JSON  # Sanitized experience
is_public: bool
is_approved: bool
rating: float
installs: int

Relationships:

AgentInstallation - Tracks installations
AgentSkill - Capability mappings

Skill (Enhanced)

Purpose: Base skill model with marketplace features

Marketplace Fields:

category: str  # Skill category
tags: List[str]  # Search tags
is_public: bool  # Published to marketplace
is_approved: bool  # Admin approved
is_featured: bool  # Featured listing
price: float  # USD (0 = free)
rating: float  # Average rating
rating_count: int  # Number of ratings
installs: int  # Install count
submitted_for_approval: bool
submitted_at: datetime

SpecialistDomain (Enhanced)

Purpose: Domain expertise templates

Marketplace Fields:

is_public: bool
is_approved: bool
approval_status: str  # pending, approved, rejected
approval_rejected_reason: str
price_usd: float
license_type: str
tags: List[str]
install_count: int
rating_average: float
rating_count: int

SkillRating

Purpose: User ratings and reviews

Fields:

id: UUID
skill_id: UUID
tenant_id: UUID  # Rater's tenant
user_id: UUID  # Rater's user
rating: int  # 1-5 stars
review: str
created_at: datetime
updated_at: datetime

Multi-Tenant Enforcement:

Ratings scoped by tenant_id
Prevents cross-tenant rating manipulation
Enables per-tenant review moderation

3. API Endpoints

Public Marketplace API

Base: /api/public/v1/marketplace

Endpoints:

GET /skills - Browse skills (public, no auth)
GET /skills/{skill_id} - Get skill details
GET /categories - List categories
GET /tags - List tags with counts
POST /submit - Submit skill (requires auth)
POST /skills/{skill_id}/rate - Rate skill (requires auth)
GET /skills/{skill_id}/reviews - Get reviews

Authentication:

Public: No auth required for read operations
API Key: X-API-Key: atom_pub_...
OAuth: Authorization: Bearer <token>

Rate Limiting:

Unauthenticated: 60 req/min
API Key: 300 req/min
OAuth: 600 req/min

Private Marketplace API

Base: /api/marketplace

Endpoints:

GET /agents - Browse published agents
GET /domains - Browse domain templates
POST /agents/publish - Publish agent
POST /agents/{template_id}/install - Install agent
POST /domains/submit - Submit domain
POST /domains/{domain_id}/install - Install domain

Authentication:

Requires tenant authentication
Scoped to tenant's resources

Federation API

Base: /api/federation

Endpoints:

GET /agents - List federated agents
GET /agents/{template_id} - Get agent bundle

Authentication:

X-Federation-Key: sk-federation-...
Rate limited: 100 req/min per IP

4. Security Architecture

Multi-Tenant Isolation

Data Segregation:

# All queries scoped by tenant_id
def browse_agents(self, tenant_id: str):
    return self.db.query(AgentRegistry).filter(
        AgentRegistry.tenant_id == tenant_id
    ).all()

Publishing Controls:

Only tenant-owned agents can be published
Author tenant_id stored in template
Installations create new tenant-owned copies

Anonymization:

Experience memory sanitized before publishing
PII redaction via regex patterns
UUID replacement for identifiers
Optional LLM semantic rewriting

Approval Workflow

Admin Controls:

approve_domain(domain_id, approved_by)
reject_domain(domain_id, rejected_by, reason)
Audit trail of approval actions

Rate Limiting

Implementation:

# Redis-based rate limiting
rate_limit_key = f"federation:rate_limit:{client_ip}:{current_minute}"
current_count = cache_service.get(rate_limit_key)

if current_count >= rate_limit:
    raise HTTPException(status_code=429, headers={"Retry-After": "60"})

Graceful Degradation:

If Redis unavailable, requests allowed
Logs errors for monitoring
Prevents service disruption

Data Flow

Publishing Flow

Installation Flow

Federation Flow

Integration Patterns

1. Skill Marketplace Integration

Python SDK:

from atom_marketplace import SkillMarketplaceClient

client = SkillMarketplaceClient(api_key="atom_pub_...")

# Browse skills
skills = client.browse_skills(
    category="data-processing",
    type="api",
    sort_by="rating",
    limit=10
)

# Submit skill
skill_id = client.submit_skill(
    name="Data Extractor",
    description="Extract structured data",
    type="api",
    category="data-processing",
    tags=["extraction", "nlp"],
    input_schema={...},
    output_schema={...}
)

2. Agent Marketplace Integration

Installation:

from core.agent_marketplace_service import AgentMarketplaceService

service = AgentMarketplaceService(db)

# Publish agent
result = service.publish_agent(
    tenant_id=tenant_id,
    agent_id=agent_id,
    user_id=user_id,
    name="Sales Assistant",
    description="Automated sales outreach",
    category="sales"
)

# Install agent
installed = service.install_agent(
    tenant_id=tenant_id,
    template_id=result["id"],
    user_id=user_id
)

3. Federation Integration

Cross-Instance Discovery:

import requests

# List agents from remote instance
response = requests.get(
    "https://remote-atom.com/api/federation/agents",
    headers={"X-Federation-Key": "sk-federation-..."},
    params={"limit": 50}
)

agents = response.json()["agents"]

# Download agent bundle
bundle = requests.get(
    f"https://remote-atom.com/api/federation/agents/{template_id}",
    headers={"X-Federation-Key": "sk-federation-..."}
).json()

# Install locally
local_agent = install_bundle(bundle)

Performance Considerations

Caching Strategy

Redis Cache:

Category and tag lists (1 hour TTL)
Featured skills (15 min TTL)
Rate limit counters (1 min TTL)

Cache Invalidation:

On skill submission
On approval status change
On rating updates

Database Optimization

Indexes:

-- Skill marketplace
CREATE INDEX idx_skills_category ON skills(category);
CREATE INDEX idx_skills_tags ON skills USING GIN(tags);
CREATE INDEX idx_skills_public_approved ON skills(is_public, is_approved);
CREATE INDEX idx_skills_rating ON skills(rating DESC, installs DESC);

-- Agent templates
CREATE INDEX idx_agent_templates_public ON agent_templates(is_public, is_approved);
CREATE INDEX idx_agent_templates_category ON agent_templates(category);
CREATE INDEX idx_agent_templates_rating ON agent_templates(rating DESC, installs DESC);

-- Federation
CREATE INDEX idx_agent_templates_federation ON agent_templates(is_public, is_approved) WHERE is_public = true;

Query Optimization:

Pagination for all list endpoints
Selective field loading
Batch queries for related data

Rate Limiting

Strategy:

Redis-based sliding window
Per-IP limits for federation
Per-key limits for API keys
Graceful degradation on Redis failure

Limits:

Federation: 100 req/min per IP
Public API: 60 req/min (unauthenticated)
API Key: 300 req/min
OAuth: 600 req/min

Monitoring & Observability

Logging

Structured Logging:

logger.info(
    "marketplace_submission",
    extra={
        "action": "submit_skill",
        "tenant_id": tenant_id,
        "skill_id": skill_id,
        "category": category,
        "timestamp": datetime.now(UTC).isoformat()
    }
)

Key Events:

Submissions
Approvals
Installations
Ratings
Federation requests
Rate limit violations

Metrics

Business Metrics:

Total submissions
Approval rate
Installation count
Average rating
Active publishers

Technical Metrics:

API response times
Rate limit violations
Cache hit rates
Federation request volume
Error rates

Best Practices

For Publishers

Anonymize Sensitive Data
- Remove PII from experience memory
- Sanitize business-specific information
- Use generic examples
Provide Clear Documentation
- Detailed descriptions
- Input/output schemas
- Usage examples
- Configuration options
Test Thoroughly
- Validate all skill inputs
- Handle edge cases
- Provide error messages
- Test with various inputs
Version Carefully
- Semantic versioning
- Backward compatibility
- Migration guides
- Deprecation notices

For Consumers

Review Before Installing
- Check ratings and reviews
- Read documentation
- Verify compatibility
- Test in development
Monitor Usage
- Track performance
- Monitor costs
- Review behavior
- Report issues
Provide Feedback
- Rate installations
- Submit reviews
- Report bugs
- Suggest improvements

For Administrators

Review Submissions Carefully
- Verify functionality
- Check security
- Validate documentation
- Test installations
Monitor Marketplace Health
- Track approval rates
- Monitor quality metrics
- Review user feedback
- Identify trends
Enforce Standards
- Code quality requirements
- Documentation standards
- Security guidelines
- Performance benchmarks

Future Enhancements

Planned Features

Marketplace Analytics
- Download statistics
- Usage trends
- Popular categories
- Publisher dashboards
Advanced Search
- Full-text search
- Semantic search
- Recommendation engine
- Similar skills
Monetization
- Paid marketplace
- Revenue sharing
- Subscription tiers
- Usage-based pricing
Federation Improvements
- Peer discovery
- Reputation scoring
- Automated syncing
- Version management
Quality Metrics
- Success rates
- Performance benchmarks
- Security scanning
- Dependency checking

Marketplace Architecture

Overview

Architecture Diagram

Data Flow Diagrams

Marketplace Ecosystem Data Flow

Federation Protocol Flow

Multi-Tenant Isolation Boundaries

Security Layers

System Components

1. Marketplace Services

AgentMarketplaceService

PublicMarketplaceService

DomainMarketplaceService

2. Data Models

AgentTemplate

Skill (Enhanced)

SpecialistDomain (Enhanced)

SkillRating

3. API Endpoints

Public Marketplace API

Private Marketplace API

Federation API

4. Security Architecture

Multi-Tenant Isolation

Approval Workflow

Rate Limiting

Data Flow

Publishing Flow

Installation Flow

Federation Flow

Integration Patterns

1. Skill Marketplace Integration

2. Agent Marketplace Integration

3. Federation Integration

Performance Considerations

Caching Strategy

Database Optimization

Rate Limiting

Monitoring & Observability

Logging

Metrics

Best Practices

For Publishers

For Consumers

For Administrators

Future Enhancements

Planned Features

References