PrioStack Platform Documentation v0.1

PrioStack is a dynamic microservices platform that enables deployment and execution of service bundles with automatic API routing and user isolation. Deploy bundles containing multiple services, each with their own goals, intents, and REST endpoints.

🚀 Current Features: Bundle deployment, service APIs, user authentication, WASM module support, and automated testing.

⚠️ Coming Soon: Advanced bidding system, metrics monitoring, and future reservations are planned but not yet implemented.

💡 What you'll learn: How to create a complete e-commerce bundle with catalog, cart, order, and payment services using YAML configuration and WASM modules.

Quick Start

To get started with PrioStack, you need to:

Create a user account and authenticate
Create a bundle folder with YAML configurations and WASM modules
Upload your bundle via ZIP or Git import
Run the bundle to start all services
Access your service APIs through the platform

Core Concepts

Bundles

A Bundle is a collection of related services packaged together. Think of it as a microservices application. Each bundle has a bundle.yaml file that defines its name and lists all services.

Learn more about Bundles →

Services

A Service is a single unit of functionality with its own goals, intents, and API. Services are defined in YAML files and can expose REST endpoints.

Learn more about Services →

Intents

Intents are reactive behaviors triggered by sensors. When a sensor fires, the intent executes a function. This is the core of PrioStack's automation.

Learn more about Intents →

Goals & Metrics

Each service can define Goals with associated Metrics that define success criteria. The metrics framework is designed for future monitoring capabilities.

Learn more about Goals & Metrics →

WASM Modules

Services can include WASM modules for server-side execution. WASM modules are automatically loaded when bundles start and can handle API requests.

Learn more about WASM Modules →

Resource Contracts

Resource Contracts declare service resource requirements and quality-of-service expectations. They separate business logic from resource economics and prepare for future bidding.

Learn more about Resource Contracts →

Tutorial: E-Commerce Bundle

Let's build a complete e-commerce bundle with four services: Catalog, Cart, Order, and Payment. This tutorial shows how to create services with YAML configuration and optional WASM modules for custom logic.

1Create the Folder Structure

First, create a folder for your bundle with the following structure:

📁 ecommerce/
  ├── bundle.yaml
  ├── 📁 catalog/
  │   └── catalog-service.yaml
  ├── 📁 cart/
  │   └── cart-service.yaml
  ├── 📁 order/
  │   └── order-service.yaml
  ├── 📁 payment/
  │   └── payment-service.yaml
  └── 📁 wasm/
      ├── catalog.wasm
      ├── cart.wasm
      ├── order.wasm
      └── payment.wasm

2Define the Bundle

Create bundle.yaml in the root folder:

# ecommerce/bundle.yaml
name: ecommerce
description: E-commerce platform with catalog, cart, orders, and payments
services:
  - path: catalog/catalog-service.yaml
  - path: cart/cart-service.yaml
  - path: order/order-service.yaml
  - path: payment/payment-service.yaml

⚠️ Important: The path is relative to the bundle folder. Make sure your file structure matches exactly.

3Create the Services

Catalog Service

The catalog service manages products. Create catalog/catalog-service.yaml:

# catalog/catalog-service.yaml
name: catalogService
description: Manages product catalog and inventory

goals:
  - name: HighAvailability
    metrics:
      - signal: catalogHealth
        type: availability
        goal: uptime
        threshold: 0.99
        delay: 0
        window: 60

intents:
  - name: syncInventory
    whenSensor: inventoryChange
    toFunc: wasm:catalog:updateInventoryCache
    primitiveIntent: stateMutation
    cooldown: 5s

api:
  basePath: "/api/v1/catalog"
  endpoints:
    - name: listProducts
      method: GET
      path: "/products"
      to: "wasm:catalog:listProducts"
      description: "List all products"
    - name: getProduct
      method: GET
      path: "/products/:id"
      to: "wasm:catalog:getProductById"
      description: "Get product by ID"
    - name: searchProducts
      method: GET
      path: "/products/search"
      to: "wasm:catalog:searchProducts"
      description: "Search products by query"

Cart Service

Create cart/cart-service.yaml:

# cart/cart-service.yaml
name: cartService
description: Manages shopping carts for users

goals:
  - name: CartConsistency
    metrics:
      - signal: cartSync
        type: consistency
        goal: dataIntegrity
        threshold: 1.0
        delay: 0
        window: 30

