Architecture Overview
The interactive version of this page is the ArchitectureExplorer on the Developer Hub home page — click a node to see its files and env vars. The text below is the same story in prose, for when you want to skim rather than click.
The one-sentence version
The UI layer talks to Next.jsNext.jsReact framework used by HiveCFM Core. Handles routing, server rendering, and API routes in one bundle., which talks to Postgres via PrismaPrismaThe TypeScript ORM HiveCFM uses to talk to Postgres. The schema lives at packages/database/schema.prisma. and delegates async work to the Go Hub via the River queue; Superset reads the same Postgres read-replica for dashboards, and MinIOMinIOS3-compatible object storage for survey attachments and uploads. Runs locally; swaps for real S3 in prod. holds any uploaded files.
What each service owns
| Service | Responsibility | Language | Entry point |
|---|---|---|---|
| hivecfm-core (web) | User-facing app, admin, internal and public APIs, server-rendered UI. | TypeScriptTypeScriptJavaScript with a static type system. Every HiveCFM Node service, the frontend, and the dev hub are written in it. | hivecfm-core/apps/web/app/ |
| hivecfm-hubHubThe Go service that owns background processing, integrations, and the admin API. Sibling to Core. | Background workers: embeddings, sentiment analysis, webhook dispatch, semantic search API. | Go | hivecfm-hub/cmd/api/main.go |
| Postgres + pgvectorpgvectorA Postgres extension that adds a vector column type for similarity search. Used for AI-powered survey insights. | Single source of truth for all domain data, plus vector columns for semantic search. Also hosts the RiverRiverThe Go background-job queue Hub uses. Jobs are rows in Postgres, so there is no separate broker to run. job queue tables. | — | hivecfm-core/packages/database/schema.prisma |
| RedisRedisIn-memory key-value store used for caching, sessions, and rate limiting. Runs on port 6380 locally. | Session cache, rate-limit counters, short-lived query cache. | — | hivecfm-core/packages/cache/ |
| MinIOMinIOS3-compatible object storage for survey attachments and uploads. Runs locally; swaps for real S3 in prod. | S3-compatible blob storage for survey uploads and exports. | — | hivecfm-core/packages/storage/ |
| Superset | Analyst-facing dashboards; embedded back into the app via signed guest tokens. | — | hivecfm-core/superset/ |
| MailHog (dev only) | Catch-all SMTP so outgoing email is visible without leaving the machine. | — | http://localhost:8027 |
How a request moves through the stack
- A browser hits
hivecfm-coreon port 3001. Next.js routes the request to a server component or an API route. - The handler validates input with zod, then reads or writes through Prisma against Postgres on port 5433.
- If the handler needs durable async work (score a response, dispatch a webhook, index for search), it enqueues a River job. The queue itself is just a Postgres table.
- The Go Hub polls River with
SELECT ... FOR UPDATE SKIP LOCKED, runs the worker, writes results back to Postgres, and acks the job. - The browser renders. Analytics views load a Superset iframe that reads the same Postgres.
The two round-trips that matter most are detailed on their own pages:
- Auth Flow — how
NextAuth+ SAML turn a login into a signed session cookie. - Data Flow — how a survey response gets from the browser to the Hub.
Why this shape
- One write path, many read paths. Postgres is the only place data is authoritative. Superset, the Hub, and the web all read from it.
- The queue is the seam. Synchronous API responses never wait on embeddings, webhooks, or external services — those go through River. This keeps p99 latencies predictable.
- Two languages, one database. TypeScript runs everywhere the user sees; Go runs everywhere you want predictable concurrency and throughput. Prisma and a matching Go repository layer share the same table names.
Next
- Monorepo Layout — which folders hold which of these services.
- Services & Responsibilities — the full service card for each node on the landing-page diagram.