Architecture Technology Stack

Architecture - Technology Stack

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

Table of Contents

1. Introduction
2. Backend Stack
3. Frontend Stack
4. Database & Cache
5. Development Tools
6. Infrastructure

Introduction

AgentID is built with modern, proven technologies chosen for their performance, reliability, and developer experience. This document details the complete technology stack.

Backend Stack

Runtime & Framework

Technology	Version	Purpose
Node.js	18+	JavaScript runtime
Express.js	4.x	Web framework

Key Dependencies

Package	Purpose
pg	PostgreSQL client
ioredis	Redis client
axios	HTTP client
tweetnacl	Ed25519 cryptography
bs58	Base58 encoding
express-rate-limit	Rate limiting
helmet	Security headers
cors	CORS handling
uuid	UUID generation

Dependency Tree

graph TB
Express["Express.js"] --> Middleware["Middleware"]
Express --> Routes["Routes"]
Routes --> Services["Services"]
Services --> Models["Models"]
Models --> PG["pg"]
Models --> Redis["ioredis"]
Services --> Axios["axios"]
Services --> NaCl["tweetnacl"]
Services --> BS58["bs58"]
Middleware --> Helmet["helmet"]
Middleware --> RateLimit["express-rate-limit"]
Middleware --> CORS["cors"]

Loading

Frontend Stack

Core Framework

Technology	Version	Purpose
React	18.x	UI library
React DOM	18.x	DOM renderer
React Router	6.x	Client-side routing

Build Tools

Technology	Purpose
Vite	Build tool & dev server
@vitejs/plugin-react	React plugin
TailwindCSS	Utility-first CSS

Key Dependencies

Package	Purpose
axios	HTTP client
prop-types	Runtime type checking
lucide-react	Icon library

Frontend Architecture

graph TB
Vite["Vite"] --> React["React 18"]
React --> Router["React Router"]
React --> Components["Components"]
Components --> Pages["Pages"]
Components --> UI["UI Components"]
Components --> Widget["Widget"]
Pages --> API["API Client"]
Widget --> API
API --> Axios["axios"]
Vite --> Tailwind["TailwindCSS"]

Loading

Database & Cache

PostgreSQL

• Version: 14+
• Purpose: Primary data store
• Features Used:
  • JSONB for capability sets
  • Indexes on frequently queried columns
  • Connection pooling

Redis

• Version: 7+
• Purpose: Caching layer
• Use Cases:
  • Badge data caching
  • Challenge nonce storage
  • Session management (future)

Data Storage Architecture

graph TB
App["Application"] --> Pool["PostgreSQL Pool"]
App --> Redis[("Redis")]
Pool --> DB[("PostgreSQL")]
DB --> Tables["Tables"]
Tables --> Identities["agent_identities"]
Tables --> Verifications["agent_verifications"]
Tables --> Flags["agent_flags"]

Loading

Development Tools

Code Quality

Tool	Purpose
ESLint	Linting
Prettier	Code formatting
Jest	Testing framework

Backend Dev Tools

{
  "devDependencies": {
    "eslint": "^8.x",
    "jest": "^29.x",
    "nodemon": "^3.x",
    "supertest": "^6.x"
  }
}

Frontend Dev Tools

{
  "devDependencies": {
    "@types/react": "^18.x",
    "@types/react-dom": "^18.x",
    "@vitejs/plugin-react": "^4.x",
    "autoprefixer": "^10.x",
    "eslint": "^8.x",
    "postcss": "^8.x",
    "tailwindcss": "^3.x",
    "vite": "^5.x"
  }
}

Infrastructure

Deployment Stack

Component	Technology
Web Server	Nginx
Process Manager	PM2
SSL/TLS	Certbot (Let's Encrypt)
Containerization	Docker
Orchestration	Docker Compose

Nginx Configuration

server {
    listen 443 ssl http2;
    server_name agentid.provenanceai.network;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /api/ {
        proxy_pass http://localhost:3002/;
        proxy_http_version 1.1;
    }
    
    location / {
        root /var/www/agentid/frontend/dist;
        try_files $uri $uri/ /index.html;
    }
}

Docker Services

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3002:3002"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/agentid
      - REDIS_URL=redis://redis:6379
  
  db:
    image: postgres:14
    environment:
      - POSTGRES_DB=agentid
      - POSTGRES_PASSWORD=password
    volumes:
      - postgres_data:/var/lib/postgresql/data
  
  redis:
    image: redis:7
    volumes:
      - redis_data:/data

Technology Selection Rationale

Technology	Why Chosen
Node.js	Fast I/O, JavaScript ecosystem
Express.js	Minimal, flexible, proven
React	Component-based, large ecosystem
Vite	Fast builds, modern dev experience
PostgreSQL	ACID compliance, JSON support
Redis	High-performance caching
TailwindCSS	Rapid UI development