Generating a sales-offer PDF

Generating a sales offer is an async flow. The portal asks the backend to start generation, gets back a tracking id, polls for status, and only downloads once a signed URL appears. The heavy work — rendering HTML to images and stitching a PDF — happens in a separate Node/Puppeteer microservice (backend-pdf-service), driven by a queued Laravel job. Everything here is traced to current code across two repos: backend/ (Laravel) and backend-pdf-service/ (Node/Express).

It starts with one control — the Download Sales Offer link on a unit page (shopper, broker, and sales-man portals all have it):

One controller, three portals

There is one shared controller — SalesOfferPdfController (backend/app/Http/Controllers/Api/Base/SalesOfferPdfController.php) — and all three personas point their routes at it. The portal is inferred from the route-name prefix: 1 = shopper, 2 = broker, 3 = sales-man (SalesOfferPdfController.php:107-113 → PortalWebEnums::fromRoutePrefix). So the shopper, broker and sales-man “generate a sales offer” flows are the same three actions (generate, showGeneration/status, download) with different route prefixes.

The one thing to know before you touch this

The PDF service fails CLOSED — an unset API_TOKEN returns 401 for every request

isAuthenticated() in the microservice reads process.env.API_TOKEN; if it is falsy, it returns false, and the handler responds 401 for every request (backend-pdf-service/src/routes/sales-offer.ts:8-16,20-23). There is no unauthenticated bypass.

This contradicts the service’s own CLAUDE.md §2 rule 6, which still claims “if the env var is unset, the service has no auth at all.” That doc is stale relative to the code — trust the code.

The practical consequence: the backend’s PDF_SERVICE_TOKEN must equal the service’s API_TOKEN. If they differ, or the service’s API_TOKEN is unset, every job fails with the PDF service returning 401, and the generation ends up failed. This is the single most common misconfiguration in this flow.

The whole trip, in one diagram

sequenceDiagram
actor U as Portal user
participant SPA as Portal SPA (React)
participant API as Backend (Laravel)
participant DB as SalesOfferPdfGeneration
participant Q as Queue "pdf-service"
participant JOB as GenerateSalesOfferPdfJob
participant PDF as PDF service (Puppeteer)
participant FS as Cache disk (SALES_OFFER_DISK)
U->>SPA: Click "download sales offer"
SPA->>API: POST .../units/{unit}/sales-offer/{plan}/generate
Note over API: validate offer context + payment plan<br/>throttle:sales-offer-generate
API->>DB: create row, status=Pending
API->>Q: dispatch GenerateSalesOfferPdfJob(id)
API-->>SPA: 200 { id }
Q->>JOB: run (only if row still Pending)
Note over JOB: status=Processing<br/>resolve plan + EGP rate if capping
JOB->>FS: cache hit? sales-offers/cache/{sha}.pdf
alt cache miss
  JOB->>PDF: POST /api/sales-offer (Bearer token)
  PDF-->>JOB: 200 application/pdf
  JOB->>FS: store {sha}.pdf
end
JOB->>DB: status=Completed, storage_path
loop poll every 5s (max ~20 attempts)
  SPA->>API: GET .../sales-offer/{id}/status
  API-->>SPA: { status, file_url when Completed }
end
SPA->>API: GET signed file_url (download route)
Note over API: signed middleware + path guards<br/>(NOT persona auth)
API-->>SPA: stream PDF (attachment)
SPA->>U: browser saves the PDF

Sales-offer PDF — async generate → poll → download (verified)

The status machine

Every generation is one SalesOfferPdfGeneration row whose status is a SalesOfferPdfGenerationStatus enum (backend/app/Enums/SalesOfferPdfGenerationStatus.php:5-11):

Status	Backed string	Set by
Pending	pending	generate action creates the row here (StartSalesOfferPdfGeneration.php:27-53).
Processing	processing	the job, right after it starts (GenerateSalesOfferPdfJob.php:54-56).
Completed	completed	the job, on a 2xx from the PDF service, with storage_path set (:120-127).
Failed	failed	the job’s fail() path, with error_message persisted (:234-246).

The job is idempotent

GenerateSalesOfferPdfJob re-loads the row and only proceeds if it still exists and is Pending (getGeneration(), GenerateSalesOfferPdfJob.php:157-170). A retried or double-dispatched job for a row that already advanced simply exits. That is also why a row stuck in pending is almost always a worker problem, not a stuck job — see Support.

Step by step (with the exact code)

