Project Core Components

Project - Core Components

**Referenced Files in This Document** - [agentid_build_plan.md](https://github.com/RunTimeAdmin/AgentID/blob/main/agentid_build_plan.md) - [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/models/db.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/db.js) - [backend/src/models/queries.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/models/queries.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/routes/widget.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/widget.js) - [backend/src/routes/reputation.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/routes/reputation.js) - [backend/src/config/index.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/config/index.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) - [frontend/src/lib/api.js](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/src/lib/api.js)

Table of Contents

1. Introduction
2. Project Structure
3. Core Components
4. Architecture Overview
5. Detailed Component Analysis
6. Dependency Analysis
7. Performance Considerations
8. Troubleshooting Guide
9. Conclusion

Introduction

This document details the six major subsystems that compose AgentID's trust verification platform. Each component collaborates to establish identity, prevent spoofing, compute reputation, and surface trust signals.

Project Structure

AgentID is organized into a backend service (Node.js/Express) and a frontend (React/Vite).

graph TB
subgraph "Backend"
CFG["config/index.js"]
DB["models/db.js"]
Q["models/queries.js"]
R1["routes/register.js"]
R2["routes/verify.js"]
R3["routes/badge.js"]
R4["routes/widget.js"]
R5["routes/reputation.js"]
S1["services/bagsAuthVerifier.js"]
S2["services/saidBinding.js"]
S3["services/pkiChallenge.js"]
S4["services/bagsReputation.js"]
S5["services/badgeBuilder.js"]
end
subgraph "Frontend"
FE1["components/TrustBadge.jsx"]
FE2["widget/Widget.jsx"]
FE3["lib/api.js"]
end
CFG --> S1
CFG --> S2
CFG --> S3
CFG --> S4
CFG --> S5
CFG --> DB
DB --> Q
R1 --> S1
R1 --> S2
R1 --> Q
R2 --> S3
R2 --> Q
R3 --> S5
R3 --> Q
R4 --> S5
R5 --> S4
R5 --> Q
FE1 --> FE3
FE2 --> FE3

Loading

Core Components

Component 1: Bags Agent Auth Wrapper

Purpose: Wrap Bags' Ed25519 agent authentication to verify wallet ownership.

Key behaviors:

• Initialize Bags auth challenge
• Verify Ed25519 signature locally
• Return reference identifier

Component 2: SAID Protocol Binding

Purpose: Bind agent identity to SAID Identity Gateway.

Key behaviors:

• Register agent with SAID
• Retrieve SAID trust score
• Discover agents by capability

Component 3: AgentID Database Record

Purpose: Persist AgentID-specific agent data.

Key entities:

• agent_identities: metadata, status, scores
• agent_verifications: challenges with expiry
• agent_flags: community-reported flags

Component 4: PKI Challenge-Response

Purpose: Ongoing verification to prevent spoofing.

Key behaviors:

• Issue challenge with random nonce
• Enforce single-use and expiry
• Verify Ed25519 signature

Component 5: Bags Ecosystem Reputation Score

Purpose: Compute composite trust score (0-100).

Factors:

• Fee activity (max 30)
• Success rate (max 25)
• Registration age (max 20)
• SAID trust score (max 15)
• Community verification (max 10)

Component 6: Trust Badge API + Widget

Purpose: Expose trust badges in multiple formats.

Endpoints:

• GET /badge/:pubkey → JSON
• GET /badge/:pubkey/svg → SVG
• GET /widget/:pubkey → HTML widget

Architecture Overview

AgentID orchestrates identity, verification, and trust presentation across three layers.

Detailed Component Analysis

Each component is documented with sequence diagrams and implementation details covering authentication flow, SAID integration, database schema, challenge-response, reputation calculation, and badge generation.

Dependency Analysis

• External: Bags API, SAID Gateway, PostgreSQL, Redis
• Internal: services depend on models; routes depend on services

Performance Considerations

• Caching: Badge JSON cached in Redis
• Database pooling: PostgreSQL with SSL
• Rate limiting: Route-level protection
• Async operations: Non-blocking SAID binding

Troubleshooting Guide

• Registration: Check signature format
• Verification: Re-issue expired challenges
• Badge: Verify pubkey and registration

Conclusion

AgentID's six components form a cohesive trust layer establishing ownership, integrating with Solana ecosystem, persisting state, preventing spoofing, synthesizing signals, and delivering trust indicators.