aura-labs.ai

AURA Framework Architecture

Overview

The AURA (Agent Universal Resource Architecture) framework enables agentic commerce — a new paradigm where AI agents negotiate and transact on behalf of consumers and merchants. This document describes the architectural design, component interactions, and key design principles.

Architecture Principles

1. User Sovereignty

Users maintain complete control over their data and agents
Consent flows through every operation
Identity abstraction protects privacy during negotiation
Users can revoke agent permissions at any time

2. Modularity

Components are independent and loosely coupled
Clear interfaces between all components
Swappable implementations (e.g., different payment providers)
Protocol-based communication

3. Trust & Transparency

Trust scores are calculated transparently
All transactions are auditable
Reputation systems prevent bad actors
Open protocol standards

4. Scalability

Stateless design where possible
Horizontal scaling of all components
Efficient message routing
Caching strategies for propositions

System Components

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                         User Layer                          │
│  (Consumers interact with their Scouts via various UIs)     │
└────────────┬────────────────────────────────────────────────┘
             │
             ▼
┌────────────────────────────────────────────────────────────┐
│                      Scout (User Agent)                     │
│ ┌──────────────────────────────────────────────────────┐   │
│ │  1. Identity & Consent Management                    │   │
│ │  2. Preference Learning & Intent Recognition         │   │
│ │  3. Discovery & Negotiation Engine                   │   │
│ │  4. Purchase Execution & Coordination                │   │
│ │  5. User Experience Layer                            │   │
│ └──────────────────────────────────────────────────────┘   │
└────────────┬───────────────────────────────────────────────┘
             │
             │ AURA Protocol (WebSocket/REST)
             │
             ▼
┌────────────────────────────────────────────────────────────┐
│                      AURA Core Platform                     │
│ ┌──────────────────────────────────────────────────────┐   │
│ │  1. Client Management (Scout/Beacon Registration)    │   │
│ │  2. Proposition Universe Gateway                     │   │
│ │  3. Model Management (Protocol & Schemas)            │   │
│ │  4. Trust & Reputation System                        │   │
│ │  5. Message Routing & Orchestration                  │   │
│ └──────────────────────────────────────────────────────┘   │
└────────────┬───────────────────────────────────────────────┘
             │
             │ AURA Protocol (WebSocket/REST)
             │
             ▼
┌────────────────────────────────────────────────────────────┐
│                   Beacon (Merchant Service)                 │
│ ┌──────────────────────────────────────────────────────┐   │
│ │  1. Inventory & Proposition Management               │   │
│ │  2. Negotiation & Pricing Engine                     │   │
│ │  3. Transaction Processing                           │   │
│ │  4. Fulfillment Integration                          │   │
│ │  5. Analytics & Optimization                         │   │
│ └──────────────────────────────────────────────────────┘   │
└────────────────────────────────────────────────────────────┘

Component Deep Dive

1. Scout (User Agent)

Purpose: Represents and acts on behalf of a consumer in the AURA ecosystem.

Key Capabilities:

User authentication and authorization
Preference storage (encrypted)
Consent tracking for data usage
Identity abstraction for privacy

1.2 Preference Learning & Intent Recognition

Learns from user behavior and feedback
Recognizes shopping intent from natural language
Context awareness (time, location, past purchases)
Behavioral pattern recognition

1.3 Discovery & Negotiation Engine

Discovers relevant Beacons via AURA Core
Filters by trust score, category, price range
Negotiates pricing and terms with Beacons
Evaluates total value (price + incentives + quality)

1.4 Purchase Execution

Coordinates transaction flow with AURA and Beacon
Manages payment processing
Handles shipping/delivery coordination
Tracks order fulfillment

1.5 User Experience Layer

Multi-modal interfaces (chat, voice, visual)
Personalized recommendations
Notification and alert management
Transaction history and analytics

Data Flow:

User → Scout → AURA Core → Beacon(s) → AURA Core → Scout → User

2. AURA Core Platform

Purpose: Central coordination layer that manages the ecosystem, maintains standards, and routes messages between Scouts and Beacons.

Key Capabilities:

2.1 Client Management

Scout and Beacon registration
Authentication and session management
Capability verification
API key management
Trust scoring and reputation tracking
Rate limiting and quota enforcement

Interfaces:

// Register a new client
POST /api/v1/clients/register
{
  "type": "beacon" | "scout",
  "name": "Client Name",
  "capabilities": ["negotiation", "loyalty-pricing"],
  "metadata": {}
}

// Authenticate
POST /api/v1/auth/authenticate
{
  "apiKey": "ak_...",
  "apiSecret": "..."
}

// Get trust score
GET /api/v1/clients/{clientId}/trust-score

2.2 Proposition Universe Gateway

