Survey Response Flow

A survey submission travels from the respondent’s browser through two Next.jsNext.jsReact framework used by HiveCFM Core. Handles routing, server rendering, and API routes in one bundle. routes inside hivecfm-core (the client response route, then an internal pipeline route), crosses the HTTP boundary into the Go hivecfm-hub service, and only there gets enqueued as a RiverRiverThe Go background-job queue Hub uses. Jobs are rows in Postgres, so there is no separate broker to run. job that the HubHubThe Go service that owns background processing, integrations, and the admin API. Sibling to Core.’s embedding worker drains back into Postgres.

Step explanations.

1-3. The client-facing v2 route validates the payload with zod, enforces the organization’s license and completed-response quota, then writes the Response row via Prisma. It responds 201 to the browser before any async work has run.

4-6. sendToPipeline in app/lib/pipelines.ts does NOT enqueue a RiverRiverThe Go background-job queue Hub uses. Jobs are rows in Postgres, so there is no separate broker to run. job directly; it POSTs to the app’s own internal /api/pipeline route, signed with x-api-key: CRON_SECRET. This indirection lets the response route stay thin while the pipeline route owns fan-out (webhooks, auto-tagging, follow-up emails, HubHubThe Go service that owns background processing, integrations, and the admin API. Sibling to Core. push).

7-10. The pipeline route calls pushResponseToHub (one POST per answer to ${HIVECFM_HUB_URL}/v1/feedback-records). The HubHubThe Go service that owns background processing, integrations, and the admin API. Sibling to Core.’s FeedbackRecordsService.CreateFeedbackRecord inserts the row and publishes an in-process FeedbackRecordCreated event; the registered EmbeddingProvider consumes that event and calls inserter.Insert(FeedbackEmbeddingArgs{...}) against River.

11-14. RiverRiverThe Go background-job queue Hub uses. Jobs are rows in Postgres, so there is no separate broker to run. schedules the job in Postgres. FeedbackEmbeddingWorker.Work loads the record, invokes the embedding client, and calls back into the service to upsert the embedding row. Failures retry up to embeddingMaxAttempts.

Where to look in the code

• hivecfm-core/apps/web/app/api/v2/client/[environmentId]/responses/route.ts — respondent-facing endpoint.
• hivecfm-core/apps/web/app/lib/pipelines.ts — sendToPipeline wrapper that posts to the internal pipeline route.
• hivecfm-core/apps/web/app/api/(internal)/pipeline/route.ts — fan-out route that invokes pushResponseToHub.
• hivecfm-core/apps/web/lib/hivecfm-hub/service.ts — pushResponseToHub HTTP client into the Hub.
• hivecfm-hub/internal/api/handlers/feedback_records_handler.go — Hub HTTP surface for /v1/feedback-records.
• hivecfm-hub/internal/service/feedback_records_service.go — CreateFeedbackRecord writes the row and publishes FeedbackRecordCreated.
• hivecfm-hub/internal/service/embedding_provider.go — converts FeedbackRecordCreated events into FeedbackEmbeddingArgs River inserts.
• hivecfm-hub/internal/workers/feedback_embedding.go — River worker that generates and stores the embedding.