Architecture Data Flow

Architecture - Data Flow

**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/badge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/badge.js) - [backend/src/services/badgeBuilder.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/badgeBuilder.js) - [backend/src/services/bagsReputation.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsReputation.js) - [backend/src/models/queries.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/queries.js) - [backend/src/models/redis.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/redis.js)

Table of Contents

1. Introduction
2. Registration Data Flow
3. Verification Data Flow
4. Badge Generation Data Flow
5. Reputation Calculation Data Flow
6. Discovery Data Flow

Introduction

This document describes how data flows through the AgentID system during various operations, showing the transformation of data as it moves between components.

Registration Data Flow

Input to Output Transformation

Input: {pubkey, name, signature, message, nonce, ...metadata}
  ↓
Validation & Verification
  ↓
Bags Authentication
  ↓
SAID Registration
  ↓
Database Insert
  ↓
Output: {agent: {...}, said: {registered, trust_score}}

Detailed Flow

flowchart TD
Start(["POST /register"]) --> Validate["Validate Input"]
Validate --> VerifySig["Verify Ed25519 Signature"]
VerifySig --> BagsAuth["Bags Authentication"]
BagsAuth --> SaidReg["SAID Registration"]
SaidReg --> CreateAgent["Create Agent Record"]
CreateAgent --> ReturnResponse["Return Agent + SAID Status"]

Validate -->|Invalid| Error400["400 Bad Request"]
VerifySig -->|Invalid| Error401["401 Unauthorized"]

Loading

Data Transformations

Stage	Input	Output
Validation	Raw request body	Validated params or error
Signature Verification	message, signature, pubkey	boolean
Bags Auth	pubkey	{message, nonce, apiKeyId}
SAID Registration	agent metadata	{registered, trust_score}
Database Insert	agent data	Created agent record

Verification Data Flow

Challenge Issuance

flowchart TD
Start(["POST /verify/challenge"]) --> Validate["Validate Pubkey"]
Validate --> CheckAgent["Check Agent Exists"]
CheckAgent --> GenNonce["Generate UUID Nonce"]
GenNonce --> BuildChallenge["Build Challenge String"]
BuildChallenge --> StoreChallenge["Store in DB with Expiry"]
StoreChallenge --> Encode["Base58 Encode"]
Encode --> Return["Return {nonce, challenge, expiresIn}"]

CheckAgent -->|Not Found| Error404["404 Not Found"]

Loading

Challenge Response

flowchart TD
Start(["POST /verify/response"]) --> Validate["Validate Input"]
Validate --> LoadChallenge["Load Challenge from DB"]
LoadChallenge --> CheckExpiry["Check Not Expired"]
CheckExpiry --> VerifySig["Verify Ed25519 Signature"]
VerifySig --> MarkComplete["Mark Challenge Complete"]
MarkComplete --> UpdateAgent["Update last_verified"]
UpdateAgent --> Return["Return {verified, pubkey, timestamp}"]

LoadChallenge -->|Not Found| Error404["404 Not Found"]
CheckExpiry -->|Expired| Error401["401 Unauthorized"]
VerifySig -->|Invalid| Error401

Loading

Badge Generation Data Flow

Cache-First Strategy

flowchart TD
Start(["GET /badge/:pubkey"]) --> CheckCache["Check Redis Cache"]
CheckCache -->|Cache Hit| ReturnCached["Return Cached JSON"]
CheckCache -->|Cache Miss| LoadAgent["Load Agent from DB"]
LoadAgent --> ComputeRep["Compute Reputation Score"]
ComputeRep --> LoadStats["Load Action Statistics"]
LoadStats --> BuildJSON["Build Badge JSON"]
BuildJSON --> StoreCache["Store in Redis"]
StoreCache --> ReturnJSON["Return Badge JSON"]

LoadAgent -->|Not Found| Error404["404 Not Found"]

Loading

Badge JSON Structure

// Input data sources
const agent = await getAgent(pubkey);           // From PostgreSQL
const scoreData = await computeBagsScore(pubkey); // From Bags API + DB
const stats = await getAgentActions(pubkey);     // From PostgreSQL

// Output badge JSON
const badge = {
  pubkey: agent.pubkey,
  name: agent.name,
  status: deriveStatus(agent, scoreData),
  score: scoreData.score,
  label: scoreData.label,
  capabilities: agent.capability_set,
  registeredAt: agent.registered_at,
  totalActions: stats.total_actions,
  widgetUrl: `${baseUrl}/widget/${pubkey}`
};

Reputation Calculation Data Flow

Score Computation

flowchart TD
Start(["computeBagsScore(pubkey)"]) --> LoadAgent["Load Agent from DB"]
LoadAgent --> FetchFees["Fetch Token Fees from Bags"]
FetchFees --> CalcFeeScore["Calculate Fee Score"]
LoadAgent --> FetchActions["Fetch Action Stats"]
FetchActions --> CalcSuccessScore["Calculate Success Rate Score"]
LoadAgent --> CalcAgeScore["Calculate Age Score"]
LoadAgent --> FetchSAID["Fetch SAID Trust Score"]
FetchSAID --> CalcSAIDScore["Calculate SAID Contribution"]
LoadAgent --> CountFlags["Count Unresolved Flags"]
CountFlags --> CalcCommunityScore["Calculate Community Score"]
CalcFeeScore --> SumScores["Sum All Scores"]
CalcSuccessScore --> SumScores
CalcAgeScore --> SumScores
CalcSAIDScore --> SumScores
CalcCommunityScore --> SumScores
SumScores --> DetermineLabel["Determine Label"]
DetermineLabel --> Return["Return Score + Breakdown"]

Loading

Score Factors

Factor	Max Points	Data Source
Fee Activity	30	Bags Analytics API
Success Rate	25	PostgreSQL (agent actions)
Registration Age	20	PostgreSQL (registered_at)
SAID Trust	15	SAID Gateway
Community	10	PostgreSQL (flags count)

Discovery Data Flow

Agent Discovery

flowchart TD
Start(["GET /agents"]) --> ParseFilters["Parse Query Parameters"]
ParseFilters --> BuildQuery["Build SQL Query"]
BuildQuery --> ExecuteQuery["Execute Query"]
ExecuteQuery --> FormatResults["Format Results"]
FormatResults --> Return["Return {agents, total, limit, offset}"]

Loading

Filtering Logic

// Input: query parameters
const { status, capability, limit, offset } = req.query;

// Query building
let whereClause = [];
if (status) whereClause.push(`status = '${status}'`);
if (capability) whereClause.push(`capability_set @> '["${capability}"]'`);

// Output: filtered agents
const result = {
  agents: [...],
  total: 100,
  limit: 20,
  offset: 0
};