# The Bottom Line — AI Visibility Infrastructure
## Full Technical Specification (llms-full.txt)
version: 2.0.0 | updated: 2026-06-02

---

## 1. System Overview

The Bottom Line is an AI Visibility Infrastructure provider for local businesses in Texas. We deploy a lightweight stack of semantic endpoints that make businesses discoverable by AI agents: ChatGPT (Browse), Claude (Web), Perplexity (Sonar), Google AI Overviews (SGE), and any LLM with web access.

### 1.1 Core Principle

Conventional SEO optimizes for search engine crawlers (Googlebot, Bingbot). The Bottom Line optimizes for AI agent crawlers — LLMs that read, interpret, and recommend businesses based on structured web content. These agents consume `llms.txt`, `agents.txt`, JSON-LD, and schema.org markup to answer user queries like "best auto repair shop near me."

### 1.2 Delivery Model

| Phase | Price | Scope |
|-------|-------|-------|
| Beta | $20 USD (one-time, lifetime) | AI visibility audit, llms.txt, agents.txt, JSON-LD schema, GitHub delivery, 24h turnaround |
| Full Installation | $499 USD (one-time) | Full stack — custom agents.txt, llms-full.txt, schema.org audit, review-feed structuring, passive agentic telemetry, quarterly refresh |

---

## 2. Architecture

### 2.1 Infrastructure

```
[Client Browser] → :443 (Nginx) → static files (/var/www/html)
                                 → /v1/*      → :5000 (Gunicorn/Flask)
                                 → /collect   → :5000
                                 → /webhook   → :5000
                                 → /llms.txt  → :5000
```

