docs(GRO-106): 10DLC pilot registration runbook

Co-Authored-By: Paperclip <noreply@paperclip.ing>

.github/workflows/ci.yml

@@ -340,7 +340,7 @@ jobs:
     name: Update Infra Image Tags
     runs-on: ubuntu-latest
     needs: [docker]
-    if: (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/dev') && github.event_name == 'push'
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
     permissions:
       contents: write
       pull-requests: write

README.md

@@ -1,43 +1,218 @@
-# GroomBook Monorepo — Archived
+# GroomBook
 
-> **This repository has been archived and replaced by standalone repositories.**
+> **The open-source scheduling and client management platform built specifically for independent pet groomers** — giving you the tools of enterprise software without the enterprise price tag or vendor lock-in.
 
-## Successor Repositories
-
-| Repository | Description |
-|---|---|
-| [groombook/api](https://github.com/groombook/api) | Hono REST API (TypeScript, Node.js) |
-| [groombook/web](https://github.com/groombook/web) | React PWA frontend |
-| [groombook/charts](https://github.com/groombook/charts) | Helm charts for Kubernetes deployment |
-
-## What Changed
-
-- **Monorepo split complete** — The former `apps/api`, `apps/web`, and `packages/*` are now standalone repos
-- **`@groombook/types`** — Inlined directly into `groombook/api` and `groombook/web`
-- **E2E testing** — Now via Playwright MCP, no standalone repo needed
-- **CI/CD** — Each repo has its own pipeline; see individual repos for status
-
-## Migration Notes
-
-If you were cloning `groombook/groombook` for local development:
-
-```bash
-# API
-git clone https://github.com/groombook/api.git
-cd api && pnpm install && pnpm dev
-
-# Web (in a new terminal)
-git clone https://github.com/groombook/web.git
-cd web && pnpm install && pnpm dev
-```
-
-For full Docker Compose setup, see each repo's README.
-
-## Archive Info
-
-This repository was archived on 2026-05-14 as part of the monorepo decommission ([GRO-1081]).
-The history is preserved but the repo is read-only.
+**Built for groomers, not corporations.**
 
 ---
 
-*For Kubernetes deployments, see [groombook/infra](https://github.com/groombook/infra) (private).*
+## Key Features
+
+**Stop chasing confirmations**
+- **Customer portal** — Clients confirm or cancel appointments on their own. Reduce no-shows with an automated waitlist.
+
+**Your calendar, your way**
+- **iCal calendar feed** — Push GroomBook appointments directly into Google Calendar or Apple Calendar. No app switching.
+
+**Know every pet at a glance**
+- **Client & pet records** — Detailed profiles with grooming history, preferences, and breed-specific notes. Full appointment notes for context on every regular.
+- **Quick-find search** — Find clients and pets instantly without digging through spreadsheets.
+
+**Staff access without stress**
+- **Role-based access control (RBAC)** — Front desk sees bookings; only you see financials. Right access for every role.
+
+**Everything else**
+- **Appointment scheduling** — Calendar management for single or multiple groomers
+- **Service management** — Pricing, duration, and service catalog
+- **POS & invoicing** — Payments, tips, and receipt generation
+- **Automated reminders** — SMS and email notifications
+- **Reporting dashboard** — Revenue, utilization, and trend analytics
+- **Staff impersonation** — Managers can view the customer portal as any client, with full audit logging and session controls
+- **PWA** — Installable on mobile devices, works offline
+
+---
+
+## 🚀 Try the Demo
+
+[**Live Demo**](https://demo.groombook.app) — explore GroomBook without installing anything.
+
+---
+
+## Quick Start
+
+### Docker Compose (recommended for indie groomers)
+
+Run GroomBook on your own hardware in minutes. Everything you need is in the box — no subscription, no vendor lock-in.
+
+```bash
+git clone https://github.com/groombook/groombook.git
+cd groombook
+
+# Start everything (Postgres + database migrations + API + web UI)
+docker compose up --build
+```
+
+- **Web UI**: http://localhost:8080
+- **API**: http://localhost:3000
+
+The default `docker-compose.yml` sets `AUTH_DISABLED=true` so you can explore the app without configuring an OIDC provider. **Important:** Disable this in any internet-facing deployment.
+
+---
+
+## Tech Stack
+
+| Layer | Technology |
+|---|---|
+| Backend | [Hono](https://hono.dev/) (TypeScript, Node.js) |
+| Frontend | React 19 + Vite + [vite-plugin-pwa](https://vite-pwa-org.netlify.app/) |
+| Database | PostgreSQL via [CNPG](https://cloudnative-pg.io/) + [Drizzle ORM](https://orm.drizzle.team/) |
+| Auth | OIDC via [Authentik](https://goauthentik.io/) |
+| Infra | Kubernetes (namespace: `groombook`), Flux GitOps |
+| CI | GitHub Actions (self-hosted `groombook-runners`) |
+
+## Repository Structure
+
+```
+groombook/
+├── apps/
+│   ├── api/          # Hono REST API
+│   └── web/          # React PWA
+├── packages/
+│   ├── db/           # Drizzle schema + migrations
+│   └── types/        # Shared TypeScript types
+├── .github/
+│   └── workflows/    # CI/CD pipelines
+└── docker-compose.yml
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js >= 20
+- pnpm >= 9 (`npm install -g pnpm`)
+- Docker & Docker Compose (for local Postgres)
+
+### Local Development
+
+```bash
+# Clone the repo
+git clone https://github.com/groombook/groombook.git
+cd groombook
+
+# Install dependencies
+pnpm install
+
+# Start local Postgres
+docker compose up postgres -d
+
+# Run database migrations
+DATABASE_URL=postgres://groombook:groombook@localhost:5432/groombook pnpm db:migrate
+
+# Start API and Web in parallel
+pnpm dev
+```
+
+API will be available at http://localhost:3000
+Web will be available at http://localhost:5173
+
+### Environment Variables
+
+#### API (`apps/api/.env`)
+
+```env
+DATABASE_URL=postgres://groombook:groombook@localhost:5432/groombook
+OIDC_ISSUER=https://authentik.example.com
+OIDC_AUDIENCE=groombook
+CORS_ORIGIN=http://localhost:5173
+PORT=3000
+```
+
+### Running Tests
+
+```bash
+# Unit tests (vitest)
+pnpm test
+
+# E2E tests (Playwright) — requires the full Docker Compose stack to be running
+docker compose up -d --wait
+pnpm --filter @groombook/e2e test
+
+# Open the Playwright UI (interactive test runner)
+pnpm --filter @groombook/e2e test:ui
+
+# View the last E2E test report
+pnpm --filter @groombook/e2e test:report
+```
+
+E2E tests target the Docker Compose stack (`http://localhost:8080`). They use API route mocking where needed so happy-path tests are deterministic without requiring seed data.
+
+### Building
+
+```bash
+pnpm build
+```
+
+## Self-Hosting
+
+### Production Configuration
+
+Copy `.env.example` to `.env` and configure:
+
+```bash
+cp .env.example .env
+```
+
+Key variables to update for production:
+
+| Variable | Description |
+|---|---|
+| `DATABASE_URL` | PostgreSQL connection string |
+| `AUTH_DISABLED` | Set to `false` in production |
+| `OIDC_ISSUER` | Authentik issuer URL |
+| `OIDC_AUDIENCE` | OAuth2 audience (default: `groombook`) |
+| `CORS_ORIGIN` | Public URL of the web frontend |
+
+To use your `.env` file with Docker Compose:
+
+```bash
+docker compose --env-file .env up --build
+```
+
+### Kubernetes (production-grade deployments)
+
+See the [groombook/infra](https://github.com/groombook/infra) repository for Kubernetes manifests and Flux configuration.
+
+Groom Book is deployed in the `groombook` Kubernetes namespace using:
+- **CNPG** for PostgreSQL
+- **Authentik** for OIDC authentication
+- **Flux** for GitOps-managed deployments
+
+---
+
+## Contributing
+
+GroomBook thrives on contributions from the grooming community. Whether you're a groomer with a feature request, a developer fixing a bug, or someone improving docs — we'd love your help.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes
+4. Open a pull request
+
+All PRs require CI to pass before merge. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+---
+
+## Why GroomBook?
+
+- **Open source** — You own your data. No vendor lock-in.
+- **Purpose-built** — Features designed for grooming workflows, not generic scheduling.
+- **Self-hosted or managed** — Run it yourself for free, or pay for hosted support (coming soon).
+- **Community-driven** — Used and built by actual groomers.
+
+---
+
+## License
+
+AGPL-3.0
+

docs/runbooks/10dlc-pilot-registration.md

@@ -0,0 +1,309 @@
+# 10DLC Pilot Tenant Registration Runbook
+
+Authored for [GRO-106](/GRO/issues/GRO-106) Phase 1.
+
+---
+
+## Pre-Flight Checklist
+
+Before starting Telnyx registration, collect the following:
+
+| Item | Details |
+|------|---------|
+| Legal business name | Exact name on EIN / business registration |
+| EIN (Employer Identification Number) | 9-digit IRS format: XX-XXXXXXX |
+| Business type | Sole Proprietor / LLC / Corporation |
+| Primary contact email | General contact address (postmaster@, info@, etc.) |
+| Primary contact phone | Direct line for carrier verification |
+| Website URL | Must be live and contain privacy policy |
+| Sample message templates | See [Sample Templates](#sample-message-templates) below |
+| Messaging use case | Customer Care / Account Notification |
+
+---
+
+## Step 1 — Telnyx Account Requirements
+
+- Active Telnyx account with billing configured.
+- Role required: **Admin** or **Super User** to register brands and campaigns.
+
+---
+
+## Step 2 — Brand Registration
+
+### Via Telnyx Console
+
+1. Log in to [Telnyx Portal](https://portal.telnyx.com).
+2. Navigate to **Messaging → A2P 10DLC → Brands**.
+3. Click **Register Brand**.
+4. Fill in:
+   - **Brand Name**: Legal business name
+   - **Legal Company Name**: Exact EIN name
+   - **Company Type**: Select from dropdown
+   - **EIN**: XX-XXXXXXX
+   - **Primary Contact**: Name, email, phone
+   - **Website**: Must be accessible
+   - **BusinessVertical**: Select appropriate vertical
+5. Acknowledge the **Terms of Service**.
+6. Submit.
+
+### Via API
+
+```bash
+curl -X POST https://api.telnyx.com/v2/10dlc/brands \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "Your Legal Business Name",
+    "legal_company_name": "Your Legal Business Name",
+    "company_type": "llc",
+    "ein": "XX-XXXXXXX",
+    "primary_contact": {
+      "name": "Jane Doe",
+      "email": "compliance@example.com",
+      "phone": "+13125551000"
+    },
+    "website": "https://www.example.com",
+    "business_vertical": "FINANCE_INSURANCE_BANKING"
+  }'
+```
+
+**Response fields to record:**
+- `brand_id` — required for campaign registration
+- `brand_score` — affects campaign vetting speed
+
+### Expected Fees
+
+| Fee Type | Amount |
+|----------|--------|
+| Brand registration fee | ~$0 (no direct fee from Telnyx) |
+| Campaign registration fee | ~$15–$25 per campaign (Telnyx fee, subject to change) |
+| Carrier fees | Passed through from T-Mobile/AT&T/Verizon |
+
+### Expected Approval Window
+
+- **Vetting by Telnyx**: 1–3 business days after submission.
+- **Carrier (T-Mobile/AT&T/Verizon) review**: 2–5 business days after Telnyx approval.
+- Total end-to-end: **3–8 business days**.
+
+---
+
+## Step 3 — Campaign Registration
+
+### Use Case Selection
+
+- **Primary**: Customer Care
+- **Secondary**: Account Notification
+
+### Via Telnyx Console
+
+1. Navigate to **Messaging → A2P 10DLC → Campaigns**.
+2. Click **Register Campaign**.
+3. Select **Brand** (use the brand registered in Step 2).
+4. Fill in:
+   - **Campaign Name**: e.g., `groombook-pilot-customer-care`
+   - **Use Case**: Customer Care / Account Notification
+   - **Sample Messages**: Paste exactly the templates from [Sample Templates](#sample-message-templates) below.
+   - **Description**: Brief description of messaging program
+   - **Estimated Volume**: Enter monthly estimate (e.g., 500)
+5. Submit.
+
+### Via API
+
+```bash
+curl -X POST https://api.telnyx.com/v2/10dlc/campaigns \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "brand_id": "YOUR_BRAND_ID",
+    "name": "groombook-pilot-customer-care",
+    "use_case": "CUSTOMER_CARE",
+    "sample_messages": [
+      "Hi {{first_name}}, this is a reminder from {{business_name}} that your appointment is scheduled for {{date}} at {{time}}. Reply STOP to opt out.",
+      "Your appointment with {{business_name}} is confirmed for {{date}}. Need to reschedule? Reply HELP or call us at {{phone}}."
+    ],
+    "description": "Appointment reminders and account notifications for grooming clients",
+    "estimated_monthly_volume": 500
+  }'
+```
+
+**Response fields to record:**
+- `campaign_id` — required for messaging profile
+- `status` — initially `PENDING`, transitions to `ACTIVE` after carrier approval
+
+### Campaign Vetting — STOP/HELP Language Requirements
+
+Every campaign **must** include compliant STOP/HELP messaging. The following must appear in your sample messages or be included in your terms of service:
+
+- **STOP**: Users can text `STOP` to opt out of all messages.
+- **HELP**: Users can text `HELP` to receive contact information.
+
+Example STOP/HELP block:
+
+```
+Text STOP to opt out. Text HELP for help. Msg & data rates may apply.
+```
+
+---
+
+## Step 4 — Messaging Profile + Phone Number Provisioning
+
+### Create Messaging Profile
+
+1. In Telnyx Portal, navigate to **Messaging → Messaging Profiles**.
+2. Click **Create Messaging Profile**.
+3. Name it (e.g., `groombook-pilot-prod`).
+4. Copy the **Messaging Profile ID** (`messaging_profile_id`) — record this in the DB.
+
+### Provision a 10DLC Phone Number
+
+1. Navigate to **Messaging → Phone Numbers**.
+2. Search for a number in your desired area code.
+3. Confirm the number is 10DLC-capable.
+4. Purchase the number.
+
+### Associate Number with Messaging Profile
+
+```bash
+# Assign number to messaging profile
+curl -X PATCH https://api.telnyx.com/v2/phone_numbers/YOUR_PHONE_NUMBER_ID \
+  -H "Authorization: Bearer $TELNYX_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messaging_profile_id": "YOUR_MESSAGING_PROFILE_ID"
+  }'
+```
+
+---
+
+## Step 5 — Record in Database
+
+Once [GRO-981](/GRO/issues/GRO-981) lands, record the following against the business record:
+
+### SQL Path (when GRO-981 is complete)
+
+```sql
+UPDATE businesses
+SET
+  messaging_phone_number = '+13125551000',
+  telnyx_messaging_profile_id = 'YOUR_MESSAGING_PROFILE_ID',
+  telnyx_brand_id = 'YOUR_BRAND_ID',
+  telnyx_campaign_id = 'YOUR_CAMPAIGN_ID',
+  telnyx_brand_status = 'APPROVED',
+  telnyx_campaign_status = 'ACTIVE',
+  updated_at = NOW()
+WHERE id = 'pilot_business_id';
+```
+
+### Manual Admin Path (before GRO-981)
+
+Until GRO-981 is complete, use the Telnyx Portal to verify and record values manually in your internal ops sheet:
+
+| Field | Value |
+|-------|-------|
+| `messagingPhoneNumber` | +1XXXXXXXXXX |
+| `telnyxMessagingProfileId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `telnyxBrandId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `telnyxCampaignId` | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
+| `brandStatus` | APPROVED / PENDING |
+| `campaignStatus` | ACTIVE / PENDING |
+
+---
+
+## Sample Message Templates
+
+These must match exactly what your system will send. Vetting reviewers compare templates against actual traffic.
+
+### Transactional Appointment Reminder
+
+```
+Hi {{first_name}}, this is a reminder from {{business_name}} that your appointment is scheduled for {{date}} at {{time}}. Reply STOP to opt out. Msg & data rates may apply.
+```
+
+### Manual Staff Message
+
+```
+Your appointment with {{business_name}} is confirmed for {{date}}. Need to reschedule? Reply HELP for assistance or call us at {{phone}}. Msg & data rates may apply.
+```
+
+---
+
+## Failure Modes + Retry Guidance
+
+### Vetting Rejection — Brand
+
+| Rejection Reason | Common Fix |
+|-----------------|------------|
+| Legal name mismatch with EIN | Ensure exact EIN name matches legal company name exactly |
+| Website not accessible / missing privacy policy | Add privacy policy page to website before resubmitting |
+| Incomplete primary contact | Provide direct phone and real email (no noreply) |
+| High-risk business vertical | Contact Telnyx support for pre-screening before resubmitting |
+
+### Campaign Rejection
+
+| Rejection Reason | Common Fix |
+|-----------------|------------|
+| Sample messages do not match actual traffic | Update sample messages to match exactly what the system sends |
+| Missing STOP/HELP language | Add compliant STOP/HELP block to sample messages |
+| Volume estimate too low/high | Revise estimate to be realistic |
+| Use case mismatch | Re-select use case that matches actual messaging |
+
+### Re-submission
+
+After fixing the rejection reason, re-submit via the same API endpoint. Telnyx will re-run vetting (typically 24–48 hours).
+
+---
+
+## Cost Summary
+
+### Telnyx Fees (as of 2026)
+
+| Fee Type | Amount | Notes |
+|----------|--------|-------|
+| 10DLC number (monthly) | ~$1.00–$2.50/number | Varies by type and area code |
+| Outbound message | $0.005–$0.015/message | Depends on destination carrier |
+| Inbound message | Included | No charge for received messages |
+| Campaign registration | ~$15–$25 one-time | Per campaign, subject to change |
+
+### Carrier Fees (T-Mobile / AT&T / Verizon)
+
+| Carrier | Outbound Fee | Notes |
+|---------|-------------|-------|
+| T-Mobile | ~$0.005–$0.01/message | Varies by message size (segment) |
+| AT&T | ~$0.005–$0.015/message | Varies by message size (segment) |
+| Verizon | ~$0.005–$0.01/message | Varies by message size (segment) |
+
+**Note**: Carrier fees are subject to change. Check [Telnyx pricing page](https://telnyx.com/pricing) and carrier fee schedules for current rates.
+
+### Example Monthly Cost (Pilot — 500 messages/month)
+
+| Line Item | Cost |
+|-----------|------|
+| 1x 10DLC number | ~$2.00 |
+| 500 outbound messages | ~$5.00–$7.50 |
+| Carrier pass-through | ~$2.50–$7.50 |
+| **Estimated Monthly Total** | **~$9.50–$17.00** |
+
+---
+
+## Rollback / De-provisioning
+
+If the pilot tenant must be de-provisioned:
+
+1. Release the phone number: Telnyx Portal → Phone Numbers → Release.
+2. Archive the campaign: set status to `INACTIVE` via API or console.
+3. Remove DB record: clear `messagingPhoneNumber`, `telnyxMessagingProfileId`, `telnyxCampaignId` fields in the business record.
+4. Brand can remain registered (no harm) but will not be used.
+
+---
+
+## Contacts
+
+| Resource | Contact |
+|----------|---------|
+| Telnyx Support | support@telnyx.com |
+| Telnyx Dashboard | portal.telnyx.com |
+| Internal Engineering | Raise issue in [GRO-106](/GRO/issues/GRO-106) |
+
+---
+
+_Last updated: 2026-05-04_

docs/runbooks/README.md

@@ -0,0 +1,11 @@
+# GroomBook Runbooks
+
+Operational runbooks for GroomBook staff and operators.
+
+| Runbook | Description | Status |
+|---------|-------------|--------|
+| [10DLC Pilot Registration](./10dlc-pilot-registration.md) | Register a pilot grooming business as an A2P 10DLC brand + campaign on Telnyx | Active |
+
+---
+
+_To add a runbook, create a markdown file in this directory and update this table._

packages/db/src/seed.ts

@@ -883,7 +883,6 @@ async function seed() {
   let appointmentCount = 0;
   let invoiceCount = 0;
   let visitLogCount = 0;
-  let paidInvoiceCounter = 0;
 
   // Process in batches per client to keep memory manageable
   const apptBatchSize = 100;
@@ -978,11 +977,8 @@ async function seed() {
 
         const invoiceStatus = rand() < 0.95 ? "paid" as const : "pending" as const;
         const paidAt = invoiceStatus === "paid" ? new Date(endTime.getTime() + randInt(5, 30) * 60 * 1000) : null;
-        paidInvoiceCounter++;
-        const stripePaymentIntentId = invoiceStatus === "paid"
-          ? `pi_test_seed_${String(paidInvoiceCounter).padStart(6, "0")}`
-          : null;
 
+        const stripePaymentIntentId = invoiceStatus === "paid" && rand() < 0.2 ? `pi_test_${uuid().replace(/-/g, "").slice(0, 24)}` : null;
         invoiceBatch.push({
           id: invoiceId,
           appointmentId: apptId,
@@ -1098,16 +1094,14 @@ async function seed() {
       const taxCents = Math.round(effectivePrice * 0.08);
       const totalCents = effectivePrice + taxCents + tipCents;
       const paidAt = new Date(endTime.getTime() + randInt(5, 30) * 60 * 1000);
-      paidInvoiceCounter++;
+      const stripePaymentIntentId = rand() < 0.2 ? `pi_test_${uuid().replace(/-/g, "").slice(0, 24)}` : null;
 
       invoiceBatch.push({
         id: invoiceId, appointmentId: apptId, clientId,
         subtotalCents: effectivePrice, taxCents, tipCents, totalCents,
         status: "paid" as const,
         paymentMethod: pick(["cash", "card", "card", "card", "check"]) as "cash" | "card" | "check",
-        paidAt,
-        stripePaymentIntentId: `pi_test_seed_${String(paidInvoiceCounter).padStart(6, "0")}`,
-        notes: null,
+        paidAt, stripePaymentIntentId, notes: null,
       });
       lineItemBatch.push({
         id: uuid(), invoiceId, description: svc.name, quantity: 1,