# Weekly Sales Pipeline Digest

An importable n8n workflow suite plus an included Python reporting service. Built against the supplied 620-line blueprint, with HubSpot as the implemented CRM adapter. The service is a required component, not a hypothetical API or a hosted product. This is a configurable reference implementation, not provider-agnostic plug-and-play.

## Included

| File | Purpose |
|---|---|
| `workflows/01-weekly-digest.json` | Monday 08:00, config → CRM → validation → snapshots/metrics → optional AI → charts → Slack → email → audit |
| `workflows/02-delivery-recovery.json` | Hourly recovery; successful components skipped; ambiguous sends held |
| `workflows/03-error-handler.json` | Production execution error → protected audit and admin Slack alert |
| `service/` | Working HubSpot, analytics, persistence, AI validation, rendering and delivery implementation |
| `config.example.json`, `.env.example` | Business configuration and named credential placeholders |
| `Dockerfile`, `compose.yaml` | Single-process deployment with durable SQLite volume |
| `docs/ARCHITECTURE.md` | Node-by-node implementation, contracts, metric semantics, blueprint alignment |
| `docs/SETUP.md` | Credentials, import, deployment, rollout and operations |
| `docs/VERIFICATION.md` | Exact checks performed, limitations and live acceptance checklist |
| `samples/` | Synthetic role-specific Slack JSON, thread text, HTML email, PNG charts and analytics |
| `tests/` | Deterministic unit tests and mocked integration tests |

Start with [setup instructions](docs/SETUP.md), then review the [architecture](docs/ARCHITECTURE.md). Preview [executive email](samples/executive.html), [manager email](samples/manager.html), and [rep email](samples/rep-101.html). Sample HTML uses local PNGs; actual email uses inline CID images.

## Important implementation choices

- **Two time concepts:** activity covers the previous Monday-to-Monday calendar week in the workspace timezone; open pipeline is observed at collection. The report does not pretend a Monday morning API scan is a Sunday night atomic snapshot.
- **Verified money:** Decimal calculations, explicit stage probabilities and dated finance-approved FX rates. Missing currency/rates or critical invalid records block reporting. Example rates are synthetic and must be replaced.
- **AI with bounded authority:** optional OpenAI structured output chooses existing evidence/action IDs. It cannot author new facts or financial figures. Disabled, unavailable or invalid AI produces a deterministic report.
- **Privacy by scope:** manager/rep owner allowlists are applied before calculations, AI and chart rendering. There are no contacts, emails, company associations or activity bodies fetched from the CRM.
- **Durable delivery:** root messages, thread details, each upload phase and email have separate ledger entries. SMTP acceptance is not an inbox receipt. Exactly-once delivery is not promised; uncertain outcomes require reconciliation.
- **Explicit prerequisites:** n8n plus the service, persistent volume, HubSpot private app, Slack bot, STARTTLS SMTP, approved FX table and verified recipient mapping. n8n Cloud needs a privately secured HTTPS route to the service.

The implementation and synthetic outputs were locally tested. No workflow was published, no live CRM was queried and no Slack/email messages were sent during this build.