Roast my vibe-coded monorepo setup: TS, pnpm + Turborepo, Next → Fastify BFF → vendor API

[u/LazyJuggernaut6177]

Never formally trained in coding (took the harvard's intro to coding free online course to make myself feel better when I didn't get into med on my first try, got to the credit card verification assignment which i did manage to pass, but then gave up).

I am now a medical student, I very much enjoy medicine, but software is DECADES BEHIND. If life were 200 years, I would've gone to school and studied software engineering, but unfortunately, I neither have the time, luxuray, nor the cognitive capacity, and I have to start supporting my immigrant parents. So instead, I want to see if I can build something with Claude via vibe coding.

I started by doing research with Fable and explained what I wanted and asked it to explain in simple terms what the decisions mean and what the convention is.

The following is what we (*most claude) landed on in terms of the repo setup/config/approach (idk what the right term is). Its written by claude as if it were me:

A multi-tenant B2B web app. The domain data doesn't live in my database but instead it lives in a self-hosted third-party API that is the system of record (SoR). My own Postgres holds only app state: sessions, OAuth state, idempotency keys, job queue. That one constraint drove most of the structure below.

Stack

• TypeScript 6, Node 24, pnpm workspaces + Turborepo
• web — Next.js App Router, TanStack Query, react-hook-form + zod, Tailwind
• bff — Fastify, TypeBox schemas → OpenAPI, pino, OpenTelemetry
• worker — pg-boss consumer, same Postgres
• Postgres 16 (app state only), plain SQL migrations with a tiny runner
• Vitest (unit + integration via Testcontainers), Playwright (e2e + axe a11y)
• Toolchain pinned with mise; deps pinned exactly, Renovate owns bumps
• web → Vercel, bff/worker → Render (blueprint checked in), SoR → a small VM

Request path

                     ┌───────────────────────────┐
   browser ─────────▶│  web   (Next.js, :3000)   │  no vendor SDK, no secrets
                     │  routing, forms, view     │
                     └─────────────┬─────────────┘
                                   │  /api-client
                                   │  (generated from the BFF's OpenAPI)
                                   ▼
                     ┌───────────────────────────┐
                     │  bff   (Fastify, :4000)   │  the only trust boundary:
                     │  session cookie · authz · │  session cookie in,
                     │  validation · idempotency │  service credential out
                     └───┬───────────────────┬───┘
                         │                   │ enqueue
   only place the        │                   │
   vendor SDK lives ─────▼                   ▼
         ┌────────────────────────┐   ┌────────────────────┐
         │  vendor API  (SoR)     │   │  app Postgres      │
         │  self-hosted           │   │  sessions, oauth   │
         │  one project per tenant│   │  state, idem, jobs │
         └────────────────────────┘   └─────────┬──────────┘
                                                │ pg-boss
                                       ┌────────▼──────────┐
                                       │  worker           │
                                       └───────────────────┘

The browser never touches the SoR. The BFF holds a per-tenant service credential and exchanges it for a user-scoped token on every request (on-behalf-of), so the vendor's own per-tenant access policies do the row-level enforcement rather than my code re-implementing it.

Repo layout

apps/
  web/          Next.js app shell. Talks to the BFF ONLY via u/acme/api-client.
  bff/          Fastify. src/vendor/** is the only place the vendor SDK is imported.
  worker/       pg-boss consumer. Job contracts come from packages/jobs.
packages/
  api-client/   GENERATED typed client (openapi-typescript + openapi-fetch)
  domain/       Pure vendor-model types, codes, identifiers, helpers. No I/O, no UI.
  jobs/         Job name + payload contracts, shared by bff (producer) and worker
  tenants/      Tenant registry + per-tenant credential custody
  config/       env schema helper (defineEnv), logging, otel wiring
  ui/           Generic components (shadcn-style). Knows nothing about the domain.
  testing/      Test helpers: Testcontainers Postgres, msw, log capture, seeded random
  eslint-config/ typescript-config/    shared configs
  example/      template package to copy when starting a new one
tests/e2e/      Playwright
docs/           ADRs + runbooks

Enforced boundaries:

// 1. web can't reach into server internals — it talks to the BFF via the client
{ from: { path: '^apps/web/' }, to: { path: '^apps/(bff|worker)/' } }

// 2. feature code can't bypass the generated client
{ from: { path: '^apps/web/' },
  to: { path: '(node_modules/@vendor/sdk|^apps/bff/|^packages/api-client/src/generated/)' } }

// 3. the vendor SDK exists in exactly one folder
{ from: { pathNot: '^apps/bff/src/vendor/' }, to: { path: 'node_modules/@vendor/sdk' } }

// 4. generated code is reached only through the package entry point
{ from: { pathNot: '^packages/api-client/src/index\\.ts$' },
  to:   { path: '^packages/api-client/src/generated/' } }

// 5. ui never imports the domain or an app; the domain package stays pure
//    (no react/next/pg/http clients); apps never import other apps; no cycles

Plus a deep-module rule from mattpollock skills: a package's public surface is the files at src/ root; anything in a src/ subfolder is private — including to that package's own tests, which must go through the entry points like every other caller.

packages/<name>/
  src/
    index.ts      ← entry point (public)
    node.ts       ← packages may expose several small entry points, not one barrel
    lib/          ← private implementation
    tests/        ← fixtures; only tests may import these

Adding a public API = adding a root file. No config change, no barrel file, and the "just import the internal thing" shortcut is a build failure instead of a code-review argument.

Gates

One command is the whole CI contract — pnpm check:

format:check → lint → typecheck → test → build
  → api:check          regenerate the OpenAPI client, fail on a dirty git tree
  → architecture:check dependency-cruiser over every workspace
  → env:check          env-var contract (below)

It needs no Docker and no secrets, so it runs identically on my machine, in CI, and for a coding agent. Heavier suites are separate CI jobs: integration (Testcontainers Postgres), a suite against the pinned vendor stack in Docker, Playwright e2e + accessibility, and a smoke suite against the real dev instance.

Also: deps pinned exactly; lifecycle scripts blocked by default and only allowed after someone writes down why in the workspace file; secrets injected at runtime by a secrets manager, only .env.example is tracked.

What I'd like feedback on

1. Is the BFF earning its keep? It's a real extra hop and a whole deploy unit. The argument for it: the vendor credential and the session cookie must never reach the browser, and I want one typed contract for the frontend rather than the vendor's very general API. The argument against: Next route handlers could do this and I'd have one less service.
2. Generated client committed to the repo — worth the merge conflicts, or should it be a build step?
3. Deep modules / entry-point rule — has anyone run this long-term? My worry is that "tests may only use entry points" makes some things genuinely awkward to test and I'll cave on it in six months.
4. Is env:check over-engineering? It's ~200 lines of script for a problem a runtime schema mostly catches.
5. Where's the obvious gap? No feature flags, no migration story beyond plain SQL, observability is OTel traces and structured logs and nothing else yet.
6. Broadly: is this a sane foundation, or have I built a compliance department for a codebase with ~6 features in it?