# TagHost Comprehensive Technical Reference (llms-full.txt)

This document contains the complete technical specification, developer guide, CLI manual, and API documentation for TagHost, structured for language models, coding assistants, and automated agents.

---

## 1. Executive Overview

TagHost is an edge-native cloud hosting platform and in-context visual content management system (CMS) tailored specifically for modern React and Vite applications.

### Key Value Propositions
1. **Developer Freedom**: Pure React 19 source code without vendor-proprietary component wrappers.
2. **Marketer Empowerment**: In-context visual canvas editor allowing non-technical editors to update copy and images directly on the deployed site.
3. **Sub-millisecond Edge Delivery**: Dynamic text and image replacements executed at the Cloudflare network edge via streaming `HTMLRewriter` (<1ms execution overhead).
4. **Zero Vendor Lock-In**: Standalone AST codemod (`tag eject`) cleanly removes all CMS metadata and replaces attributes with current static text.
5. **Integrated Wholesale Registrar**: In-app zero-config domain search, WHOIS capture, and automated Universal SSL provisioning via Name.com API v4 and Cloudflare for SaaS.

---

## 2. Platform Architecture

### Components
1. **Edge Router (`apps/edge-router`)**:
   - Runtime: Cloudflare Workers (V8 Isolates).
   - Datastores: Cloudflare KV (`KV_DOMAINS`) for sub-millisecond hostname-to-deployment routing; Cloudflare R2 (`taghost-assets`) for streaming static bundle assets.
   - Dynamic Rewrite Engine: Intercepts `text/html` responses, fetches CMS entries from KV/cache, and executes streaming replacements on elements matching `[data-tag]`.
   - Custom Routing: Parses `_redirects` file from deployment root (301/302 redirects, custom headers, SPA rewrite fallbacks), serves project `404.html` before system default.
   - Tier Hard Caps: Enforces request limits (Free: 100k, Starter: 2M, Pro: 6M) with zero surprise overage billing.

2. **Control Plane Brain (`apps/control-plane`)**:
   - Runtime: Cloudflare Workers with Hono web framework.
   - Primary Database: Cloudflare D1 (Serverless SQLite) with Drizzle ORM.
   - Message Queues: Cloudflare Queues (`taghost-leads`, `taghost-leads-dlq`, `taghost-builds`).
   - Authentication: PBKDF2-SHA256 password hashing (100,000 iterations), single-use challenge tokens, and HS256 JWT sessions for browser dashboards; Bearer API tokens (`tag_live_*`) with SHA-256 hashing for CLI and automated agents.
   - Multi-Tenant Isolation: Strict `requireProjectAccess` middleware enforcing workspace ownership and preventing IDOR vulnerabilities (returns HTTP 404 on tenant mismatch).

3. **In-Context Visual Studio (`apps/studio`)**:
   - Visual drag-and-drop builder embedded directly in console or standalone canvas.
   - AST drawer with bidirectional JSON and React JSX synchronization.
   - LocalStorage draft persistence with change review / publish diff modal before pushing to edge KV.

---

## 3. Developer CLI Reference (`@taghost/cli`)

### Installation
```bash
npm install -g @taghost/cli
```

### Commands

#### `tag init [project-name]`
Initializes a new React project pre-configured for TagHost:
- Creates Vite + React + TypeScript scaffold.
- Installs `@taghost/react` and configures `vite.config.ts`.
- Adds sample editable components with `data-tag` attributes.

#### `tag login`
Authenticates the CLI with your TagHost account:
- Prompts for API token or opens the browser to generate a new developer token.
- Stores credentials in `~/.taghost/credentials.json` with secure file permissions (0600).

#### `tag deploy [options]`
Packages and deploys the project to the production edge:
- Options:
  - `--dir <directory>`: Specify build directory (default: auto-detected `dist`, `build`, or `.`).
  - `--message <msg>`: Custom commit/deployment message.
  - `--preview`: Deploy as an isolated ephemeral preview URL instead of production.
- Mechanism: Bundles assets into memory-efficient ZIP archive using `fflate` and streams directly to `POST /projects/:id/deployments/bundle`. Updates edge routing in <1s.

#### `tag rollback [deployment-id]`
Rolls back edge traffic to a previous stable deployment in sub-seconds (<10ms global switchover):
- Options:
  - `--list`: Interactively browse recent production deployments.
  - Without arguments, selects the immediately preceding successful deployment.
- Mechanism: Atomically rewrites the active deployment pointer in Cloudflare KV without re-uploading files.

