Architecture Component Interactions

Architecture - Component Interactions

**Referenced Files in This Document** - [backend/src/routes/register.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/register.js) - [backend/src/routes/verify.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/verify.js) - [backend/src/routes/agents.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/agents.js) - [backend/src/routes/badge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/badge.js) - [backend/src/services/bagsAuthVerifier.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsAuthVerifier.js) - [backend/src/services/pkiChallenge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/pkiChallenge.js) - [backend/src/services/saidBinding.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/saidBinding.js) - [backend/src/services/bagsReputation.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsReputation.js) - [backend/src/services/badgeBuilder.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/badgeBuilder.js) - [backend/src/models/queries.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/queries.js)

Table of Contents

1. Introduction
2. Route-to-Service Interactions
3. Service-to-Model Interactions
4. External Service Interactions
5. Data Flow Patterns

Introduction

This document details how components interact within the AgentID system, showing the flow of data and control between routes, services, models, and external systems.

Route-to-Service Interactions

Registration Flow

sequenceDiagram
participant Route as "register.js"
participant Auth as "bagsAuthVerifier"
participant SAID as "saidBinding"
participant Queries as "queries.js"
Route->>Route: validateRegistrationInput()
Route->>Auth: verifyBagsSignature()
Auth-->>Route: isValid
Route->>Auth: initBagsAuth()
Auth-->>Route: {message, nonce}
Route->>Auth: completeBagsAuth()
Auth-->>Route: apiKeyId
Route->>SAID: registerWithSAID()
SAID-->>Route: saidResult
Route->>Queries: createAgent()
Queries-->>Route: agent
Route->>Route: Return response

Loading

Verification Flow

sequenceDiagram
participant Route as "verify.js"
participant PKI as "pkiChallenge"
participant Queries as "queries.js"
Route->>Route: POST /verify/challenge
Route->>Queries: getAgent()
Queries-->>Route: agent
Route->>PKI: issueChallenge()
PKI->>Queries: createVerification()
Queries-->>PKI: verification
PKI-->>Route: {nonce, challenge, expiresIn}
Route->>Route: POST /verify/response
Route->>Queries: getVerification()
Queries-->>Route: verification
Route->>PKI: verifyChallenge()
PKI->>Queries: completeVerification()
Queries-->>PKI: result
PKI->>Queries: updateLastVerified()
PKI-->>Route: {verified, pubkey, timestamp}

Loading

Badge Generation Flow

sequenceDiagram
participant Route as "badge.js"
participant Builder as "badgeBuilder"
participant Rep as "bagsReputation"
participant Redis as "redis.js"
participant Queries as "queries.js"
Route->>Builder: getBadgeJSON()
Builder->>Redis: getCache()
Redis-->>Builder: cachedData|null
alt Cache Miss
Builder->>Queries: getAgent()
Queries-->>Builder: agent
Builder->>Rep: computeBagsScore()
Rep->>Queries: getAgentActions()
Queries-->>Rep: actions
Rep-->>Builder: scoreData
Builder->>Queries: getAgentActions()
Queries-->>Builder: stats
Builder->>Redis: setCache()
end
Builder-->>Route: badgeJSON

Loading

Service-to-Model Interactions

Query Patterns

Services interact with the database through the queries module:

graph LR
Service["Service Layer"] --> Queries["queries.js"]
Queries --> Pool["PostgreSQL Pool"]
Pool --> DB[("PostgreSQL")]

Loading

Common Query Operations

Operation	Function	Usage
Create Agent	createAgent(params)	Registration
Get Agent	getAgent(pubkey)	All lookups
Update Agent	updateAgent(pubkey, data)	Metadata updates
Create Verification	createVerification(data)	Challenge issuance
Complete Verification	completeVerification(nonce)	Response verification
Get Agent Actions	getAgentActions(pubkey)	Reputation scoring

External Service Interactions

Bags API Integration

sequenceDiagram
participant Service as "bagsAuthVerifier"
participant API as "Bags API"
Service->>API: POST /agent/v2/auth/init
API-->>Service: {message, nonce}
Service->>Service: Client signs message
Service->>API: POST /agent/v2/auth/callback
API-->>Service: {apiKeyId}

Loading

SAID Gateway Integration

sequenceDiagram
participant Service as "saidBinding"
participant Gateway as "SAID Gateway"
Service->>Gateway: POST /agents/register
Gateway-->>Service: {registered, trust_score}
Service->>Gateway: GET /agents/{pubkey}
Gateway-->>Service: {trust_score, trust_label}
Service->>Gateway: GET /discover?capability
Gateway-->>Service: {agents}

Loading

Bags Analytics Integration

sequenceDiagram
participant Service as "bagsReputation"
participant API as "Bags API"
Service->>API: GET /analytics/token/{mint}/fees
API-->>Service: {total_fees_sol}

Loading

Data Flow Patterns

Request-Response Pattern

Standard API request flow:

1. Client sends HTTP request
2. Express route receives request
3. Route validates input
4. Route calls service(s)
5. Service(s) interact with models/external APIs
6. Service returns result to route
7. Route formats response
8. Response sent to client

Caching Pattern

Badge data caching flow:

1. Request arrives for badge data
2. Check Redis cache
3. If cache hit: return cached data
4. If cache miss:
   • Query database
   • Compute reputation
   • Build badge JSON
   • Store in cache
   • Return data

Event-Driven Pattern

Database error handling:

1. Query executed
2. If error: throw error
3. Error caught by route
4. Error passed to error handler
5. Error logged
6. Client receives error response