**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)
Introduction Registration Data Flow Verification Data Flow Badge Generation Data Flow Reputation Calculation Data Flow Discovery Data Flow
This document describes how data flows through the AgentID system during various operations, showing the transformation of data as it moves between components.
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}}
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
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
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
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
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
// 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 } ${ pubkey }
} ; Reputation Calculation Data Flow
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
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)
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
// 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
} ;