Glossary

Jargon you’ll see in HiveCFM. Terms link back here when used inline — use <Term name="...">word</Term> in MDX to surface a hover-definition tooltip that points at the entry below.

Stack

Next.js

Next.js is the React framework HiveCFM Core is built on. It combines the routing, server-side rendering, and API-route pieces a .NET team would recognise from ASP.NET Core MVC plus Web API, but for TypeScript and React. Pages live under the app or pages directory and URLs follow the folder structure automatically. Core runs on port 3001 locally.

Reference: https://nextjs.org/docs

pnpm

pnpm is a drop-in alternative to npm. It stores each package version once on disk and symlinks it into every project's node_modules, which saves space and speeds up installs in a monorepo. Commands mirror npm — pnpm install, pnpm run dev — and workspaces are first-class, so hivecfm-core's apps and packages install together.

Reference: https://pnpm.io

Prisma

Prisma is a typed query builder and migration tool for Postgres. The schema file describes every table and relation; running the generator produces a fully-typed client you import from @prisma/client. Think of it as a blend of Entity Framework and a migrations tool, except the schema is the source of truth rather than the C# classes.

Reference: https://www.prisma.io/docs

React

React is the UI library underneath Next.js. You write components as TypeScript functions that return JSX (HTML-like markup). State flows through hooks like useState and useEffect. The closest .NET analogy is Blazor components, but React runs on the client by default and the server rehydrates it.

Reference: https://react.dev

Turbo

Turborepo runs scripts across a monorepo while caching outputs. When you run turbo run build, it only rebuilds packages whose inputs changed and reuses cached artifacts for the rest. It is similar to how MSBuild skips projects whose outputs are up to date, but applied to every package in the repo.

Reference: https://turborepo.com/docs

TypeScript

TypeScript adds compile-time types on top of JavaScript. It catches the shape-mismatch bugs a C# developer would expect the compiler to catch. HiveCFM uses strict mode everywhere — no implicit any, null and undefined tracked separately. The compiler strips types and emits plain JavaScript; nothing runs TypeScript at runtime.

Reference: https://www.typescriptlang.org

Auth

JWT

A JWT (JSON Web Token) is a base64-encoded JSON payload with a cryptographic signature. The Core app signs it when a user logs in, and downstream services verify the signature to trust the claims inside (user id, org, role) without a database lookup. Keep the signing key secret — whoever holds it can mint valid tokens.

NextAuth

NextAuth (now called Auth.js) plugs into Next.js to handle login flows, session cookies, and provider integrations (Google, GitHub, SAML). The team configures it once in Core; every protected route uses its session helpers. It is the Node equivalent of ASP.NET Identity plus the external-provider middleware.

Reference: https://next-auth.js.org

SAML

SAML (Security Assertion Markup Language) is the single sign-on protocol most enterprise customers speak. The identity provider signs an XML assertion describing who the user is; HiveCFM validates the signature and creates a session. It is older and chattier than OIDC, but enterprise IT still mandates it.

Data

MinIO

MinIO is an open-source object store that speaks the Amazon S3 API. HiveCFM uses it for file uploads — survey attachments, logos, exported reports. The app code uses the AWS SDK and does not care whether it is talking to MinIO or real S3, which keeps local dev self-contained.

pgvector

pgvector extends Postgres with a vector column type and distance operators. HiveCFM stores embedding vectors for survey responses in a pgvector column and runs nearest-neighbour queries for clustering and retrieval. It keeps the vector store in the same database as the relational data, so there is no separate service to operate.

PostgreSQL

Postgres is the primary database. Locally it runs in Docker on port 5433 (5432 was already taken on this host). Schema is managed by Prisma migrations; you rarely write raw SQL in app code, but you will open psql for debugging. Postgres differs from SQL Server in small syntax ways (double-quoted identifiers, no TOP, SERIAL not IDENTITY) but the mental model is the same.

Reference: https://www.postgresql.org/docs/

Redis

Redis is an in-memory data store. HiveCFM uses it for short-lived caches, session data, and rate-limit counters. Locally it is on port 6380 (6379 was in use on this host). It is the rough equivalent of Microsoft's Azure Cache for Redis or an in-memory distributed cache.

HiveCFM

Campaign

A Campaign groups one or more Surveys with a schedule and an audience. If a product team wants to run the same NPS survey every quarter to a rolling list of customers, they model it as a Campaign. Responses roll up to the Campaign for longitudinal reporting.

Hub

Hub is the Go service in the HiveCFM stack. Where Core (Next.js) handles the user-facing web app, Hub handles the heavy lifting — long-running jobs, third-party integrations, admin endpoints. It talks to the same Postgres database and exposes its own OpenAPI surface.

Response

A Response is a single submission to a Survey — one row per respondent, with child rows per answered question. All of HiveCFM's analytics, exports, and dashboards aggregate over Responses. Responses are immutable once submitted; edits create a new row with a revision.

River

River is a background-job library for Go that stores jobs in Postgres rather than a dedicated broker. Hub enqueues work — send email, process a response, run an export — and River workers pick the jobs up. Because the queue is just a table, you can see pending work with a normal SQL query.

Reference: https://riverqueue.com

Survey

A Survey is the top-level thing HiveCFM creates, edits, and distributes. It owns the list of questions, the branching logic, the styling, and the audience rules. When a respondent answers a survey they generate a Response. Many surveys belong to a Campaign.

Ops

Docker Compose

Docker Compose declares a set of containers in a docker-compose.yml file and starts them together. HiveCFM uses it for every local dependency — Postgres, Redis, MinIO, MailHog — so a new developer runs one command and has the whole stack up. In production the services run on managed platforms instead; Compose is dev-only.

Hydration

When Next.js renders a page on the server it sends plain HTML to the browser so the content shows up fast. React then runs on the client, walks the same component tree, and attaches event handlers — that second pass is hydration. A hydration mismatch means the server and client produced different trees, which usually breaks interactivity and shows a warning in the console.