# shoaibnoor95/salespad architecture

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

- Interactive diagram: https://gitdiagram.com/shoaibnoor95/salespad
- Repository: https://github.com/shoaibnoor95/salespad

## Overview

#### Purpose and Runtime
SalesPad is a Node.js/Express backend prototype for outbound-sales lead automation. It exposes HTTP endpoints to create leads, send outreach, record replies, generate AI replies, and retrieve lead state. The process starts in `src/index.ts`; API documentation is configured in `src/config/swagger.ts`.

#### HTTP API Boundary
Routes define the public contract and Swagger JSDoc for:
- `POST /lead`
- `POST /send`
- `POST /reply`
- `POST /ai/reply`
- `GET /lead/:id`

Routing is centralized in `src/routes/lead.routes.ts`, with request handling in `src/controllers/lead.controller.ts`. Controllers form the boundary between HTTP concerns and domain/service operations.

#### Lead Domain and Persistence
The lead record is the core stateful entity: it holds lead data and supports outbound/reply workflow updates. Persistence access is encapsulated by `src/models/lead.model.ts`, backed by PostgreSQL through Prisma schema definitions in `prisma/schema.prisma`.

This isolates database representation from controller behavior and enables service-layer workflow orchestration.

#### Workflow Orchestration
`src/services/lead.service.ts` coordinates the core sales flow:
1. Create and persist a lead.
2. Initiate an outbound send operation.
3. Register an inbound lead reply and update state.
4. Request or persist AI-assisted reply output.
5. Return the current lead record.

The service sits between controllers and model/queue/AI dependencies, making it the primary business-policy boundary.

#### Async Delivery Boundary
`src/services/queue.service.ts` provides an in-memory asynchronous queue mock. Sending is therefore decoupled from the API request lifecycle, modeling a future Redis/BullMQ-backed delivery pipeline without requiring external queue infrastructure in the prototype.

The queue boundary is important for eventual integration with email, CRM, or multi-channel sending workers; no production broker or delivery provider is present in the repository.

#### AI Reply Integration
`src/services/ai.service.ts` encapsulates AI reply generation. Lead workflow code should depend on this service rather than embed generation behavior in routes/controllers, preserving an external-provider boundary for a future LLM API integration. The repository does not identify a concrete AI vendor.

#### Infrastructure and Operations
Required local infrastructure is Node.js 18+, npm, and PostgreSQL 14+. Environment configuration is represented by `.env.example`; Prisma owns database schema management through `prisma/schema.prisma`. Swagger is served from the running Express process, and `verify.ps1` provides an end-to-end local verification path.

