> ## Documentation Index
> Fetch the complete documentation index at: https://docs.searchcompany.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Architecture and internal services for the Ranking Score endpoint

## Purpose

Returns a pre-payment AI ranking score for the marketing website. Visitors see their "AI Visibility Score" before signing up.

## Architecture

```mermaid theme={null}
flowchart TD
    Request["GET /api/ranking-score?url=..."]
    
    subgraph services [Internal Services]
        GetScore["get_or_create_ranking_score()"]
        GenCompetitors["generate_competitor_scores()"]
        GenPlatforms["generate_platform_statuses()"]
    end
    
    subgraph db [Database]
        Table["pre_payment_rankings table"]
    end
    
    Request --> GetScore
    GetScore -->|"Check existing"| Table
    Table -->|"Found"| ReturnExisting["Return stored score"]
    Table -->|"Not found"| GenerateNew["Generate 32-49, save"]
    GenerateNew --> Table
    
    GetScore --> GenCompetitors
    GenCompetitors --> GenPlatforms
    GenPlatforms --> Response["Return JSON response"]
```

## Internal Services

| Service                                                    | Purpose                           |
| ---------------------------------------------------------- | --------------------------------- |
| [get\_or\_create\_ranking\_score](get-or-create-score)     | Database lookup/insert for score  |
| [generate\_competitor\_scores](generate-competitor-scores) | Creates 4 fake competitor scores  |
| [generate\_platform\_statuses](generate-platform-statuses) | Assigns LOW/MEDIUM to 8 platforms |

## Code Location

```
src/website/ranking_score/
└── routes.py    # All logic in single file
```

## Database Schema

```sql theme={null}
-- In supabase_ranking database (separate from main)
CREATE TABLE pre_payment_rankings (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  website_url TEXT UNIQUE NOT NULL,
  score INTEGER NOT NULL,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
```

## Rate Limiting

* **5 requests per minute** per IP address
* Prevents abuse of the public endpoint