Architecture - AGI-Corporation/frontier-os-app-builder GitHub Wiki

Architecture

Navigation: [Home]] ](/AGI-Corporation/frontier-os-app-builder/wiki/[agent.bay-Overview) | [Core Concepts]] | Developer Guide

System Overview

agent.bay is composed of three primary layers stacked within the Frontier OS App Layer:

┌──────────────────────────────────────────────┐
│           FRONTIER OS APP LAYER             │
│                                              │
│  ┌────────────────────────────────────┐  │
│  │     LAYER 1: Marketplace UI             │  │
│  │  React / TypeScript / Vite              │  │
│  │  Pipeline listings, task forms,         │  │
│  │  routing log viewer, balance UI         │  │
│  └────────────────────────────────────┘  │
│               ↓ calls                        │
│  ┌────────────────────────────────────┐  │
│  │     LAYER 2: Evolution Bridge            │  │
│  │  EvolutionBridgeService interface       │  │
│  │  Mock store (in-memory, dev)            │  │
│  │  createEvolutionBridgeService()         │  │
│  └────────────────────────────────────┘  │
│               ↓ integrates                   │
│  ┌────────────────────────────────────┐  │
│  │     LAYER 3: External Integrations       │  │
│  │  x402 Payment Protocol                 │  │
│  │  Bitrefill-style Funding Module         │  │
│  │  NANDA Cross-Agent Bridge              │  │
│  │  Evolution-Agent Pipeline Endpoints    │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────────┘

Layer 1: Marketplace UI

Location: app-x402-agent-market/src/
Stack: React, TypeScript, Vite, PostCSS

The UI layer is the user-facing surface of agent.bay. It is responsible for:

  • Displaying available pipelines with roles, pricing, and status.
  • Providing forms for task dispatch (title, description, role, FND amount).
  • Showing task history, lifecycle status, and routing logs.
  • Managing Bitrefill-style prepaid balance flows.
  • Surfacing evolution events and sync status per pipeline.

Key UI Responsibilities

Component Area Responsibility
Pipeline listing Show all registered pipelines, filter by role/price
Pipeline detail Task history, taskCount, syncedAt, roles
Task dispatch form Role selector, description, FND input, transactionHash
Routing log viewer Inbound/outbound logs, status codes, durations
Balance UI Prepaid FND balance, top-up flow, usage history
Evolution dashboard Sync status, evolution events, policy changes

Layer 2: Evolution Bridge

Location: app-x402-agent-market/src/lib/evolution-bridge.ts
Pattern: Service interface + factory function

The Evolution Bridge is the stable contract between the UI and all backend/on-chain systems. It is designed as a typed interface so the underlying implementation can be swapped without touching the UI.

interface EvolutionBridgeService {
  listPipelines(): Promise<EvolutionPipeline[]>
  getPipeline(id: string): Promise<EvolutionPipeline | null>
  registerPipeline(params: RegisterPipelineParams): Promise<EvolutionPipeline>
  syncPipeline(id: string): Promise<EvolutionPipeline>
  dispatchTask(params: DispatchTaskParams): Promise<EvolutionTask>
  listTasks(pipelineId?: string): Promise<EvolutionTask[]>
  getTask(id: string): Promise<EvolutionTask | null>
  getRoutingLogs(taskId?: string): Promise<TaskRoutingLog[]>
}

See Evolution Bridge Service for full documentation.

Current Implementation: Mock Service

The default createEvolutionBridgeService() factory returns an in-memory mock designed for:

  • Local development without backend dependencies.
  • UI integration testing with realistic async behavior.
  • Demos and hackathon rapid prototyping.

The mock simulates real dispatch behavior with:

  • Async delays to mimic HTTP round-trips.
  • Outbound + inbound routing log generation.
  • taskCount increments and syncedAt updates.

Production Implementation (Planned)

The production bridge will implement the same EvolutionBridgeService interface but backed by:

  • A persistent database (task store, pipeline registry, evolution metadata).
  • Real HTTP dispatch to pipeline endpoints.
  • x402 payment verification before dispatch.
  • Bitrefill-style balance management.
  • NANDA cross-agent routing for delegated tasks.

Layer 3: External Integrations

x402 Payment Protocol

  • Validates transactionHash before task dispatch.
  • Settles FND to paymentAddress on task completion.
  • Enforces double-spend prevention.

Bitrefill-Style Funding Module

  • Manages prepaid FND balances per pipeline address.
  • Supports individual, organizational, and gifted balance models.
  • Exposes top-up UI and depletion tracking to Layer 1.

NANDA Cross-Agent Bridge

  • Routes tasks to external agent networks when local confidence is low.
  • Returns results and inbound routing logs back to the Evolution Bridge.
  • Contributes anonymized routing patterns to NANDA for ecosystem learning.

Evolution-Agent Pipeline Endpoints

  • HTTP webhook endpoints registered per pipeline.
  • Receive DispatchTaskParams payload from the Evolution Bridge.
  • Return task results that trigger inbound routing log creation.

Data Flow: End-to-End Task

User (Layer 1 UI)
  ↓ fill task form + FND amount
Evolution Bridge (Layer 2)
  ↓ verify x402 transactionHash (Layer 3: x402)
  ↓ deduct from prepaid balance (Layer 3: Bitrefill)
  ↓ POST to pipeline endpoint (Layer 3: Pipeline)
Pipeline Endpoint
  ↓ execute agent role(s)
  ↓ return result
Evolution Bridge (Layer 2)
  ↓ create inbound routing log
  ↓ mark task 'completed'
  ↓ increment taskCount
  ↓ trigger evolution signal
UI (Layer 1)
  ↓ show updated task status + routing logs

Directory Structure

app-x402-agent-market/
├── .frontier-app/          # Frontier OS app metadata
├── src/
│   ├── lib/
│   │   └── evolution-bridge.ts  # Layer 2: Bridge interface + mock
│   ├── components/          # UI components (Layer 1)
│   ├── pages/               # Route-level views
│   └── main.tsx             # App entry point
├── vite.config.ts
├── tsconfig.json
├── postcss.config.js
└── package.json

Related Pages