Documentation

End-to-end B2B sales-acquisition automation platform: research prospect companies → score them once → email → call → close, all on one benchmark and one target lifecycle. Build the glue; integrate the commodities.

Built for a German company (client sign-off tracked as "⚠️ Needs client sign-off" where noted). Stack: TypeScript monorepo — NestJS API (apps/api) + Next.js 16 / React 19 (apps/web) + shared packages/; pnpm workspaces + Turborepo; Node 22+.

Start here (authoritative product docs)

These three are the source of truth for the whole product; everything below elaborates on them:

• Product Requirements — vision, vocabulary, the funnel, roles, integrations, out-of-scope.
• Technical Requirements — data model, integrations, async model, security, audit, performance, testing.
• How it works — visual explainer of the whole product (funnel, glossary, module walkthrough).

Read in order

1. 00 — Overview — guiding principle, personas, scope, build-vs-integrate, locked decisions, glossary
2. 01 — Architecture — stack, modular layering, feature modules, tenancy, RBAC, integration interfaces, conventions
3. 02 — Roadmap — phases 0–5, dependency-ordered
4. 03 — Data Model — entities, ERD, tables
5. 04 — Docs & Design Workflow — the Next.js /docs route: docs + roadmap + prototypes, shared React/shadcn components, gated showcase

Module specs

Research & scoring (the differentiator — build first)

• Target Research Pipeline — Serper.dev Maps discovery + enrichment jobs, budget guard, hiring-manager de-duplication
• Benchmark Scoring Engine — one versioned 0–100 score across 5 weighted dimensions

Campaign & lifecycle

• Campaigns & Targets — campaign CRUD, postal codes + industry, assignment rules (threshold / LLM prompt), target lifecycle state machine

The four stages

• Outreach — VirtualCompany/VirtualEmployee sender identities, Microsoft Graph / Exchange Online transport, Trulyinbox warmup, 3-mail sequence, bandit variant selection, reply processing
• Connect — Call Center — Connect-Agents, shifts, benchmark-driven call packages, live call cockpit, KPIs, commissions
• Closing — drag-drop pipeline, appointments, contracts (SignRequest), payment (GoCardless), no-show tracking, warm handoff
• Controlling — cross-team read-model dashboards, budget allocation optimization

Phase deep-dives

Detailed, phase-by-phase breakdowns — how each phase works, integration options researched (with docs links + trade-offs), and the decisions each phase needs. One per roadmap phase (1–5).

• Phase 1 — Research + Benchmark — Serper.dev Maps discovery + enrichment + benchmark: build-vs-integrate, provider options, legal, decisions
• Phase 2 — Outreach (Email) — Microsoft Graph transport + Trulyinbox warmup + VirtualCompany/VirtualEmployee senders, AI email generation, 3-mail sequence flow, bandit, legal
• Phase 3 — Connect (Call Center) — CloudTalk dialer, shifts, benchmark call packages, call cockpit, call-outcome capture, KPIs + commissions
• Phase 4 — Closing (Sales) — drag-drop pipeline, appointments, no-show tracking, contracts (SignRequest), payment (GoCardless), closing commissions, controlling view
• Phase 5 — Controlling + Optimisation — cross-team overview dashboard, budget allocation optimization, benchmark weighting A/B

Locked decisions (quick reference)

See 00-overview for the full table with rationale.

• Build the glue, integrate the commodities — email transport, inbox warmup, telephony, Maps data, crawling, e-sign and payments are integrated behind interfaces; the funnel orchestration, research/benchmark engine, sender management, bandit, workforce layer, closing and controlling are built.
• Email: the platform builds the sender layer — send via Microsoft Graph / Exchange Online, warm inboxes with Trulyinbox, from VirtualCompany / VirtualEmployee synthetic identities. (Not Smartlead/Instantly.)
• Dialer: CloudTalk (client already chose it).
• Maps: Serper.dev (Google Maps/Places — primary ID source); on-demand website crawling via Firecrawl.dev.
• Modular monorepo — NestJS feature modules under apps/api/src/*, business logic in services.
• PostgreSQL (recommended; still [open]) · Redis + BullMQ (queue-driven pipeline; [open]).
• Next.js App Router + React 19 + shadcn/ui + Tailwind 4 for the frontend.
• Single benchmark score, versioned, computed once per target, drives all four stages.
• Single-tenant build now; multi-tenancy achieved by forking the instance. ⚠️ Needs client sign-off.
• Every integration sits behind an interface (mockable, retried, timed-out, cost-tracked) so providers are swappable.
• Docs-first via the Next.js /docs route (in-app docs/roadmap + fake-data prototypes); shared React/shadcn components; env-gated showcase.

Legal note

GDPR + German UWG shape the outreach and calling design. A full compliance layer is explicitly out of scope for v1 — treat legal as a design consideration and get a written data-protection/UWG opinion before building Outreach (Phase 2). See 00-overview.