Post-Job Voice Note to Structured CRM Entry

Recipe 003 — Post-Job Voice Note to Structured CRM Entry

THE AI TRADES Platform

---

Recipe Slug: `post-job-voice-note-to-crm`

Recipe Number: 003

Difficulty: Replit Build

Time Estimate: 4-6 hours

Category: Internal Operations

Revenue Impact: Prevents $5K-$15K/year in lost upsells and forgotten follow-ups

Hours Saved: 5-8 hrs/week of manual CRM data entry

Replaces: Manual job notes, post-job paperwork, CRM data entry backlog

Design Reference: `attached_assets/design-system.md` — all screens, components, typography, colors, and spacing must follow this document exactly. Light mode only. No exceptions.

---

1. Recipe Overview

The Post-Job Voice Note app turns a 60-second voice recording into a structured job summary that syncs directly to the contractor's CRM. The tech finishes a job, opens the app on their phone, enters the customer email, hits record, talks, and hits stop. The AI does the rest.

Two Modes:

• Free Flow — tech talks naturally, AI structures it
• Guided — ElevenLabs voice agent asks configurable questions one by one, tech answers verbally

Core Flow:

1. Tech opens app on phone

2. Enters customer email address (text field — can also use voice-to-text on mobile keyboard)

3. Hits one button to record

4. Talks (free flow) or answers guided questions (ElevenLabs)

5. Hits one button to stop

6. AI transcribes and extracts structured data

7. Tech reviews structured output, makes edits if needed

8. One tap to sync to CRM via email match

---

2. Strategy Brief

The Business Villain

"The Black Hole Between Job and Office"

The tech knows everything that happened on the job. The office knows almost nothing. The gap between what happened and what gets documented is where money disappears.

Today: Tech finishes a $400 AC repair. They replaced a capacitor, noticed the evaporator coil is caked with grime, saw that the system is 14 years old, and told the homeowner they should think about replacement next year. They drive to the next job. In the CRM, they type: "fixed AC."

The office has no idea what parts were used. No idea a coil cleaning was recommended. No idea the homeowner was told someone would send a quote. No idea the system is near end-of-life. That upsell opportunity — worth $4,000-$12,000 for a replacement — evaporates. The coil cleaning quote never gets sent. The customer promise is broken.

The compounding damage:

• Average tech completes 4-6 jobs/day. Each one loses 5-10 minutes of detail
• 20-30% of upsell opportunities are never communicated to the office
• Customer promises made verbally are forgotten within hours
• Parts usage goes untracked, inventory drifts
• When a customer calls back about "what the tech said," nobody knows
• Warranty claims need details that were never recorded

The villain is not lazy techs. They are busy. They are driving. They are already at the next job. Typing detailed notes on a phone while navigating to the next address is unrealistic. The villain is the input method — text entry on a tiny keyboard while driving.

The fix: Let them talk. They already know what happened. They just told the homeowner. Now they tell their phone. The AI handles the rest.

The Behavioral Solution

The trust ladder:

1. First use: Tech records a note, sees it structured perfectly. "That's actually what I said."

2. Day 2: Office manager sees detailed notes for every job. "Finally."

3. Week 1: A follow-up quote gets sent because the AI caught "told homeowner we'd send a quote." Revenue recovered.

4. Month 1: Tech doesn't think about it — recording a voice note is muscle memory, like clocking out.

---

3. Core Loop

Single loop, two variants (Free Flow vs. Guided):

Variant A: Free Flow

Variant B: Guided (ElevenLabs)

---

4. Data Model

Voice Note Record

```ts

interface VoiceNote {

id: string;

customerEmail: string;

mode: "free_flow" | "guided";

audioUrl: string | null;

rawTranscript: string;

structuredOutput: StructuredJobSummary;

crmSyncStatus: "pending" | "synced" | "failed" | "not_configured";

crmSyncedAt: string | null;

crmProvider: string | null;

createdAt: string;

updatedAt: string;

}

interface StructuredJobSummary {

workPerformed: string;

partsUsed: string[];

equipmentNotes: string;

customerPromises: string[];

followUpActions: string[];

urgencyFlags: string[];

rawNotes: string;

}

```

Settings / Contractor Profile

