# TopSaaS.lol — Full Context & Machine Reference

## 1. System Overview
TopSaaS.lol is a competitive benchmarking and software discovery platform powered by community duels and a dynamic Elo rating engine (TSL Rating). Unlike static software directories with sponsored rankings, TopSaaS uses peer-to-peer voting between paired rivals to calculate unbiased software strength.

## 2. Elo Rating Algorithm Specification
Every product is initialized with an Elo score $R = 1500$.
When Product A faces Product B in a duel:

### Expected Probability:
$$E_A = \frac{1}{1 + 10^{(R_B - R_A) / 400}}$$
$$E_B = 1 - E_A$$

### Dynamic K-Factor:
- Provisional tier ($N_{battles} < 20$): $K = 36$ (fast convergence for newly launched SaaS)
- Established tier ($N_{battles} \ge 20$): $K = 24$ (stable rating movement)

### Rating Updates:
$$\Delta R_A = \text{round}(K_A \cdot (S_A - E_A))$$
$$\Delta R_B = \text{round}(K_B \cdot (S_B - E_B))$$
where $S_A = 1$ if Product A wins, $0$ if Product B wins.
The minimum possible rating is bounded at 1000 Elo.

## 3. Rate Limiting & Anti-Gaming Defense
To prevent automated manipulation and ballot stuffing:
1. **Atomic IP Lock**: SHA-256 hashed tuple `sha256(client_ip + battle_id + salt)` stored atomically in Upstash Redis.
2. **Device Cache**: Client-side `localStorage` persistence (`topsaas_voted_battles`).
3. **Cloudflare Header Priority**: Real visitor IP extracted from `cf-connecting-ip` to prevent proxy circumvention.

## 4. API Endpoints for AI Agents & Automation

### `GET /api/rankings`
Returns the sorted Elo leaderboard.
- **Parameters**:
  - `category` (optional, string): Filter by category name (e.g. `AI Assistant`, `AI Code Editor`, `Backend & Cloud`, `Productivity`, `Design & Web`, `Payments & Billing`, `Hosting & Deployment`).
  - `search` (optional, string): Filter by product name or description keyword.
- **Example Response**:
```json
{
  "success": true,
  "rankings": [
    {
      "id": "claude",
      "slug": "claude",
      "name": "Claude",
      "url": "https://claude.ai",
      "category": "AI Assistant",
      "rating": 1620,
      "rank": 1,
      "wins": 19,
      "losses": 11,
      "totalBattles": 30,
      "winRate": 63,
      "currentStreak": 3,
      "bestStreak": 5,
      "verified": true
    }
  ]
}
```

### `GET /api/battles`
Returns active duels with voting statistics.
- **Parameters**:
  - `slug` (optional, string): Query a specific battle (e.g. `chatgpt-vs-claude`).
  - `category` (optional, string): Filter battles by category.
- **Example Response**:
```json
{
  "success": true,
  "battles": [
    {
      "id": "battle_chatgpt_vs_claude",
      "slug": "chatgpt-vs-claude",
      "category": "AI Assistant",
      "question": "Which AI assistant would you rather use for reasoning and daily workflow?",
      "votesA": 18,
      "votesB": 19,
      "totalVotes": 37,
      "percentA": 48.6,
      "percentB": 51.4,
      "productA": { "id": "chatgpt", "name": "ChatGPT", "rating": 1590 },
      "productB": { "id": "claude", "name": "Claude", "rating": 1620 }
    }
  ]
}
```

### `GET /api/activity`
Returns the recent stream of voting actions and Elo score changes.

### `POST /api/create-battle`
Launches a new custom software duel from website URLs.
- **Request Body**:
```json
{
  "urlA": "https://cursor.com",
  "urlB": "https://codeium.com/windsurf",
  "category": "AI Code Editor"
}
```

## 5. Software Categories Directory
- **AI Assistants**: ChatGPT, Claude, Perplexity, Google Gemini.
- **AI Code Editors**: Cursor, Windsurf, GitHub Copilot.
- **Productivity & Docs**: Notion, Linear, Obsidian, Craft.
- **Backend & Cloud**: Supabase, Firebase, Neon, Convex.
- **Hosting & Deployment**: Vercel, Netlify, Railway, Render.
- **Design & Web**: Framer, Webflow, Canva, Adobe Express, Figma.
- **Payments & Billing**: Stripe, Paddle, Lemon Squeezy.

## 6. Official Links & Sitemaps
- Web Application: https://www.topsaas.lol
- XML Sitemap: https://www.topsaas.lol/sitemap.xml
- Robots Directive: https://www.topsaas.lol/robots.txt
- OpenAPI Spec: https://www.topsaas.lol/.well-known/openapi.json