Developer Guide

Developer Guide

**Referenced Files in This Document** - [agentid_build_plan.md](https://github.com/RunTimeAdmin/AgentID/blob/main/agentid_build_plan.md) - [backend/package.json](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/package.json) - [frontend/package.json](https://github.com/RunTimeAdmin/AgentID/blob/main/frontend/package.json) - [backend/src/services/bagsAuthVerifier.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/bagsAuthVerifier.js) - [backend/src/services/pkiChallenge.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/pkiChallenge.js) - [backend/src/services/saidBinding.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/saidBinding.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)

Table of Contents

1. Introduction
2. Getting Started
3. Project Structure
4. Development Workflow
5. Key Services
6. Integration Patterns
7. Testing
8. Deployment

Introduction

This guide provides developers with the information needed to understand, extend, and contribute to the AgentID project. It covers the architecture, key components, development workflows, and best practices.

Getting Started

Prerequisites

• Node.js 18+
• PostgreSQL 14+
• Redis 7+
• Git

Quick Start

1. Clone the repository
2. Install dependencies: npm install in both backend and frontend directories
3. Set up environment variables (copy .env.example to .env)
4. Run database migrations: npm run migrate
5. Start the backend: npm run dev
6. Start the frontend: npm run dev

Project Structure

AgentID/
├── backend/
│   ├── src/
│   │   ├── config/         # Environment configuration
│   │   ├── middleware/     # Express middleware
│   │   ├── models/         # Database models and queries
│   │   ├── routes/         # API route handlers
│   │   ├── services/       # Business logic services
│   │   └── utils/          # Utility functions
│   ├── package.json
│   └── server.js           # Application entry point
├── frontend/
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── lib/            # API client and utilities
│   │   ├── pages/          # Page components
│   │   └── widget/         # Embeddable widget
│   ├── package.json
│   └── vite.config.js
└── docs/                   # Documentation

Development Workflow

Branch Strategy

• main: Production-ready code
• develop: Integration branch
• Feature branches: feature/description
• Bug fix branches: fix/description

Code Style

• ESLint configuration in both backend and frontend
• Prettier for code formatting
• Follow existing patterns for consistency

Commit Messages

Use conventional commits:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• refactor: Code refactoring
• test: Test changes

Key Services

BagsAuthVerifier

Wraps the Bags Ed25519 authentication flow:

• initBagsAuth(pubkey): Initialize authentication
• verifyBagsSignature(message, signature, pubkey): Verify signatures
• completeBagsAuth(pubkey, signature): Complete authentication

PKIChallenge

Manages challenge-response verification:

• issueChallenge(pubkey): Create new challenge
• verifyChallenge(pubkey, nonce, signature): Verify response

SAID Binding

Integrates with SAID Identity Gateway:

• registerWithSAID(params): Register agent
• getSAIDTrustScore(pubkey): Retrieve trust score
• discoverSAIDAgents(capability): Discover agents

BagsReputation

Computes reputation scores:

• computeBagsScore(pubkey): Calculate score
• refreshAndStoreScore(pubkey): Update stored score

BadgeBuilder

Generates trust badges:

• getBadgeJSON(pubkey): JSON badge data
• getBadgeSVG(pubkey): SVG badge image
• getWidgetHTML(pubkey): HTML widget

Integration Patterns

Adding a New Route

1. Create route file in backend/src/routes/
2. Implement handlers with proper validation
3. Add rate limiting if needed
4. Register in server.js
5. Add tests

Adding a New Service

1. Create service file in backend/src/services/
2. Export functions with clear interfaces
3. Document with JSDoc comments
4. Add unit tests
5. Update relevant documentation

Frontend Component Development

1. Create component in frontend/src/components/
2. Use TailwindCSS for styling
3. Follow existing component patterns
4. Add PropTypes for type checking
5. Document props and usage

Testing

Backend Tests

cd backend
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Frontend Tests

cd frontend
npm test              # Run all tests
npm run test:ui       # UI component tests

Test Structure

• Unit tests for services and utilities
• Integration tests for routes
• Component tests for React components
• E2E tests for critical user flows

Deployment

Docker Deployment

docker-compose up -d

Manual Deployment

1. Build frontend: cd frontend && npm run build
2. Set production environment variables
3. Start backend: cd backend && npm start
4. Configure reverse proxy (Nginx)

Environment-Specific Considerations

• Development: Hot reload, debug logging
• Staging: Production-like, test data
• Production: Optimized, monitored, SSL