```ts

interface ContractorSettings {

id: string;

businessName: string;

ownerName: string;

tradeType: string;

recordingMode: "free_flow" | "guided";

// ElevenLabs (Guided Mode)

elevenLabsApiKey: string | null;

elevenLabsVoiceId: string | null;

guidedQuestions: string[];

// CRM

crmProvider: "servicetitan" | "jobber" | "housecallpro" | "gohighlevel" | "pipedrive" | "hubspot" | null;

crmApiKey: string | null;

crmConnected: boolean;

}

```

Default Guided Questions (Pre-loaded)

```

1. "What work did you perform on this job?"

2. "What parts or materials did you use?"

3. "Did you notice anything about the equipment — age, condition, model?"

4. "Did you make any promises or commitments to the customer?"

5. "Any recommended follow-ups or upsell opportunities?"

```

These are editable in Settings. The contractor can add, remove, or reorder questions.

---

5. Screens & VTCR Specifications

5.1 — Home Screen (Record View)

Visual:

Mobile-first single screen. Clean white background. At the top: the app name with the bolt icon logo (per `design-system.md`). Below: a text input field labeled "Customer Email" with standard input styling (44px height, 6px radius, slate-300 border). Below that: a large circular record button (80px diameter, emerald-500 background, white microphone icon centered). Below the button: small text showing current mode — "Free Flow" or "Guided" — as a tappable link that opens Settings. At the bottom: a "Recent Notes" section showing the last 5 voice notes as compact cards.

Trigger:

Tech opens the app.

Condition:

• Settings have been completed (at minimum: business name, recording mode)
• If settings are not configured, redirect to Onboarding (see 5.4)

Result:

Home screen renders. Customer email field is focused and ready for input. Keyboard appears on mobile.

---

5.2 — Recording State (Free Flow)

Visual:

When recording is active, the screen transforms: background gets a subtle emerald-50 tint. The record button becomes a red stop button (same 80px size, red-600 background, white square "stop" icon). A timer appears above the button counting up (MM:SS format, Inter font, 24px, semibold). A minimal waveform visualization bar sits between the timer and the stop button — thin horizontal bars that react to audio input amplitude.

The customer email field is still visible but disabled/dimmed. A small "Recording..." label with a pulsing red dot appears at the top of the screen.

Trigger:

Tech taps the record button.

Condition:

• Customer email field is not empty (basic format validation)
• Browser has microphone permission (if not, show permission request)
• If Guided mode is active AND ElevenLabs API key is configured, route to Guided flow (5.3) instead

Result:

• Browser MediaRecorder API starts capturing audio
• Timer begins counting
• Waveform visualization activates
• Record button transforms to Stop button
• Screen gets recording state styling

---

VTCR 5.2.1 — Stop Recording

Visual:

The red stop button on the recording screen.

Trigger:

Tech taps the stop button.

Condition:

• Recording is currently active
• At least 3 seconds of audio has been captured (prevents accidental taps)

Result:

• Recording stops
• Audio blob is prepared for upload
• Screen transitions to Processing state: stop button is replaced by a spinner with "Processing your notes..." text
• Audio is uploaded to the server
• Server sends audio to OpenAI Whisper for transcription (via Replit OpenAI integration — no API key needed from user)
• Whisper returns transcript
• Transcript is sent to LLM (Replit Anthropic or OpenAI integration) with extraction prompt
• LLM returns structured data
• Screen transitions to Review state (5.5)

If transcription fails:

• Show error card: "Couldn't process that recording. Try again?"
• Retry button + option to re-record
• Audio is preserved locally so they don't lose it

---

5.3 — Recording State (Guided / ElevenLabs)

Visual:

Similar to Free Flow recording state, but instead of a plain waveform, the screen shows a conversation-style UI. At the top: "Guided Interview" label with a pulsing indicator. The center area shows the current question being asked in large text (18px, semibold, slate-900): e.g., "What work did you perform on this job?" Below it: a listening indicator (animated sound wave) when the system is waiting for the tech to speak, or a speaking indicator (animated dots) when ElevenLabs is talking. At the bottom: the same red stop button (which ends the session early if needed) plus a "Skip Question" text button.

A progress indicator (e.g., "Question 2 of 5") appears at the top.

Trigger:

Tech taps the record button when Settings → Recording Mode is "Guided" and ElevenLabs API key is configured.

Condition:

• ElevenLabs API key is valid and stored
• At least one guided question is configured in Settings
• Microphone permission granted

