CustomerETA

CustomerETA is a SaaS platform that helps service businesses automatically notify customers about upcoming appointments, pickups, deliveries, and scheduled visits.

Businesses can connect their calendar or dispatch system and send customers notifications by text, email, or both.

Status: Pre-implementation. This repository currently contains planning and documentation only. See AGENTS.md for the engineering knowledge base (stack, architecture, conventions, roadmap) and CLAUDE.md for the Claude Code entry point. Pricing/competitive strategy: PRICING.md. Marketing strategy: MARKETING.md. Go-to-market search strategy: SEO-STRATEGY.md. Legal: TERMS.md, PRIVACY.md.

How It Works

1. A business creates an account.
2. The business connects a calendar or dispatch tool.
3. Customer and appointment information is imported.
4. The business chooses when notifications should be sent.
5. CustomerETA automatically sends the notifications.
6. Delivery status and customer responses appear in the dashboard.

Features

• Customer and contact management
• Text notifications with Twilio
• Email notifications with Resend
• Text only, email only, or both
• Google Calendar integration
• Microsoft Outlook integration
• CSV schedule imports
• API and webhook support
• Custom message templates
• Appointment confirmations
• Reschedule requests
• Delivery and failure tracking
• Team accounts and permissions
• Subscription billing
• Notification usage tracking
• Reply-keyword handling (CONFIRM, RESCHEDULE, CANCEL, STOP/START)
• Two-way messaging inbox (read and reply to free-text customer responses, not just keywords)
• Bulk / mass messaging (route delays, weather cancellations, holiday schedules, seasonal recalls)
• Multi-step reminder sequences (e.g. 2 days before → morning-of → 1 hour before)
• Field-service dispatch integrations (Jobber, Housecall Pro, ServiceTitan) alongside Google Calendar and Outlook
• Per-customer notification preferences (channel, quiet hours)
• Audit log / activity history per business
• Delivery analytics (send, delivery, and response rates)
• Webhook signature verification for inbound and outbound events
• Password reset and email verification
• Guided onboarding (connect calendar, verify sender number/domain, import first customers)
• Message template editor with variable substitution and live preview
• Paginated, searchable customer and appointment lists
• Bulk CSV import with per-row validation and an error report
• Billing edge cases: free trial, plan upgrade/downgrade, failed-payment retries and dunning, usage/overage alerts

Example Notifications

CustomerETA can send notifications when:

• An appointment is scheduled
• A visit is coming tomorrow
• A driver is on the way
• A technician is delayed
• A schedule changes
• A visit is canceled
• A service is completed
• A service could not be completed

Who It Is For

CustomerETA can be used by:

• Waste and recycling companies
• Oil pickup companies
• HVAC businesses
• Plumbers
• Electricians
• Pest-control companies
• Cleaning companies
• Landscaping companies
• Delivery companies
• Maintenance companies
• Mobile service providers
• Inspection companies

Non-Functional Requirements

These are treated as first-class requirements, not later cleanup:

• Multi-tenant data isolation — every business's data (customers, appointments, messages) must be strictly scoped and unable to leak across tenants.
• SMS compliance (TCPA / 10DLC) — opt-out (STOP/START) handling, quiet-hour restrictions, and 10DLC registration are required before any production SMS traffic, not optional add-ons.
• Timezone-aware scheduling — appointment times and reminder windows (e.g. "day-before") are computed in the customer's local timezone, not the server's or business's.
• Reliable background processing — notification scheduling, retries, and reminder dispatch run through a background job queue, not inline in request handlers, so a slow provider or crash can't drop a customer notification.
• Duplicate-send prevention — enforced at the job/queue level (idempotency keys), not just application logic.
• Observability — structured logging and error tracking so failed sends and integration errors are visible, not silent.
• Rate limiting — on public API and webhook endpoints to prevent abuse and provider-side throttling.
• Automated testing — unit test coverage is required for notification logic, scheduling logic, and billing/webhook handling before those paths ship; critical user paths (signup, calendar connect, first notification sent) need E2E coverage.
• Input validation at every boundary — all API routes and forms validate input server-side (not just client-side) before it touches the database or a provider call.
• Session and CSRF security — httpOnly/secure/sameSite session cookies; CSRF protection on all state-changing routes.
• Backups and disaster recovery — automated, regularly-tested Postgres backups with point-in-time recovery; a documented restore procedure.
• Accessibility and responsiveness — dashboard targets WCAG 2.1 AA and works on mobile viewports, since technicians/dispatchers may check it in the field.
• Health checks — the app exposes a health endpoint so Railway (and any uptime monitor) can detect and restart unhealthy deployments.

Legal & Compliance

Required before accepting real customer data or sending real notifications:

