# khmorsy/the-negotiator architecture

> Architecture diagram of the GitHub repository khmorsy/the-negotiator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khmorsy/the-negotiator
- Repository: https://github.com/khmorsy/the-negotiator

## Overview

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: [`src/app/api/webhooks/elevenlabs/route.ts`](https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/webhooks/elevenlabs/route.ts) (Voice webhooks), [`src/app/webhooks/handleTranscriptEvent.ts`](https://github.com/khmorsy/the-negotiator/blob/main/src/app/webhooks/handleTranscriptEvent.ts) (Transcript handling), [`src/domain/skills/skillEngine.ts`](https://github.com/khmorsy/the-negotiator/blob/main/src/domain/skills/skillEngine.ts) (Skill selection), [`src/contracts/ports/repositories.ts`](https://github.com/khmorsy/the-negotiator/blob/main/src/contracts/ports/repositories.ts) (Application repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Customer experience"]
  node_ui["Web journey<br/>[IntakeScreen.tsx]"]
  node_intake_api["Intake routes<br/>[route.ts]"]
  node_report_api["Report route<br/>[route.ts]"]
  node_live_status["Live call status"]
end

subgraph group_workflow["Procurement workflow"]
  node_job_spec["Job specification<br/>[buildJobSpec.ts]"]
  node_intake_flow["Intake orchestration"]
  node_document_parse["Upload parsing"]
  node_call_api["Call routes<br/>[route.ts]"]
  node_call_flow["Call orchestration"]
  node_webhook["Voice webhooks<br/>[route.ts]"]
  node_transcript["Transcript handling"]
  node_email_fallback["Email fallback"]
  node_report["Ranked report<br/>[reportComposer.ts]"]
end

subgraph group_negotiation["Negotiation intelligence"]
  node_quote_extract["Quote extraction<br/>[extractQuote.ts]"]
  node_skill_handler["Skill tool handler"]
  node_skill_engine["Skill selection<br/>[skillEngine.ts]"]
  node_knowledge["Knowledge retrieval<br/>[tavilyKb.ts]"]
  node_copilot["Assisted-call copilot"]
  node_skill_generator["Skill generator<br/>[skillGenerator.ts]"]
end

subgraph group_infrastructure["Persistence and integrations"]
  node_telephony["Telephony adapter"]
  node_audit["Audit events"]
  node_repositories["Application repositories<br/>[repositories.ts]"]
end

node_customer(("Customer"))

node_customer -.->|"starts intake"| node_ui
node_ui -.->|"submits details"| node_intake_api
node_intake_api -->|"updates draft"| node_repositories
node_intake_flow -->|"uses parser service"| node_document_parse
node_customer -.->|"confirms job"| node_job_spec
node_job_spec -.->|"starts vendor calls"| node_call_api
node_call_api -.->|"dispatches"| node_call_flow
node_call_flow -->|"places calls"| node_telephony
node_telephony -.->|"sends events"| node_webhook
node_webhook -->|"dispatches tool call"| node_skill_handler
node_webhook -->|"dispatches transcript"| node_transcript
node_transcript -->|"extracts quote"| node_quote_extract
node_transcript -->|"invokes fallback"| node_email_fallback
node_skill_handler -->|"chooses skill"| node_skill_engine
node_skill_engine -->|"retrieves snippets"| node_knowledge
node_skill_engine -->|"appends evidence"| node_audit
node_customer -.->|"views results"| node_report_api
node_report_api -->|"composes report"| node_report
node_report -->|"reads quotes"| node_repositories
node_live_status -.->|"shows call progress"| node_customer
node_live_status -.->|"subscribes to updates"| node_repositories
node_customer -.->|"assisted calling"| node_copilot
node_customer -.->|"generates skills"| node_skill_generator

click node_ui "https://github.com/khmorsy/the-negotiator/blob/main/src/frontend/screens/IntakeScreen.tsx"
click node_intake_api "https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/intake/%5BjobSpecId%5D/complete-live/route.ts"
click node_job_spec "https://github.com/khmorsy/the-negotiator/blob/main/src/domain/jobSpec/buildJobSpec.ts"
click node_intake_flow "https://github.com/khmorsy/the-negotiator/blob/main/src/app/intake/intakeOrchestrator.ts"
click node_document_parse "https://github.com/khmorsy/the-negotiator/blob/main/src/app/intake/documentParserService.ts"
click node_call_api "https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/calls/%5BjobId%5D/start/route.ts"
click node_call_flow "https://github.com/khmorsy/the-negotiator/blob/main/src/app/calls/callOrchestrator.ts"
click node_telephony "https://github.com/khmorsy/the-negotiator/blob/main/src/adapters/telephony/twilioElevenLabs.ts"
click node_webhook "https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/webhooks/elevenlabs/route.ts"
click node_transcript "https://github.com/khmorsy/the-negotiator/blob/main/src/app/webhooks/handleTranscriptEvent.ts"
click node_quote_extract "https://github.com/khmorsy/the-negotiator/blob/main/src/domain/quotes/extractQuote.ts"
click node_email_fallback "https://github.com/khmorsy/the-negotiator/blob/main/src/app/calls/emailFallbackHandler.ts"
click node_skill_handler "https://github.com/khmorsy/the-negotiator/blob/main/src/app/webhooks/handleSkillToolCall.ts"
click node_skill_engine "https://github.com/khmorsy/the-negotiator/blob/main/src/domain/skills/skillEngine.ts"
click node_knowledge "https://github.com/khmorsy/the-negotiator/blob/main/src/adapters/kb/tavilyKb.ts"
click node_report_api "https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/reports/%5BjobId%5D/route.ts"
click node_report "https://github.com/khmorsy/the-negotiator/blob/main/src/app/report/reportComposer.ts"
click node_audit "https://github.com/khmorsy/the-negotiator/blob/main/src/domain/audit/appendAuditEvent.ts"
click node_repositories "https://github.com/khmorsy/the-negotiator/blob/main/src/contracts/ports/repositories.ts"
click node_live_status "https://github.com/khmorsy/the-negotiator/blob/main/src/frontend/hooks/useCallStatusFeed.ts"
click node_copilot "https://github.com/khmorsy/the-negotiator/blob/main/src/app/copilot/assistedCallCopilot.ts"
click node_skill_generator "https://github.com/khmorsy/the-negotiator/blob/main/src/app/skills/skillGenerator.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_intake_api,node_report_api,node_live_status toneBlue
class node_job_spec,node_intake_flow,node_document_parse,node_call_api,node_call_flow,node_webhook,node_transcript,node_email_fallback,node_report toneAmber
class node_quote_extract,node_skill_handler,node_skill_engine,node_knowledge,node_copilot,node_skill_generator toneMint
class node_telephony,node_audit,node_repositories toneRose
class node_customer toneIndigo
```

## Components

### Customer experience

- [Web journey](https://github.com/khmorsy/the-negotiator/blob/main/src/frontend/screens/IntakeScreen.tsx): `src/frontend/screens/IntakeScreen.tsx`
- [Intake routes](https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/intake/%5BjobSpecId%5D/complete-live/route.ts): `src/app/api/intake/[jobSpecId]/complete-live/route.ts`
- [Report route](https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/reports/%5BjobId%5D/route.ts): `src/app/api/reports/[jobId]/route.ts`
- [Live call status](https://github.com/khmorsy/the-negotiator/blob/main/src/frontend/hooks/useCallStatusFeed.ts): `src/frontend/hooks/useCallStatusFeed.ts`

### Procurement workflow

- [Job specification](https://github.com/khmorsy/the-negotiator/blob/main/src/domain/jobSpec/buildJobSpec.ts): `src/domain/jobSpec/buildJobSpec.ts`
- [Intake orchestration](https://github.com/khmorsy/the-negotiator/blob/main/src/app/intake/intakeOrchestrator.ts): `src/app/intake/intakeOrchestrator.ts`
- [Upload parsing](https://github.com/khmorsy/the-negotiator/blob/main/src/app/intake/documentParserService.ts): `src/app/intake/documentParserService.ts`
- [Call routes](https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/calls/%5BjobId%5D/start/route.ts): `src/app/api/calls/[jobId]/start/route.ts`
- [Call orchestration](https://github.com/khmorsy/the-negotiator/blob/main/src/app/calls/callOrchestrator.ts): `src/app/calls/callOrchestrator.ts`
- [Voice webhooks](https://github.com/khmorsy/the-negotiator/blob/main/src/app/api/webhooks/elevenlabs/route.ts): `src/app/api/webhooks/elevenlabs/route.ts`
- [Transcript handling](https://github.com/khmorsy/the-negotiator/blob/main/src/app/webhooks/handleTranscriptEvent.ts): `src/app/webhooks/handleTranscriptEvent.ts`
- [Email fallback](https://github.com/khmorsy/the-negotiator/blob/main/src/app/calls/emailFallbackHandler.ts): `src/app/calls/emailFallbackHandler.ts`
- [Ranked report](https://github.com/khmorsy/the-negotiator/blob/main/src/app/report/reportComposer.ts): `src/app/report/reportComposer.ts`

### Negotiation intelligence

- [Quote extraction](https://github.com/khmorsy/the-negotiator/blob/main/src/domain/quotes/extractQuote.ts): `src/domain/quotes/extractQuote.ts`
- [Skill tool handler](https://github.com/khmorsy/the-negotiator/blob/main/src/app/webhooks/handleSkillToolCall.ts): `src/app/webhooks/handleSkillToolCall.ts`
- [Skill selection](https://github.com/khmorsy/the-negotiator/blob/main/src/domain/skills/skillEngine.ts): `src/domain/skills/skillEngine.ts`
- [Knowledge retrieval](https://github.com/khmorsy/the-negotiator/blob/main/src/adapters/kb/tavilyKb.ts): `src/adapters/kb/tavilyKb.ts`
- [Assisted-call copilot](https://github.com/khmorsy/the-negotiator/blob/main/src/app/copilot/assistedCallCopilot.ts): `src/app/copilot/assistedCallCopilot.ts`
- [Skill generator](https://github.com/khmorsy/the-negotiator/blob/main/src/app/skills/skillGenerator.ts): `src/app/skills/skillGenerator.ts`

### Persistence and integrations

- [Telephony adapter](https://github.com/khmorsy/the-negotiator/blob/main/src/adapters/telephony/twilioElevenLabs.ts): `src/adapters/telephony/twilioElevenLabs.ts`
- [Audit events](https://github.com/khmorsy/the-negotiator/blob/main/src/domain/audit/appendAuditEvent.ts): `src/domain/audit/appendAuditEvent.ts`
- [Application repositories](https://github.com/khmorsy/the-negotiator/blob/main/src/contracts/ports/repositories.ts): `src/contracts/ports/repositories.ts`

### Other components

- **Customer**

## Connections

- Customer → Web journey: starts intake
- Web journey → Intake routes: submits details
- Intake routes → Application repositories: updates draft (evidence: `src/app/api/intake/[jobSpecId]/complete-live/route.ts`)
- Intake orchestration → Upload parsing: uses parser service (evidence: `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 (evidence: `src/app/composition/createContainer.ts`)
- Telephony adapter → Voice webhooks: sends events
- Voice webhooks → Skill tool handler: dispatches tool call (evidence: `src/app/api/webhooks/elevenlabs/route.ts`)
- Voice webhooks → Transcript handling: dispatches transcript (evidence: `src/app/api/webhooks/elevenlabs/route.ts`)
- Transcript handling → Quote extraction: extracts quote (evidence: `src/app/webhooks/handleTranscriptEvent.ts`)
- Transcript handling → Email fallback: invokes fallback (evidence: `src/app/webhooks/handleTranscriptEvent.ts`)
- Skill tool handler → Skill selection: chooses skill (evidence: `src/app/webhooks/handleSkillToolCall.ts`)
- Skill selection → Knowledge retrieval: retrieves snippets (evidence: `src/domain/skills/skillEngine.ts`)
- Skill selection → Audit events: appends evidence (evidence: `src/domain/skills/skillEngine.ts`)
- Customer → Report route: views results
- Report route → Ranked report: composes report (evidence: `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 (evidence: `src/frontend/hooks/useCallStatusFeed.ts`)
- Customer → Assisted-call copilot: assisted calling
- Customer → Skill generator: generates skills
