diff --git a/.planning/phases/09-client-property-address/09-RESEARCH.md b/.planning/phases/09-client-property-address/09-RESEARCH.md new file mode 100644 index 0000000..10f8edd --- /dev/null +++ b/.planning/phases/09-client-property-address/09-RESEARCH.md @@ -0,0 +1,428 @@ +# Phase 9: Client Property Address - Research + +**Researched:** 2026-03-21 +**Domain:** Drizzle ORM schema migration, Next.js server actions, React form patterns, prepare-document pipeline +**Confidence:** HIGH + + +## Phase Requirements + +| ID | Description | Research Support | +|----|-------------|-----------------| +| CLIENT-04 | Agent can add a property address to a client profile | DB column `property_address TEXT` nullable on `clients` table; extend `ClientModal` form + `updateClient` / `createClient` server actions to accept the new field; display on `ClientProfileClient` profile card | +| CLIENT-05 | Client property address is available as a pre-fill data source alongside client name | `DocumentPage` already fetches client data (name, email) for `PreparePanel`; extend that select to include `propertyAddress`; pass it to `PreparePanel` as a new prop; `PreparePanel` pre-seeds `textFillData` state with `{ propertyAddress: value }` so it flows into the existing prepare pipeline untouched | + + +--- + +## Summary + +Phase 9 is a narrow, well-understood CRUD extension. The `clients` table needs one new nullable TEXT column (`property_address`). No new tables, no new libraries, no new API routes. Every layer that must change is small and clearly bounded. + +The existing prepare-document pipeline (`/api/documents/[id]/prepare` → `preparePdf()`) already accepts `textFillData: Record` and stamps any key/value pair onto the PDF. Property address simply becomes one more key in that map. No changes to the pipeline itself are needed. + +The only non-trivial design decision is where to inject the pre-fill: the `DocumentPage` server component already fetches client name and email for `PreparePanel`; it must be extended to also fetch `propertyAddress` and pass it as a prop. `PreparePanel` initializes `textFillData` state — it should seed a `propertyAddress` key from the prop when the value is non-empty, so the field arrives pre-populated without agent typing. + +**Primary recommendation:** Add `propertyAddress` as a nullable TEXT column via `drizzle-kit generate` + `drizzle-kit migrate`, extend the Zod schema + server actions + `ClientModal` in one atomic pass, display on the profile card, and pre-seed `PreparePanel` state from the fetched client data. + +--- + +## Standard Stack + +### Core +| Library | Version | Purpose | Why Standard | +|---------|---------|---------|--------------| +| drizzle-orm | ^0.45.1 (installed) | ORM and schema definition | Already the project ORM; schema changes happen here | +| drizzle-kit | ^0.31.10 (installed) | Migration generation and running | Generates SQL from schema diff; `db:generate` + `db:migrate` scripts already defined | +| zod | ^4.3.6 (installed) | Server action input validation | Already used in `clients.ts` action for name + email validation | +| next | 16.2.0 (installed) | Server actions, `revalidatePath`, `useActionState` | All client management already uses this pattern | + +### Supporting +| Library | Version | Purpose | When to Use | +|---------|---------|---------|-------------| +| react `useActionState` | React 19 (installed) | Form state management in client modal | Already used in `ClientModal.tsx` | + +### Alternatives Considered +| Instead of | Could Use | Tradeoff | +|------------|-----------|----------| +| Single TEXT column for full address | Structured columns (street, city, state, zip) | Single TEXT is explicitly called for in requirements as "structured data for AI pre-fill" — AI reads the whole string; structured parsing adds complexity with no benefit in v1.1 | +| `ALTER TABLE` raw SQL migration | `drizzle-kit generate` | Use drizzle-kit — it keeps `_journal.json` and snapshots in sync; raw SQL bypasses snapshot tracking and breaks future diffs | + +**Installation:** No new packages needed. All dependencies already installed. + +--- + +## Architecture Patterns + +### Recommended Project Structure + +No new files/folders needed. Changes touch only existing files: + +``` +src/ +├── lib/ +│ ├── db/ +│ │ └── schema.ts # ADD propertyAddress column to clients table +│ └── actions/ +│ └── clients.ts # EXTEND Zod schema + createClient + updateClient +├── app/ +│ └── portal/ +│ ├── _components/ +│ │ ├── ClientModal.tsx # ADD property address input field +│ │ └── ClientProfileClient.tsx # DISPLAY property address in profile card +│ └── (protected)/ +│ └── documents/ +│ └── [docId]/ +│ ├── page.tsx # EXTEND client select to include propertyAddress +│ └── _components/ +│ └── PreparePanel.tsx # ACCEPT + pre-seed propertyAddress prop +drizzle/ +└── 0007_property_address.sql # Generated by drizzle-kit generate +``` + +### Pattern 1: Drizzle Schema Column Addition + +**What:** Add nullable TEXT column to existing pgTable definition, then run generate + migrate. +**When to use:** Any time a new optional field is added to an existing table. + +```typescript +// src/lib/db/schema.ts — add to the clients table definition +export const clients = pgTable("clients", { + id: text("id").primaryKey().$defaultFn(() => crypto.randomUUID()), + name: text("name").notNull(), + email: text("email").notNull(), + propertyAddress: text("property_address"), // nullable — no .notNull() + createdAt: timestamp("created_at").defaultNow().notNull(), + updatedAt: timestamp("updated_at").defaultNow().notNull(), +}); +``` + +```bash +# Generate SQL migration file (creates drizzle/0007_*.sql) +npm run db:generate + +# Apply to database +npm run db:migrate +``` + +The generated SQL will be: +```sql +ALTER TABLE "clients" ADD COLUMN "property_address" text; +``` + +### Pattern 2: Extending a Zod Schema + Server Action + +**What:** Add an optional field to the existing Zod clientSchema and pass it through `.set()`. +**When to use:** When a new nullable DB column is added and the form should be optional. + +```typescript +// src/lib/actions/clients.ts +const clientSchema = z.object({ + name: z.string().min(1, "Name is required"), + email: z.string().email("Valid email address required"), + propertyAddress: z.string().optional(), // empty string or absent = null +}); + +// In createClient and updateClient, after safeParse succeeds: +await db.insert(clients).values({ + name: parsed.data.name, + email: parsed.data.email, + propertyAddress: parsed.data.propertyAddress || null, +}); + +// updateClient .set(): +await db.update(clients).set({ + name: parsed.data.name, + email: parsed.data.email, + propertyAddress: parsed.data.propertyAddress || null, + updatedAt: new Date(), +}).where(eq(clients.id, id)); +``` + +### Pattern 3: ClientModal Form Field Addition + +**What:** Add a new input with `name="propertyAddress"` and `defaultValue` prop, mirroring existing name/email pattern. +**When to use:** Every new client field that agent can edit. + +```typescript +// src/app/portal/_components/ClientModal.tsx +// Add to ClientModalProps: +type ClientModalProps = { + isOpen: boolean; + onClose: () => void; + mode?: "create" | "edit"; + clientId?: string; + defaultName?: string; + defaultEmail?: string; + defaultPropertyAddress?: string; // new +}; + +// Add input element inside the form (after email): +
+ + +
+``` + +### Pattern 4: Pre-seeding PreparePanel with Client Data + +**What:** `DocumentPage` fetches `propertyAddress` from the joined client; passes it to `PreparePanel`; `PreparePanel` seeds `textFillData` state on mount via `useEffect`. +**When to use:** Any time a known value should be pre-populated into a text fill field. + +```typescript +// src/app/portal/(protected)/documents/[docId]/page.tsx +// Extend the client select: +db.select({ email: clients.email, name: clients.name, propertyAddress: clients.propertyAddress }) + .from(clients) + .innerJoin(documents, eq(documents.clientId, clients.id)) + .where(eq(documents.id, docId)) + .limit(1) + .then(r => r[0] ?? null) + +// Pass to PreparePanel: + +``` + +```typescript +// src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx +interface PreparePanelProps { + ... + clientPropertyAddress?: string | null; +} + +// In component body — seed state on first render: +const [textFillData, setTextFillData] = useState>( + () => clientPropertyAddress ? { propertyAddress: clientPropertyAddress } : {} +); +``` + +### Pattern 5: ClientProfileClient — Display Property Address + +**What:** Render `propertyAddress` in the header card, guarded by nullish check. +**When to use:** Any optional field displayed in a profile card. + +```typescript +// src/app/portal/_components/ClientProfileClient.tsx +// Update Props type: +type Props = { + client: { id: string; name: string; email: string; propertyAddress?: string | null }; + docs: DocumentRow[]; +}; + +// In the header card JSX, after the email paragraph: +{client.propertyAddress && ( +

