Ty
2aa7a2cf97
Archive the 5-screen form wizard spec (signup → data entry → scrape → pointer install → live status) as superseded by the conversational flow (UC-04/UC-05). Preserved for structured data field reference and historical traceability.
205 lines
6.4 KiB
Markdown
205 lines
6.4 KiB
Markdown
# SSP Form-Based Screen Spec — Superseded
|
|
|
|
**Archived:** 2026-07-29
|
|
**Superseded by:** UC-04 (Conversational SSP — First Hour), UC-05 (Conversational SSP — Ongoing)
|
|
**Source:** `docs/product/ssp-refined.md` §3, §6 (legacy flow), §7, §9
|
|
|
|
---
|
|
|
|
## Decision Note
|
|
|
|
> **Why cut:** Ty decided "chat replaces forms entirely" (Decision #4, SSP Refinement channel, 2026-07-29). The entire form-based activation path — 5-screen wizard with signup, manual data entry, scrape reflection, pointer install, and live status — is replaced by a single conversational flow. The form screens are retained here for historical traceability and as a reference for the structured data fields that the conversational flow must still capture.
|
|
|
|
---
|
|
|
|
## Screen 1: Signup
|
|
|
|
**Purpose:** Create an account tied to one business. No OAuth — email + password only for MVP.
|
|
|
|
**Fields:**
|
|
- Email (required, validated format)
|
|
- Password (required, min 8 chars)
|
|
- Password confirm (required, must match)
|
|
|
|
**Behavior:**
|
|
- Creates a `tenants` row (email, password hash, status = 'active')
|
|
- Creates a `businesses` row with status = 'draft'
|
|
- Associates tenant with business via FK
|
|
- Redirects to Screen 2 (Business Info)
|
|
- No email verification for MVP (defer)
|
|
|
|
**Errors:**
|
|
- Email already registered → "Account exists. Try signing in." (add signin link)
|
|
- Password mismatch → "Passwords don't match"
|
|
- Empty required field → inline validation
|
|
|
|
---
|
|
|
|
## Screen 2: Business Info Capture
|
|
|
|
**Purpose:** Collect the structured data that becomes the MCP payload.
|
|
|
|
**Fields (organized in sections):**
|
|
|
|
**Identity:**
|
|
- Business name (required)
|
|
- Business slug (auto-generated from name, editable, unique)
|
|
- Category (required, select from predefined list)
|
|
- Description / story (optional, textarea)
|
|
|
|
**Location:**
|
|
- Street address (optional but encouraged)
|
|
- City, State, ZIP (optional)
|
|
- Phone (optional)
|
|
- Website URL (optional — used for scrape reflection)
|
|
|
|
**Operations:**
|
|
- Hours (JSON structure: Mon-Sun open/close, plus holiday override flag)
|
|
- Services (array of name/description pairs)
|
|
- Booking link (optional, URL — Cal.com or equivalent)
|
|
|
|
**Schema mapping:**
|
|
|
|
| Field | businesses column |
|
|
|-------|-------------------|
|
|
| Business name | `name` |
|
|
| Slug | `slug` |
|
|
| Category | `category` |
|
|
| Description | `story` |
|
|
| Address fields | `address`, `city`, `state`, `zip` |
|
|
| Phone | `phone` |
|
|
| Website | `website` |
|
|
| Hours | `hours` (JSONB) |
|
|
| Services | `services` (JSONB) |
|
|
| Booking link | `calcom_link` |
|
|
|
|
---
|
|
|
|
## Screen 3: Scrape Reflection
|
|
|
|
**Purpose:** Show the owner what the platform already sees on their website — and where there are gaps.
|
|
|
|
**Input:** Website URL from Screen 2.
|
|
|
|
**Behavior:**
|
|
- One-time scrape triggered when user clicks "Analyze my site"
|
|
- Parse public HTML for: business name, hours, services, phone, address, booking links
|
|
- Display side-by-side comparison (green check / yellow warning / red X)
|
|
- "Use what we found" button to auto-populate gaps from scrape
|
|
- "Skip" button to proceed without scrape
|
|
|
|
**Technical notes:**
|
|
- Scrape runs server-side (not client-side — CORS)
|
|
- Timeout: 10 seconds per page
|
|
- No JS rendering for MVP (static HTML only)
|
|
- Rate limit: one scrape per signup session
|
|
|
|
---
|
|
|
|
## Screen 4: Pointer Install
|
|
|
|
**Purpose:** Give the owner concrete instructions to attach a discovery pointer on their website.
|
|
|
|
**Options:**
|
|
- A: `.well-known/mcp-server` (preferred)
|
|
- B: DNS CNAME (for static sites / hosted platforms)
|
|
- C: Link tag (quick test)
|
|
|
|
**Verification:**
|
|
- "Verify" button triggers a server-side fetch of the pointer location
|
|
- Proceed without verification allowed (unverified badge)
|
|
|
|
---
|
|
|
|
## Screen 5: Live Status
|
|
|
|
**Purpose:** Confirm the endpoint is live and show what an AI agent sees.
|
|
|
|
**Content:**
|
|
- Status banner: Green (discoverable) / Yellow (almost live) / Red (not ready)
|
|
- MCP Preview: actual JSON response for `get_business_info`
|
|
- Preflight Checklist: required fields verified
|
|
- Actions: edit, re-verify, share endpoint URL
|
|
|
|
---
|
|
|
|
## Legacy Form Flow Diagram
|
|
|
|
```
|
|
Owner arrives at geolocal.io
|
|
|
|
|
v
|
|
[Screen 1] Signup (email + password)
|
|
| creates tenant + business(draft)
|
|
v
|
|
[Screen 2] Business Info Capture (manual entry)
|
|
| populates businesses row
|
|
v
|
|
[Screen 3] Scrape Reflection (one-time, optional)
|
|
| compares site content vs entered data
|
|
| owner confirms or edits
|
|
v
|
|
[Screen 4] Pointer Install (instructions + verify)
|
|
| owner installs .well-known/mcp-server or CNAME
|
|
| platform verifies pointer
|
|
v
|
|
[Screen 5] Live Status
|
|
| status = 'active'
|
|
| preflight passes
|
|
| MCP endpoint live at /mcp/{slug}
|
|
```
|
|
|
|
---
|
|
|
|
## Screen-Based Acceptance Criteria (Superseded)
|
|
|
|
### Screen 1: Signup
|
|
- [ ] User can create an account with email + password
|
|
- [ ] Duplicate email is rejected
|
|
- [ ] Tenant row created with correct business_id FK
|
|
- [ ] Business row created with status = 'draft'
|
|
|
|
### Screen 2: Business Info
|
|
- [ ] All fields save to businesses row
|
|
- [ ] Slug is auto-generated, editable, unique
|
|
- [ ] Category is required (from predefined list)
|
|
- [ ] Services can be added/removed (min 1)
|
|
- [ ] Hours captured as JSONB
|
|
|
|
### Screen 3: Scrape Reflection
|
|
- [ ] Server-side scrape of provided URL (10s timeout)
|
|
- [ ] Side-by-side comparison displayed
|
|
- [ ] "Use what we found" populates gaps
|
|
- [ ] Skippable (proceed without scrape)
|
|
|
|
### Screen 4: Pointer Install
|
|
- [ ] Three pointer options presented (well-known, CNAME, link tag)
|
|
- [ ] Verification fetches and validates pointer
|
|
- [ ] Proceed without verification allowed (unverified badge)
|
|
|
|
### Screen 5: Live Status
|
|
- [ ] Status banner reflects endpoint state
|
|
- [ ] MCP preview shows actual JSON response
|
|
- [ ] Preflight checklist is accurate
|
|
- [ ] Setting status = 'active' makes endpoint queryable
|
|
|
|
### Cross-cutting
|
|
- [ ] HTTP transport replaces stdio for `/mcp/{slug}`
|
|
- [ ] Slug-based routing returns correct business data
|
|
- [ ] Done-when criteria 1-4 are all satisfied
|
|
|
|
---
|
|
|
|
## What Changed from Original SSP Spec (Historical)
|
|
|
|
| Area | Before | After |
|
|
|------|--------|-------|
|
|
| Length | 14 lines | Implementation-ready |
|
|
| Screens | Named but not described | 5 screens with fields, behavior, errors |
|
|
| Data model | Not specified | Schema with status column, tenants table |
|
|
| Scrape | Mentioned | One-time on signup, side-by-side comparison |
|
|
| Pointer | Mentioned | 3 options with verification flow |
|
|
| Transport | Not decided | Streamable-HTTP with decision record |
|
|
| Quality flags | Separate table | Status column on businesses |
|
|
| Acceptance criteria | None | Per-screen + cross-cutting |
|