Davies CXsmart — Developer Guide
Davies CXsmart is a greenfield rebuild of the Davies/ServiceTick "Voice of the Customer" platform on a modern Cloudflare + Postgres stack. This guide is for engineers building, extending or operating the platform. If you're a day-to-day user of the app, see the User Guide instead.
The stack at a glance
| Layer | Technology |
|---|---|
| Front end | Vite + React + TypeScript + Tailwind CSS v4 (SPA) on Cloudflare Workers (Static Assets) |
| Public survey runtime | Respondent survey completion — a client-rendered route in the same SPA |
| API / back end | Cloudflare Workers (Hono), ports/adapters (hexagonal) |
| Database | Neon Postgres via Hyperdrive — one connection per request; RLS default-deny + FORCE |
| Auth | Clerk (sole identity provider) behind an Identity port |
| Email / SMS / IVR | Resend + Twilio, behind channel ports |
| AI / STT | Gemini, behind an AI port |
| Async / scheduled | Cloudflare Queues + Cron Triggers |
Where to start
- Run it locally: Getting started.
- Understand the shape: Architecture overview and Ports & adapters — everything hangs off the hexagonal seams.
- Data & tenancy: Schema and Multi-tenancy & RLS — read this before writing any query.
Map of the guide
| Area | What it covers |
|---|---|
| Architecture | Request lifecycle, hexagonal seams, monorepo packages |
| Data model | Postgres schemas, RLS multi-tenancy, migrations |
| API | Hono routes, auth, error envelope, rate limiting |
| Public API | API keys & scopes, inbound/outbound webhooks |
| Channels | Email, SMS/IVR, short URLs, tracking |
| Survey runtime | Capture pipeline, completion runtime |
| AI & verbatim | Gemini adapter, sentiment, topic coding, prompts |
| Jobs | Queues + scheduled cron |
| Frontend | SPA architecture, filters, dashboard widgets |
| Testing | Vitest + the in-memory database fake, the green gate |
| Deployment | Cloudflare topology, configuration, observability |
| Contributing | Conventions, the gate, branch model |
:::info Auth is Clerk
The platform authenticates via Clerk as its sole identity provider — identity lives in Clerk, not
the database, which keeps the application's Postgres portable across providers. A Clerk Organization
is a VoC tenant / client account. The API only ever verifies the Clerk session JWT (via
@clerk/backend) behind the same IdentityProvider port. See
Authentication & authorization and CLERK_MIGRATION.md at the repo root.
:::