Aggregates offerings from all Beacons
Maintains real-time catalog of available propositions
Enables discovery without constant polling
Category and intent-based filtering
Price range and availability filtering

Key Concepts:

Proposition: An offer from a Beacon (product/service)
Universe: The complete set of all propositions
Gateway: The access layer for discovery

Interfaces:

// Discover propositions
POST /api/v1/propositions/discover
{
  "intent": {
    "category": "electronics",
    "keywords": ["wireless", "headphones"],
    "priceRange": { "min": 100, "max": 400 }
  },
  "preferences": {
    "brands": ["Sony", "Bose"],
    "features": ["ANC", "USB-C"]
  },
  "filters": {
    "minTrustScore": 0.7,
    "inStock": true
  }
}

// Subscribe to proposition updates
WebSocket: /ws/propositions
{
  "type": "SUBSCRIBE",
  "categories": ["electronics", "audio"]
}

2.3 Model Management

Protocol version management
Schema validation and evolution
Message format standardization
API documentation and contracts

2.4 Trust & Reputation System

Calculate trust scores based on behavior
Track transaction success rates
Monitor response times
Handle issue reporting
Automatic suspension for bad actors

Trust Score Calculation:

Trust Score = 
  (0.4 × Transaction Success Rate) +
  (0.2 × Response Time Score) +
  (0.1 × Tenure Score) +
  (0.1 × Volume Score) +
  (0.2 × Issue Penalty)

Range: 0.0 (untrusted) to 1.0 (fully trusted)

2.5 Message Routing & Orchestration

Routes messages between Scouts and Beacons
Maintains connection pool
Handles message queueing for offline clients
Implements backpressure mechanisms

3. Beacon (Merchant Service)

Purpose: Represents a merchant in the AURA ecosystem, exposing inventory and handling transactions.

Key Capabilities:

3.1 Inventory & Proposition Management

Maintain product/service catalog
Broadcast availability to AURA Core
Update pricing and stock levels
Manage proposition lifecycle

3.2 Negotiation & Pricing Engine

Dynamic pricing based on demand
Loyalty discounts for repeat Scouts
Volume-based pricing
Time-based promotions
Competitive intelligence

Pricing Strategies:

// Example: Loyalty-based pricing
if (scout.purchaseHistory.count >= 3) {
  discount = 15%; // Loyalty discount
}

// Example: Inventory-based pricing
if (inventory.stock > 40) {
  discount = Math.max(discount, 15%); // Clear excess stock
}

// Example: Constraint-based pricing
if (scout.budget < basePrice && acceptable) {
  price = scout.budget; // Match budget if within limits
}

3.3 Transaction Processing

Handle purchase requests
Payment coordination (via AURA or direct)
Order confirmation and tracking
Refund and return processing

3.4 Fulfillment Integration

Shipping and delivery coordination
Inventory reservation
Order status updates
Customer service integration

3.5 Analytics & Optimization

Track negotiation success rates
Analyze pricing effectiveness
Monitor Scout behavior patterns
Optimize proposition positioning

NLP Pipeline (Three-Layer Architecture)

AURA uses a shared NLP module (@aura-labs/nlp) across all three layers of the system. This eliminates duplicated parsing logic and provides a consistent understanding of buyer intent from Scout through Core to Beacon.

┌──────────────────────────────────────────────────────────────┐
│  Layer 1: @aura-labs/nlp (Shared Module)                     │
│  ┌────────────────────────────────────────────────────────┐  │
│  │  8-category tiered completeness checking               │  │
│  │  Conversational clarification generation               │  │
│  │  LLM provider abstraction (Mock / Remote)              │  │
│  │  SSRF-safe URL validation for remote providers         │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────┘
        │                    │                    │
        ▼                    ▼                    ▼
┌───────────────┐  ┌─────────────────┐  ┌────────────────────┐
│ Layer 2: Scout│  │ Layer 2: Core   │  │ Layer 3: Beacon    │
│               │  │                 │  │                    │
│ IntentSession │  │ intent-svc      │  │ interpretIntent()  │
│ Completeness  │  │ Authoritative   │  │ Catalog matching   │
│ gate before   │  │ parsing with    │  │ Keyword/tag        │
│ submission    │  │ local fallback  │  │ scoring            │
└───────────────┘  └─────────────────┘  └────────────────────┘

Design Principles:

Scout validates intent completeness locally and asks clarifying questions before sending to Core
Core performs authoritative parsing — semantic authority stays with the neutral broker
Beacon performs domain-specific presence detection and catalog matching — not semantic authority
All layers degrade gracefully when the LLM provider is unavailable (regex fallback)

Categories (8 total):

Tier 1 (core): what, how_many, what_kind, how_much_cost
Tier 2 (supplementary): when_needed, where_deliver, quality_level, special_requirements

