ClusterBid

Taking a Go-and-Next.js inference-cloud platform from monorepo checks to a real-host k3s UAT — without mistaking pre-production proof for production.

Context

ClusterBid is a pre-production, region-pinned inference-cloud platform. Its repository puts Go services and shared packages, Next.js clients, TypeScript packages, Helm charts, and infrastructure code under one review surface. That shape is useful: a gateway change can move with its console contract and deployment values. It also creates a harder standard for what “green” means.

My role was engineering advisor across process and platform. The work here was not to claim a commercial launch. It was to make the repository and its deployment path tell the truth about what had been implemented, what had been exercised, and what was still mocked.

Problem

A root command can look successful while checking only one part of a mixed repository. A Go workspace cannot honestly be covered by an undifferentiated go vet ./... at the root; each module needs its own invocation. The Next.js clients and TypeScript packages carry their own build, lint, and test contracts. A quality gate that treats those trees as one language will either miss work or become too noisy to trust.

Local verification was only half the problem. The first real-host UAT deploy surfaced assumptions that local and rendered-chart checks had not: stateful database containers could not start with a blanket capability drop, isolated image builds needed complete per-service module sums, and the console's browser-origin guard needed the environment's own public URL at runtime. Passing tests was necessary. Feeding deployment findings back into source was the real closure condition.

Approach

The fix had four layers.

Makefile as the routing layer. The root Makefile enumerates the Go workspace modules and routes vet, lint, race tests, and coverage through each module. Separate TypeScript targets build, lint, and test the client and package trees. quality-gate-local composes those checks with repository linting, so one command can be broad without pretending every subtree uses the same tool.

Native git-boundary checks. The repository has no root application package, so .githooks/commit-msg and .githooks/pre-push carry the conventional-commit and Trellis process-gate contracts without making a nested Next.js client own repository-wide policy. The pre-push hook blocks direct main pushes and delegates the actual verification to the same gate used elsewhere.

UAT as a separate contract. A dedicated Helm overlay and bring-up runbook describe the single-VM k3s shape explicitly: one-node NATS settings, environment-specific public URLs, mock inference, local Stripe, and the secrets the deployment does and does not require. The UAT hosts use publicly valid TLS, but the workload remains a pre-production environment.

Deployment findings returned to source. The chart, image-build, and runtime-origin fixes were persisted rather than left as one-off cluster patches. That makes the next render and upgrade reproduce the tested shape instead of depending on operator memory.

What reached UAT

A real-host k3s UAT exposed the marketing site, console, and API gateway over TLS. A mock-inference request exercised the gateway, metering, and billing path, with spend and reconciliation checks observed in that environment. The exercise also produced durable source fixes for the chart and console runtime configuration.

That is meaningful engineering evidence, but it is deliberately narrower than a production result. The inference runner was in mock mode, Stripe used the in-repository local provider, and the fine-tuning storage path remained outside the UAT scope.

Trade-offs

One repository over service-by-service repositories. Cross-surface changes stay reviewable together, at the cost of maintaining an explicit routing layer for validation.

Mock providers inside UAT. Mock inference and local Stripe let the team test service topology, request flow, metering, billing, and browser contracts without pretending GPU or payment-provider readiness. The trade is intentional: topology confidence now, provider proof later.

Single-node UAT over production-shaped high availability. The environment was sized to expose integration and deployment defects economically. Replica and storage decisions in that overlay are UAT constraints, not production recommendations.

Honest scope

This case study is about UAT and pre-production engineering. It makes no claim of customer traffic, adoption, revenue, a production deployment, live GPU inference, or live Stripe processing. The role claim is limited to engineering advisor for process and platform, and the technical claims stop at repository evidence plus the recorded UAT verification.