1. The portal starts generation. POST .../units/{unit}/sales-offer/{paymentPlanId}/generate hits SalesOfferPdfController@generate (SalesOfferPdfController.php:26-56). All three personas wire this route to the same controller and all carry ->middleware('throttle:sales-offer-generate') (shopper routes/api/shopper.php:63-65, broker broker.php:135-137, sales-man sales-man.php:82-84). The limiter allows config('services.pdf-service.generate_rate_limit_per_minute') per minute (default 5, floored at 1), keyed by user->id ?: ip (AppServiceProvider.php:77-85).

2. The backend validates the offer context. loadUnitRelations (:115-125) hydrates the unit (project → destination → country, images, masterplans, unit type, phase, base-PDF documents), then ValidatesSalesOfferContext->handle(...) (:38) asserts the unit has a sales-offer base-PDF config and a base_pdf document, and resolves the payment plan via CRM middleware (app/Actions/Unit/SalesOffer/ValidatesSalesOfferContext.php:31-64). Missing config or plan throws SalesOfferException / SalesOfferPaymentPlanException → HTTP 404.

3. A row is created as Pending. StartSalesOfferPdfGeneration->handle(...) (:42) computes is_capping_enabled = (currency === EGP and destination->requires_payment_currency_choice === true), does a dry-run BuildSalesOfferUnitPayload to fail fast, then creates the SalesOfferPdfGeneration row with status = Pending and expires_at = now + SALES_OFFER_EXPIRY_DAYS (default 14) (StartSalesOfferPdfGeneration.php:27-53).

4. The job is queued and the id is returned. GenerateSalesOfferPdfJob::dispatch($generation->id) (:44) enqueues onto queue pdf-service (GenerateSalesOfferPdfJob.php:34); the controller records a metric and returns { id } (:51,55). The HTTP request ends here — everything below runs on the worker.

5. The job processes. It flips the row to Processing (:54-56), re-resolves the payment plan (:73-78), and — only when is_capping_enabled — fetches the USD/EGP rate (resolveExchangeRate, :80-83,207-232) from GetEgpExchangeRateCrm->handle() (GET {CRMS_MIDDLEWARE base_url}/api/portals/egp-exchange-rate, header country: egypt), reading data.USDEGP and rounding to 3 dp. A missing rate throws InvalidArgumentException → the job fails.

6. The payload is built and the PDF is fetched (cache-or-call). BuildSalesOfferUnitPayload->handle(...) (:85-90) assembles {unit, selectedPaymentTerms, salesOfferTemplate}, then GetCachedSalesOfferPdf->handle(...) (:92-96) returns the cached PDF or calls the microservice (see below).

7. The row is completed or failed. On a 2xx, the job sets status = Completed and storage_path = the cache path for that payload (:120-127). On a non-2xx it reads error/message, records a failed metric, and calls fail() → status = Failed + error_message + Log::warning (:98-118,234-246). Payment-plan and InvalidArgumentException failures land the same way (:140-154).

8. The portal polls, then downloads. The SPA polls GET .../sales-offer/{id}/status and, once status = Completed, receives a 15-minute signed file_url; it then fetches that URL and saves the blob as the file. (Frontend orchestration: downloadSalesOffer, frontend/libs/common-components/src/lib/download-sales-offer/download-sales-offer.tsx:579-645 — poll every 5000 ms, up to 20 attempts.)

Inside the microservice

backend-pdf-service is Node 20 + Express + Puppeteer + pdf-lib. It boots in src/index.ts (express.json({ limit: BODY_PAYLOAD_LIMIT ?? '20mb' }), router mounted at /api/sales-offer, GET /health, listens on PORT ?? 3001).

1. Auth. isAuthenticated(req) — fail-closed against API_TOKEN (see the caution above), then a plain Bearer <token> === API_TOKEN string compare (sales-offer.ts:8-16).

2. Validate. SalesOfferBodySchema.safeParse(req.body) (Zod, sales-offer.ts:26-30, 400 on failure). The schema requires unit, selectedPaymentTerms, salesOfferTemplate; the template file accepts a base64 string and transforms it to a Uint8Array (sales-offer.schema.ts:99-102,110-114); show_capping / usd_to_egp_rate are optional.

3. Render. salesOfferPdfService.generate(...) builds 3 HTML blocks — floor-plan heading, payment calculator, payment installments (sales-offer-pdf.service.ts:35-39) — and screenshots them with Puppeteer.

