# 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

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

## Run

```bash
# 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

```bash
# 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

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

## Time Budget

Implementation: ~2 hours (Option A minimal scope)