A runnable multi-tenant inquiry, follow-up and appointment workspace for nonmedical beauty salons. Next.js/React, strict TypeScript, Prisma/PostgreSQL, Better Auth, Redis/BullMQ and a separately runnable worker.
P0 is still in progress. See implementation status, feature traceability, test evidence and limitations. No production deployment or external customer messaging has been performed.
Use Node 24 LTS, npm and Docker Compose. PostgreSQL 17 and Redis 7 are the development dependencies.
npm ci
cp .env.example .env
# Set a random BETTER_AUTH_SECRET, e.g. using openssl rand -base64 48.
docker compose up -d db redis
npm run db:generate
npm run db:migrate
npm run db:seed
npm run dev
# In a second terminal:
npm run workerOpen http://localhost:3000. Register, read the verification link in the private .mail/ folder, sign in and create a workspace. Add a service, enable eligible staff and working hours, then share the Inquiry form link. No default password or customer records are seeded. The onboarding transaction seeds six lead statuses and operational email templates. Seed checks DB connectivity only.
The complete local workflow is: inquiry → durable contact/lead/task/message/outbox → staff follow-up → conflict-protected booking → recorded confirmation → real cohort conversion. Local spool records are labeled SPOOLED, never DELIVERED. The app works without an AI provider.
The execution host has an already-configured untracked .env using isolated PostgreSQL on port 55432; keep it for this workspace. See the runbook for native DB startup and container alternatives.
Create dedicated disposable databases ending _test; set TEST_DATABASE_URL and E2E_DATABASE_URL. Do not use a customer database. E2E uses an isolated Redis database and starts its own app and worker on localhost:3100.
docker compose exec db createdb -U leadflow leadflow_test
docker compose exec db createdb -U leadflow leadflow_e2e_test
npx tsx scripts/test-db.ts
npx tsx scripts/test-db.ts --e2e
npx playwright install chromium
npm run format:check
npm run lint
npm run typecheck
npm test
npm run test:integration
npm run build
npm run test:e2eIf Chromium download is unavailable, set PLAYWRIGHT_CHROMIUM_EXECUTABLE to an installed compatible Chrome/Chromium binary. Tests add synthetic fixtures to disposable DBs; they do not drop arbitrary databases. See TEST_REPORT for actual executed results and failed attempts.
- Local email: MAIL_TRANSPORT=spool (development only), private
.mail/directory, no external sends. - Real email adapter: Resend, requires explicit MAIL_TRANSPORT=resend, RESEND_API_KEY and verified MAIL_FROM. Webhook requires RESEND_WEBHOOK_SECRET. External delivery remains unverified and requires authorization before sending customer messages.
- Auth: BETTER_AUTH_URL is the canonical trusted origin and BETTER_AUTH_SECRET must be high entropy. Production requires HTTPS.
- API ingestion: workspace-scoped, hashed, expiring keys via Settings;
POST /api/ingest/v1/leadswith Bearer auth and Idempotency-Key. API contracts. - Operations:
/api/healthliveness,/api/readyDB/Redis readiness. Review dead events through owner API and worker logs. Recovery, deployment, backup/restore. - Container recipe: Dockerfile plus
compose.app.yaml; no production environment is created automatically. Production rejects the spool mail transport. - CI:
.github/workflows/ci.ymldefines local-equivalent checks and browser testing; remote CI execution is not claimed.
No billing, autonomous AI, external calendars, SMS, WhatsApp or medical workflows. Public legal pages are marked drafts requiring qualified review. Original GPL license retained.