archive: supersede form-based SSP spec with decision notes
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.
This commit is contained in:
@@ -0,0 +1,204 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user