4. Screenshot. captureAllBlocksWithNewBrowser launches puppeteer.launch({ headless: true, args: [--no-sandbox, --disable-setuid-sandbox, --disable-dev-shm-usage, --disable-gpu] }) and renders the 3 blocks in parallel (capture-render.ts:62-112); each page waits for networkidle0 + document.fonts.ready + 300 ms, then screenshots [data-pdf-render-ready] (fallback body) as base64 PNG. Browser and pages are closed in finally blocks.

5. Assemble. buildSalesOfferPdf(...) loads the base template PDF from the template file bytes and conditionally appends floor-plan, payment-plan, master-plan and gallery pages (pdf/sales-offer.ts:354-417). It returns application/pdf + Content-Disposition: attachment; any throw becomes 500 { error, message }.

The EGP capping path is why the job resolves an exchange rate: when salesOfferTemplate.show_capping === true the service treats the offer as El Gouna EGP and uses usd_to_egp_rate in the payment blocks (sales-offer-pdf.service.ts:28). The rate is resolved backend-side (step 5 above), never inside the service.

The service will fetch arbitrary URLs from the request body (SSRF surface)

embedImageWithFallback(pdfDoc, imageUrl) does an unrestricted await fetch(imageUrl) on caller-supplied URLs (src/pdf/embed-image.ts:6-33) — no scheme or host allowlist, no private-IP block, no size cap. It is reachable through several request-body fields: unit.masterplan_image, unit.masterplans[].image, and unit.gallery[].

Treat the service as needing an egress / URL allowlist: today it will happily issue outbound GETs to whatever URL a caller puts in the body — the classic SSRF primitive against internal metadata or private services. This matters more given the fail-closed auth only holds if API_TOKEN is strong and not shared. Note also that a fetch error is console.error’d then swallowed to null (embed-image.ts:29-32) — it lands in the daily log, but nothing is surfaced to the caller or the PDF output: the image is simply omitted, so a broken image reads as a silent gap rather than a failure.

Do not treat this section as an exhaustive security review. The full list of hardening items (egress allowlist, CORS origin allowlist, constant-time token compare, dead-route removal, the stale service CLAUDE.md) is tracked on the knowledge-transfer tracker.

Storage, the signed URL, and the download guards

Cache. GetCachedSalesOfferPdf keys the PDF by a SHA of the payload: sales-offers/cache/{sha}.pdf (storagePathForPayload, GetCachedSalesOfferPdf.php:33-38) on the disk config('filesystems.sales_offer_disk') (env SALES_OFFER_DISK). On a cache hit it returns the stored bytes as a synthetic 200; on a miss it calls the service and, only on success, puts the body at the cache path (:45-93). A completed generation records that same path as storage_path.

The signed download URL. GetGeneratedPdfStatus adds a 15-minute file_url when a generation is Completed with a storage_path (GetGeneratedPdfStatus.php:19-50):

• On an s3 disk it uses Storage::disk('s3')->temporaryUrl(...).
• Otherwise it hand-rolls an HMAC-signed URL (buildSignedDownloadUrl, :55-69): hash_hmac('sha256', "{url}?expires={ts}", config('app.key')) over the persona-specific download path — deliberately matching Laravel’s built-in signed (ValidateSignature) middleware that guards the route.

Download is authorized by the signed URL, not by persona auth

The download route carries ->middleware('signed') (plus withoutMiddleware([FormatApiResponse::class])) and is declared outside the persona-auth group on the broker and sales-man portals on purpose (e.g. broker.php:74-77, sales-man.php:15-18). So “who may download” is decided by the 15-minute signature, not a session token. This is why a download link works when pasted into a fresh tab — and why it stops working after 15 minutes.

Download guards. GetGeneratedPdfPath->handle() re-validates before streaming (GetGeneratedPdfPath.php:16-60): the generation must belong to the unit (404); status must be Completed with a storage_path (404); the path must start with sales-offers/ and contain no .. (403 traversal guard); the s3 disk is rejected for streamed download (404); and the file must exist (404). Only then does the controller stream it via response()->streamDownload reading Storage::disk($disk)->readStream($path) (SalesOfferPdfController.php:86-101).

Support: reading a stuck or failed generation

Start from the SalesOfferPdfGeneration row’s status, then the status-endpoint payload and logs.

