How khmorsy/the-negotiator works
The Negotiator is a voice-AI procurement agent for home-cleaning services. Its principal journey is customer intake and job-spec confirmation, vendor calls and negotiation, then a ranked quote report with an audit trail. The application layer orchestrates intake, calls, and reporting; adapters provide interchangeable simulated or live services and persistence. The README documents these stages and tiered capabilities. Some connections below are documented but unsampled, so they are marked dashed without evidence rather than presented as inspected call paths.
Main entry points: route.ts Voice webhooks · handleTranscriptEvent.ts Transcript handling · skillEngine.ts Skill selection · repositories.ts Application repositories
Components 23
Customer experience
- Web journey
src/frontend/screens/IntakeScreen.tsx - Intake routes
src/app/api/intake/[jobSpecId]/complete-live/route.ts - Report route
src/app/api/reports/[jobId]/route.ts - Live call status
src/frontend/hooks/useCallStatusFeed.ts
Procurement workflow
- Job specification
src/domain/jobSpec/buildJobSpec.ts - Intake orchestration
src/app/intake/intakeOrchestrator.ts - Upload parsing
src/app/intake/documentParserService.ts - Call routes
src/app/api/calls/[jobId]/start/route.ts - Call orchestration
src/app/calls/callOrchestrator.ts - Voice webhooks
src/app/api/webhooks/elevenlabs/route.ts - Transcript handling
src/app/webhooks/handleTranscriptEvent.ts - Email fallback
src/app/calls/emailFallbackHandler.ts - Ranked report
src/app/report/reportComposer.ts
Negotiation intelligence
- Quote extraction
src/domain/quotes/extractQuote.ts - Skill tool handler
src/app/webhooks/handleSkillToolCall.ts - Skill selection
src/domain/skills/skillEngine.ts - Knowledge retrieval
src/adapters/kb/tavilyKb.ts - Assisted-call copilot
src/app/copilot/assistedCallCopilot.ts - Skill generator
src/app/skills/skillGenerator.ts
Persistence and integrations
- Telephony adapter
src/adapters/telephony/twilioElevenLabs.ts - Audit events
src/domain/audit/appendAuditEvent.ts - Application repositories
src/contracts/ports/repositories.ts
Other components
- Customer
Connections 23
- Customer → Web journey: starts intake
- Web journey → Intake routes: submits details
- Intake routes → Application repositories: updates draft
src/app/api/intake/[jobSpecId]/complete-live/route.ts - Intake orchestration → Upload parsing: uses parser service
src/app/composition/createContainer.ts - Customer → Job specification: confirms job
- Job specification → Call routes: starts vendor calls
- Call routes → Call orchestration: dispatches
- Call orchestration → Telephony adapter: places calls
src/app/composition/createContainer.ts - Telephony adapter → Voice webhooks: sends events
- Voice webhooks → Skill tool handler: dispatches tool call
src/app/api/webhooks/elevenlabs/route.ts - Voice webhooks → Transcript handling: dispatches transcript
src/app/api/webhooks/elevenlabs/route.ts - Transcript handling → Quote extraction: extracts quote
src/app/webhooks/handleTranscriptEvent.ts - Transcript handling → Email fallback: invokes fallback
src/app/webhooks/handleTranscriptEvent.ts - Skill tool handler → Skill selection: chooses skill
src/app/webhooks/handleSkillToolCall.ts - Skill selection → Knowledge retrieval: retrieves snippets
src/domain/skills/skillEngine.ts - Skill selection → Audit events: appends evidence
src/domain/skills/skillEngine.ts - Customer → Report route: views results
- Report route → Ranked report: composes report
src/app/api/reports/[jobId]/route.ts - Ranked report → Application repositories: reads quotes
- Live call status → Customer: shows call progress
- Live call status → Application repositories: subscribes to updates
src/frontend/hooks/useCallStatusFeed.ts - Customer → Assisted-call copilot: assisted calling
- Customer → Skill generator: generates skills