File size: 3,578 Bytes
b5e5eac | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | # 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:
```typescript
{
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:
```typescript
{
response: string; // Agent's response (or "message" field accepted)
conversationId: string; // Conversation identifier
metadata?: Record<string, any>; // Optional response metadata
}
```
### Client Usage
```typescript
// 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
|