Harbor Pilot CRM

Harbor Pilot CRM is a local-first CRM workspace built from the original Deep Sea design package. The primary product is now the protected workspace routes, not the imported HTML screen library.

The legacy 49-screen design package still exists under /s for reference while features are converted into real routes and database-backed workflows.

User Documentation

• Setup Guide
• HarborPilot User Guide

Quick Start

HarborPilot installs and builds without private secrets, but the working CRM requires your own Clerk app and Postgres database.

npm ci
cp .env.example .env.local
# fill in .env.local
node --env-file=.env.local ./node_modules/.bin/tsx scripts/migrate.ts
npm run dev

Open http://localhost:3000, sign in through Clerk, then create the first contact. See the Setup Guide for the required provider setup.

Stack

• Next.js 15 App Router, React 19, TypeScript
• Tailwind CSS 3 for the app shell and workspace pages
• Clerk authentication and user webhooks
• Stripe checkout, customer portal, and subscription webhooks
• Drizzle ORM on Neon Postgres
• Deployable to any Node.js/Next.js host after environment variables and migrations are configured.

Primary Routes

• / - public entry page
• /dashboard - command center
• /contacts - contact list, filtering, and create form
• /contacts/[id] - contact profile, edit form, linked opportunities, tasks, and activity
• /pipeline - opportunity board with stage updates
• /calendar - task queue and completion flow
• /messages - communication/activity timeline
• /automation - automation readiness
• /integrations - provider configuration status
• /audit - database-backed workspace action log
• /projects - project delivery records linked to contacts
• /documents - document metadata linked to contacts/projects
• /billing - Stripe checkout and customer portal actions
• /settings - workspace/system links
• /s and /s/[slug] - imported Deep Sea design reference library
• /api/health - public operational health check

All workspace routes are protected by Clerk middleware. The public page and auth/webhook endpoints are intentionally public.

Data Model

The current app-owned tables are namespaced to avoid colliding with the broader existing Neon schema:

• harbor_contacts
• harbor_opportunities
• harbor_tasks
• harbor_activities
• harbor_audit_events
• harbor_projects
• harbor_documents

Existing shared tables remain:

• users - Clerk user records
• subscriptions - Stripe subscription records

Development

npm install
npm run dev
npm run build
npm run typecheck
npm run lint
npm run connections
npm run smoke
npm run smoke:workflow

For local dev, bind to 0.0.0.0 if testing through both localhost and 127.0.0.1:

npm run dev -- --port 3020 --hostname 0.0.0.0

Migrations

Generate migrations after schema changes:

npx drizzle-kit generate

Apply migrations using Node's env-file loader. Do not use source .env.local; the database URL can contain shell-sensitive characters.

node --env-file=.env.local ./node_modules/.bin/tsx scripts/migrate.ts

Verify live table shape:

node --env-file=.env.local ./node_modules/.bin/tsx scripts/verify-db.ts

Important Boundaries

• Do not edit screens/<slug>/code.html unless explicitly converting or fixing a design reference screen.
• Do not build new product functionality by mutating the imported HTML mockups. Add real routes, components, server actions, and database-backed records.
• Do not add sample/demo data to make pages look full. Empty states should stay honest until real workspace records exist.
• Do not print or commit .env.local values.
• Keep external actions explicit and auditable.

Current Verification Gates

Before pushing/deploying a working slice:

npm run build
npm run typecheck
npm run lint

Then smoke-test:

• npm run smoke -- http://localhost:3020
• npm run smoke:workflow
• npm run connections
• / returns 200
• /api/health returns 200 with status: ok
• protected routes redirect to /sign-in
• Coolify image hash matches the pushed commit
• public production URL returns 200