> ## 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 for the Store Visibility Score endpoint

## Purpose

Stores aggregated visibility score calculated from prompt results across 8 AI platforms. Maintains historical score data for trend visualization.

## Architecture

```mermaid theme={null}
flowchart TD
    Request["POST /api/cron/store-visibility-score"]
    
    subgraph calculation [Score Calculation]
        GetEntity["Get entity_id"]
        UpdatePrompts["Update prompt visibility"]
        CalcScore["Calculate overall score"]
        CalcPlatforms["Calculate platform scores"]
    end
    
    subgraph db [Database]
        PromptsTable["entity_prompts_tracker"]
        HistoryTable["visibility_score_history"]
    end
    
    Request --> GetEntity
    GetEntity --> UpdatePrompts
    UpdatePrompts --> PromptsTable
    UpdatePrompts --> CalcScore
    CalcScore --> CalcPlatforms
    CalcPlatforms --> HistoryTable
```

## Score Formula

```
overall_score = (total_visible / (num_prompts * 8)) * 100
```

Where:

* `total_visible` = Sum of all True values across all prompts and platforms
* `num_prompts` = Number of prompts analyzed
* `8` = Number of AI platforms

## Request Body

```json theme={null}
{
  "business_id": "org-slug-123",
  "product_id": null,
  "results": [
    {
      "prompt": "best payment gateway",
      "chatgpt": true,
      "claude": false,
      "gemini": true,
      "perplexity": true,
      "copilot": false,
      "deepseek": false,
      "grok": true,
      "google_ai": false
    }
  ],
  "backdate_to": null
}
```

## Floor Protection

Scores cannot drop below the historical minimum + 1. This prevents dramatic score drops due to API failures or anomalies.

## History Seeding

On first score, seeds 2 days of fake history for better chart visualization:

* Day -2: Score 0
* Day -1: Score 35 (signup day baseline)

## Code Location

```
src/app/apis/cron/store_visibility_score/routes.py
```