shoaibnoor95/salespad

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.