Code walkthroughs

Architecture diagrams show you how the boxes connect. These walkthroughs show you what the code inside each box actually does.

Each walkthrough takes one real file from hivecfm-core/ or hivecfm-hub/, breaks it into 4–6 slices, and explains each slice in its own right before moving on. The code is pulled verbatim at build time by scripts/sync-code-samples.ts — if upstream shifts, the sync step prints a drift warning and re-emits the new content. Nothing here is transcribed by hand.

Available walkthroughs

• NextAuth & session flow. The entry point for every authenticated request. How authOptions works, what the JWT/session/signIn callbacks do, and why audit logging is threaded through them.
• Survey response persistence. The hottest write path in Core. From request body parse, through Zod validation, license and quota guards, Prisma.create, to the pipeline fan-out.
• Hub Go worker (embeddings). A full River worker. Job args, Work() lifecycle, retry vs. terminal error classification, and how metrics and logs are emitted.

How to read a walkthrough

Read top-to-bottom. Skipping slices is fine once you have the shape, but the first time through, let each paragraph land before the nextNext.jsReact framework used by HiveCFM Core. Handles routing, server rendering, and API routes in one bundle. code block — the commentary is where the concepts live.

Every slice has a “View full file” link in its header. That opens the real file on GitHub at the exact line range, so once you want the whole picture you are one click away.

When to write a new one

Any time you have watched two people get stuck on the same file, it is a walkthrough candidate. Add an entry to data/code-samples.yaml, write an MDX page that interleaves <CodeWalkthrough> blocks with prose, and re-run pnpm run sync.