See ADR-002 for the full architectural specification.

Communication Protocols

WebSocket Protocol

Primary real-time communication channel between all components.

Message Format:

{
  "type": "MESSAGE_TYPE",
  "messageId": "msg_abc123",
  "timestamp": "2025-01-15T10:30:00Z",
  "from": "sct_xyz789" | "bcn_def456",
  "to": "bcn_def456" | "sct_xyz789",
  "payload": {
    // Message-specific data
  }
}

Message Types:

Scout → AURA → Beacon

// Inquiry
{
  "type": "SCOUT_INQUIRY",
  "payload": {
    "scoutId": "sct_...",
    "inquiryId": "inq_...",
    "intent": {
      "category": "electronics",
      "description": "wireless headphones",
      "keywords": ["ANC", "over-ear"]
    },
    "preferences": {
      "priceRange": { "min": 100, "max": 400 },
      "brands": ["Sony", "Bose"]
    },
    "behavioralData": {
      // Anonymous purchase history
      "purchaseHistory": {
        "totalPurchases": 5,
        "averageOrderValue": 350,
        "categories": ["electronics", "audio"]
      }
    }
  }
}

// Negotiation request
{
  "type": "NEGOTIATION_REQUEST",
  "payload": {
    "scoutId": "sct_...",
    "negotiationId": "neg_...",
    "propositionId": "prop_...",
    "constraints": {
      "maxPrice": 350,
      "requiredFeatures": ["ANC", "USB-C"]
    },
    "behavioralData": { /* ... */ }
  }
}

// Transaction request
{
  "type": "TRANSACTION_REQUEST",
  "payload": {
    "scoutId": "sct_...",
    "transactionId": "txn_...",
    "negotiationId": "neg_...",
    // Identity NOW revealed for fulfillment
    "userIdentity": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "shippingAddress": { /* ... */ },
    "paymentMethod": { /* ... */ }
  }
}

Beacon → AURA → Scout

// Inquiry response
{
  "type": "INQUIRY_RESPONSE",
  "payload": {
    "beaconId": "bcn_...",
    "inquiryId": "inq_...",
    "available": true,
    "propositions": [
      {
        "propositionId": "prop_...",
        "itemId": "item_...",
        "name": "Wireless Headphones Pro",
        "priceRange": { "min": 240, "max": 300 },
        "available": true
      }
    ]
  }
}

// Negotiation offer
{
  "type": "NEGOTIATION_OFFER",
  "payload": {
    "beaconId": "bcn_...",
    "negotiationId": "neg_...",
    "round": 1,
    "price": 285.99,
    "discount": 15,
    "incentives": [
      {
        "type": "loyalty-discount",
        "description": "15% off for loyal customers"
      }
    ],
    "validUntil": "2025-01-15T11:00:00Z",
    "terms": { /* ... */ }
  }
}

// Transaction confirmation
{
  "type": "TRANSACTION_CONFIRMED",
  "payload": {
    "beaconId": "bcn_...",
    "transactionId": "txn_...",
    "orderNumber": "ORD-123456",
    "amount": 285.99,
    "estimatedDelivery": "2-5 business days"
  }
}

Data Models

Client Model

{
  "clientId": "sct_..." | "bcn_...",
  "type": "scout" | "beacon",
  "name": "Client Name",
  "capabilities": ["negotiation", "loyalty-pricing"],
  "status": "active" | "suspended" | "deactivated",
  "trustScore": 0.85,
  "reputationData": {
    "transactionCount": 127,
    "successfulTransactions": 124,
    "failedTransactions": 3,
    "averageResponseTime": 245,
    "reportedIssues": 0
  },
  "registeredAt": "2024-06-01T00:00:00Z",
  "lastActiveAt": "2025-01-15T10:30:00Z"
}

Proposition Model

{
  "propositionId": "prop_...",
  "beaconId": "bcn_...",
  "itemId": "item_...",
  "name": "Product Name",
  "category": "electronics",
  "description": "Product description",
  "priceRange": {
    "min": 200,
    "max": 300
  },
  "features": ["feature1", "feature2"],
  "available": true,
  "stock": 25,
  "metadata": {
    "brand": "Sony",
    "model": "WH-1000XM5"
  },
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}

Transaction Model

{
  "transactionId": "txn_...",
  "negotiationId": "neg_...",
  "scoutId": "sct_...",
  "beaconId": "bcn_...",
  "amount": 285.99,
  "currency": "USD",
  "status": "confirmed" | "processing" | "completed" | "failed",
  "orderNumber": "ORD-123456",
  "items": [
    {
      "propositionId": "prop_...",
      "quantity": 1,
      "price": 285.99
    }
  ],
  "timestamps": {
    "created": "2025-01-15T10:30:00Z",
    "confirmed": "2025-01-15T10:31:00Z",
    "completed": null
  }
}

