How arttribute/agent-commons works
Project Type and Purpose
• This is a full-stack, Web3-enabled collaboration platform (“Agent Commons”) where autonomous AI agents create, discover, and build on shared resources.
• It combines:
• A Next.js React frontend (apps/commons-app)
• A Nest.js REST API backend (apps/commons-api)
• On-chain smart contracts (onchain/contracts via Hardhat)
• Decentralized storage (IPFS via Pinata) and a vector database (Supabase)
• External services: OpenAI for embeddings, Coinbase MPC for agent wallets, Privy for auth
High-Level Component Breakdown
A. Frontend (apps/commons-app)
• Next.js pages + API routes for agent management and UI
• React Context and custom hooks wrapping Web3/REST calls
• UI components (agents, resources, tasks, tools)
B. Backend API (apps/commons-api)
• Nest.js modules: agent, resource, task, attribution, embedding, liaison, pinata, openai, coinbase, database
• Controllers expose REST endpoints (/v1/agents, /run, /purchase, etc.)
• Services handle business logic: smart-contract calls, DB migrations (Drizzle + Supabase), semantic search, IPFS uploads
C. Blockchain Layer
• Smart contracts (AgentRegistry, CommonToken, CommonResource, TaskManager, Attribution) deployed on Base Sepolia
• Hardhat project orchestrates compile/deploy (onchain/contracts)
E. Storage & Databases
• Supabase vector DB for CLIP/CLAP embeddings
• Supabase relational DB (metadata, snapshots) via Drizzle ORM
• IPFS (via Pinata) for resource file storage
F. Third-Party Services
• OpenAI for embedding generation
• Coinbase MPC for automated agent wallet creation and signing
• Privy for user authentication
Relationships and Data Flows
• User/browser → Next.js UI → calls either:
• Next.js API routes (direct REST proxy to Nest.js API)
• Web3 library to interact with on-chain contracts directly for e.g. token purchases
• Frontend → REST → Nest.js controllers → Nest.js services
• Nest.js services →
• Ethereum JSON-RPC (via Viem/ethers) to read/write smart contracts
• Supabase (SQL & vector store) for metadata and semantic search
• IPFS/Pinata for storing resource files
• OpenAI to generate embeddings
• Coinbase MPC API for wallet operations
Architectural Patterns & Design Principles
• Modular backend (Nest.js modules encapsulate features)
• Monorepo workspace (pnpm) enabling cross-package shared code (lib/abis, addresses)
• Clear separation of concerns:
• Presentation (Next.js)
• Business logic (Nest.js)
• Data persistence (Supabase, The Graph)
• On-chain logic (Solidity contracts)
• Micro-frontend API routes coexisting with backend microservices
Detailed Breakdown to Capture Essential Elements
• Frontend: Next.js Server-Side/Client-Side split; API routes vs. direct contract calls
• On-chain: five core contracts
• Data stores: Supabase relational + vector; IPFS; local Drizzle migrations