Hyperfold AI

Architecture Overview

Hyperfold is a cloud-native solution architected on Google Cloud Platform, favoring serverless components for scalability and managed services for data consistency.

System Overview

The Hyperfold architecture consists of four primary layers, each with specific responsibilities in the agentic commerce workflow:

┌───────────────────────────────────────────────────────────────────────┐
│                       EXTERNAL INTERACTION                            │
│  ┌───────────────────┐              ┌───────────────────┐             │
│  │    Buyer Agent    │              │   Developer CLI   │             │
│  │  (OpenAI/Claude)  │              │                   │             │
│  └─────────┬─────────┘              └─────────┬─────────┘             │
└────────────┼──────────────────────────────────┼───────────────────────┘
             │                                  │
             │ POST /acp/negotiate              │ hyperfold deploy
             ▼                                  ▼
┌───────────────────────────────────────────────────────────────────────┐
│                       INTERACTION LAYER                               │
│  ┌───────────────────┐              ┌───────────────────┐             │
│  │  GCP API Gateway  │              │    Stripe API     │             │
│  │                   │              │       (SPT)       │             │
│  └─────────┬─────────┘              └───────────────────┘             │
└────────────┼──────────────────────────────────────────────────────────┘
             │
             ▼
┌───────────────────────────────────────────────────────────────────────┐
│                      HYPERFOLD CORE (GCP)                             │
│                                                                       │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                    INTELLIGENCE LAYER                           │  │
│  │  ┌───────────────────────────────────────────────────────────┐  │  │
│  │  │             Vertex AI (Gemini 1.5 Pro)                    │  │  │
│  │  │                   Agent Reasoning                         │  │  │
│  │  └───────────────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                       │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                   INFRASTRUCTURE LAYER                          │  │
│  │  ┌─────────────┐  ┌─────────────┐  ┌───────────────────┐        │  │
│  │  │  Cloud Run  │  │  Firestore  │  │   Cloud Spanner   │        │  │
│  │  │  (Agents)   │  │  (Context)  │  │ (Global Inventory)│        │  │
│  │  └─────────────┘  └─────────────┘  └───────────────────┘        │  │
│  │  ┌───────────────────────────────────────────────────────────┐  │  │
│  │  │                  Redis (Price Cache)                      │  │  │
│  │  └───────────────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────┘
             │
             │ Order Created
             ▼
┌───────────────────────────────────────────────────────────────────────┐
│                    INTEGRATION LAYER (The Glue)                       │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────┐              │
│  │    Pub/Sub    │  │Cloud Functions│  │  Legacy ERP   │              │
│  │ (Order Events)│─▶│(Egress Adapt.)│─▶│(Shopify/SF/..)│              │
│  └───────────────┘  └───────────────┘  └───────────────┘              │
└───────────────────────────────────────────────────────────────────────┘

Interaction Layer

The Interaction Layer handles all external communication with Hyperfold, including ACP-compliant agent requests and developer CLI commands.

GCP API Gateway

Routes incoming requests, handles authentication via API keys and JWT tokens, enforces rate limiting, and provides DDoS protection.

Stripe API Integration

Manages Shared Payment Tokens (SPT) for secure, delegated agent payments. Supports tokenized checkout without exposing card details.

Intelligence Layer

The Intelligence Layer provides the "brain" for agent reasoning and decision-making.

Hyperfold supports multiple LLM providers including Vertex AI (Gemini), OpenAI (GPT-4), and Anthropic (Claude) for agent reasoning.

Vertex AI (Gemini 1.5 Pro)

Primary inference engine for negotiation, product understanding, and catalog ingestion. Gemini's long context window (up to 1M tokens) enables processing entire product catalogs.

  • Multi-modal product analysis (images, specs, reviews)
  • Real-time price negotiation reasoning
  • Semantic understanding of buyer intent
  • EU region support for GDPR compliance

Infrastructure Layer

The Infrastructure Layer provides the compute, storage, and caching services that power agent operations.

Cloud Run (Agent Orchestrator)

Serverless container runtime that hosts agent code. Auto-scales from 0 to thousands of instances based on demand. Each agent runs in isolated containers with configurable CPU/memory limits.

Firestore (Agent State/Prompts)

NoSQL document database for storing agent configurations, system prompts, session context, and negotiation history. Supports hot-swapping prompts without redeployment.

Cloud Spanner (Global Inventory)

Globally distributed relational database for inventory management. Provides strong consistency across regions with 99.999% availability SLA.

Redis (Price Cache)

In-memory cache for competitor prices, dynamic pricing rules, and frequently accessed product data. Sub-millisecond latency for real-time negotiation.

Integration Layer ("The Glue")

The Integration Layer connects Hyperfold to your existing commerce infrastructure, enabling seamless order write-back and inventory synchronization.

Order Write-Back

When an agent completes a purchase, Hyperfold commits to Spanner, then triggers a Cloud Function via Pub/Sub to push the order to the legacy platform (e.g., Shopify Admin API).

Inventory Read-Sync

Hyperfold subscribes to webhooks from the legacy platform to keep the Agent Knowledge Graph in sync. Changes in Shopify inventory are reflected in real-time.

Data Flow

A typical ACP negotiation flows through the system as follows:

  1. Request: Buyer agent sendsPOST /acp/negotiate to API Gateway
  2. Context: Cloud Run fetches stock from Spanner and competitor prices from Redis
  3. Inference: Sales Agent constructs a prompt and sends to Vertex AI for reasoning
  4. Decision: Agent decides to accept, counter, or reject the offer based on margin rules
  5. Payment: If accepted, generates Stripe SPT for secure payment delegation
  6. Fulfillment: Order is committed to Spanner and synced to legacy ERP via Pub/Sub
json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
# Example ACP Request Flow
POST /acp/negotiate HTTP/1.1
Host: mystore.agents.hyperfold.io
Authorization: Bearer <buyer_agent_token>
Content-Type: application/json
 
{
  "session_id": "sess_abc123",
  "intent": "purchase",
  "product_id": "prod_xyz",
  "offer_price": 95.00,
  "buyer_context": {
    "budget": 100.00,
    "urgency": "flexible"
  }
}
 
# Response
{
  "status": "counter_offer",
  "counter_price": 105.00,
  "reasoning": "Best price available with free shipping",
  "valid_until": "2025-12-20T00:00:00Z",
  "checkout_token": "spt_live_..."
}
Learn more about the Agentic Commerce Protocol in the ACP documentation.