Atom AI Labs - AI-Powered Multi-Tenant Platform

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

**Browse Endpoints (No Auth):**

GET /skills - Browse skills (public, no auth)
GET /skills/{skill_id} - Get skill details
GET /categories - List categories
GET /tags - List tags with counts

**Submit Endpoints (Auth Required):**

POST /submit - Submit skill for review
POST /skills/{skill_id}/rate - Rate skill
GET /skills/{skill_id}/reviews - Get reviews

**Install/Uninstall Endpoints (Auth Required):**

POST /skills/{skill_id}/install - Install skill from public marketplace
DELETE /skills/{skill_id}/install - Uninstall skill
POST /agents/{agent_id}/install - Install agent from public marketplace
DELETE /agents/{agent_id}/install - Uninstall agent
POST /canvases/{canvas_id}/install - Install canvas from public marketplace
DELETE /canvases/{canvas_id}/install - Uninstall canvas
POST /domains/{domain_id}/install - Install domain from public marketplace
DELETE /domains/{domain_id}/install - Uninstall domain

**Install Endpoint Details:**

# Install a skill from public marketplace
POST /api/public/v1/marketplace/skills/{skill_id}/install
Headers: {
  "X-API-Key": "atom_pub_YOUR_KEY_HERE",
  "Content-Type": "application/json"
}
Body: {
  "tenant_id": "your-tenant-id",  # Required: target tenant
  "config": {                     # Optional: installation config
    "settings": {},
    "custom_name": "My Skill"
  }
}
Response: {
  "success": true,
  "installation_id": "install_abc123",
  "skill_id": "skill_xyz",
  "tenant_id": "your-tenant-id",
  "status": "installed"
}

**Uninstall Endpoint Details:**

# Uninstall a skill
DELETE /api/public/v1/marketplace/skills/{skill_id}/install
Headers: {
  "X-API-Key": "atom_pub_YOUR_KEY_HERE",
  "Content-Type": "application/json"
}
Body: {
  "tenant_id": "your-tenant-id",  # Required
  "installation_id": "install_abc123"
}
Response: {
  "success": true,
  "skill_id": "skill_xyz",
  "status": "uninstalled"
}

**Authentication:**

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

**Rate Limiting:**

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

**Self-Hosted Sync:**

Public marketplace endpoints enable self-hosted instances to sync with the commercial mothership:

# Self-hosted instance syncs marketplace items
from atom_federation import MarketplaceSyncClient

sync_client = MarketplaceSyncClient(
    public_api_url="https://atomagentos.com/api/public/v1/marketplace",
    api_key="atom_pub_SELF_HOSTED_KEY"
)

# Browse and install from public marketplace
skills = sync_client.list_skills(category="integration")

for skill in skills:
    sync_client.install_skill(
        skill_id=skill['id'],
        tenant_id="local-tenant-id"
    )

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