photoncloud-monorepo/docs/por/T029-practical-app-demo

PlasmaCloud Demo API

Minimal HTTP API demonstrating PlasmaCloud MVP-Alpha E2E functionality.

Overview

This demo validates that all PlasmaCloud components work together for real applications:

• IAM: Token-based authentication
• FlareDB: Persistent key-value storage
• Nightlight: Prometheus metrics export
• Platform Integration: Complete E2E data flow

Architecture

User → HTTP API → FlareDB (storage)
         ↓           ↓
       IAM (auth)  Metrics → Nightlight

API Endpoints

Method	Path	Auth Required	Description
GET	/health	No	Health check
GET	/metrics	No	Prometheus metrics
POST	/items	Yes	Create item
GET	/items/:id	No	Retrieve item
DELETE	/items/:id	Yes	Delete item

Prerequisites

Running PlasmaCloud services:

• flaredb-server on port 8001
• iam-server on port 8002 (default)

Build

cd docs/por/T029-practical-app-demo
nix develop /home/centra/cloud -c cargo build

Run

# Set environment variables (optional)
export FLAREDB_ADDR=127.0.0.1:8001
export IAM_ADDR=http://127.0.0.1:8002
export BIND_ADDR=0.0.0.0:3000

# Run the server
./target/debug/plasma-demo-api

Usage Example

# 1. Health check
curl http://localhost:3000/health

# 2. Create item (requires IAM token)
TOKEN=$(curl -X POST http://localhost:8002/auth/token \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"test","user_id":"demo"}' | jq -r '.token')

curl -X POST http://localhost:3000/items \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":"item1","data":"Hello PlasmaCloud"}'

# 3. Retrieve item (no auth required)
curl http://localhost:3000/items/item1

# 4. Check metrics
curl http://localhost:3000/metrics | grep items

# 5. Delete item (requires IAM token)
curl -X DELETE http://localhost:3000/items/item1 \
  -H "Authorization: Bearer $TOKEN"

Data Persistence

Items are stored in FlareDB with key format: item:{id}

Data persists across server restarts as long as FlareDB is running.

Metrics

Exported Prometheus metrics:

• http_requests_total - Total HTTP requests
• items_created_total - Total items created
• items_retrieved_total - Total items retrieved

Metrics are scraped by Nightlight on the /metrics endpoint.

Implementation

• HTTP Framework: Axum
• Storage Client: flaredb-client (raw KV operations)
• Auth Client: iam-client (token validation)
• Metrics: Prometheus (text export format)
• Runtime: Tokio async

Code Structure

src/main.rs
├── AppState - Shared state (DB, IAM, Metrics)
├── Metrics - Prometheus registry and counters
├── Routes
│   ├── /health - Health check
│   ├── /metrics - Prometheus metrics
│   ├── POST /items - Create item
│   ├── GET /items/:id - Get item
│   └── DELETE /items/:id - Delete item
└── Middleware
    └── auth_middleware - IAM token validation

Acceptance Criteria

• Application deploys successfully
• CRUD operations work
• Data persists in FlareDB
• IAM authentication validates tokens
• Metrics exported to /metrics endpoint

Time Budget

Implementation: ~2 hours (Option A minimal scope)