Architecture Overview

Architecture Overview

**Referenced Files in This Document** - [backend/src/services/bagsAuthVerifier.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsAuthVerifier.js) - [backend/src/services/saidBinding.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/saidBinding.js) - [backend/src/services/pkiChallenge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/pkiChallenge.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/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/models/db.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/db.js) - [backend/src/models/redis.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/redis.js) - [frontend/src/components/TrustBadge.jsx](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/components/TrustBadge.jsx) - [frontend/src/widget/Widget.jsx](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/widget/Widget.jsx)

Table of Contents

1. Introduction
2. System Overview
3. Component Interactions
4. Data Flow Architecture
5. Security Architecture
6. Technology Stack

Introduction

AgentID is a Bags-native trust verification layer for AI agents on Solana. It wraps Bags' Ed25519 authentication, binds to the SAID Protocol, adds Bags-specific reputation scoring, and surfaces human-readable trust badges.

System Overview

graph TB
subgraph "External Systems"
BAGS["Bags API<br/>Authentication & Analytics"]
SAID["SAID Identity Gateway<br/>Agent Registry"]
end
subgraph "AgentID Backend"
API["Express API"]
REG["Registration Service"]
VER["Verification Service"]
REP["Reputation Service"]
BAD["Badge Service"]
DB[("PostgreSQL")]
REDIS[("Redis Cache")]
end
subgraph "AgentID Frontend"
UI["Registry UI"]
WIDGET["Embeddable Widget"]
end
BAGS <-->|"Ed25519 Auth"| REG
SAID <-->|"A2A Discovery"| REP
API --> REG
API --> VER
API --> REP
API --> BAD
REG --> DB
VER --> DB
REP --> DB
BAD --> DB
BAD --> REDIS
UI --> API
WIDGET --> API

Loading

Component Interactions

Registration Flow

sequenceDiagram
participant Dev as "Developer"
participant API as "AgentID API"
participant BAGS as "Bags API"
participant SAID as "SAID Gateway"
participant DB as "PostgreSQL"
Dev->>API: POST /register
API->>API: validateRegistrationInput()
API->>API: verifyBagsSignature()
API->>BAGS: POST /agent/v2/auth/init
BAGS-->>API: {message, nonce}
API->>BAGS: POST /agent/v2/auth/callback
BAGS-->>API: {apiKeyId}
API->>SAID: POST /agents/register
SAID-->>API: {result}
API->>DB: INSERT agent_identities
DB-->>API: {created agent}
API-->>Dev: 201 {agent, said}

Loading

Verification Flow

sequenceDiagram
participant App as "Bags App"
participant API as "AgentID API"
participant PKI as "PKI Challenge"
participant DB as "PostgreSQL"
App->>API: POST /verify/challenge
API->>PKI: issueChallenge(pubkey)
PKI->>DB: INSERT agent_verifications
DB-->>PKI: {verification}
PKI-->>API: {nonce, challenge, expiresIn}
API-->>App: 200 {nonce, challenge, expiresIn}
App->>API: POST /verify/response
API->>PKI: verifyChallenge(pubkey, nonce, signature)
PKI->>DB: SELECT verification
DB-->>PKI: {verification}
PKI->>PKI: verify Ed25519 signature
PKI->>DB: UPDATE completed=true
PKI->>DB: UPDATE last_verified
PKI-->>API: {verified, pubkey, timestamp}
API-->>App: 200 {verified, ...}

Loading

Data Flow Architecture

Badge Generation Flow

flowchart TD
Start(["GET /badge/:pubkey"]) --> CacheCheck["Check Redis Cache"]
CacheCheck -->|Hit| ReturnCached["Return Cached JSON"]
CacheCheck -->|Miss| LoadAgent["Load Agent from DB"]
LoadAgent --> ComputeRep["Compute Reputation"]
ComputeRep --> LoadActions["Load Action Stats"]
LoadActions --> BuildBadge["Build Badge JSON"]
BuildBadge --> CacheStore["Store in Redis"]
CacheStore --> ReturnBadge["Return Badge JSON"]
ReturnCached --> End([End])
ReturnBadge --> End

Loading

Security Architecture

Authentication Layer

• Ed25519 signature verification using tweetnacl
• Challenge-response mechanism with time-bound nonces
• Replay attack prevention through single-use nonces

Authorization Layer

• Signature-based authorization for modifications
• Rate limiting on all endpoints
• CORS configuration for frontend access

Data Protection

• Parameterized SQL queries prevent injection
• Output encoding prevents XSS
• Helmet.js provides security headers

Technology Stack

Backend

Component	Technology
Runtime	Node.js 18+
Framework	Express.js
Database	PostgreSQL 14+
Cache	Redis 7+
Crypto	tweetnacl, bs58
HTTP Client	axios

Frontend

Component	Technology
Framework	React 18
Build Tool	Vite
Styling	TailwindCSS
Routing	React Router
HTTP Client	axios

Infrastructure

Component	Technology
Web Server	Nginx
Process Manager	PM2
SSL	Certbot
Container	Docker