#### `tag eject`
Permanently ejects your codebase from the TagHost ecosystem:
- Parses all `.jsx` and `.tsx` source files using `@babel/parser` and `@babel/traverse`.
- Replaces `<element data-tag="key">old</element>` with the latest live published content.
- Strips `@taghost/react` imports and dependencies from `package.json`.
- Results in a 100% standard, clean React application with zero proprietary vendor lock-in.

---

## 4. React SDK (`@taghost/react`)

### Visual Content Tagging
TagHost decouples content from code by using the standard `data-tag` attribute:

```tsx
import React from 'react';

export function HeroBanner() {
  return (
    <section className="hero">
      {/* Marketers can visually edit this heading in TagHost Studio */}
      <h1 data-tag="home.hero.title">
        High-Performance Edge Hosting for React
      </h1>
      
      {/* Marketers can visually edit this subtitle */}
      <p data-tag="home.hero.subtitle">
        Deploy globally in seconds with automated SSL and edge rewriting.
      </p>
      
      {/* Images with data-tag allow desktop-to-canvas drag-and-drop replacement */}
      <img
        data-tag="home.hero.image"
        src="/assets/default-hero.png"
        alt="Platform illustration"
      />
    </section>
  );
}
```

### Lead Capture with Bot Protection (`<TagForm>`)
TagHost includes native form submission handling with zero backend server code:

```tsx
import React from 'react';
import { TagForm } from '@taghost/react';

export function ContactSection() {
  return (
    <TagForm
      name="enterprise-contact"
      className="space-y-4"
      onSuccess={() => alert('Message received! We will be in touch shortly.')}
      onError={(err) => alert(`Submission failed: ${err.message}`)}
    >
      <input type="text" name="name" required placeholder="Full Name" />
      <input type="email" name="email" required placeholder="Work Email" />
      <textarea name="message" required placeholder="Project Details" />
      <button type="submit">Submit Request</button>
    </TagForm>
  );
}
```

#### Under the Hood:
- **Honeypot Shield**: Automatically injects invisible decoy fields that trap spam bots before execution.
- **D1 Submission Storage**: Submissions stored in `form_submissions` table with client IP, user agent, and UTM attribution.
- **Transactional Alerting**: Automatically triggers notifications via Resend and delivers webhooks to registered endpoints.

---

## 5. Domain Management & Registrar API

TagHost implements a dual-path domain strategy:

### Path A: Bring Your Own Domain (BYOD)
- Point a CNAME record at your registrar:
  - Record Type: `CNAME`
  - Host / Name: `@` or `www` or subdomain
  - Target / Value: `cname.taghost.io`
- TagHost automatically provisions an SSL certificate via Cloudflare for SaaS.

### Path B: In-App Wholesale Registrar
- Powered by Name.com API v4.
- Retail prices matched directly to wholesale rates with zero hidden markups.
- Automatic edge routing and DNS configuration immediately upon purchase.

### Public Registrar Endpoints (No Auth Required)

#### 1. Supported TLDs
```http
GET https://api.taghost.io/tlds/supported
```
Response:
```json
["com", "io", "dev", "app", "net", "co"]
```

#### 2. Bulk Availability & Pricing Check
```http
POST https://api.taghost.io/domains/check
Content-Type: application/json

{
  "domains": ["acmepreview.com", "acmepreview.io", "acmepreview.dev"]
}
```
Response:
```json
{
  "results": [
    {
      "domain": "acmepreview.com",
      "available": true,
      "purchasePrice": 13.99,
      "renewalPrice": 15.99,
      "transferPrice": null,
      "years": 1,
      "premium": false
    },
    {
      "domain": "acmepreview.io",
      "available": true,
      "purchasePrice": 38.99,
      "renewalPrice": 42.99,
      "transferPrice": null,
      "years": 1,
      "premium": false
    }
  ]
}
```

---

## 6. Security Principles & Architecture Standards

1. **Authentication Hierarchy**:
   - `owner`: Full workspace, project, billing, member, and token management.
   - `admin`: Project creation, deployment promotion, domain management.
   - `developer`: Deployments, env vars, build trigger, rollback.
   - `editor`: Content editing in Studio, form viewing.
   - `viewer`: Read-only access to deployment logs and status.

2. **Edge Isolation**:
   - Workspaces cannot access or query deployments, assets, or database shards belonging to other workspaces.
   - Database operations use parameterized SQLite prepared statements through Drizzle ORM, eliminating SQL injection.

3. **No Pulse / Toy UI Policy**:
   - The TagHost design system strictly bans animated pulse dots (`animate-pulse`), neon green status badges, decorative emojis in JSX, and raw hex colors. All UI elements adhere to token-backed surfaces (`bg-surface-main`, `bg-surface-card`, `bg-brand-crimson`) and Google Material Symbols.