• Privacy Policy and Terms of Service — published and linked from signup, covering both business users and the end-customers whose contact data is processed. Drafts live in TERMS.md and PRIVACY.md; both require attorney review before publishing.
• CAN-SPAM compliance — every notification email includes an unsubscribe mechanism and a physical mailing address.
• Twilio A2P 10DLC brand and campaign registration — completed before any production SMS traffic; unregistered numbers get throttled or blocked by carriers.
• Data retention and deletion — a defined retention period and a way for a business (or its customers) to request deletion of their data.
• Subprocessor transparency — since CustomerETA processes a business's customers' PII (name, phone, email), maintain a subprocessor list (Twilio, Resend, Stripe, Google/Microsoft, Railway) available to business customers. See PRIVACY.md for the working subprocessor table.

Competitive Positioning

Full comparison and pricing in PRICING.md; marketing strategy in MARKETING.md; search/discovery strategy in SEO-STRATEGY.md. Summary:

• Competitors: Apptoto (apptoto.com) and Appointment Reminder (appointmentreminder.com). Both send SMS/email/voice appointment reminders and target broad verticals (Apptoto: legal/finance/healthcare/education/real estate; Appointment Reminder: healthcare/salons/real estate/therapists). Neither owns field service.
• CustomerETA's wedge: field-service verticals (HVAC, plumbing, waste/recycling, pest control, landscaping, delivery, inspection — see "Who It Is For") served with simpler, flatter pricing. Apptoto's credit pool split across SMS/voice/email with $0.12/credit overages and paid add-ons is the direct contrast; Appointment Reminder's simplicity/speed/risk-reversal playbook is the model we adopt and apply to a field-service reader.
• Deliberate non-features (vs. both competitors): voice-call reminders, an end-customer self-booking portal, in-app payments, post-service review requests, and a native mobile app are out of scope for the MVP and the near roadmap. These are tracked in PRICING.md's "Competitive Feature Gaps to Track" so the include/exclude decision is deliberate, not silent.

Recommended Technology

• Next.js (App Router) + TypeScript
• PostgreSQL with Prisma ORM
• Redis + BullMQ (background jobs / notification queue)
• Auth.js (NextAuth) for authentication
• Tailwind CSS + shadcn/ui for the UI layer
• Twilio (SMS)
• Resend (email)
• Stripe (subscriptions/billing)
• Google Calendar API
• Microsoft Graph API
• Vitest (unit tests) + Playwright (E2E)
• Zod (runtime input validation)
• Sentry (error tracking) + pino (structured logging)
• GitHub Actions (CI: lint + test on every PR)
• Railway (hosting, Postgres, Redis, deploys, staging environment)

Basic Architecture

Calendar or Dispatch Tool
          |
          v
      CustomerETA
          |
   +------+------+
   |             |
   v             v
 Text Message   Email
   |             |
   +------+------+
          |
          v
 Customer Response and Delivery Status

MVP

The first version should include:

• User registration and login
• Business accounts
• Stripe subscriptions
• Customer management
• Google Calendar integration
• CSV schedule imports
• Twilio text messages
• Resend emails
• Day-before reminders (with multi-step sequence support)
• Schedule-change notifications
• Bulk / mass messaging for route and schedule changes
• Confirmation links
• Delivery-status dashboard
• Duplicate-message prevention
• SMS opt-out (STOP/START) handling
• Timezone-aware reminder scheduling
• Background job queue for scheduling and retries
• Basic unit test coverage (notifications, scheduling, billing webhooks)
• Password reset and email verification
• Health check endpoint
• Privacy Policy and Terms of Service pages
• CAN-SPAM-compliant email footer (unsubscribe + mailing address)

Roadmap

Development is sequenced into phases, each building on the last:

1. Foundation — Next.js/TS scaffold, Postgres schema, auth + business accounts, Railway deploy pipeline, test infra, base UI shell
2. Customers & Scheduling — customer/contact management, CSV import, appointment data model
3. Notifications Engine — Twilio SMS + Resend email, templates, multi-step reminder sequences, bulk/mass messaging, confirmation links, duplicate-send prevention, opt-out handling
4. Calendar & Dispatch Integration — Google Calendar first, Microsoft Outlook next, then field-service dispatch tools (Jobber, Housecall Pro, ServiceTitan)
5. Billing — Stripe subscriptions, usage tracking and limits
6. Dashboard & Status — delivery status, two-way messaging inbox, customer responses, team accounts/permissions, audit log
7. API & Webhooks — public API, outbound webhooks, webhook signature verification
8. Launch Readiness — Twilio 10DLC registration, Privacy Policy/Terms of Service live, backup/restore tested, staging environment, monitoring and alerting configured, load/burst testing for reminder spikes (e.g. hundreds of "day-before" sends firing at once)

Environment Variables

DATABASE_URL=
REDIS_URL=

AUTH_SECRET=
APP_URL=

TWILIO_ACCOUNT_SID=
TWILIO_AUTH_TOKEN=
TWILIO_PHONE_NUMBER=

RESEND_API_KEY=
RESEND_FROM_EMAIL=

STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=

GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

MICROSOFT_CLIENT_ID=
MICROSOFT_CLIENT_SECRET=

SENTRY_DSN=

Local Development

pnpm install
pnpm dev

pnpm test   # unit tests (Vitest)
pnpm lint   # ESLint

Product Goal

Connect your schedule and automatically keep customers informed through text and email.

License

Proprietary software. All rights reserved.