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:

```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