Symptom	Most likely cause	Where to look
Stuck in pending	The queue worker for the pdf-service queue isn’t running, so the job never ran; or the row wasn’t Pending when it ran (idempotency guard exited early).	Confirm queue:work is processing queue pdf-service; GenerateSalesOfferPdfJob.php:165-167.
failed with a message	The job caught a non-2xx / exception. The reason is in the status payload message and the logs.	message = error_message (GetGeneratedPdfStatus.php:45-47); logs PDF service error / processing failed (GenerateSalesOfferPdfJob.php:110-116,148-153).
failed, message shows a 401	Service API_TOKEN unset (fails closed) or PDF_SERVICE_TOKEN ≠ API_TOKEN.	sales-offer.ts:8-16,20-23; align the two env vars.
failed on a capping (EGP) unit	USD/EGP rate missing or the CRM rate call failed.	resolveExchangeRate (GenerateSalesOfferPdfJob.php:207-232); GetEgpExchangeRateCrm.php:14-26.
download returns 403	Path failed the sales-offers/ prefix / .. traversal guard.	GetGeneratedPdfPath.php:37-46.
download returns 404	Wrong unit, not Completed, s3 disk rejected for streaming, expired/invalid signature, or the cached file was swept (rows carry expires_at).	GetGeneratedPdfPath.php:25-60; signature TTL is 15 min.

Trace the whole path in logs. Backend: Sales offer PDF generate: request started / job dispatched (SalesOfferPdfController.php:34,46-49); PDF service: sending request / response received with duration_ms (CallPdfServiceSalesOffer.php:30-55); cache hit / miss / stored (GetCachedSalesOfferPdf.php:59-89). Service: per-stage timings in a daily log file (patchConsoleToDailyFile, backend-pdf-service/src/index.ts:1-4). Neither side logs the PDF body or customer PII — the outbound call logs metadata only (the PDF service: sending request / response received lines with status + duration_ms, CallPdfServiceSalesOffer.php:30-56; :57 is the metric).

A dead synchronous route is still wired on broker + sales-man

routes/api/broker.php:132-134 and routes/api/sales-man.php:79-81 still map GET .../sales-offer/{paymentPlanId} to SalesOfferPdfController@getSalesOfferPdf — a method that no longer exists (the controller’s only public actions are generate, showGeneration, download). Hitting either route throws a “method does not exist” error. The shopper portal has no such route. This is dead config left after the synchronous path was removed; it is safe to delete those two route lines. It is logged on the knowledge-transfer tracker.

Config / env quick reference

Names and defaults only — never commit real values.

Var	Repo / location	Default	Note
PDF_SERVICE_URL	backend config/services.php:69	http://localhost:3001	Doc drift: backend CLAUDE.md says http://pdf-service:3001.
PDF_SERVICE_TOKEN	backend config/services.php:70	—	Sent as Bearer; must equal the service API_TOKEN.
PDF_SERVICE_TIMEOUT	backend config/services.php:71	120 (s)	HTTP client timeout for the outbound call.
PDF_SERVICE_GENERATE_RATE_LIMIT_PER_MINUTE	backend config/services.php:72	5	Per-user/IP throttle for generate.
SALES_OFFER_DISK	backend config/filesystems.php:27	—	Cache/store + download disk.
SALES_OFFER_EXPIRY_DAYS	backend config/filesystems.php:28	14	Generation expires_at window.
API_TOKEN	pdf-service routes/sales-offer.ts:9	—	Unset ⇒ 401 for all requests (fail closed).
PORT	pdf-service index.ts:14	3001	Service listen port.
BODY_PAYLOAD_LIMIT	pdf-service index.ts:15	20mb	Ceiling for the base64 template body.

Related

ArchitectureHow the portals, backend, CRM middleware and supporting services fit together — the big picture this flow sits inside.

Knowledge-transfer trackerThe running list of known issues and hardening items (SSRF egress allowlist, CORS, token compare, the dead route, the stale service CLAUDE.md).

Shopper buys a unitThe purchase flow that a sales offer supports — reservation state machine, card vs non-card, CRM-owned truth.

Broker submits a leadThe reference write-flow: React → Laravel → CRM middleware → Dynamics.

Verified, not guessed

Every claim on this page is traced to a file and line in the current code across backend/ and backend-pdf-service/ (see the evidence in docs-site/_evidence/flow-pdf.md). Where the code and the service’s own CLAUDE.md disagree — notably the fail-closed auth — the code is the source of truth and the doc is flagged as stale. There are no open questions in this flow; known defects are recorded on the knowledge-transfer tracker.