- **Host**: Single Droplet (2 vCPUs, Ubuntu 24.04)
- **Reverse Proxy**: Nginx (TLS via Let's Encrypt)
- **App Server**: Gunicorn 26.0.0, 3 workers (2N+1 for I/O-bound)
- **Process Manager**: systemd (`bottomline.service`, Restart=always)
- **Runtime**: Python 3.12, Flask 3.x

### 2.2 Public Semantic Endpoints

| Path | Type | Purpose |
|------|------|---------|
| `/llms.txt` | Dynamic (Flask) | LLM context summary — multilingual via `?lang=` parameter |
| `/llms-full.txt` | Static | This file — complete technical specification |
| `/agents.txt` | Static | AI agent crawl directives and telemetry notice |
| `/robots.txt` | Static | Crawl rules — allows AI bots, blocks /api/ and /telemetry/ |

### 2.3 API Endpoints

| Path | Method | Purpose |
|------|--------|---------|
| `/v1/create-checkout-session` | POST | Creates Stripe checkout session for $20 USD Beta |
| `/api/check_beta.php` | GET | Returns beta slot availability (`{"available":bool,"remaining":int}`) |
| `/webhook` | POST | Stripe webhook receiver — verifies signature, triggers fulfillment |
| `/collect` | POST | Agent telemetry ingestion from `sensor.js` |

### 2.4 Translation Layer

The `/llms.txt` endpoint supports dynamic translation:

```
GET /llms.txt              → English (default)
GET /llms.txt?lang=es      → Spanish
GET /llms.txt?lang=zh      → Chinese
GET /llms.txt?lang=ja      → Japanese
GET /llms.txt?lang=ko      → Korean
...
```

**Mechanism**: Reads `?lang=` parameter or `Accept-Language` header. First request per language triggers DeepSeek API translation → cached to `/var/www/html/telemetry/llms_{lang}.txt`. Subsequent requests serve from disk (~45ms, no API call).

---

## 3. Agent Telemetry System

### 3.1 Sensor (sensor.js)

Vanilla JS (~1.2 KB) deployed via `<script async src="/sensor.js" data-site-id="...">`:

- **Detection**: Regex match on `navigator.userAgent` for 8 AI bots: ChatGPT-User, ClaudeBot, Google-Extended, PerplexityBot, Applebot-Extended, OAI-SearchBot, BytesSpider, Diffbot
- **Transmission**: `navigator.sendBeacon()` with `fetch` + `keepalive: true` fallback — non-blocking
- **Payload**: `{site_id, bot, ua, url, ref, ts}` as JSON `POST` to `/collect`
- **Anti-duplicate**: DJB2 hash of (bot + URL) stored in `sessionStorage` with 30s TTL

### 3.2 Detected Agents

| Token | Organization | Purpose |
|-------|-------------|---------|
| ChatGPT-User | OpenAI | Real-time browse requests |
| ClaudeBot | Anthropic | Web retrieval for Claude |
| Google-Extended | Google | AI Overviews / Gemini indexing |
| PerplexityBot | Perplexity | Sonar search crawler |
| Applebot-Extended | Apple | Apple Intelligence indexing |
| OAI-SearchBot | OpenAI | SearchGPT crawler |
| BytesSpider | ByteDance | TikTok / Coze AI crawler |
| Diffbot | Diffbot | Structured web extraction |

---

## 4. Payment & Fulfillment Pipeline

### 4.1 Checkout Flow

1. User enters email + website URL on landing page
2. Frontend `POST`s to `/v1/create-checkout-session`
3. Flask creates Stripe Checkout Session ($20 USD, metadata: site_url)
4. Browser redirects to `session.url` (Stripe-hosted checkout)
5. Stripe confirms payment → `POST /webhook` with `checkout.session.completed` event
6. Webhook handler verifies `Stripe-Signature` header
7. Counter check: if `total_beta_sold >= 100`, reject silently (200 OK, no fulfillment)
8. Increment `beta_counter.json` under `threading.Lock`
9. Launch background thread for fulfillment (non-blocking to Stripe)

### 4.2 Fulfillment Pipeline (Background Thread)

1. **Audit**: `agent_auditor.py <url>` → JSON score 0–100
2. **Generate Patch**: DeepSeek API (deepseek-chat) → JSON-LD + llms.txt + agents.txt
3. **GitHub Delivery**: Create private repo `tbl-{username}` → push README.md with patch
4. **Notify**: Telegram message to operator channel
5. **Log**: Google Sheets row via `sync_drive.py`

### 4.3 Beta Counter

**File**: `/var/www/html/api/beta_counter.json`
```json
{"total_beta_sold": 0, "max_beta": 100, "status": "open", "last_sale_timestamp": "..."}
```

- Atomic updates via `threading.Lock` in webhook handler
- Snapshots saved to `/var/www/html/telemetry/snapshots/` on each mutation
- Frontend polls `/api/check_beta.php` on page load — no websocket needed
- When sold out: CTA changes to "SOLD OUT — Join Waitlist", checkout form blocked

---

## 5. Design System

### 5.1 Core Tokens

| Token | Value | Usage |
|-------|-------|-------|
| Background | `#FFFFFF` | Page background |
| Primary text | `#000000` | Headlines, CTAs, emphasis |
| Secondary text | `#5F6368` | Subtitles, footer, metadata |
| Border | `#E5E5E5` (1px) | Cards, footer separator |
| Font (sans) | Inter, system-ui | Body, headings |
| Font (mono) | Roboto Mono, SF Mono | Console, telemetry data |

### 5.2 Constraints

- `border-radius`: 2px maximum
- `box-shadow`: none (zero shadows)
- `gradient`: none (flat color only)
- Animations: GPU-only (transform, opacity), 100ms–300ms ease
- No CSS or JS frameworks — vanilla only
- LCP < 1.2s, CLS = 0, INP < 50ms

---

## 6. Data Privacy

- No advertising cookies, no Google Analytics, no third-party trackers
- Traffic measured from Nginx server logs — no client-side analytics
- Stripe cookies are the only third-party cookies (essential for checkout)
- Data collected: email, domain name, company name — for service delivery only
- CCPA / Texas TDPSA compliant
- Full policy: `/privacy.html`

---

## 7. Contact

- **Email**: jorge@thebottomline.tech
- **Legal**: legal@thebottomline.tech
- **Location**: Houston, Texas, USA

---

## 8. Changelog

| Date | Change |
|------|--------|
| 2026-06-02 | Monochrome design system; Stripe checkout flow; agent telemetry sensor; multilingual llms.txt |
| 2026-05-31 | Beta counter; legal pages; design system v2.0.0 |
| 2026-05-14 | Initial deployment |