Sprout Deal Engine

An autonomous B2B deal engine that runs a lead from first touch to signed, paid, and handed-off — with a human one-tap approval in front of every outbound step, on a stack that costs ₱0 to run.

Built for the Philippine sales motion: Viber voice notes, Taglish call transcription, RA 8792-style self-hosted e-signatures, QR Ph payments, and Data-Privacy-Act-aware consent tracking — all runnable offline on one laptop.

New here? Three commands:

git clone https://github.com/newonathe/deal-engine.git && cd deal-engine
bash bootstrap.sh     # checks prereqs, containers, deps, DB, demo data
bash launch.sh        # starts everything, prints the status table

Then log in at http://localhost:3001 as admin@example.com / sprout-demo-login-2026 (a realistic ~40-deal pipeline), and open http://localhost:8025 (Mailpit) to see every email the demo "sends" — nothing ever leaves your machine.

Want proof before clicking around? cd backend && npm run demo:seed && npm run demo:run drives the entire lifecycle against the live API and prints a ✓ per step.

The handover pack (start here)

Read	To get
01 · Setup	must-haves, laptop specs, Windows/WSL2–macOS–Linux install, the AI tier, troubleshooting
02 · Walkthrough	every page, every dashboard, every feature in detail + a guided 15-minute end-to-end demo
03 · API reference	every endpoint with auth, bodies, and working curl examples
04 · Data import	importing your contacts (CSV/manual/API), CRM-export mapping, feeding real data lawfully (RA 10173)
05 · Testing	the six test gates, full-suite commands, manual test scripts, CI
06 · Operations	start/stop, every setting, ports, backups, security posture
07 · Value for Sprout	feature-by-feature mapping to Sprout's sales motion + honest limits
08 · Recognition & MOU	authorship & ownership under the internship agreement, researched PH benchmarks, ready-to-sign MOU draft
09 · Codebase map	every folder and file explained — modules, migrations, components, where to start reading
10 · Scale, deploy, monetize	deployment paths, scaling model, pre-live hardening list, feature roadmap, go-live sequence, monetization paths
LICENSE	authorship & use notice — internal evaluation/demos are free; production use waits for the written agreement in 08

Demo logins (all fictional, seeded automatically)

Tenant	Email	Password	Purpose
Sprout Demo	admin@example.com	sprout-demo-login-2026	realistic populated dashboard
Acme Test	acme.admin@example.com	sprout-demo-login-2026	second tenant — see the isolation with your own eyes
Deal Engine Demo	demo@example.com	sprout-demo-login-2026	clean single-lead tenant for the guided demo (npm run demo:seed)

What it does

flowchart LR
  A[Lead in<br/>CSV · manual · API] --> B[Score & tier<br/>rules over facts]
  B --> C[Route first contact<br/>email / Viber voice / wait]
  C --> D[Draft + one-tap approve<br/>AI or template]
  D --> E[Call recap<br/>on-device Whisper]
  E --> F[Proposal + PDF<br/>gates evaluated]
  F --> G[Follow-ups &<br/>stakeholder chasing]
  G --> H[E-sign<br/>hash-sealed, verifiable]
  H --> I[Payment + QR Ph]
  I --> J[Handoff to<br/>onboarding]

Loading

Every arrow is governed by the autonomy dial: each step runs as Draft (generate, wait for a human tap — the default) or Auto (dispatch immediately), per tenant, editable live in the dashboard.

The design rule that makes it trustworthy: all decisions come from a deterministic rules engine (json-rules-engine) over named facts, and the rules/weights/templates/cadences are data you edit in the dashboard — not code. AI only drafts language and transcribes audio; it is optional, local-first (Ollama), PII-redacted before any cloud call (Presidio, with PH-specific recognizers: TIN, SSS, PhilHealth, Pag-IBIG, UMID, +63 mobiles), schema-validated, usage-ledgered, and kill-switchable. The whole product runs with AI off.

Verified state of this commit

• 306 backend unit tests (30 suites) and 29 e2e tests (3 suites) green, including the two ⛔ gates: DB-enforced tenant isolation (RLS FORCED, non-superuser runtime role) and the PII redaction boundary.
• Frontend production build clean across all 12 routes.
• demo:run end-to-end chain: all 20 lifecycle steps pass against a live stack — evaluate → route → draft → approve → email in Mailpit → recap → proposal PDF → follow-ups → approvals → deal won → e-sign → Valid & unaltered verification → payment QR → mark-paid → deal closed → handoff.
• CSV import: the shipped sample-data/leads-sample.csv imports 8/8 with per-line error reporting for bad rows.
• CI (.github/workflows/ci.yml) enforces the backend gates server-side on every push.

Stack

NestJS 11 · Drizzle ORM · PostgreSQL 17 (Docker, port 5433, RLS FORCED everywhere) · Redis 7 + BullMQ · Next.js 16 + Tailwind (dashboard) · Python sidecar (faster-whisper STT, Kokoro TTS, Presidio PII redaction, PDF sealing) · LiteLLM gateway → Ollama local / optional Groq · Mailpit (dev SMTP sink).

Port	3001	3000	5433	6379	8025	8000	4000
Service	dashboard	API	Postgres	Redis	Mailpit	AI sidecar	LLM gateway

Repository map

(Full per-file documentation: handover/09-codebase-map.md.)

backend/     NestJS API — modules: leads, core (deals/scoring), contact,
             backhalf (recap/proposal/followups/rooms), esign, payment,
             engine-config, integrations, ai, auth, health, db (schema+21
             migrations), test/ (e2e gates incl. tenant isolation)
frontend/    Next.js dashboard — 8 sections + login + public deal room
ai-sidecar/  FastAPI voice/redaction/seal service + LiteLLM gateway config
handover/    the documentation pack above
sample-data/ ready-to-import demo CSV
sbom/        CycloneDX software bill of materials
bootstrap.sh one-command environment build   ·   launch.sh one-command start

License & compensation

This is not open-source. It is the final project of the author's Sprout internship — the concept came from his mentor; the research and the entire implementation are the author's work. Internal evaluation and demos at Sprout Solutions are free and encouraged (LICENSE); before adoption into live operations or any product/release, the parties settle ownership and recognition with the written agreement their internship contract itself contemplates — the researched framework and a ready-to-sign MOU are in handover/08-compensation-mou.md.