📉Diagrams

System Architecture Diagram

Overview:

This diagram illustrates how components communicate within the SpyAgents ecosystem, divided into 4 main blocks:

• Client

• Authentication

• Core System

• Blockchain

• Storage

Components:

Client

• User / Company: These are the system's clients — both end-users and companies. They can log in or subscribe to agents.

Authentication

• JWT Auth: Responsible for authenticating regular users with JWT.

• API Key Validation: Middleware that validates if the API Key sent in calls is associated with an active contract.

Core System

• AI Agent: The core of the AI agents, which execute tasks when called.

• Contract Manager: Manages contracts between users and agents (including API Key generation).

• Usage Controller: Monitors each agent's usage, decrementing credits and logging records.

Storage

• PostgreSQL: Stores structured data (users, contracts, logs...).

• Supabase Storage: Stores agent images (via upload).

Blockchain

• Payment Handler: Responsible for processing payments via smart contracts.

• API Key Validator: Smart contract that ensures the validity of the access key on-chain.

Flow:

• The user logs in → JWT is issued → accesses the core system.

• Upon subscribing to an agent: payment is processed → contract is created → API Key is issued and validated.

• Calls via API are validated → usage is logged in the database → call is forwarded to the agent.

Sequence Diagram

Objective:

This diagram illustrates the step-by-step process of subscribing to an agent, focusing on the sequence of calls between components.

Steps:

1. User → Frontend: Selects an agent.

2. Frontend → Authentication: Verifies authentication (JWT).

3. Authentication → Frontend: Returns a valid token.

4. Frontend → Backend: Sends subscription request.

5. Backend → Blockchain: Processes payment.

6. Blockchain → Backend: Confirms transaction.

7. Backend → Agent: Registers contract and generates API Key.

8. Backend → Frontend → User: API Key is returned and displayed to the user.

Result:

The user can now use the API Key to call the agent directly, with control and billing configured.

Database Diagram

Relational Model:

This diagram shows the data structure in the PostgreSQL database, with three main entities.

Tables:

USER

• name, email, walletAddress, password, role, company, phone, createdAt

• A user can create multiple contracts.

AGENT

• name, description, endpoint, pricePerCall, specialty, useCases, imageUrl, createdAt, creatorId

• An agent is created by one user and can be subscribed to by multiple users.

CONTRACT

• userId, agentId, callsPurchased, callsRemaining, paymentTxHash, apiKey, createdAt

• Many-to-many relationship between users and agents.

• Represents the subscription, call control, and authentication via API Key.