# usernamermh/help-sale architecture

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

- Interactive diagram: https://gitdiagram.com/usernamermh/help-sale
- Repository: https://github.com/usernamermh/help-sale

## Overview

This is a sales-assistance platform for automotive teams: conversation and customer data feed agent analysis, which retrieves team knowledge and returns suggested replies and follow-up actions. The product also supports conversation extraction and script checks, vehicle matching, task/test-drive management, operational insights, and parallel subagents. The README documents these capabilities; sampled routes show API dispatch to agent flows and selected persistence calls, but most subsystem wiring is not shown, so uncertain links are omitted.

Main entry points: [`apps/api/src/db/database.ts`](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/db/database.ts) (Business Database), [`apps/api/src/routes.ts`](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/routes.ts) (HTTP API), [`apps/api/src/pi/agent-tools.ts`](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/agent-tools.ts) (Agent Tools), [`tools_system/dialog_extract/main.ts`](https://github.com/usernamermh/help-sale/blob/main/tools_system/dialog_extract/main.ts) (Conversation Extract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and Agent Entry"]
  node_api_routes["HTTP API<br/>[routes.ts]"]
  node_agent_runtime["Sales Agent<br/>[agent-runtime.ts]"]
  node_agent_tools["Agent Tools<br/>[agent-tools.ts]"]
end

subgraph group_assist["Sales Assistance"]
  node_copilot["Conversation Analysis<br/>[copilot.ts]"]
  node_vehicle_advisor["Vehicle Matching<br/>[vehicle-advisor.ts]"]
  node_business_tools["Business Tools"]
  node_system_tools["System Tools"]
end

subgraph group_knowledge["Knowledge and Quality"]
  node_conversation_extract["Conversation Extract<br/>[main.ts]"]
  node_playbook_check["Script Quality Check<br/>[main.ts]"]
  node_knowledge_search["Knowledge Search<br/>[knowledge.ts]"]
  node_knowledge_ingest["Knowledge Ingestion<br/>[ingest.ts]"]
  node_chunker["Document Chunking<br/>[chunker.ts]"]
  node_knowledge_candidates["Candidate Review"]
end

subgraph group_operations["Sales Operations"]
  node_customer_tasks["Customer Follow-up<br/>[automation.ts]"]
  node_test_drives["Test-drive Management<br/>[test-drives.ts]"]
  node_insights["Morning Briefs<br/>[insights.ts]"]
  node_subagents["Subagent Coordination<br/>[subagent-runner.ts]"]
end

subgraph group_data["State and Integrations"]
  node_sqlite[("Business Database<br/>[database.ts]")]
  node_reminders["Reminder Queue<br/>[reminder-queue.ts]"]
  node_mysql_archive[("MySQL Archive<br/>[mysql-sink.ts]")]
end

node_sales_user(("Sales Team"))
node_model{{"Configured Model"}}

node_sales_user -->|"requests"| node_api_routes
node_api_routes -->|"dispatches sales run"| node_agent_runtime
node_api_routes -->|"dispatches analysis"| node_copilot
node_api_routes -->|"dispatches matching"| node_vehicle_advisor
node_agent_runtime -->|"loads tools"| node_agent_tools
node_agent_tools -->|"dispatches business calls"| node_business_tools
node_agent_tools -->|"dispatches system calls"| node_system_tools
node_copilot -->|"requests analysis"| node_model
node_vehicle_advisor -->|"requests recommendations"| node_model
node_conversation_extract -->|"selects passages"| node_model
node_conversation_extract -->|"reads messages"| node_sqlite
node_playbook_check -->|"reads phrases and conversations"| node_sqlite
node_playbook_check -.->|"embeds text"| node_model
node_knowledge_ingest -->|"splits documents"| node_chunker
node_knowledge_ingest -->|"writes knowledge"| node_sqlite
node_knowledge_search -->|"searches knowledge"| node_sqlite
node_knowledge_candidates -->|"stores candidates"| node_sqlite
node_api_routes -->|"persists analysis and plans"| node_sqlite
node_api_routes -->|"dispatches queued work"| node_subagents
node_customer_tasks -->|"queues due tasks"| node_reminders
node_test_drives -->|"stores test drives"| node_sqlite
node_insights -->|"collects operating data"| node_sqlite
node_mysql_archive -.->|"archives selected records"| node_sqlite

click node_api_routes "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/routes.ts"
click node_agent_runtime "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/agent-runtime.ts"
click node_copilot "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/copilot.ts"
click node_vehicle_advisor "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/vehicle-advisor.ts"
click node_agent_tools "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/agent-tools.ts"
click node_business_tools "https://github.com/usernamermh/help-sale/tree/main/tools"
click node_system_tools "https://github.com/usernamermh/help-sale/tree/main/tools_system"
click node_conversation_extract "https://github.com/usernamermh/help-sale/blob/main/tools_system/dialog_extract/main.ts"
click node_playbook_check "https://github.com/usernamermh/help-sale/blob/main/tools/playbook_check/main.ts"
click node_knowledge_search "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/repositories/knowledge.ts"
click node_knowledge_ingest "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/ingest.ts"
click node_chunker "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/chunker.ts"
click node_knowledge_candidates "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/repositories/knowledge-candidates.ts"
click node_customer_tasks "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/automation.ts"
click node_test_drives "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/repositories/test-drives.ts"
click node_insights "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/insights.ts"
click node_subagents "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/subagent-runner.ts"
click node_sqlite "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/db/database.ts"
click node_reminders "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/integrations/reminder-queue.ts"
click node_mysql_archive "https://github.com/usernamermh/help-sale/blob/main/apps/api/src/integrations/mysql-sink.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_api_routes,node_agent_runtime,node_agent_tools toneBlue
class node_copilot,node_vehicle_advisor,node_business_tools,node_system_tools toneAmber
class node_conversation_extract,node_playbook_check,node_knowledge_search,node_knowledge_ingest,node_chunker,node_knowledge_candidates toneMint
class node_customer_tasks,node_test_drives,node_insights,node_subagents toneRose
class node_sqlite,node_reminders,node_mysql_archive,node_sales_user,node_model toneIndigo
```

## Components

### API and Agent Entry

- [HTTP API](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/routes.ts): `apps/api/src/routes.ts`
- [Sales Agent](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/agent-runtime.ts): `apps/api/src/pi/agent-runtime.ts`
- [Agent Tools](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/agent-tools.ts): `apps/api/src/pi/agent-tools.ts`

### Sales Assistance

- [Conversation Analysis](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/copilot.ts): `apps/api/src/pi/copilot.ts`
- [Vehicle Matching](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/pi/vehicle-advisor.ts): `apps/api/src/pi/vehicle-advisor.ts`
- [Business Tools](https://github.com/usernamermh/help-sale/tree/main/tools): `tools`
- [System Tools](https://github.com/usernamermh/help-sale/tree/main/tools_system): `tools_system`

### Knowledge and Quality

- [Conversation Extract](https://github.com/usernamermh/help-sale/blob/main/tools_system/dialog_extract/main.ts): `tools_system/dialog_extract/main.ts`
- [Script Quality Check](https://github.com/usernamermh/help-sale/blob/main/tools/playbook_check/main.ts): `tools/playbook_check/main.ts`
- [Knowledge Search](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/repositories/knowledge.ts): `apps/api/src/repositories/knowledge.ts`
- [Knowledge Ingestion](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/ingest.ts): `apps/api/src/services/ingest.ts`
- [Document Chunking](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/chunker.ts): `apps/api/src/services/chunker.ts`
- [Candidate Review](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/repositories/knowledge-candidates.ts): `apps/api/src/repositories/knowledge-candidates.ts`

### Sales Operations

- [Customer Follow-up](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/automation.ts): `apps/api/src/services/automation.ts`
- [Test-drive Management](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/repositories/test-drives.ts): `apps/api/src/repositories/test-drives.ts`
- [Morning Briefs](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/insights.ts): `apps/api/src/services/insights.ts`
- [Subagent Coordination](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/services/subagent-runner.ts): `apps/api/src/services/subagent-runner.ts`

### State and Integrations

- [Business Database](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/db/database.ts): `apps/api/src/db/database.ts`
- [Reminder Queue](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/integrations/reminder-queue.ts): `apps/api/src/integrations/reminder-queue.ts`
- [MySQL Archive](https://github.com/usernamermh/help-sale/blob/main/apps/api/src/integrations/mysql-sink.ts): `apps/api/src/integrations/mysql-sink.ts`

### Other components

- **Sales Team**
- **Configured Model**

## Connections

- Sales Team → HTTP API: requests
- HTTP API → Sales Agent: dispatches sales run
- HTTP API → Conversation Analysis: dispatches analysis
- HTTP API → Vehicle Matching: dispatches matching
- Sales Agent → Agent Tools: loads tools
- Agent Tools → Business Tools: dispatches business calls
- Agent Tools → System Tools: dispatches system calls
- Conversation Analysis → Configured Model: requests analysis
- Vehicle Matching → Configured Model: requests recommendations
- Conversation Extract → Configured Model: selects passages
- Conversation Extract → Business Database: reads messages
- Script Quality Check → Business Database: reads phrases and conversations
- Script Quality Check → Configured Model: embeds text
- Knowledge Ingestion → Document Chunking: splits documents
- Knowledge Ingestion → Business Database: writes knowledge
- Knowledge Search → Business Database: searches knowledge
- Candidate Review → Business Database: stores candidates
- HTTP API → Business Database: persists analysis and plans
- HTTP API → Subagent Coordination: dispatches queued work
- Customer Follow-up → Reminder Queue: queues due tasks
- Test-drive Management → Business Database: stores test drives
- Morning Briefs → Business Database: collects operating data
- MySQL Archive → Business Database: archives selected records