Result:

• ElevenLabs Conversational AI session initiates
• The voice agent greets briefly: "Let's go through your job notes." then asks the first configured question
• Tech answers verbally
• ElevenLabs processes the response, then asks the next question
• This continues through all configured questions
• After the last question, the voice says: "Got it. Processing your notes now."
• Session ends
• System pulls the full conversation transcript from ElevenLabs API (no re-transcription with Whisper — use the ElevenLabs transcript directly)
• Transcript sent to LLM for structuring
• Screen transitions to Review state (5.5)

If ElevenLabs connection fails:

• Show error: "Voice guide unavailable. Switch to Free Flow?"
• Button to switch modes and continue with manual recording
• Link to Settings to check API key

---

5.4 — Onboarding Flow

Visual:

Full-screen onboarding wizard. Clean, step-by-step. White background, centered content, max-width 480px. Progress bar at top showing current step. Each step has a heading, brief description, and the relevant input fields.

Step 1: Business Profile (Required)

• Business name (text input)
• Owner / manager name (text input)
• Trade type (dropdown: HVAC, Plumbing, Electrical, Roofing, General Contractor, Pest Control, Cleaning, Landscaping, Other)
• "Next" button (emerald-500, full-width)

Step 2: Recording Mode (Required)

• Two selectable cards side by side:
• "Free Flow" card — microphone icon, description: "Just talk. AI structures your notes."
• "Guided" card — conversation icon, description: "Voice assistant asks you questions one by one."
• If "Guided" is selected, an ElevenLabs API key field appears below:
• Text input: "ElevenLabs API Key"
• Helper text with link: "Get your API key at elevenlabs.io/settings"
• "Test Connection" button — calls ElevenLabs API to verify key is valid
• Green checkmark or red X result
• "Next" button

Step 3: CRM Connection (Optional but encouraged)

• Heading: "Connect Your CRM"
• Description: "So your voice notes sync automatically to your job records."
• CRM provider selector (cards with logos):
• ServiceTitan
• Jobber
• Housecall Pro
• GoHighLevel
• Pipedrive
• HubSpot
• When a CRM is selected, an API key input appears:
• Text input: "[CRM Name] API Key"
• Helper text with link to that CRM's API key location
• "Test Connection" button
• Green checkmark or red X result
• "Skip for now" text link + "Next" button

Trigger:

First app load when no settings exist, or when settings are incomplete.

Condition:

• No `ContractorSettings` record exists in the database

Result:

