create-crm-starter 0.1.0

package/template/extras/customers/_shared/src/app/(dashboard)/customers/page.tsx

@@ -0,0 +1,73 @@
+import Link from 'next/link';
+import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import { Card } from '@/components/ui/card';
+import { getCustomers } from '@/lib/customers/data';
+import { formatCurrency } from '@/lib/utils';
+
+export default async function CustomersPage() {
+  const customers = await getCustomers();
+  return (
+    <div className="space-y-6">
+      <div className="flex items-center justify-between">
+        <div>
+          <h1 className="text-3xl font-bold tracking-tight">Customers</h1>
+          <p className="text-muted-foreground mt-1 text-sm">
+            {customers.length} customer{customers.length === 1 ? '' : 's'}
+          </p>
+        </div>
+        <Button asChild>
+          <Link href="/customers/new">New customer</Link>
+        </Button>
+      </div>
+      <Card className="overflow-hidden">
+        <table className="w-full text-sm">
+          <thead className="bg-muted/50 text-muted-foreground text-xs uppercase">
+            <tr>
+              <th className="px-4 py-3 text-left font-medium">Name</th>
+              <th className="px-4 py-3 text-left font-medium">Tags</th>
+              <th className="px-4 py-3 text-left font-medium">Contact</th>
+              <th className="px-4 py-3 text-right font-medium">LTV</th>
+              <th className="px-4 py-3 text-right font-medium">Balance</th>
+            </tr>
+          </thead>
+          <tbody className="divide-border divide-y">
+            {customers.map((c) => (
+              <tr key={c.id} className="hover:bg-muted/30">
+                <td className="px-4 py-3">
+                  <Link href={`/customers/${c.id}`} className="font-medium hover:underline">
+                    {c.name}
+                  </Link>
+                </td>
+                <td className="px-4 py-3">
+                  <div className="flex flex-wrap gap-1">
+                    {c.tags.map((t) => (
+                      <Badge key={t} variant="secondary" className="text-[10px] uppercase">
+                        {t}
+                      </Badge>
+                    ))}
+                  </div>
+                </td>
+                <td className="text-muted-foreground px-4 py-3">
+                  <div>{c.phones[0]}</div>
+                  <div className="text-xs">{c.emails[0]}</div>
+                </td>
+                <td className="px-4 py-3 text-right font-medium">{formatCurrency(c.lifetimeValue)}</td>
+                <td className="px-4 py-3 text-right">
+                  {c.balanceDue > 0 ? (
+                    <span className="text-destructive font-medium">{formatCurrency(c.balanceDue)}</span>
+                  ) : (
+                    <span className="text-muted-foreground">—</span>
+                  )}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </Card>
+      <p className="text-muted-foreground text-xs">
+        Loaded via <code>src/lib/customers/data.ts</code>. Default is sample data; Drizzle/Convex installers swap in real queries.
+      </p>
+    </div>
+  );
+}

package/template/extras/customers/_shared/src/lib/customers/data.ts

@@ -0,0 +1,15 @@
+/**
+ * Default data-source — returns hardcoded sample data so the UI works
+ * before any DB is connected. Stack-specific installers (Drizzle/Convex)
+ * OVERWRITE this file with real DB queries.
+ */
+import { sampleCustomers } from './sample-data';
+import type { Customer } from './types';
+
+export async function getCustomers(): Promise<Customer[]> {
+  return sampleCustomers;
+}
+
+export async function getCustomer(id: string): Promise<Customer | null> {
+  return sampleCustomers.find((c) => c.id === id) ?? null;
+}

package/template/extras/customers/_shared/src/lib/customers/sample-data.ts

@@ -0,0 +1,67 @@
+import type { Customer } from './types';
+
+// Placeholder data used until the seed module populates the real DB.
+// Replace this import with a server-side query once your DB is wired up.
+export const sampleCustomers: Customer[] = [
+  {
+    id: 'cus_001',
+    name: 'Acme Property Management',
+    phones: ['(555) 010-1100'],
+    emails: ['ops@acmepm.com'],
+    billingAddress: { line1: '120 Main St', city: 'Austin', state: 'TX', postalCode: '78701' },
+    serviceAddresses: [
+      { line1: '120 Main St', city: 'Austin', state: 'TX', postalCode: '78701' },
+      { line1: '845 Oak Ave', city: 'Austin', state: 'TX', postalCode: '78704' },
+    ],
+    tags: ['commercial', 'recurring'],
+    leadSource: 'Referral',
+    lifetimeValue: 1287400,
+    balanceDue: 0,
+    doNotContact: false,
+    notes: '6-month maintenance contract.',
+    createdAt: '2025-09-12T14:21:00Z',
+  },
+  {
+    id: 'cus_002',
+    name: 'Jamie Rodriguez',
+    phones: ['(555) 010-2200'],
+    emails: ['jamie.r@gmail.com'],
+    billingAddress: { line1: '32 Elm Ct', city: 'Round Rock', state: 'TX', postalCode: '78664' },
+    serviceAddresses: [{ line1: '32 Elm Ct', city: 'Round Rock', state: 'TX', postalCode: '78664' }],
+    tags: ['residential', 'vip'],
+    leadSource: 'Google',
+    lifetimeValue: 92500,
+    balanceDue: 24500,
+    doNotContact: false,
+    createdAt: '2026-01-08T10:02:00Z',
+  },
+  {
+    id: 'cus_003',
+    name: 'Mason Hardware Co.',
+    phones: ['(555) 010-3300', '(555) 010-3301'],
+    emails: ['accounts@masonhw.com'],
+    billingAddress: { line1: '2200 Industrial Blvd', city: 'Pflugerville', state: 'TX', postalCode: '78660' },
+    serviceAddresses: [],
+    tags: ['commercial'],
+    leadSource: 'Trade show',
+    lifetimeValue: 458200,
+    balanceDue: 152000,
+    doNotContact: false,
+    createdAt: '2025-11-22T09:30:00Z',
+  },
+  {
+    id: 'cus_004',
+    name: 'Priya Patel',
+    phones: ['(555) 010-4400'],
+    emails: ['priya.patel@example.com'],
+    billingAddress: { line1: '78 Cedar Ln', city: 'Cedar Park', state: 'TX', postalCode: '78613' },
+    serviceAddresses: [{ line1: '78 Cedar Ln', city: 'Cedar Park', state: 'TX', postalCode: '78613' }],
+    tags: ['residential', 'lead'],
+    leadSource: 'Yelp',
+    lifetimeValue: 0,
+    balanceDue: 0,
+    doNotContact: false,
+    notes: 'Requested estimate for water heater install.',
+    createdAt: '2026-05-01T16:11:00Z',
+  },
+];

package/template/extras/customers/_shared/src/lib/customers/types.ts

@@ -0,0 +1,31 @@
+export type CustomerTag = 'vip' | 'recurring' | 'commercial' | 'residential' | 'lead';
+
+export interface Address {
+  line1: string;
+  line2?: string;
+  city: string;
+  state: string;
+  postalCode: string;
+}
+
+export interface Customer {
+  id: string;
+  name: string;
+  phones: string[];
+  emails: string[];
+  billingAddress: Address;
+  serviceAddresses: Address[];
+  tags: CustomerTag[];
+  leadSource?: string;
+  lifetimeValue: number;
+  balanceDue: number;
+  doNotContact: boolean;
+  notes?: string;
+  createdAt: string; // ISO
+}
+
+export function formatAddress(a: Address): string {
+  const parts = [a.line1, a.line2, `${a.city}, ${a.state} ${a.postalCode}`].filter(Boolean);
+  return parts.join(', ');
+}
+

package/template/extras/customers/convex/convex/customers.ts

@@ -0,0 +1,52 @@
+import { v } from 'convex/values';
+import { mutation, query } from './_generated/server';
+
+/**
+ * Convex queries + mutations for customers. After `npx convex dev` runs,
+ * these are exposed at `api.customers.list`, `api.customers.getById`,
+ * `api.customers.create`.
+ */
+
+const addressShape = v.object({
+  line1: v.string(),
+  line2: v.optional(v.string()),
+  city: v.string(),
+  state: v.string(),
+  postalCode: v.string(),
+});
+
+export const list = query({
+  args: {},
+  handler: async (ctx: any) => {
+    return await ctx.db.query('customers').order('desc').take(100);
+  },
+});
+
+export const getById = query({
+  args: { id: v.id('customers') },
+  handler: async (ctx: any, args: { id: any }) => {
+    return await ctx.db.get(args.id);
+  },
+});
+
+export const create = mutation({
+  args: {
+    name: v.string(),
+    phones: v.array(v.string()),
+    emails: v.array(v.string()),
+    billingAddress: addressShape,
+    serviceAddresses: v.array(addressShape),
+    tags: v.array(v.string()),
+    leadSource: v.optional(v.string()),
+    notes: v.optional(v.string()),
+  },
+  handler: async (ctx: any, args: any) => {
+    return await ctx.db.insert('customers', {
+      ...args,
+      lifetimeValue: 0,
+      balanceDue: 0,
+      doNotContact: false,
+      createdAt: Date.now(),
+    });
+  },
+});

package/template/extras/customers/convex/src/lib/customers/data.ts

@@ -0,0 +1,64 @@
+import 'server-only';
+import { fetchQuery } from 'convex/nextjs';
+import { api } from '../../../convex/_generated/api';
+import { sampleCustomers } from './sample-data';
+import type { Customer, CustomerTag } from './types';
+
+const convexConfigured = (() => {
+  const url = process.env.NEXT_PUBLIC_CONVEX_URL;
+  return typeof url === 'string' && url.startsWith('http') && !url.includes('placeholder');
+})();
+
+interface RawCustomer {
+  _id: string;
+  name: string;
+  phones: string[];
+  emails: string[];
+  billingAddress: Customer['billingAddress'];
+  serviceAddresses: Customer['serviceAddresses'];
+  tags: string[];
+  leadSource?: string;
+  lifetimeValue: number;
+  balanceDue: number;
+  doNotContact: boolean;
+  notes?: string;
+  createdAt: number;
+}
+
+function toCustomer(row: RawCustomer): Customer {
+  return {
+    id: row._id,
+    name: row.name,
+    phones: row.phones,
+    emails: row.emails,
+    billingAddress: row.billingAddress,
+    serviceAddresses: row.serviceAddresses,
+    tags: row.tags as CustomerTag[],
+    leadSource: row.leadSource,
+    lifetimeValue: row.lifetimeValue,
+    balanceDue: row.balanceDue,
+    doNotContact: row.doNotContact,
+    notes: row.notes,
+    createdAt: new Date(row.createdAt).toISOString(),
+  };
+}
+
+export async function getCustomers(): Promise<Customer[]> {
+  if (!convexConfigured) return sampleCustomers;
+  try {
+    const rows = (await fetchQuery(api.customers.list)) as RawCustomer[] | null;
+    return (rows ?? []).map(toCustomer);
+  } catch {
+    return sampleCustomers;
+  }
+}
+
+export async function getCustomer(id: string): Promise<Customer | null> {
+  if (!convexConfigured) return sampleCustomers.find((c) => c.id === id) ?? null;
+  try {
+    const row = (await fetchQuery(api.customers.getById, { id })) as RawCustomer | null;
+    return row ? toCustomer(row) : null;
+  } catch {
+    return sampleCustomers.find((c) => c.id === id) ?? null;
+  }
+}

package/template/extras/customers/drizzle/src/app/(dashboard)/customers/new/page.tsx

@@ -0,0 +1,82 @@
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Label } from '@/components/ui/label';
+import { createCustomer } from '@/lib/customers/actions';
+
+export default function NewCustomerPage() {
+  return (
+    <form action={createCustomer} className="mx-auto max-w-2xl space-y-6">
+      <h1 className="text-3xl font-bold tracking-tight">New customer</h1>
+      <Card>
+        <CardHeader>
+          <CardTitle>Contact</CardTitle>
+          <CardDescription>Required fields are marked with *</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="name">Name *</Label>
+            <Input id="name" name="name" required />
+          </div>
+          <div className="grid grid-cols-1 gap-3 sm:grid-cols-2">
+            <div className="space-y-2">
+              <Label htmlFor="phone">Phone *</Label>
+              <Input id="phone" name="phone" type="tel" required />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="email">Email</Label>
+              <Input id="email" name="email" type="email" />
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader>
+          <CardTitle>Billing address</CardTitle>
+          <CardDescription>Also used as the default service address.</CardDescription>
+        </CardHeader>
+        <CardContent className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="line1">Street *</Label>
+            <Input id="line1" name="line1" required />
+          </div>
+          <div className="grid grid-cols-3 gap-3">
+            <div className="space-y-2">
+              <Label htmlFor="city">City *</Label>
+              <Input id="city" name="city" required />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="state">State *</Label>
+              <Input id="state" name="state" maxLength={2} required />
+            </div>
+            <div className="space-y-2">
+              <Label htmlFor="postalCode">ZIP *</Label>
+              <Input id="postalCode" name="postalCode" required />
+            </div>
+          </div>
+        </CardContent>
+      </Card>
+      <Card>
+        <CardHeader><CardTitle>Optional</CardTitle></CardHeader>
+        <CardContent className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="leadSource">Lead source</Label>
+            <Input id="leadSource" name="leadSource" placeholder="Google, Referral, Yelp..." />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="notes">Notes</Label>
+            <textarea
+              id="notes"
+              name="notes"
+              rows={3}
+              className="border-input bg-background focus-visible:ring-ring flex w-full rounded-md border px-3 py-2 text-sm focus-visible:outline-none focus-visible:ring-2"
+            />
+          </div>
+        </CardContent>
+      </Card>
+      <div className="flex justify-end gap-3">
+        <Button type="submit">Create customer</Button>
+      </div>
+    </form>
+  );
+}

package/template/extras/customers/drizzle/src/db/schema/customers.ts

@@ -0,0 +1,34 @@
+import { boolean, integer, jsonb, pgTable, text, timestamp, uuid } from 'drizzle-orm/pg-core';
+
+interface AddressJson {
+  line1: string;
+  line2?: string;
+  city: string;
+  state: string;
+  postalCode: string;
+}
+
+export const customers = pgTable('customers', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  name: text('name').notNull(),
+  phones: jsonb('phones').$type<string[]>().notNull().default([]),
+  emails: jsonb('emails').$type<string[]>().notNull().default([]),
+  billingAddress: jsonb('billing_address').$type<AddressJson>().notNull(),
+  serviceAddresses: jsonb('service_addresses').$type<AddressJson[]>().notNull().default([]),
+  tags: jsonb('tags').$type<string[]>().notNull().default([]),
+  leadSource: text('lead_source'),
+  lifetimeValue: integer('lifetime_value').notNull().default(0), // cents
+  balanceDue: integer('balance_due').notNull().default(0),       // cents
+  doNotContact: boolean('do_not_contact').notNull().default(false),
+  notes: text('notes'),
+  // Customer-portal magic-link token. Nullable for back-compat with rows
+  // seeded before the portal module existed; new rows get one via
+  // createCustomer (32 hex chars). The /portal/[token] route uses this
+  // as the sole credential — same security model as HCP magic links.
+  publicToken: text('public_token').unique(),
+  createdAt: timestamp('created_at').notNull().defaultNow(),
+  updatedAt: timestamp('updated_at').notNull().defaultNow(),
+});
+
+export type CustomerRow = typeof customers.$inferSelect;
+export type NewCustomer = typeof customers.$inferInsert;

package/template/extras/customers/drizzle/src/lib/customers/actions.ts

@@ -0,0 +1,67 @@
+'use server';
+
+import crypto from 'node:crypto';
+import { redirect } from 'next/navigation';
+import { revalidatePath } from 'next/cache';
+import { db } from '@/db/client';
+import { customers } from '@/db/schema';
+
+export interface CreateCustomerInput {
+  name: string;
+  phone: string;
+  email: string;
+  line1: string;
+  city: string;
+  state: string;
+  postalCode: string;
+  leadSource?: string;
+  notes?: string;
+}
+
+export type CreateCustomerResult =
+  | { ok: true; id: string }
+  | { ok: false; error: string };
+
+/**
+ * Server action — creates a customer in Postgres and redirects to the
+ * detail page. Used by `app/(dashboard)/customers/new/page.tsx`.
+ */
+export async function createCustomer(formData: FormData): Promise<void> {
+  const get = (key: string) => (formData.get(key) ?? '').toString().trim();
+
+  const name = get('name');
+  const phone = get('phone');
+  const email = get('email');
+  const line1 = get('line1');
+  const city = get('city');
+  const state = get('state');
+  const postalCode = get('postalCode');
+  const leadSource = get('leadSource') || undefined;
+  const notes = get('notes') || undefined;
+
+  if (!name || !phone || !line1 || !city || !state || !postalCode) {
+    throw new Error('Missing required fields');
+  }
+
+  const [row] = await db
+    .insert(customers)
+    .values({
+      name,
+      phones: [phone],
+      emails: email ? [email] : [],
+      billingAddress: { line1, city, state, postalCode },
+      serviceAddresses: [{ line1, city, state, postalCode }],
+      tags: [],
+      leadSource,
+      lifetimeValue: 0,
+      balanceDue: 0,
+      doNotContact: false,
+      notes,
+      // Magic-link token for /portal/[token] access.
+      publicToken: crypto.randomBytes(16).toString('hex'),
+    })
+    .returning({ id: customers.id });
+
+  revalidatePath('/customers');
+  redirect(`/customers/${row.id}`);
+}

package/template/extras/customers/drizzle/src/lib/customers/data.ts

@@ -0,0 +1,34 @@
+import { eq, desc } from 'drizzle-orm';
+import { db } from '@/db/client';
+import { customers as customersTable } from '@/db/schema';
+import type { Customer, CustomerTag } from './types';
+
+type Row = typeof customersTable.$inferSelect;
+
+function toCustomer(row: Row): Customer {
+  return {
+    id: row.id,
+    name: row.name,
+    phones: row.phones,
+    emails: row.emails,
+    billingAddress: row.billingAddress,
+    serviceAddresses: row.serviceAddresses,
+    tags: row.tags as CustomerTag[],
+    leadSource: row.leadSource ?? undefined,
+    lifetimeValue: row.lifetimeValue,
+    balanceDue: row.balanceDue,
+    doNotContact: row.doNotContact,
+    notes: row.notes ?? undefined,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
+
+export async function getCustomers(): Promise<Customer[]> {
+  const rows = await db.select().from(customersTable).orderBy(desc(customersTable.createdAt));
+  return rows.map(toCustomer);
+}
+
+export async function getCustomer(id: string): Promise<Customer | null> {
+  const [row] = await db.select().from(customersTable).where(eq(customersTable.id, id)).limit(1);
+  return row ? toCustomer(row) : null;
+}

package/template/extras/db-convex/convex/_generated/README.md

@@ -0,0 +1,13 @@
+# Convex generated files
+
+This directory is **auto-managed by Convex**. The files here ship as
+permissive stubs so the project type-checks before you connect a
+deployment. As soon as you run:
+
+```bash
+pnpm convex:dev
+```
+
+Convex regenerates real `.d.ts` + `.js` files derived from
+`convex/schema.ts`. Don't edit these manually — your changes will be
+overwritten on every `convex dev` cycle.

package/template/extras/db-convex/convex/_generated/api.d.ts

@@ -0,0 +1,8 @@
+/* eslint-disable */
+/**
+ * Placeholder stub. Replaced by real, schema-derived `api` and `internal`
+ * objects when you run `npx convex dev`. Permissive `any` here means user
+ * code compiles before the first deployment exists.
+ */
+export declare const api: any;
+export declare const internal: any;

package/template/extras/db-convex/convex/_generated/api.js

@@ -0,0 +1,12 @@
+/* eslint-disable */
+// Placeholder runtime stub. Overwritten by `npx convex dev`.
+// Using a Proxy so any chained access (api.customers.list) returns
+// something callable that resolves to null at runtime — keeps server
+// components from crashing before the deployment exists.
+const makeProxy = () =>
+  new Proxy(() => null, {
+    get() { return makeProxy(); },
+    apply() { return Promise.resolve(null); },
+  });
+export const api = makeProxy();
+export const internal = makeProxy();

package/template/extras/db-convex/convex/_generated/dataModel.d.ts

@@ -0,0 +1,9 @@
+/* eslint-disable */
+/**
+ * Placeholder stub. Replaced by schema-derived types when you run
+ * `npx convex dev`.
+ */
+export type Doc<TableName extends string = string> = any;
+export type Id<TableName extends string = string> = string & { __tableName?: TableName };
+export type DataModel = any;
+export type TableNames = string;

package/template/extras/db-convex/convex/_generated/server.d.ts

@@ -0,0 +1,18 @@
+/* eslint-disable */
+/**
+ * Placeholder stub. Replaced by real type declarations when you run
+ * `npx convex dev` for the first time. These permissive types just make
+ * `tsc --noEmit` pass before the deployment exists.
+ */
+export declare const query: any;
+export declare const mutation: any;
+export declare const internalQuery: any;
+export declare const internalMutation: any;
+export declare const action: any;
+export declare const internalAction: any;
+export declare const httpAction: any;
+export declare const httpRouter: any;
+export declare const cronJobs: any;
+export type QueryCtx = any;
+export type MutationCtx = any;
+export type ActionCtx = any;

package/template/extras/db-convex/convex/_generated/server.js

@@ -0,0 +1,12 @@
+/* eslint-disable */
+// Placeholder runtime stub. Overwritten by `npx convex dev`.
+const noop = () => ({ args: undefined, handler: undefined });
+export const query = noop;
+export const mutation = noop;
+export const internalQuery = noop;
+export const internalMutation = noop;
+export const action = noop;
+export const internalAction = noop;
+export const httpAction = noop;
+export const httpRouter = () => ({ route: () => {} });
+export const cronJobs = () => ({ daily: () => {}, weekly: () => {}, monthly: () => {} });

package/template/extras/db-convex/convex/auth.config.ts

@@ -0,0 +1,17 @@
+/**
+ * Convex auth config — pulls the JWT issuer URL from your Clerk
+ * application. Find it at https://dashboard.clerk.com → JWT Templates →
+ * "convex" (create one if it doesn't exist), then set:
+ *
+ *   CLERK_JWT_ISSUER_DOMAIN=https://<your-frontend-api>.clerk.accounts.dev
+ *
+ * in your Convex deployment (`npx convex env set ...`).
+ */
+export default {
+  providers: [
+    {
+      domain: process.env.CLERK_JWT_ISSUER_DOMAIN ?? '',
+      applicationID: 'convex',
+    },
+  ],
+};

package/template/extras/db-convex/convex/schema.ts

@@ -0,0 +1,28 @@
+import { defineSchema, defineTable } from 'convex/server';
+import { v } from 'convex/values';
+
+/**
+ * Top-level Convex schema. Each feature module adds its own tables
+ * via `convex/<module>.ts` files that re-export from this object.
+ *
+ * For Phase 2 we only define `users` (synced from Clerk on first call).
+ * Later phases extend this with customers, jobs, estimates, invoices, etc.
+ */
+export default defineSchema({
+  users: defineTable({
+    clerkId: v.string(),
+    email: v.string(),
+    firstName: v.optional(v.string()),
+    lastName: v.optional(v.string()),
+    role: v.union(
+      v.literal('admin'),
+      v.literal('dispatcher'),
+      v.literal('technician'),
+      v.literal('csr'),
+      v.literal('sales'),
+      v.literal('accountant'),
+    ),
+    createdAt: v.number(),
+  }).index('by_clerk_id', ['clerkId']),
+  // <crm-starter:tables>
+});