intents:
  - name: validateCart
    whenSensor: cartModified
    toFunc: wasm:cart:validateCartItems
    primitiveIntent: validation
    cooldown: 1s
    
  - name: expireCart
    whenSensor: cartInactive
    toFunc: wasm:cart:cleanupExpiredCarts
    primitiveIntent: cleanup
    expiresIn: 24h

api:
  basePath: "/api/v1/cart"
  endpoints:
    - name: getCart
      method: GET
      path: "/:userId"
      to: "wasm:cart:getUserCart"
      description: "Get user's cart"
    - name: addItem
      method: POST
      path: "/:userId/items"
      to: "wasm:cart:addToCart"
      description: "Add item to cart"
    - name: removeItem
      method: DELETE
      path: "/:userId/items/:itemId"
      to: "wasm:cart:removeFromCart"
      description: "Remove item from cart"
    - name: checkout
      method: POST
      path: "/:userId/checkout"
      to: "wasm:cart:initiateCheckout"
      description: "Start checkout process"

Order Service

Create order/order-service.yaml:

# order/order-service.yaml
name: orderService
description: Manages order lifecycle

goals:
  - name: OrderFulfillment
    metrics:
      - signal: orderProcessing
        type: latency
        goal: fastProcessing
        threshold: 5000
        delay: 0
        window: 60

intents:
  - name: processOrder
    whenSensor: newOrder
    toFunc: wasm:orders:processNewOrder
    primitiveIntent: workflow
    retries: 3
    expectedDuration: 30s
    
  - name: notifyShipping
    whenSensor: orderPaid
    toFunc: wasm:orders:sendToShipping
    primitiveIntent: notification

api:
  basePath: "/api/v1/orders"
  endpoints:
    - name: createOrder
      method: POST
      path: "/"
      to: "wasm:order:createOrder"
      description: "Create new order"
    - name: getOrder
      method: GET
      path: "/:orderId"
      to: "wasm:order:getOrder"
      description: "Get order details"
    - name: listOrders
      method: GET
      path: "/user/:userId"
      to: "wasm:order:getUserOrders"
      description: "List user's orders"
    - name: cancelOrder
      method: POST
      path: "/:orderId/cancel"
      to: "wasm:order:cancelOrder"
      description: "Cancel an order"

Payment Service

Create payment/payment-service.yaml:

# payment/payment-service.yaml
name: paymentService
description: Handles payment processing

goals:
  - name: PaymentSecurity
    metrics:
      - signal: paymentValidation
        type: security
        goal: fraudPrevention
        threshold: 0.999
        delay: 0
        window: 10

intents:
  - name: processPayment
    whenSensor: paymentRequest
    toFunc: wasm:payment:processPaymentTransaction
    primitiveIntent: transaction
    retries: 2
    expectedDuration: 10s
    
  - name: refundPayment
    whenSensor: refundRequest
    toFunc: wasm:payment:processRefund
    primitiveIntent: transaction
    cooldown: 60s

api:
  basePath: "/api/v1/payments"
  endpoints:
    - name: processPayment
      method: POST
      path: "/process"
      to: "wasm:payment:processPayment"
      description: "Process a payment"
    - name: getPayment
      method: GET
      path: "/:paymentId"
      to: "wasm:payment:getPaymentStatus"
      description: "Get payment status"
    - name: refund
      method: POST
      path: "/:paymentId/refund"
      to: "wasm:payment:refundPayment"
      description: "Refund a payment"

4Add Resource Contracts

Resource contracts define how services should access compute resources. Let's add contracts to our services to ensure critical operations get priority.

Payment Service - Critical Priority

Payment processing needs guaranteed low latency and high reliability:

services:
  - name: payment
    goals:
      - name: transactionSuccess
        metric: successRate
        target: "> 99.9%"
        resourceContract:
          priority: critical
          computeUnits: 200
          maxWaitTime: "2s"
          futuresEnabled: true
          fallbackBehavior: fail
          costCeiling: 10

      - name: responseTime
        metric: latency
        target: "< 500ms"
        resourceContract:
          priority: critical
          computeUnits: 100
          maxWaitTime: "1s"

Catalog Service - High Priority

Product catalog needs good performance but can tolerate some delay:

services:
  - name: catalog
    goals:
      - name: searchResponse
        metric: latency
        target: "< 200ms"
        resourceContract:
          priority: high
          computeUnits: 50
          maxWaitTime: "5s"
          fallbackBehavior: degrade

      - name: availability
        metric: uptime
        target: "> 99.5%"
        resourceContract:
          priority: normal
          computeUnits: 25

