Build your own lead management starter (a personal HighLevel)

Build a Next.js 15 lead-management starter called lead-starter in this empty repository. Requirements:
- Next.js 15 with TypeScript and the App Router, strict mode on
- Drizzle ORM connecting to PostgreSQL 16, connection string read from DATABASE_URL in .env
- A docker-compose.yml that starts PostgreSQL with a named volume so data survives restarts
- One documented startup path in the README: docker compose up -d then npm run dev serving a page at localhost:3000
- .env.example listing DATABASE_URL and EMAIL_PROVIDER_API_KEY, with .env covered by .gitignore
- A health endpoint at /api/health returning { "status": "ok" }
Out of scope: authentication, CSS frameworks, CI pipelines.
Pain warning: Next.js 15 and React type versions drift often, pin exact versions in package.json so a fresh install reproduces your working state.

Add the database schema to lead-starter using Drizzle ORM against the PostgreSQL service from docker-compose.yml. Requirements:
- Tables: companies, contacts with company_id, deals with contact_id, stage, and value, notes, tasks with due date and done flag, and pipeline_stages with a position column
- Seed five stages exactly: New, Contacted, Proposal, Won, Lost
- An npm run seed script inserting two companies, six contacts, four deals spread across stages, and three tasks due soon
- Apply the schema with drizzle-kit push, then verify psql \c leadstarter \dt lists all six tables
- An index on contacts.email plus a helper that finds duplicates by lowercase email match
- Store timestamps as UTC in every table
Keep migration files in ./drizzle. Out of scope: user accounts, row permissions, audit tables.
Pain warning: due dates will bite you across timezones later, deciding on UTC storage now saves a painful migration.

Add a public inquiry form at /inquire in lead-starter. Requirements:
- Fields for name, email, optional phone, and message, plus a required consent checkbox storing the timestamp and consent text version in a consents table
- Spam protection using a honeypot field, an invisible input bots fill, plus a minimum 3-second fill time, with no external captcha service
- Server-side validation with zod, invalid input re-rendering with inline messages, success rendering a plain confirmation state
- On valid submit, POST to /api/leads creates a contact at stage New, opens a deal, and stores the message as a note, matching the step-two schema
- Rate limit the endpoint to 5 submissions per IP per hour with an in-memory counter
Out of scope: file uploads, embeddable form builders, analytics scripts.
Pain warning: when the honeypot trips, return a normal-looking success response instead of an error, otherwise bots learn they were caught.

Add the daily-use views to lead-starter, built on the tables created earlier. Requirements:
- /contacts with search by name or email, pagination at 25 rows, and a detail page showing notes and deals
- /pipeline showing deals grouped by the five seeded stages with a stage-change action persisting the update
- /today listing tasks due today or overdue with a done toggle stamping completed_at
- A duplicate finder comparing lowercase emails and a merge action repointing deals and notes to the surviving contact inside one transaction
- An activity_log row written on every mutation with actor, entity, action, and timestamp
Out of scope: drag-and-drop libraries, board animations, bulk edit.
Pain warning: a merge that moves deals but not notes corrupts your data silently, wrap the whole merge in a single database transaction and test it twice.

Add manual email sending to lead-starter using the provider credentials in EMAIL_PROVIDER_API_KEY from the earlier setup step. Requirements:
- An emails table logging every attempt with contact_id, template name, status, provider_message_id, and error text
- Three editable templates in ./templates as markdown files supporting {{first_name}} style tokens
- A compose page that picks one template, previews it against one chosen contact, then sends to a filtered segment of subscribed contacts only
- An /unsubscribe/[contactId] page setting subscribed to false, checked by a suppression lookup before every send
- A rate limit of 10 messages per minute and one automatic retry on transient provider failures, both visible in the log
Out of scope: scheduled sends, A/B testing, drag-and-drop HTML editors.
Pain warning: provider sandbox keys accept sends but deliver nothing, so test the complete path with one real address you own before any batch.

Add import and export to lead-starter so data stays portable. Requirements:
- Export endpoints producing contacts.csv and deals.csv with column order documented in README_IMPORT.md
- An import page accepting a CSV upload, showing a field-mapping preview against existing columns, then creating or updating contacts matched by lowercase email
- An import report with counts of created, updated, and skipped rows plus row numbers and reasons for rejects
- An interaction timeline on each contact page merging notes, sent emails, form submissions, and stage changes, newest first
- Parse CSVs with papaparse, not string splitting
Out of scope: Excel formats, Google Sheets sync, webhook ingestion.
Pain warning: quoted fields containing commas break naive parsers and corrupt imports, which is exactly why papaparse is required here.

Harden lead-starter with tests and a backup routine. Requirements:
- Vitest unit tests covering duplicate detection and the unsubscribe suppression check
- One Playwright end-to-end test walking submit form, contact appears, task toggled done, unsubscribed contact blocked from sending
- npm run backup writing pg_dump output to ./backups/YYYY-MM-DD-HHMM.sql.gz
- npm run restore loading one of those files into a fresh database, verified by counting contacts afterward
- README sections for setup, architecture, where data lives, backup and restore, and the sending-domain setup completed earlier
Out of scope: deploy pipelines, monitoring dashboards, load testing.
Pain warning: an untested restore is not a backup, run the restore against a scratch database today while the stakes are zero.