Developer Guidelines

Developer Guidelines

**Referenced Files in This Document** - [backend/src/middleware/rateLimit.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/middleware/rateLimit.js) - [backend/src/middleware/errorHandler.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/middleware/errorHandler.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/services/badgeBuilder.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/services/badgeBuilder.js) - [backend/src/utils/transform.js](https://github.com/RunTimeAdmin/AgentID/blob/main/backend/src/utils/transform.js)

Table of Contents

1. Introduction
2. Code Style
3. Naming Conventions
4. Error Handling
5. Security Practices
6. Performance Guidelines
7. Documentation Standards

Introduction

These guidelines ensure consistency, maintainability, and quality across the AgentID codebase. All contributors should follow these standards.

Code Style

JavaScript/Node.js

• Use ES6+ features (async/await, destructuring, arrow functions)
• Prefer const and let over var
• Use semicolons consistently
• 2-space indentation
• Max line length: 100 characters

React/Frontend

• Functional components with hooks
• PropTypes for type checking
• Destructure props in component parameters
• Use TailwindCSS utility classes

Naming Conventions

Files

• Routes: kebab-case.js (e.g., agents.js, badge.js)
• Services: camelCase.js (e.g., bagsAuthVerifier.js)
• Components: PascalCase.jsx (e.g., TrustBadge.jsx)

Variables

• Constants: UPPER_SNAKE_CASE
• Functions: camelCase
• Classes: PascalCase
• Private methods: _camelCase (prefix with underscore)

Database

• Tables: snake_case (e.g., agent_identities)
• Columns: snake_case (e.g., registered_at)
• Primary keys: id or {table}_id
• Foreign keys: {referenced_table}_id

Error Handling

Backend

Always use try-catch blocks and pass errors to the next middleware:

try {
  const result = await someAsyncOperation();
  res.json(result);
} catch (error) {
  next(error);
}

The global error handler will:

• Log errors with context
• Return appropriate HTTP status codes
• Sanitize error messages in production

Frontend

Use error boundaries and handle API errors gracefully:

try {
  const data = await api.getAgent(pubkey);
  setAgent(data);
} catch (error) {
  setError(error.message);
}

Security Practices

Input Validation

• Validate all user inputs
• Use parameterized queries (never string concatenation)
• Sanitize data before rendering

Authentication

• Verify Ed25519 signatures for sensitive operations
• Use nonces to prevent replay attacks
• Implement rate limiting on all endpoints

Data Protection

• Never log sensitive data (API keys, private keys)
• Use environment variables for secrets
• Enable HTTPS in production

Performance Guidelines

Database

• Use indexes on frequently queried columns
• Implement connection pooling
• Use pagination for large result sets

Caching

• Cache badge data with appropriate TTL
• Use Redis for distributed caching
• Invalidate cache on data updates

Frontend

• Lazy load components when possible
• Optimize images and assets
• Minimize re-renders with React.memo

Documentation Standards

JSDoc Comments

Document all public functions:

/**
 * Computes the Bags reputation score for an agent
 * @param {string} pubkey - Agent's public key
 * @returns {Promise<Object>} Score data with breakdown
 * @throws {Error} If agent not found
 */
async function computeBagsScore(pubkey) {
  // implementation
}

README Files

Each major directory should have a README explaining:

• Purpose of the directory
• Key files and their roles
• Usage examples

Wiki Documentation

Update wiki pages when:

• Adding new API endpoints
• Changing architecture
• Modifying deployment procedures