# highermark AI — Architecture One
## OpenRouter + Stripe Pay-As-You-Go · WorkOS Auth

---

## Overview

highermark AI is a cloud inference layer that routes prompts to the best available model (via OpenRouter) with a Stripe-powered credit wallet. Users authenticate via WorkOS, buy credits, and consume them per token.

---

## Stack

| Layer | Technology |
|-------|------------|
| Auth | WorkOS (SSO, magic link, OAuth) |
| Payments | Stripe (checkout, webhooks, credits) |
| LLM Router | OpenRouter API |
| Fast Inference | Cerebras Cloud (primary) |
| Frontend | Static HTML/JS (highermark.xyz) |
| Backend | Node.js / Python serverless (Vercel / Railway) |

---

## OpenRouter Integration

### Credentials

```
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
OPENROUTER_APP_NAME=highermark
OPENROUTER_APP_URL=https://highermark.xyz
```

Get your key at: https://openrouter.ai/keys

### Model Selection Strategy

```js
const MODEL_TIERS = {
  fast:     "cerebras/llama3.1-8b",        // ~$0.10/1M tokens
  balanced: "openai/gpt-4o-mini",          // ~$0.15/1M tokens
  capable:  "anthropic/claude-3-5-sonnet", // ~$3/1M tokens
  best:     "openai/gpt-4o",               // ~$5/1M tokens
};

function pickModel(creditBalance, taskComplexity) {
  if (creditBalance < 0.10) return MODEL_TIERS.fast;
  if (taskComplexity === 'simple') return MODEL_TIERS.balanced;
  return MODEL_TIERS.capable;
}
```

### API Call

```js
import OpenAI from "openai";

const openrouter = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
  defaultHeaders: {
    "HTTP-Referer": "https://highermark.xyz",
    "X-Title": "highermark AI",
  },
});

const response = await openrouter.chat.completions.create({
  model: "anthropic/claude-3-5-sonnet",
  messages: [{ role: "user", content: prompt }],
  stream: true,
});
```

---

## Stripe Pay-As-You-Go Credits

### Credit System

1 credit = $0.01 USD
Tokens cost credits based on model:
- Fast tier: 0.001 credits/1k tokens
- Balanced: 0.015 credits/1k tokens
- Capable: 0.30 credits/1k tokens

### Stripe Setup

```
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PUBLISHABLE_KEY=pk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_CREDITS_10=price_...   # $10 = 1,000 credits
STRIPE_PRICE_CREDITS_50=price_...   # $50 = 5,500 credits (10% bonus)
STRIPE_PRICE_CREDITS_100=price_...  # $100 = 12,000 credits (20% bonus)
```

### Credit Purchase Flow

```js
// 1. Create Stripe checkout session
const session = await stripe.checkout.sessions.create({
  payment_method_types: ["card"],
  line_items: [{ price: STRIPE_PRICE_CREDITS_10, quantity: 1 }],
  mode: "payment",
  success_url: "https://highermark.xyz/ai?session={CHECKOUT_SESSION_ID}",
  cancel_url: "https://highermark.xyz/ai",
  metadata: { userId, creditAmount: "1000" },
});

// 2. Stripe webhook: payment_intent.succeeded
// Add credits to user's balance in database

// 3. Per-request deduction
async function consumeCredits(userId, tokens, model) {
  const cost = calculateCost(tokens, model);
  await db.user.update({ where: { id: userId },
    data: { credits: { decrement: cost } } });
}
```

---

## WorkOS Auth Flow

```
WORKOS_API_KEY=sk_...
WORKOS_CLIENT_ID=client_...
WORKOS_REDIRECT_URI=https://highermark.xyz/api/auth/callback
```

### Login Flow

```js
// 1. Generate authorization URL
const { url } = await workos.userManagement.getAuthorizationUrl({
  provider: "authkit",
  redirectUri: WORKOS_REDIRECT_URI,
  clientId: WORKOS_CLIENT_ID,
});
// Redirect user to url

// 2. Handle callback
const { user, accessToken } = await workos.userManagement.authenticateWithCode({
  clientId: WORKOS_CLIENT_ID,
  code: req.query.code,
});
// Create session, provision free credits for new users
if (isNewUser) await provisionFreeCredits(user.id, 50); // $0.50 free
```

---

## Free Tier

New users get **50 free credits ($0.50)** on signup. This is enough for:
- ~100 fast-tier completions
- ~3 capable-tier completions (Claude-level)

---

## Frontend Demo Page

The AI demo page (`highermark-ai.html`) simulates:
1. WorkOS login modal → "Try Demo" instant access
2. Credit wallet: shows $0.50 free
3. Three-column comparison (Cerebras / OpenRouter / Claude)
4. Mirrored typing across columns (streaming simulation)
5. Hover any column → expands to full glass demo
6. After 2-3 sentences → "top up credits" prompt → poof back to main

---

## Implementation Checklist

- [ ] WorkOS account + AuthKit UI setup
- [ ] Stripe account + products + webhook endpoint
- [ ] OpenRouter account + API key
- [ ] Cerebras account + API key (optional, routed via OpenRouter too)
- [ ] Database (Postgres/Supabase): users, credit_ledger, completions
- [ ] Backend: /api/auth/*, /api/credits/*, /api/completions/*
- [ ] Deploy backend (Railway or Vercel Edge Functions)
- [ ] Wire up frontend demo page
- [ ] Lightning credits (LNURL-pay → credit top-up) — future phase

---

## GitHub Reference

Core repo: https://github.com/jimbrend/highermark

The highermark device firmware + bot code lives here. The AI layer sits on top as a cloud service that the device calls out to.