+ {client.propertyAddress} +

+)} +``` + +The `ClientProfilePage` server component already passes `client` directly from `db.select()` — once the schema column is added, Drizzle infers the type and `client.propertyAddress` is available with no other changes. + +### Pattern 6: Passing propertyAddress through ClientProfileClient → ClientModal + +**What:** The "Edit" button in `ClientProfileClient` opens `ClientModal` with `defaultPropertyAddress`. This requires updating the `ClientModal` call site. + +```typescript +// ClientProfileClient.tsx — edit modal call: + setIsEditOpen(false)} + mode="edit" + clientId={client.id} + defaultName={client.name} + defaultEmail={client.email} + defaultPropertyAddress={client.propertyAddress ?? undefined} +/> +``` + +### Anti-Patterns to Avoid + +- **Storing address as JSONB:** TEXT is correct. JSONB adds no value for a flat string that AI reads as a whole. +- **Making property address required (NOT NULL):** Existing clients have no address. The column MUST be nullable; NOT NULL with no default breaks existing rows on migration. +- **Changing the prepare API route:** The route already accepts `textFillData: Record`. Passing `{ propertyAddress: "..." }` in that map is sufficient — zero changes to `/api/documents/[id]/prepare/route.ts`. +- **Using a separate pre-fill API endpoint:** The TextFillForm + PreparePanel already handle the data flow. Seed from state, not from a new endpoint. +- **Forgetting `revalidatePath`:** The existing `updateClient` calls `revalidatePath("/portal/clients")` and `revalidatePath("/portal/clients/" + id)`. Both must remain; no new paths needed. + +--- + +## Don't Hand-Roll + +| Problem | Don't Build | Use Instead | Why | +|---------|-------------|-------------|-----| +| DB schema migration | Manual `ALTER TABLE` SQL file | `npm run db:generate` (drizzle-kit) | drizzle-kit updates `_journal.json` and snapshot files that future migrations depend on; manual SQL breaks the diff chain | +| Form validation | Custom validation logic | Zod `z.string().optional()` | Already the project pattern; consistent error shape | +| Cache invalidation after update | Manual cache bust | `revalidatePath()` — already called in `updateClient` | Ensures server component re-renders with fresh data | + +**Key insight:** Every mechanism needed for Phase 9 already exists in the codebase. The task is extension, not construction. + +--- + +## Common Pitfalls + +### Pitfall 1: Migration snapshot desync + +**What goes wrong:** Developer manually writes `ALTER TABLE` SQL in `drizzle/0007_*.sql` without running `drizzle-kit generate`. The snapshot files (`meta/0007_snapshot.json` and `_journal.json`) are not updated. The next `drizzle-kit generate` produces a diff that re-adds the column. + +**Why it happens:** Developer skips `npm run db:generate` to save time. + +**How to avoid:** Always run `npm run db:generate` first. The command reads `schema.ts`, diffs against the latest snapshot, and produces both the SQL file and the updated snapshot. + +**Warning signs:** After adding the column to `schema.ts`, running `npm run db:generate` again produces a non-empty migration — indicates the first migration wasn't done via drizzle-kit. + +### Pitfall 2: Nullable column with default value confusion + +**What goes wrong:** Column declared as `.default('')` instead of truly nullable. Empty string and NULL are treated differently in WHERE clauses and TypeScript types. + +**Why it happens:** Developer adds `.default('')` thinking it's "safer". + +**How to avoid:** Declare as `text("property_address")` with no `.notNull()` and no `.default()`. TypeScript type will be `string | null`. Guard display with `client.propertyAddress && ...`. + +### Pitfall 3: Empty string vs null in server action + +**What goes wrong:** Form submits an empty string for `propertyAddress`. `z.string().optional()` returns `""` (not `undefined`). The DB gets `""` stored instead of `NULL`. + +**Why it happens:** FormData returns `""` for an unfilled text input, not `null`. + +**How to avoid:** In the server action, coerce: `propertyAddress: parsed.data.propertyAddress || null`. This converts `""` to `null` before the DB write. + +### Pitfall 4: PreparePanel textFillData state not seeded + +**What goes wrong:** `clientPropertyAddress` prop is passed to `PreparePanel` but `textFillData` state is initialized to `{}`. The property address is not pre-populated. Agent must type it manually despite it being available. + +**Why it happens:** Prop added to interface but state initialization not updated. + +**How to avoid:** Initialize `textFillData` with a lazy initializer function: `useState(() => clientPropertyAddress ? { propertyAddress: clientPropertyAddress } : {})`. This runs once on mount with the correct value. + +### Pitfall 5: ClientProfileClient Props type not updated + +**What goes wrong:** `client` prop type is `{ id: string; name: string; email: string }` — no `propertyAddress`. TypeScript error when accessing `client.propertyAddress`. The server component `ClientProfilePage` passes the full Drizzle row which now includes `propertyAddress` but the client component prop type rejects it. + +**Why it happens:** Props type not updated after schema change. + +**How to avoid:** Update the `Props` type in `ClientProfileClient.tsx` to include `propertyAddress?: string | null` before attempting to use it. + +--- + +## Code Examples + +Verified patterns from the existing codebase: + +### Drizzle nullable TEXT column (project pattern) + +```typescript +// Source: src/lib/db/schema.ts — existing nullable columns +sentAt: timestamp("sent_at"), // nullable timestamp — no .notNull() +filePath: text("file_path"), // nullable text — no .notNull() +// propertyAddress follows the same pattern: +propertyAddress: text("property_address"), +``` + +### Server action Zod optional field (project pattern) + +```typescript +// Source: src/lib/actions/clients.ts — existing pattern extended +const clientSchema = z.object({ + name: z.string().min(1, "Name is required"), + email: z.string().email("Valid email address required"), + propertyAddress: z.string().optional(), +}); +// After parse: parsed.data.propertyAddress || null (coerce "" → null) +``` + +### Drizzle .set() with optional field (project pattern) + +```typescript +// Source: src/lib/actions/clients.ts updateClient — existing pattern +await db.update(clients).set({ + name: parsed.data.name, + email: parsed.data.email, + propertyAddress: parsed.data.propertyAddress || null, + updatedAt: new Date(), +}).where(eq(clients.id, id)); +``` + +### revalidatePath in client action (project pattern) + +```typescript +// Source: src/lib/actions/clients.ts — already present, no change needed +revalidatePath("/portal/clients"); +revalidatePath("/portal/clients/" + id); +``` + +### useState lazy initializer for pre-seeding (standard React pattern) + +```typescript +// Lazy initializer runs once — correct for prop-driven initialization +const [textFillData, setTextFillData] = useState>( + () => clientPropertyAddress ? { propertyAddress: clientPropertyAddress } : {} +); +``` + +--- + +## State of the Art + +| Old Approach | Current Approach | When Changed | Impact | +|--------------|------------------|--------------|--------| +| Manual SQL migration files | `drizzle-kit generate` + `migrate` | Project convention from day 1 | Must follow for snapshot integrity | +| Class-based React forms | `useActionState` (React 19) | React 19 / Next.js 16 | Already used in ClientModal; follow same pattern | + +**Deprecated/outdated:** +- `useFormState` (React DOM): Replaced by `useActionState` from `react` in React 19. The project already uses `useActionState` — do not use the old name. + +--- + +## Open Questions + +1. **Should propertyAddress be required for new clients going forward?** + - What we know: Requirements say "Agent can ADD a property address" — implies optional + - What's unclear: Future phases (AI-02) need it for pre-fill — but not having it should not block document creation + - Recommendation: Keep nullable. Phase 13 (AI-02) can show a warning if address is missing when AI pre-fill is triggered. + +2. **How does PreparePanel handle the case where textFillData is seeded but agent clears the property address field?** + - What we know: TextFillForm is a fully controlled component; changes propagate through `onChange` callback + - What's unclear: If agent deletes the pre-seeded row, should it stay empty or re-populate? + - Recommendation: Normal behavior — once agent deletes it, it stays deleted. Pre-seeding is a convenience, not a lock. + +--- + +## Sources + +### Primary (HIGH confidence) +- Direct codebase inspection: `src/lib/db/schema.ts` — confirmed `clients` table structure, existing nullable TEXT pattern +- Direct codebase inspection: `src/lib/actions/clients.ts` — confirmed Zod schema pattern, server action shape +- Direct codebase inspection: `src/app/portal/_components/ClientModal.tsx` — confirmed `useActionState` + form pattern +- Direct codebase inspection: `src/app/portal/_components/ClientProfileClient.tsx` — confirmed Props type, display pattern +- Direct codebase inspection: `src/app/portal/(protected)/documents/[docId]/page.tsx` — confirmed client data fetch shape +- Direct codebase inspection: `src/app/portal/(protected)/documents/[docId]/_components/PreparePanel.tsx` — confirmed `textFillData` state initialization +- Direct codebase inspection: `src/lib/pdf/prepare-document.ts` — confirmed `textFillData: Record` accepted as-is +- Direct codebase inspection: `drizzle/meta/_journal.json` — confirmed next migration will be `0007_*` +- Direct codebase inspection: `drizzle.config.ts` — confirmed `db:generate` and `db:migrate` scripts + +### Secondary (MEDIUM confidence) +- `package.json` drizzle-orm ^0.45.1, drizzle-kit ^0.31.10 — versions confirmed from installed dependencies + +--- + +## Metadata + +**Confidence breakdown:** +- Standard stack: HIGH — all dependencies confirmed installed, no new libraries needed +- Architecture: HIGH — full codebase read; every touch point identified and verified +- Pitfalls: HIGH — all pitfalls derived from direct inspection of existing code patterns + +**Research date:** 2026-03-21 +**Valid until:** 2026-04-20 (stable stack — Drizzle and Next.js APIs in this project are locked)