Main entry points: [`src/services/lead.service.ts`](https://github.com/shoaibnoor95/salespad/blob/main/src/services/lead.service.ts) (Lead service), [`src/index.ts`](https://github.com/shoaibnoor95/salespad/blob/main/src/index.ts) (Express bootstrap), [`src/routes/lead.routes.ts`](https://github.com/shoaibnoor95/salespad/blob/main/src/routes/lead.routes.ts) (Lead routes), [`src/controllers/lead.controller.ts`](https://github.com/shoaibnoor95/salespad/blob/main/src/controllers/lead.controller.ts) (Lead controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_app["Express bootstrap<br/>Node.js runtime<br/>[index.ts]"]
  node_swagger["Swagger docs<br/>API documentation<br/>[swagger.ts]"]
  node_routes["Lead routes<br/>Express router<br/>[lead.routes.ts]"]
  node_controller["Lead controller<br/>HTTP controller<br/>[lead.controller.ts]"]
end

subgraph group_domain["Lead Workflow"]
  node_lead_service["Lead service<br/>workflow service<br/>[lead.service.ts]"]
  node_ai_service{{"AI service<br/>AI integration boundary<br/>[ai.service.ts]"}}
end

subgraph group_async["Async Delivery"]
  node_queue_service["Queue service<br/>in-memory queue<br/>[queue.service.ts]"]
  node_delivery_worker["Future delivery worker<br/>delivery integration"]
end

subgraph group_data["Persistence"]
  node_lead_model["Lead model<br/>persistence model<br/>[lead.model.ts]"]
  node_prisma_schema["Prisma schema<br/>database schema<br/>[schema.prisma]"]
  node_postgres[("PostgreSQL<br/>database")]
end

subgraph group_ops["Operations"]
  node_env["Environment template<br/>local configuration<br/>[.env.example]"]
  node_verify["Local verification<br/>end-to-end script<br/>[verify.ps1]"]
end

node_app -->|"mounts"| node_routes
node_app -->|"serves"| node_swagger
node_routes -->|"dispatches"| node_controller
node_controller -->|"invokes"| node_lead_service
node_lead_service -->|"creates and updates leads"| node_lead_model
node_lead_model -->|"maps through"| node_prisma_schema
node_prisma_schema -->|"defines"| node_postgres
node_lead_service -->|"queues outbound sends"| node_queue_service
node_queue_service -.->|"future consumption"| node_delivery_worker
node_lead_service -->|"generates AI replies"| node_ai_service
node_env -.->|"configures"| node_app
node_verify -.->|"exercises API flow"| node_app

click node_app "https://github.com/shoaibnoor95/salespad/blob/main/src/index.ts"
click node_swagger "https://github.com/shoaibnoor95/salespad/blob/main/src/config/swagger.ts"
click node_routes "https://github.com/shoaibnoor95/salespad/blob/main/src/routes/lead.routes.ts"
click node_controller "https://github.com/shoaibnoor95/salespad/blob/main/src/controllers/lead.controller.ts"
click node_lead_service "https://github.com/shoaibnoor95/salespad/blob/main/src/services/lead.service.ts"
click node_lead_model "https://github.com/shoaibnoor95/salespad/blob/main/src/models/lead.model.ts"
click node_prisma_schema "https://github.com/shoaibnoor95/salespad/blob/main/prisma/schema.prisma"
click node_queue_service "https://github.com/shoaibnoor95/salespad/blob/main/src/services/queue.service.ts"
click node_ai_service "https://github.com/shoaibnoor95/salespad/blob/main/src/services/ai.service.ts"
click node_env "https://github.com/shoaibnoor95/salespad/blob/main/.env.example"
click node_verify "https://github.com/shoaibnoor95/salespad/blob/main/verify.ps1"

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_app,node_swagger,node_routes,node_controller toneBlue
class node_lead_service,node_ai_service toneAmber
class node_queue_service,node_delivery_worker toneMint
class node_lead_model,node_prisma_schema,node_postgres toneRose
class node_env,node_verify toneIndigo
```

## Components

### HTTP API

- [Express bootstrap](https://github.com/shoaibnoor95/salespad/blob/main/src/index.ts): Node.js runtime · Starts the HTTP server. · `src/index.ts`
- [Swagger docs](https://github.com/shoaibnoor95/salespad/blob/main/src/config/swagger.ts): API documentation · `src/config/swagger.ts`
- [Lead routes](https://github.com/shoaibnoor95/salespad/blob/main/src/routes/lead.routes.ts): Express router · Defines lead, send, reply, AI reply, and lookup endpoints. · `src/routes/lead.routes.ts`
- [Lead controller](https://github.com/shoaibnoor95/salespad/blob/main/src/controllers/lead.controller.ts): HTTP controller · Translates requests into workflow operations. · `src/controllers/lead.controller.ts`

### Lead Workflow

- [Lead service](https://github.com/shoaibnoor95/salespad/blob/main/src/services/lead.service.ts): workflow service · Primary sales-flow policy boundary. · `src/services/lead.service.ts`
- [AI service](https://github.com/shoaibnoor95/salespad/blob/main/src/services/ai.service.ts): AI integration boundary · Encapsulates reply generation for a future LLM provider. · `src/services/ai.service.ts`

### Async Delivery

- [Queue service](https://github.com/shoaibnoor95/salespad/blob/main/src/services/queue.service.ts): in-memory queue · Decouples outbound delivery from the request lifecycle. · `src/services/queue.service.ts`
- **Future delivery worker**: delivery integration · Planned email, CRM, or multi-channel consumer.

### Persistence

- [Lead model](https://github.com/shoaibnoor95/salespad/blob/main/src/models/lead.model.ts): persistence model · Encapsulates lead record access and state updates. · `src/models/lead.model.ts`
- [Prisma schema](https://github.com/shoaibnoor95/salespad/blob/main/prisma/schema.prisma): database schema · `prisma/schema.prisma`
- **PostgreSQL**: database · Stores lead records.

### Operations

- [Environment template](https://github.com/shoaibnoor95/salespad/blob/main/.env.example): local configuration · `.env.example`
- [Local verification](https://github.com/shoaibnoor95/salespad/blob/main/verify.ps1): end-to-end script · Verifies the local workflow. · `verify.ps1`

## Connections

- Express bootstrap → Lead routes: mounts
- Express bootstrap → Swagger docs: serves
- Lead routes → Lead controller: dispatches
- Lead controller → Lead service: invokes
- Lead service → Lead model: creates and updates leads
- Lead model → Prisma schema: maps through
- Prisma schema → PostgreSQL: defines
- Lead service → Queue service: queues outbound sends
- Queue service → Future delivery worker: future consumption
- Lead service → AI service: generates AI replies
- Environment template → Express bootstrap: configures
- Local verification → Express bootstrap: exercises API flow