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
10. Appendices

This document explains the AgentID badge services that power trust badges, SVG generation, and widget rendering.

The badge services span backend and frontend:

• Backend exposes badge JSON, SVG, and widget endpoints
• Frontend provides React TrustBadge component and standalone widget

graph TB
subgraph "Backend"
S["Server<br/>server.js"]
R1["Routes<br/>routes/badge.js"]
R2["Routes<br/>routes/widget.js"]
B["Badge Builder<br/>services/badgeBuilder.js"]
C["Config<br/>config/index.js"]
D["Redis Cache<br/>models/redis.js"]
T["Transform Utils<br/>utils/transform.js"]
end
subgraph "Frontend"
F1["TrustBadge Component<br/>frontend/src/components/TrustBadge.jsx"]
F2["Widget App<br/>frontend/src/widget/Widget.jsx"]
end
S --> R1
S --> R2
R1 --> B
R2 --> B
B --> D
B --> C
B --> T
F2 --> F1

• Badge Builder service: Computes reputation, constructs badge JSON, generates SVG
• Routes: Expose endpoints for badge JSON, SVG, and widget HTML
• Redis cache: Stores badge JSON with TTL
• Frontend TrustBadge: Renders compact badge UI
• Frontend Widget: Standalone embeddable widget

The badge pipeline:

1. Request arrives at route endpoint
2. Route delegates to badgeBuilder service
3. badgeBuilder retrieves agent data, computes reputation
4. Results cached in Redis
5. For SVG/widget, generates markup and returns

Responsibilities:

• Compute reputation and derive status
• Build badge JSON with metadata
• Generate SVG with dynamic colors
• Produce HTML widget with auto-refresh

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

TrustBadge

• Props: status, name, score, registeredAt, totalActions
• Status-dependent styling

Widget Application

• Standalone React app in iframe
• Auto-refreshes every 60 seconds
• Themed CSS with glow effects

• badgeBuilder depends on queries, reputation service, redis, config
• Routes depend on badgeBuilder and rate limiting
• Frontend widget depends on axios

• Caching: Badge JSON cached with TTL
• Rate limiting: Protects backend resources
• Rendering: SVG generated server-side
• Auto-refresh: Widget refreshes every 60s

• Agent not found: Returns 404
• Redis connectivity: Graceful fallback
• XSS prevention: HTML/XML escaping
• Widget loading: Skeleton while loading

The badge services provide a robust, cache-backed pipeline for generating trust badges in JSON, SVG, and HTML formats.

• Cache TTL: Badge cache duration
• Base URL: Widget URL construction
• Redis URL: Caching connection

• Status theming: green (verified), red (flagged), amber (unverified)
• SVG colors derived from status
• Widget theme via CSS variables