ARCHITECTURE.md

Zurri Architecture - Agents Marketplace with Chat Protocol

Overview

Zurri has been refactored from a models+agents marketplace to an agents-only marketplace with a standardized chat protocol for communication.

Key Changes

❌ Removed

• Model entities and endpoints
• Proxy endpoints for model access
• Model-specific subscription logic

✅ Added/Updated

• Agent-focused architecture: All listings are fully packaged agents
• Chat Protocol: Standardized communication interface (/api/chat/:id/message)
• Conversation History: Persistent message storage per agent-user conversations
• Agent Endpoint Contract: Agents must implement standardized request/response format

Chat Protocol Specification

Agent Requirements

Agents must expose a POST endpoint that accepts:

{
  message: string;              // User's message
  conversationId?: string;      // Optional conversation identifier
  metadata?: Record<string, any>; // Additional context
  systemPrompt?: string;        // Optional system prompt if configured
}

And returns:

{
  response: string;             // Agent's response (or "message" field accepted)
  conversationId: string;       // Conversation identifier
  metadata?: Record<string, any>; // Optional response metadata
}

Client Usage

// Send message
POST /api/chat/:agentId/message
Authorization: Bearer <token>
{
  "message": "Hello!",
  "conversationId": "conv_123", // Optional
  "metadata": {}
}

// Response
{
  "response": "Hi there!",
  "conversationId": "conv_123",
  "metadata": {}
}

// Get history
GET /api/chat/:agentId/history?conversationId=conv_123&limit=50
Authorization: Bearer <token>

Data Flow

1. Agent Listing Creation

Creator → POST /api/agents
  → Upload metadata to IPFS (Pinata)
  → Store agent with PENDING status
  → Admin approves → Status → APPROVED

2. User Subscription

User → POST /api/subscriptions/agent/:agentId
  → Generate payment reference
  → User pays via Paystack
  → Webhook verifies → Subscription ACTIVE

3. Chat Communication

User → POST /api/chat/:agentId/message
  → Verify subscription
  → Forward to agent endpoint
  → Save messages to database
  → Return response to user

Database Schema

Core Entities

1. Agent: Agent listings with IPFS metadata
2. User: Platform users (creators and consumers)
3. Subscription: Agent access subscriptions
4. ChatMessage: Conversation history
5. ApiKey: API key management (for future programmatic access)

Relationships

User 1---* Agent (creator)
User *---* Agent (via Subscription)
Agent 1---* ChatMessage
User 1---* ChatMessage

Security

1. JWT Authentication: All protected routes require Bearer token
2. Subscription Verification: Chat access requires active subscription
3. Rate Limiting: Express rate limiter on all /api/ routes
4. Admin Only: Approval/rejection requires admin role
5. Endpoint Protection: Agent endpoints hidden from non-creators

Payment Flow

User creates subscription
  ↓
Payment reference generated
  ↓
User completes Paystack payment
  ↓
Paystack webhook → /api/subscriptions/webhook/paystack
  ↓
Verify signature & payment
  ↓
Activate subscription

Future Enhancements

• API key-based access (programmatic agent usage)
• Streaming chat responses
• Agent analytics dashboard
• Rating/review system
• Agent categories and tags
• Search and filtering improvements