Cart Service - Normal Priority

Shopping cart operations are important but not critical:

services:
  - name: cart
    goals:
      - name: cartOperations
        metric: latency
        target: "< 300ms"
        resourceContract:
          priority: normal
          computeUnits: 30
          maxWaitTime: "10s"
          fallbackBehavior: retry

Order Service - High Priority

Order processing needs reliability but can queue during peak times:

services:
  - name: order
    goals:
      - name: orderProcessing
        metric: successRate
        target: "> 99%"
        resourceContract:
          priority: high
          computeUnits: 150
          maxWaitTime: "15s"
          futuresEnabled: true
          fallbackBehavior: queue

💡 Resource Contract Strategy

Critical: Payment processing (can't fail, must be fast)
High: User-facing services (catalog, orders)
Normal: Supporting services (cart, analytics)
Futures: Enable for services that benefit from advance resource reservation

5Multi-Tenancy & API Access

PrioStack automatically handles multi-tenancy by isolating services per user. Each user's services are deployed with tenant-aware API paths to prevent conflicts.

Tenant-Aware API Paths

When you deploy a bundle, PrioStack automatically prefixes all API paths with your tenant ID:

# Your service defines:
basePath: "/api/v1/catalog"

# PrioStack serves it at:
/{your-tenant-id}/api/v1/catalog

API Access Examples

Here's how different users access the same service:

# User "alice" calls catalog API:
GET /alice/api/v1/catalog/products

# User "bob" calls the same service:
GET /bob/api/v1/catalog/products

# Both work independently without conflicts!

✅ Multi-Tenancy Benefits

Isolation: Each user has their own service instances
No Conflicts: Same service names and paths work for all users
Security: Users can only access their own services
Scalability: Multiple users can deploy identical bundles

6Understanding Intents

Intents are the reactive core of PrioStack. Here's what each field means:

Field	Description
`name`	Unique identifier for the intent
`whenSensor`	The sensor that triggers this intent
`toFunc`	Function to execute when triggered
`primitiveIntent`	Type: stateMutation, validation, workflow, transaction, notification, cleanup
`cooldown`	Minimum time between executions
`retries`	Number of retry attempts on failure
`expiresIn`	How long until the intent expires

6Deploy and Run

Now you can deploy your bundle to PrioStack:

Option A: Import from Git

Push your bundle folder to a Git repository
In PrioStack, click "Add Bundle"
Select the "From Git" tab
Enter your repository URL and branch
Click "Import from Git"

Option B: Upload ZIP

Zip your bundle folder (the folder containing bundle.yaml)
In PrioStack, click "Add Bundle"
Select the "Upload ZIP" tab
Enter a bundle name and select your ZIP file
Click "Upload ZIP"

✅ Success! Once imported, your bundle will appear in the Bundles page. Click "Run" to start all services.

Access Your APIs

Once running, your service APIs are available at tenant-aware paths:

# Your tenant ID is automatically added to all paths
# If your user ID is "alice", APIs are available at:

# Catalog endpoints
GET  /alice/api/v1/catalog/products
GET  /alice/api/v1/catalog/products/:id

# Cart endpoints
GET  /alice/api/v1/cart/:userId
POST /alice/api/v1/cart/:userId/items

# Order endpoints
POST /alice/api/v1/orders/
GET  /alice/api/v1/orders/:orderId

# Payment endpoints
POST /alice/api/v1/payments/process
GET  /alice/api/v1/payments/:paymentId

🔒 Multi-Tenancy Security

Each user can only access their own services. The tenant ID in the URL ensures complete isolation between users.

Reference: bundle.yaml

name: string          # Required: Bundle identifier
description: string   # Optional: What this bundle does
services:             # Required: List of services
  - path: string      # Path to service YAML file

Reference: Service Definition

name: string              # Required: Service identifier
description: string       # Optional: What this service does

goals:                    # Optional: Success metrics
  - name: string
    metrics:
      - signal: string    # Metric signal name
        type: string      # availability, latency, consistency, security
        goal: string      # Goal identifier
        threshold: number # Target value
        delay: number     # Delay in seconds
        window: number    # Time window in seconds

intents:                  # Optional: Reactive behaviors
  - name: string
    whenSensor: string
    toFunc: wasm:service:functionName
    primitiveIntent: string
    cooldown: duration
    retries: number
    expiresIn: duration
    expectedDuration: duration

api:                      # Optional: REST API
  basePath: string
  endpoints:
    - name: string
      method: string      # GET, POST, PUT, DELETE
      path: string
      to: wasm:service:functionName
      description: string

Reference: Primitive Intents

stateMutation - Modifies internal state
validation - Validates data integrity
workflow - Multi-step process orchestration
transaction - Atomic operations with rollback
notification - Sends notifications/events
cleanup - Garbage collection and maintenance

Reference: API Methods

GET - Retrieve resources
POST - Create new resources
PUT - Update existing resources
DELETE - Remove resources
PATCH - Partial update

Bidding System: Planned Feature

⚠️ Not Yet Implemented: The bidding system is planned for a future release. Currently, all compute resources are allocated on a first-come, first-served basis.

🔗 Hybrid Integration

The bidding system will integrate with Resource Contracts to automatically bid based on service priority and cost ceilings defined in goal contracts.

PrioStack will use a priority-based bidding system to allocate compute resources fairly during high demand. When the execution queue exceeds capacity, users will bid for priority using credits from their wallet.

Key Principle: When demand is low, everyone executes for free. When demand is high, those willing to pay more will get priority.

Integration with Resource Contracts

Resource contracts in service goals will automatically participate in bidding:

goals:
  - name: criticalOperation
    metric: latency
    target: "< 200ms"
    resourceContract:
      priority: critical
      costCeiling: 5        # Max credits to bid
      autoBid: true         # Automatically participate

When bidding activates, contracts with autoBid: true will:

Use their priority to determine bidding strategy
Respect their costCeiling limit
Fall back to fallbackBehavior if bidding fails

Round-Based Execution

The cloud engine processes requests in rounds:

Each service instance gets max 100 compute units per round (free tier)
Queue capacity threshold: 1,000 pending requests
When queue exceeds threshold, bidding activates

Resource Estimation

When you trigger a service action (e.g., calling an API endpoint), PrioStack will estimate how many compute units are needed to complete it. This estimate will include a +10% buffer for safety.

# Example: An action needs 225 compute units

# When market = 0 (free tier, queue not full):
# → 3 queue entries (100 + 100 + 25 units each)
# → Executes over 3 rounds

# When market = 1 and you win the bid:
# → 1 queue entry (you get 500 units)
# → Executes in 1 round

Market Dynamics

How Price will be Determined

When queue > 1,000 entries → Market price will start at 1 credit
Users with auto-bid enabled will automatically increment their bid
Price will increase until only 200 bidders remain
Market price will be fixed at that point
Winners will get: compute_units = market_price × 500
Market will reset to 0 at start of next round

Market Price	Compute Units	Cost per Action (225 units)
0 (free tier)	100 per round	Free (3 rounds)
1 credit	500	1 credit (1 round)
10 credits	5,000	10 credits (instant)
50 credits	25,000	50 credits (instant)

Auto-Bid Settings (Planned)

Configure your bidding behavior in the Dashboard:

Auto-Bid Toggle

When enabled, your account will automatically participate in bidding rounds. Your bid will increment by 1 credit each tick until you win or hit your cap.

Bid Cap

Set a maximum amount you're willing to spend per round. If the market price exceeds your cap, you'll be excluded from that round (unless you have a reservation).

# Example: Bid Cap = 50 credits

# If market price reaches 50:
# → You're still in the running

# If market price reaches 51:
# → You're excluded from this round
# → Your action waits for the next round

⚠️ No Cap (0): Setting bid cap to 0 means unlimited. You'll always win if you have enough credits in your wallet.

Future Reservations (Planned)

Future Credits (reservations) will allow you to guarantee compute priority for a specific time window, regardless of market price.

How Reservations Will Work

Specify a time window (e.g., 10:00 AM - 10:10 AM)
Pre-pay credits for the reservation
During that window, you will always win bidding rounds
Market price won't affect you during your reserved time

# Example: Critical batch job at 10:00 AM

# Without reservation:
# → Market might spike to 75 credits
# → If your cap is 50, you lose

# With reservation (10:00-10:10):
# → Guaranteed priority
# → Even if market hits 100, you win

Creating a Reservation

Go to Dashboard → Click "Reserve"
Select start and end times
Enter credits to reserve
Credits will be deducted immediately from your wallet

💡 Use Case: Reserve compute for scheduled jobs, batch processing, or peak business hours when you need guaranteed priority.

Reservation Rules

Reservations cannot overlap
Cannot cancel active reservations
Credits will be non-refundable once the window starts
Can cancel upcoming reservations for a full refund

Ready to build? Get started with PrioStack →