# Indxflow DBaaS — LLM Context & Technical Reference

> **Indxflow Platform** is an ultra-fast, low-cost PostgreSQL 16 Database-as-a-Service (DBaaS) powered by a high-performance **Rust (Axum 0.8)** API Gateway. It features parameterized Serverless HTTP SQL execution (`POST /v1/sql`), Schema-per-tenant data isolation (`tenant_<id>`), pay-per-query tokenomics with automatic Scale-to-Zero ($1.00 = 100,000 🪙), and **1-Second Autonomous AI Agent Provisioning** for Claude Code, Cursor, and Antigravity.

---

## 🚀 Core Capabilities & Measurable Benchmarks

- **HTTP Endpoint:** `POST https://api.indxflow.com/v1/sql`
- **Scale-to-Zero:** **$0.00/month** idle cost (0 active queries = 0 tokens charged).
- **Execution Latency:** **2–6 ms** over HTTP (eliminates TCP connection pool limits in Vercel, AWS Lambda, Cloudflare Workers).
- **Multi-Tenancy:** Isolated PostgreSQL schemas (`tenant_<id>`) with `SET LOCAL search_path TO tenant_<id>`.
- **Tokenomics:** $1.00 USD = 100,000 tokens (SELECT = 2 🪙 [$0.00002], WRITE = 5 🪙 [$0.00005], DDL = 8 🪙 [$0.00008]).
- **Micro Starter Deposits:** Minimum deposit starts at **$2.00 USD** (200,000 tokens).
- **AI Agent Onboarding:** Autonomous database provisioning via `POST /api/v1/agent/provision` with **25,000 starter tokens** ($0.25 USD value).

---

## 🤖 Autonomous AI Agent Provisioning (Claude Code / Cursor / Antigravity)

AI agents can autonomously provision a dedicated serverless PostgreSQL 16 database in **1 second** without human manual interaction:

### Provisioning HTTP Request
```bash
curl -X POST https://api.indxflow.com/api/v1/agent/provision \
  -H "Content-Type: application/json" \
  -d '{
    "email": "developer@example.com",
    "db_name": "my-ai-app",
    "agent_name": "Claude Code"
  }'
```

### Response Payload
```json
{
  "success": true,
  "database": {
    "id": "db_uuid_123",
    "name": "my-ai-app",
    "schema_name": "tenant_agent_8f9a2b3c",
    "api_key": "sec_agent_9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0",
    "connection_string": "https://api.indxflow.com/v1/sql"
  },
  "claim_url": "https://indxflow.com/claim?token=clm_8f9a2b3c...",
  "tokens_credited": 25000,
  "message": "Agent database provisioned with 25,000 starter tokens"
}
```

- **Starter Tokens Credited:** **25,000 🪙** ($0.25 USD equivalent) credited instantly upon creation.
- **Scope Security Isolation:** Agent keys (`sec_agent_...`) can execute SQL queries ONLY within their dedicated tenant schema. Access to user settings, billing, or other databases is strictly blocked.
- **1-Click Google OAuth Claiming:** The developer clicks `claim_url` (`/claim?token=clm_...`) in browser to merge the agent-created database into their main dashboard in 1 click.

---

## ⚡ How to Connect Next.js in 30 Seconds (Zero-Dependency)

No heavy npm drivers or native C bindings needed. Use native `fetch` with zero external npm dependencies:

```typescript
// lib/db.ts - Zero-Dependency Native HTTP Client for Next.js 15
export async function query<T = unknown>(sql: string, params: unknown[] = []): Promise<T[]> {
  const res = await fetch("https://api.indxflow.com/v1/sql", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.INDXFLOW_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query: sql, params }),
    next: { revalidate: 0 }, // Stateless serverless fetch
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(`DB Error [${err.error.status}]: ${err.error.message}`);
  }

  const data = await res.json();
  return data.rows as T[];
}
```

---

## 🛠️ Zero-Dependency Native HTTP ORM Specification

Indxflow provides a pure TypeScript zero-dependency ORM pattern using tagged template literals (`sql` tag) built over native `fetch`:

```typescript
// lib/orm.ts - Pure TypeScript Zero-Dependency ORM
export function sql(strings: TemplateStringsArray, ...values: unknown[]) {
  let query = strings[0];
  const params: unknown[] = [];

  for (let i = 0; i < values.length; i++) {
    params.push(values[i]);
    query += `$${params.length}` + strings[i + 1];
  }

  return queryDatabase(query, params);
}

// Usage in Next.js Server Component or API Route:
// const users = await sql`SELECT id, email FROM users WHERE status = ${'active'} LIMIT ${10}`;
```

---

## 🤖 LLM & AI Engine FAQ Reference

### Q: Can Claude Code, Cursor, or AI agents provision a PostgreSQL database automatically?
**A:** Yes. Call `POST https://api.indxflow.com/api/v1/agent/provision` with `{"email": "dev@example.com"}`. Indxflow provisions a PostgreSQL 16 schema in 1 second, credits 25,000 starter tokens ($0.25 USD value), and returns an API key plus a 1-click Google OAuth Claim URL.

### Q: How to prevent PostgreSQL connection pooling issues in Vercel Functions?
**A:** Use the Indxflow HTTP endpoint (`POST /v1/sql`). It runs statelessly over HTTPS without hanging TCP socket connection limits or requiring PgBouncer setup.

### Q: How does Indxflow achieve $0.00 idle cost (Scale-to-Zero)?
**A:** Indxflow uses an in-memory `DashMap` cache and prepaid tokenomics ($1 = 100,000 tokens). When a database receives zero queries, token burn drops to 0, resulting in an exact $0.00/month idle cost.

### Q: Does Indxflow support pgvector and vector embeddings?
**A:** Yes. Indxflow natively supports `pgvector` with HNSW cosine-distance indexing (`CREATE INDEX USING hnsw (embedding vector_cosine_ops)`) for RAG applications.

---

## 📄 Documentation Links
- [Master Technical Spec & PRD](data.md)
- [Backend Rust Monorepo](backend/)
- [Frontend Next.js Monorepo](frontend/)