• Each step saves progress to the database immediately (so the user doesn't lose work if they close the app)
• After final step, redirect to Home Screen
• Settings are accessible later from the gear icon in the header

---

5.5 — Review Screen (Structured Output)

Visual:

The structured job summary displayed as an editable form. White card with standard card styling (1px slate-200 border, 6px radius, 24px padding on desktop, 16px on mobile). Each extracted field is a labeled section:

• Work Performed — Multi-line text area, pre-filled with AI extraction
• Parts Used — Tag-style chips, each with an X to remove. Text input to add more.
• Equipment Notes — Multi-line text area
• Customer Promises — Bulleted list, each editable, with + button to add
• Follow-Up Actions — Bulleted list, each editable, with + button to add
• Urgency Flags — Red-tinted badges if any urgent items were detected (e.g., "safety concern," "leak," "carbon monoxide")

Below the structured fields:

• A collapsible "Raw Transcript" section (collapsed by default) so the tech can verify
• A "Sync to CRM" button (emerald-500, full-width, prominent)
• If CRM is not configured: button reads "Save Note" instead and saves locally only
• If CRM is configured: button reads "Sync to [CRM Name]"
• A "Re-record" text link to discard and start over

Trigger:

AI processing completes (from either Free Flow or Guided mode).

Condition:

• Transcription succeeded
• LLM extraction succeeded
• Structured data is available

Result:

• All fields are pre-filled and editable
• Tech can adjust anything before syncing
• Tapping "Sync to CRM" initiates the CRM push

---

VTCR 5.5.1 — Sync to CRM

Visual:

The "Sync to CRM" button on the Review screen.

Trigger:

Tech taps "Sync to CRM."

Condition:

• CRM is configured and connection is valid
• Customer email field has a value
• Structured output exists

Result:

• Button disables immediately, shows spinner + "Syncing..."
• Server sends structured data to the configured CRM API
• Match is attempted via customer email address
• If match found: updates existing contact/job record with the structured note
• If no match found: creates a new contact/lead record with the note attached
• On success: green toast "Synced to [CRM Name]", button changes to "Synced" with checkmark
• On failure: red toast with error message, "Retry" button appears
• Record is saved to PostgreSQL regardless of CRM sync status

---

5.6 — History Screen

Visual:

List of past voice notes, most recent first. Accessible via a "History" tab or icon in the bottom nav. Each entry is a compact card showing:

• Customer email
• Date and time
• Mode used (Free Flow / Guided)
• First line of "Work Performed" as preview text
• CRM sync status badge (green "Synced" / yellow "Pending" / red "Failed" / gray "Local Only")

Tapping a card opens the full Review screen (5.5) for that record in read-only mode, with an "Edit & Re-sync" option.

---

5.7 — Settings Screen

Visual:

Standard settings layout accessible from gear icon in header. Sections separated by headings with subtle dividers.

Sections:

Business Profile

• Business name, owner name, trade type (same fields as onboarding)
• All editable

Recording Mode

• Toggle between "Free Flow" and "Guided"
• When Guided is selected:
• ElevenLabs API Key field (masked, with show/hide toggle)
• Voice Selection: dropdown of ElevenLabs voice IDs (populated after valid API key is entered)
• Guided Questions: ordered list of questions
• Each question is a text field with drag-to-reorder handle and delete button
• "Add Question" button at bottom
• Pre-loaded with 5 default questions (listed in Section 4)

CRM Integration

• CRM provider selector
• API key field (masked)
• Connection status indicator (green/red)
• "Test Connection" button
• "Disconnect" text link

Data

• "Export All Notes" button (downloads JSON or CSV)
• Note count: "X voice notes recorded"

---

6. CRM Integration Specifications

Supported CRMs

Sync Logic

1. Search by email — API call to find existing contact/customer record matching the provided email

2. If found — Append structured note to the existing record as a new note/activity

3. If not found — Create a new contact/lead with the email and attach the note

4. Retry logic — On API failure, retry 3x with exponential backoff (1s, 3s, 9s)

5. Failure handling — Mark as "sync failed" in local DB, show retry option in UI, never lose data

Note Format Pushed to CRM

```

📋 Post-Job Voice Note — [Date] [Time]

Recorded by: [Tech Name / Owner Name]

WORK PERFORMED:

[workPerformed text]

PARTS USED:

• [part 1]
• [part 2]

EQUIPMENT NOTES:

[equipmentNotes text]

CUSTOMER PROMISES:

• [promise 1]
• [promise 2]

FOLLOW-UP ACTIONS:

• [action 1]
• [action 2]

[URGENT FLAGS if any]

---

Recorded via The AI Trades — Post-Job Voice Note

```

---

7. AI Extraction Prompt

The LLM receives the raw transcript and returns structured JSON. This prompt is internal — the contractor never sees or edits it.

```

You are a job documentation assistant for home service contractors (HVAC, plumbing, electrical, roofing, etc.).

You will receive a raw transcript from a technician's post-job voice note. Extract the following structured information. If a category has no relevant information in the transcript, return an empty string or empty array — never invent content.

Return ONLY valid JSON matching this schema:

{

"workPerformed": "string — concise summary of work completed",

"partsUsed": ["array of strings — each part/material mentioned"],

"equipmentNotes": "string — any observations about equipment age, condition, model, brand",

"customerPromises": ["array of strings — anything the tech told the customer they would do"],

"followUpActions": ["array of strings — recommended next steps, quotes to send, return visits"],

"urgencyFlags": ["array of strings — safety concerns, code violations, active leaks, gas smells, carbon monoxide"],

"rawNotes": "string — anything that doesn't fit the above categories"

}

Rules:

• Use the technician's own language and terminology. Do not rephrase into corporate-speak.
• Parts should include quantity and specification when mentioned (e.g., "1x 45/5 µF run capacitor" not just "capacitor").
• If the tech mentions a brand name or model number, include it in equipmentNotes.
• urgencyFlags should ONLY contain genuine safety or liability concerns. Do not flag routine maintenance items.
• Do not hallucinate. If the tech didn't mention it, don't include it.

```

---

8. Technical Stack

---

9. Coding Standards

Mandatory Rules

1. Light Mode Only — No dark mode, no theme toggles, no `dark:` classes, no `prefers-color-scheme`. Light mode only, always.

2. Mobile-First — This app is primarily used on a phone. Every screen must be fully functional at 375px width. Touch targets 44px minimum.

3. One-Tap Recording — The record and stop actions must each be a single tap. No confirmation dialogs. No "are you sure?" prompts. Speed is everything.

4. Verbose API Logging — Every external API call (CRM, ElevenLabs) must log the full request URL, method, payload, response status, and response body. This is for debugging on Replit.

5. Idempotency — The "Sync to CRM" button disables immediately on tap and shows a loading state. No double-submissions.

6. No Placeholder Content — No Lorem Ipsum. Use real field labels and realistic example data in empty states.

7. Error States Required — Every API interaction must have a visible error state. Never fail silently.

8. Loading States — Show spinners during transcription, extraction, and CRM sync. Show skeleton loaders when fetching history.

9. Data Resilience — Voice notes are saved to Replit PostgreSQL immediately after recording, before any external API calls. CRM sync failure never loses the note.

10. V1: No Authentication — Hardcode a `CURRENT_USER_ID`. Add a comment: `// TODO: Replace with auth after V1 QA`.

---

10. Onboarding Card Text

For the AI Trades recipe card on the main platform:

Name: Post-Job Voice Note to Structured CRM Entry

Description: Tech finishes a job and types "fixed AC" in the notes. Office has no idea what was done, what parts were used, or what was promised. This automation turns a 60-second voice note into a structured CRM entry with parts, promises, and follow-up actions.

Input: 60-second voice note recorded on phone after each job

Transformation: Whisper transcribes. AI extracts: work performed, parts used, customer promises, equipment observations, follow-up actions. Syncs to CRM via email match.

Output: Complete job summary in CRM. Follow-up tasks captured. Upsell opportunities flagged. Customer promises tracked.

Difficulty: Replit Build

Time Estimate: 4-6 hours

Category: Internal Operations

Trades: HVAC, Plumbing, Electrical, Roofing, General Contractor

Software: ServiceTitan, Jobber, Housecall Pro, GoHighLevel, Pipedrive, HubSpot

Principles: Turn Unstructured into Structured, Capture What's Already Happening

---

11. Edge Cases

---

12. The 10-Second Value Test

Scenario: HVAC tech finishes replacing a blower motor. On the drive to the next job, opens the app.

30 seconds later: Types the customer email, hits record, says: "Replaced the blower motor on the Lennox furnace in the basement. Used a universal direct-drive motor, half-horse. The heat exchanger looked clean but the filter was completely clogged — told the homeowner to switch to a MERV 8 and change it every 90 days. Also, the AC condenser outside has some bent fins on the east side. Might want to schedule a tune-up before summer. Oh, and the homeowner asked about getting a quote for a whole-home humidifier."

60 seconds later, the office sees:

> Work Performed: Replaced blower motor on Lennox furnace (basement unit). Universal direct-drive motor, 1/2 HP.

>

> Parts Used: 1x universal direct-drive blower motor (1/2 HP)

>

> Equipment Notes: Heat exchanger clean. Air filter severely clogged — recommended MERV 8, 90-day change interval. AC condenser has bent fins on east-facing side.

>

> Customer Promises: Told homeowner to switch to MERV 8 filter and change every 90 days.

>

> Follow-Up Actions: Schedule AC condenser tune-up before summer. Send quote for whole-home humidifier installation.

The office manager's reaction: "I actually know what happened on this job." They send the humidifier quote that afternoon. That is a $2,000 job that would have been forgotten.

---

13. Relevant Modules

The following existing modules from the AI Trades module library may be applicable for the builder:

• CRM Integration Module (`modules/crm-integration-module.md`) — CRM connection patterns, field mapping, sync status tracking. Directly applicable for the CRM sync feature.
• Settings Panel Module (`modules/settings-panel-module.md`) — Centralized settings management patterns. Applicable for the Settings screen.
• Onboarding Wizard Module (`modules/onboarding-wizard-module.md`) — Multi-step first-run setup patterns. Applicable for the Onboarding flow.
• Notification / Toast Module (`modules/notification-toast-module.md`) — Toast notifications for sync success/failure feedback.

If these module files exist and are available, include them with the build for reference.