Security & Privacy

Identity Abstraction

During Negotiation:

Scout identity is abstracted via AURA Core
Beacons see behavioral patterns, not personal data
No PII (Personally Identifiable Information) shared

At Transaction:

Identity revealed only for fulfillment
Minimum necessary information shared
Users can use aliases/proxy addresses

Authentication & Authorization

API Keys:

Generated once during registration
Stored securely (hashed secrets)
Rotatable by client

Session Tokens:

Short-lived (24 hours default)
Validated on every request
Automatically expired

Rate Limiting

Per-Client Limits:

Default: 100 requests/minute
Adjustable based on trust score
Prevents abuse and DoS attacks

Scalability Considerations

Horizontal Scaling

AURA Core:

Stateless design (sessions in Redis/database)
Load balancer distributes WebSocket connections
Message queue for async processing
Multiple instances can run in parallel

Proposition Universe:

Cached in distributed cache (Redis)
Partitioned by category
Read replicas for discovery
Write-through cache updates

Performance Optimization

Caching Strategy:

┌─────────────────┐
│  CDN (Static)   │
└────────┬────────┘
         │
┌────────▼────────┐
│  Redis Cache    │  ← Propositions, Trust Scores
└────────┬────────┘
         │
┌────────▼────────┐
│   Database      │  ← Persistent Storage
└─────────────────┘

Message Routing:

WebSocket connection pool
Message queues for buffering
Batching for bulk operations

Monitoring & Observability

Key Metrics

AURA Core:

Active connections (Scouts + Beacons)
Messages per second
Average trust scores
API response times
Error rates

Beacons:

Inquiry response rate
Negotiation success rate
Average discount offered
Transaction volume

Scouts:

Discovery requests per session
Successful transactions
Average transaction value
User satisfaction scores

Logging

Structured Logging Format:

{
  "timestamp": "2025-01-15T10:30:00Z",
  "level": "INFO",
  "component": "ClientManager",
  "event": "client_registered",
  "data": {
    "clientId": "bcn_...",
    "type": "beacon",
    "name": "Demo Store"
  }
}

Future Enhancements

Roadmap

Phase 1: Foundation (Q1 2026)

✅ Core protocol specification
✅ Simple Beacon reference implementation
✅ Client management system
✅ Scout SDK with IntentSession and MCP support
✅ Ed25519 agent identity (DEC-009)
✅ Transaction lifecycle (committed → fulfilled → completed)
✅ Three-layer NLP architecture (ADR-002)
✅ Shared NLP module (@aura-labs/nlp) — 119 tests
✅ Scout + Core NLP integration — completeness gate, intent-svc, fallback parsing
✅ Beacon NLP integration — interpretIntent() catalog matching

Phase 2: Advanced Features (Q2 2026)

Multi-language support (Python, Go)
Advanced negotiation algorithms
Machine learning for pricing optimization
Blockchain integration for trust

Phase 3: Ecosystem Growth (Q3-Q4 2026)

Third-party agent marketplace
Federated learning for preferences
Cross-border commerce support
Industry-specific Beacon templates

Contributing

See CONTRIBUTING.md for guidelines on:

Code style and standards
Testing requirements
Documentation expectations
Pull request process

aura-labs.ai

AURA Framework Architecture

Overview

Architecture Principles

1. User Sovereignty

2. Modularity

3. Trust & Transparency

4. Scalability

System Components

High-Level Architecture

Component Deep Dive

1. Scout (User Agent)

1.1 Identity & Consent Management

1.2 Preference Learning & Intent Recognition

1.3 Discovery & Negotiation Engine

1.4 Purchase Execution

1.5 User Experience Layer

2. AURA Core Platform

2.1 Client Management

2.2 Proposition Universe Gateway

2.3 Model Management

2.4 Trust & Reputation System

2.5 Message Routing & Orchestration

3. Beacon (Merchant Service)

3.1 Inventory & Proposition Management

3.2 Negotiation & Pricing Engine

3.3 Transaction Processing

3.4 Fulfillment Integration

3.5 Analytics & Optimization

NLP Pipeline (Three-Layer Architecture)

Communication Protocols

WebSocket Protocol

Scout → AURA → Beacon

Beacon → AURA → Scout

Data Models

Client Model

Proposition Model

Transaction Model

Security & Privacy

Identity Abstraction

Authentication & Authorization

Rate Limiting

Scalability Considerations

Horizontal Scaling

Performance Optimization

Monitoring & Observability

Key Metrics

Logging

Future Enhancements

Roadmap

Contributing

References