🪢 Langfuse 图解教程Langfuse Visual Guide 第一部分 · 宏观全景Part 1 · The Big Picture 04 / 55
第一部分 · 宏观全景Part 1 · The Big Picture

项目全景地图(monorepo 与窄腰)Project map (monorepo & narrow waist)

前三课讲的是「数据长什么样」,这一课换个维度:代码住在哪里。Langfuse 是一个 monorepo(单仓库多工程), 所有东西都在 langfuse/langfuse 一个仓库里,但内部分成几个各司其职的「工作区」。把这张地图记在心里,后面任何一课说「打开 web/src/...」或「这段逻辑在 worker 里」,你都能立刻知道它在哪、为什么在那。

🔌 生活类比
把这个仓库想成一座大型购物中心:整座楼是一个 monorepo,里面有几家独立店铺—— web 是面向顾客的门店(人来人往、要快、随时营业),worker 是后场的加工车间(埋头干重活、可以排队慢慢做)。 而 packages/shared 是中央仓库:所有店铺的货(数据模型、数据库访问、队列契约)都从这里取,但中央仓库从不反过来依赖某家店铺。 大家在同一栋楼里,共用水电(构建工具),却又边界清晰、各自营业。逛这座楼之前先拿到这张「楼层导览图」,后面无论去哪家店,你都不会迷路。
langfuse/langfuse 顶层目录地图 web/ Next.js 应用 UI · tRPC · 公共 REST API worker/ BullMQ 队列消费 摄取·评估·导出·删除… ee/ 企业版功能 license 校验 packages/shared/ · 共享内核(窄腰) domain 领域模型 · server 仓储/CH/队列 · prisma schema · clickhouse 迁移 被 web 与 worker 共用,自己谁都不依赖 fern/ · 公共 API 契约定义 用 Fern 描述 REST API,生成 generated/ 客户端 generated/ · 自动生成(勿手改) 由 Fern 生成的 API 客户端
顶层就这几块:web(门店)和 worker(车间)是两个运行时容器,都向上依赖 packages/shared(中央仓库 / 窄腰);ee 是企业功能、被 web 引用;fern 定义公共 API 契约并生成 generated 客户端。记住这张图,后面所有「文件在哪」的问题都有了坐标系。
谁能 import 谁:窄腰依赖矩阵 规则:行(importer)→ 列(被依赖包);✓ 表示允许 import → web worker @langfuse/shared @langfuse/ee web (Next.js) — ✓ ✓ worker (队列消费) — ✓ @langfuse/shared — @langfuse/ee ✓ —
窄腰依赖矩阵(依据 repo 的 .agents/AGENTS.md 依赖方向规则):箭头永远指向 @langfuse/shared 这个「窄腰」——web、worker、@langfuse/ee 都依赖它,而它不反向依赖任何业务包。空白格=不允许 import,对角线=自身。这把「谁能用谁」从口头约定变成一眼可查的结构。

稍微展开一下两个运行时各自在忙什么,你会更有体感。web 是那个你浏览器里打开的 Next.js 应用,它干三件事:渲染界面、 给界面提供类型安全的内部 API(tRPC,第 21 课)、以及给外部 SDK 提供公共 REST API(web/src/pages/api/public,第 27 课)—— 摄取事件的入口就在这里。worker 则是个没有界面的后台进程,它订阅几十个 BullMQ 队列,把所有重活、慢活、可重试的活都揽下来: 把摄取的事件合并写进 ClickHouse、跑 LLM 评估、导出数据、删除项目……(第三部分起逐个讲)。一句话:web 负责「快进快出」,worker 负责「埋头苦干」, 两者通过中间的 Redis 队列解耦——这也正是下一课「双存储」和第三部分「摄取链路」要展开的主线。

一个仓库,四个工作区

Langfuse 用 pnpm workspaces 把一个仓库切成几个独立可构建的包。根目录的 pnpm-workspace.yaml 一行行列出了它们:

pnpm-workspace.yamlworkspaces
packages:
  - "web"          # Next.js 应用(UI + tRPC + 公共 REST API)
  - "worker"       # 队列消费者,后台处理
  - "packages/**"  # 共享包,主要是 packages/shared
  - "ee"           # 企业版功能

packages/** 下其实不止 shared 一个,还有 config-eslint、config-typescript、 eslint-plugin 这些「工具配置包」;但真正承载业务的共享内核是 packages/shared——它就是上图里的中央仓库。 为什么要拆成工作区而不是一个大文件夹?因为这样每个包能独立声明依赖、独立构建、独立测试,pnpm 还能在它们之间做符号链接, 让 web 直接 import ... from "@langfuse/shared" 用上最新代码,不必发版。 这点对开发体验影响很大:你在 packages/shared 里改一个类型,web 和 worker 的编辑器会立刻飘红提示哪里要跟着改—— 等于把「契约变更」的影响在编码阶段就暴露出来,而不是等到运行时才报错。

依赖方向:为什么是「窄腰」

四个工作区之间不是随便互相引用的,而是有一条严格单向的依赖规则(写在 .agents/AGENTS.md 里):

.agents/AGENTS.mdDependency direction
- web    -> @langfuse/shared, @langfuse/ee
- worker -> @langfuse/shared
- ee     -> @langfuse/shared
- @langfuse/shared -> no imports from web, worker, or ee
窄腰:所有依赖箭头都指向 shared,没有回头箭头 web worker ee packages/shared 领域模型 · 仓储 · 队列契约 · DB 访问 shared 不依赖上面任何一个 → 它是地基,不是消费者
「窄腰」(narrow waist):把所有人都要用的东西收进一个谁都不反向依赖的薄层。web/worker/ee 像沙漏的上半,shared 是中间最细的「腰」,再往下是数据库。好处是:两个容器各自独立演进、独立部署,却共用同一套领域模型与队列契约,契约不会漂移。

这条纪律为什么重要?因为 web 和 worker 是两种完全不同的负载:web 要面向用户、低延迟、可随时重启;worker 要啃重活、可重试、按队列伸缩。 如果让它们互相直接引用,改一个就可能牵连另一个,部署也会绑死。把共享的东西收进 shared、并规定只能向下依赖, 就等于在两个容器之间立了一道清晰的契约墙:队列里传什么、数据库表长什么样,都由 shared 这一处定义(比如队列负载就归 packages/shared/src/server/queues.ts 管)。两边照着同一份契约各干各的,互不踩脚。

举个这条规则挡住的真实 bug:假设没有窄腰,worker 里图省事直接 import 了 web 的某个工具函数。某天 web 为了改界面重构了那个函数、 顺手改了它的参数——结果 worker 在毫不知情的情况下被改坏了,可能要到线上摄取出错才发现。而在窄腰规则下,worker 根本不允许依赖 web; 两边唯一的「共同语言」是 shared 里那份明确的契约。想共享逻辑?那就把它下沉到 shared,让它成为受契约约束的一等公民,而不是从隔壁悄悄借用。 「依赖只能向下」这一条,本质是在用编译器帮你挡住跨容器的隐式耦合。

Turbo 怎么把它们编排起来

多个工作区的构建、测试、lint 由 Turbo 统一编排(根目录 turbo.json)。它最有用的两件事是任务依赖图和缓存:

db:generate
先生成 Prisma 客户端
→
^build
先构建被依赖的包
→
build
再构建本包
⚡
cache
没变就直接命中缓存

看 turbo.json 里 build 任务的定义:"dependsOn": ["db:generate", "^build"]——意思是「构建任何一个包之前, 先生成数据库客户端、并先把它依赖的包(^ 表示上游依赖)构建好」。于是你只要 pnpm build,Turbo 就会自动算出正确顺序、 把能并行的并行、能缓存的跳过("cache": true)。这就是为什么在一个有几十个包的大仓库里,改一行代码也不必全量重建。

把窄腰和 Turbo 合起来,看一个具体的连锁反应:假设你要给 trace 加一个字段。你只需在 packages/shared/prisma/schema.prisma 改一处、再在 domain/traces.ts 改一处——一次 db:generate 重新生成 Prisma 客户端,web 和 worker 立刻都看到新字段,因为它们都从同一个 @langfuse/shared 取类型。整件事在一个 PR 里完成, CI 一起跑通。要是分成三个仓库,这同一个改动得发三次版、改三处依赖、还要祈祷三边版本对得上——这就是「原子地一起改」的实际意义。

🧩 polyrepo(分仓)

web/worker/shared 各一个仓。改一个共享结构 → 跨仓发版、对版本、易漂移。好处是各仓更小、更独立。

📦 monorepo(Langfuse 的选择)

一个仓装下全部。共享改动一个 PR 原子完成、CI 一起验。代价:仓更大、要靠 Turbo 管构建缓存。

缓存这件事对持续集成(CI)尤其值钱。一个几十包的大仓,如果每次 PR 都把所有包从头 build + lint + test 一遍,CI 会慢到没法用。 Turbo 会给每个任务的输入算一个指纹(源码 + 依赖 + 配置),只要指纹没变,就直接复用上次的输出、整段跳过。于是改了 worker 的一个文件, web 那些没被波及的构建/测试就命中缓存、秒过。配上远端缓存,团队成员之间还能共享构建结果。这就是大仓也能保持 CI 快的秘诀—— 也是「用 monorepo」这个选择能成立的工程前提:没有好的缓存,monorepo 的构建成本会劝退所有人。

Turbo 缓存:给每个任务的输入算指纹,没变就整段跳过 改 worker 一个文件 Turbo 算指纹 = 源码 + 依赖 + 配置 逐包比对 worker · 指纹变 → 重建 web · 指纹没变 → 缓存命中(秒过) shared · 没变 → 命中 远端缓存:团队成员间共享构建结果 —— 几十包的大仓 CI 也能快

每个工作区里有什么

最后给你一张「高频目录速查表」,后面的课会反复回到这些位置:

位置放什么
web/src/pagesNext.js 页面 + API 路由(含 api/public 公共 REST、api/trpc)
web/src/server/apitRPC 的 root 路由、context、中间件(第 21 课)
web/src/features按功能切分的「纵切片」目录(traces、evals、prompts…约几十个)
worker/src/queues各个 BullMQ 队列的消费者(ingestion、eval、export…)
worker/src/services核心服务(IngestionService、ClickhouseWriter)
packages/shared/src/domain领域模型(traces/observations/scores…)
packages/shared/src/server仓储层、ClickHouse/Redis/S3 客户端、队列契约
packages/shared/prismaPostgres schema 与迁移
packages/shared/clickhouseClickHouse 迁移(宽事件表)

表里没列、但值得单独一提的是 fern/ 和 generated/。Langfuse 的公共 REST API 不是手写的,而是先在 fern/ 里用 Fern 把「有哪些端点、收什么参数、返回什么」声明出来,再自动生成 generated/ 下的 API 客户端代码。 所以 generated/ 是构建产物,绝不能手改——改了下次生成就被覆盖。这也是为什么改公共 API 时要同步更新 fern/ 源(第 27 课)。 这种「契约先行、代码生成」的做法,保证了 API 文档、服务端、各语言 SDK 三者始终对得上。带着这张全景地图,下一课我们就深入支撑这一切的双存储:为什么偏要 Postgres 加 ClickHouse 一起上。

🎯 设计取舍
为什么用 monorepo + 窄腰,而不是把 web/worker/shared 拆成三个独立仓库(polyrepo)? 因为 web 和 worker 高度共享领域模型与队列契约, 如果分仓,每次改一个数据结构就要跨仓发版、对版本,极易出现「web 以为字段叫 A、worker 还在用 B」的漂移。monorepo 让三者原子地一起改—— 一个 PR 同时改 shared 的契约和两边的用法,CI 一起验。代价是仓库更大、构建工具(Turbo)更复杂, 但对一个契约高度耦合的系统,这笔账划算。换个角度说:分仓省的是「单仓的复杂度」,monorepo 省的是「跨仓协调的复杂度」——而后者往往才是真正拖慢团队的那个。
🎯 本课要点
  • Langfuse 是 pnpm + Turbo 的 monorepo:web(门店)、worker(后场车间)两个运行时 + packages/shared(中央仓库)+ ee。
  • 窄腰:依赖严格单向 web/worker/ee → shared,而 shared 谁都不依赖;契约(领域模型、队列)集中在 shared。
  • Turbo 用任务依赖图(build 依赖 db:generate + ^build)+ 缓存,让大仓也能快速、增量构建。
  • 记住高频目录:web/src/{pages,server,features}、worker/src/{queues,services}、packages/shared/src/{domain,server}——这是后面查代码的速查表。
  • 选 monorepo 是为了让契约高度耦合的 web/worker/shared 能原子地一起改,避免跨仓版本漂移与协调成本。

🧪 自测 · 想一想为什么这么设计

1. Langfuse 规定依赖只能 web/worker/ee → shared,而 shared 不依赖任何一方。这条“窄腰”规则最主要的好处是什么?
  1. 让 shared 包能直接调用 web 的 React 组件
  2. 让构建变慢以便缓存
  3. 两个容器各自独立演进/部署,却共用同一套领域模型与队列契约,契约集中在一处定义、不会漂移
  4. 强制 web 和 worker 跑在同一个进程里
看答案与解析 点击展开
答案:C。web(低延迟、面向用户)和 worker(重活、可重试)是两种负载;让它们互相直接依赖会彼此牵连。把共享内容收进谁都不反向依赖的 shared,并只许向下依赖,就在两容器间立了契约墙——队列传什么、表长什么样都由 shared 一处定义。
2. turbo.json 里 build 任务写着 "dependsOn": ["db:generate", "^build"]。这表示什么?
  1. 构建任何包之前,先生成 Prisma 客户端,并先构建它依赖的上游包(^ 表示上游);Turbo 据此算出顺序、并行、并跳过缓存命中的部分
  2. db:generate 必须手动在 build 之后运行
  3. build 任务永远不能被缓存
  4. ^build 表示构建下游的包
看答案与解析 点击展开
答案:A。dependsOn 声明任务依赖图:db:generate 先于 build(要先有 Prisma 类型),^build 表示先构建上游依赖包。于是一条 pnpm build 就能让 Turbo 自动排序、并行、并对没变的包命中缓存——大仓也能增量构建。
3. 给 trace 加一个字段,在 Langfuse 的 monorepo 里大致怎么落地?
  1. 在三个独立仓库各发一次版,再手动对版本
  2. 改 prisma/schema.prisma 与 domain/traces.ts,db:generate 后 web 和 worker 都从同一个 @langfuse/shared 拿到新类型,一个 PR、CI 一起验
  3. 必须先删掉旧的 ClickHouse 表
  4. 只能改 web,worker 不受影响
看答案与解析 点击展开
答案:B。这正是 monorepo + 窄腰的价值:共享结构改一处,web/worker 都从 @langfuse/shared 取,原子地在一个 PR 完成、一起过 CI。分仓则要跨仓发版对版本、易漂移。
💭 发散思考(没有标准答案,动手或动脑想想)
  • 你自己的项目如果同时有“面向用户的服务”和“后台 worker”,你会把它们放一个仓还是分仓?参考 Langfuse 的窄腰,你会把哪些东西抽进一个共享层?

The first three lessons covered "what the data looks like"; this one switches axes: where the code lives. Langfuse is a monorepo (one repo, many projects) — everything sits in the single langfuse/langfuse repo, split internally into a few purpose-built "workspaces". Hold this map in mind and whenever a later lesson says "open web/src/..." or "this logic is in worker", you'll instantly know where it is and why.

🔌 Analogy
Think of the repo as one big shopping mall: the whole building is one monorepo housing a few independent shops — web is the customer-facing storefront (busy, fast, always open), worker is the back-of-house workshop (heads-down heavy lifting, can queue and take its time). And packages/shared is the central warehouse: every shop draws its goods (domain models, DB access, queue contracts) from here, but the warehouse never depends back on any shop. All under one roof, sharing utilities (build tools), yet cleanly bounded and independently run. Grab this "floor directory" before you wander the mall and you won't get lost no matter which shop you visit.
langfuse/langfuse top-level map web/ Next.js app UI · tRPC · public REST API worker/ BullMQ queue consumer ingest·eval·export·delete… ee/ enterprise features license check packages/shared/ · shared core (narrow waist) domain models · server repos/CH/queues · prisma schema · clickhouse migrations used by web & worker; depends on neither fern/ · public API contract describes the REST API; generates generated/ clients generated/ · auto-generated (don't edit) API clients produced by Fern
Just a few top-level blocks: web (storefront) and worker (workshop) are two runtime containers, both depending up on packages/shared (central warehouse / narrow waist); ee holds enterprise features used by web; fern defines the public API contract and generates the generated clients. Remember this and every "where is file X" question has a coordinate system.
Who may import whom: the narrow-waist matrix rule: row (importer) → column (imported package); ✓ = allowed imports → web worker @langfuse/shared @langfuse/ee web (Next.js) — ✓ ✓ worker (consumers) — ✓ @langfuse/shared — @langfuse/ee ✓ —
The narrow-waist matrix (per the repo .agents/AGENTS.md dependency rule): arrows always point toward the @langfuse/shared "narrow waist" — web, worker and @langfuse/ee all depend on it, while it depends back on no business package. Blank cell = not allowed; diagonal = self. This turns "who may use whom" from a verbal convention into a structure you can check at a glance.

Unpacking what each runtime actually does makes it tangible. web is the Next.js app you open in your browser; it does three things: render the UI, serve that UI a type-safe internal API (tRPC, L21), and serve external SDKs a public REST API (web/src/pages/api/public, L27) — the ingestion entry point lives here. worker is a headless background process that subscribes to dozens of BullMQ queues and takes on all the heavy, slow, retryable work: merge ingested events into ClickHouse, run LLM evals, export data, delete projects… (covered from Part 3 on). In a line: web does "fast in, fast out", worker does "heads-down grind", decoupled by a Redis queue in the middle — exactly the through-line of the next lesson ("dual store") and Part 3 ("the ingestion path").

One repo, four workspaces

Langfuse uses pnpm workspaces to slice one repo into independently buildable packages. The root pnpm-workspace.yaml lists them line by line:

pnpm-workspace.yamlworkspaces
packages:
  - "web"          # Next.js app (UI + tRPC + public REST API)
  - "worker"       # queue consumer, background processing
  - "packages/**"  # shared packages, mainly packages/shared
  - "ee"           # enterprise features

Under packages/** there's more than just shared — also "tooling config" packages like config-eslint, config-typescript, eslint-plugin; but the real business shared core is packages/shared — the central warehouse in the figure. Why split into workspaces instead of one big folder? Because each package can then declare deps, build and test independently, and pnpm symlinks them so web can simply import ... from "@langfuse/shared" against the latest code with no publishing step. This hugely helps the dev experience: change a type in packages/shared and the editors in web and worker light up red immediately showing what must follow — surfacing the impact of a "contract change" at coding time rather than at runtime.

Dependency direction: why a "narrow waist"

The four workspaces don't reference each other freely — there's a strictly one-way dependency rule (written in .agents/AGENTS.md):

.agents/AGENTS.mdDependency direction
- web    -> @langfuse/shared, @langfuse/ee
- worker -> @langfuse/shared
- ee     -> @langfuse/shared
- @langfuse/shared -> no imports from web, worker, or ee
narrow waist: every arrow points to shared, none come back web worker ee packages/shared domain · repositories · queue contracts · DB access shared depends on none above → it's the foundation, not a consumer
The "narrow waist": collect what everyone needs into a thin layer that nothing depends on backwards. web/worker/ee are the top of an hourglass, shared is the thin "waist", and below is the database. The payoff: the two containers evolve and deploy independently while sharing one set of domain models and queue contracts, so the contract can't drift.

Why does this discipline matter? Because web and worker are two very different workloads: web faces users, wants low latency, must restart anytime; worker chews heavy jobs, must be retryable, scales by queue. Let them import each other directly and changing one can entangle the other, binding their deployments. Collecting shared things into shared and allowing only downward dependencies erects a clean contract wall between the two containers: what goes through queues, what the DB tables look like — all defined in one place (queue payloads, for instance, belong to packages/shared/src/server/queues.ts). Both sides work to the same contract without stepping on each other.

A concrete bug this rule blocks: imagine no narrow waist, and worker lazily imports a utility function from web. One day web refactors that function to change the UI and tweaks its parameters — and worker breaks without anyone knowing, maybe surfacing only as a production ingestion error. Under the narrow-waist rule, worker simply cannot depend on web; their only "shared language" is the explicit contract in shared. Want to share logic? Sink it down into shared so it becomes a contract-bound first-class citizen, not something borrowed quietly from next door. "Dependencies only go down" is really using the compiler to block implicit cross-container coupling.

How Turbo orchestrates them

Build, test and lint across workspaces are orchestrated by Turbo (root turbo.json). Its two most useful tricks are the task dependency graph and caching:

db:generate
generate Prisma client first
→
^build
build upstream deps first
→
build
then build this package
⚡
cache
unchanged → cache hit

Look at the build task in turbo.json: "dependsOn": ["db:generate", "^build"] — meaning "before building any package, generate the DB client and first build the packages it depends on (^ = upstream deps)". So a single pnpm build lets Turbo compute the right order, parallelize what it can, and skip what's cached ("cache": true). That's why, in a big repo of dozens of packages, changing one line doesn't force a full rebuild.

Put the narrow waist and Turbo together and watch a concrete chain reaction: say you add a field to the trace. You edit one spot in packages/shared/prisma/schema.prisma and one in domain/traces.ts — one db:generate regenerates the Prisma client and both web and worker immediately see the new field, because both pull types from the same @langfuse/shared. The whole thing lands in one PR, verified together by CI. Split into three repos and this same change needs three releases, three dependency bumps, and a prayer that versions line up — that's the practical meaning of "change atomically".

🧩 polyrepo (split)

web/worker/shared each a repo. Change a shared structure → cross-repo releases, version juggling, easy drift. Upside: smaller, more independent repos.

📦 monorepo (Langfuse's choice)

one repo holds it all. A shared change is one atomic PR, verified together by CI. Cost: bigger repo, Turbo to manage build caching.

Caching is especially valuable for CI. In a dozens-of-packages repo, rebuilding + linting + testing everything on every PR would make CI unusably slow. Turbo computes a fingerprint of each task's inputs (source + deps + config) and, if the fingerprint is unchanged, reuses last time's output and skips the whole step. So editing one file in worker lets the unaffected web builds/tests hit cache and pass instantly. With a remote cache, teammates even share build results. That's the secret to keeping CI fast in a big repo — and the engineering precondition that makes "use a monorepo" viable: without good caching, monorepo build cost scares everyone off.

Turbo cache: fingerprint each task's inputs, skip the whole thing if unchanged change worker one file Turbo fingerprints = source + deps + config compared per package worker · fingerprint changed → rebuild web · unchanged → cache hit (instant) shared · unchanged → hit remote cache: share build results across teammates — even a dozens-of-packages repo keeps CI fast

What's inside each workspace

Finally, a "hot directory cheat-sheet" — later lessons return to these spots again and again:

LocationWhat's there
web/src/pagesNext.js pages + API routes (incl. api/public REST, api/trpc)
web/src/server/apitRPC root router, context, middleware (L21)
web/src/featuresfeature "vertical slices" (traces, evals, prompts… dozens)
worker/src/queuesBullMQ queue consumers (ingestion, eval, export…)
worker/src/servicescore services (IngestionService, ClickhouseWriter)
packages/shared/src/domaindomain models (traces/observations/scores…)
packages/shared/src/serverrepositories, ClickHouse/Redis/S3 clients, queue contracts
packages/shared/prismaPostgres schema & migrations
packages/shared/clickhouseClickHouse migrations (wide-event tables)

Not in the table but worth a separate mention: fern/ and generated/. Langfuse's public REST API isn't hand-written — it's first declared in fern/ with Fern ("which endpoints, what params, what responses"), then API client code is generated into generated/. So generated/ is a build artifact you must never hand-edit — edits get overwritten on the next generation. That's why changing the public API means updating the fern/ sources too (L27). This "contract-first, code-generated" approach keeps the API docs, the server, and the per-language SDKs always in sync.

🎯 Design trade-off
Why a monorepo + narrow waist instead of three separate repos (polyrepo) for web/worker/shared? Because web and worker share domain models and queue contracts heavily; split into repos and every data-structure change means cross-repo releases and version juggling, inviting drift ("web thinks the field is A, worker still uses B"). A monorepo lets all three change atomically — one PR edits the shared contract and both usages, and CI verifies them together. The cost is a bigger repo and a more complex build tool (Turbo), but for a tightly contract-coupled system, the trade wins. Put differently: polyrepo saves "single-repo complexity", monorepo saves "cross-repo coordination complexity" — and the latter is usually what actually slows a team down.
🎯 Key points
  • Langfuse is a pnpm + Turbo monorepo: web (storefront), worker (workshop) two runtimes + packages/shared (central warehouse) + ee.
  • Narrow waist: dependencies are strictly one-way web/worker/ee → shared, and shared depends on none; contracts (domain models, queues) live in shared.
  • Turbo uses a task graph (build depends on db:generate + ^build) + caching, so even a big repo builds fast and incrementally.
  • Memorize the hot dirs: web/src/{pages,server,features}, worker/src/{queues,services}, packages/shared/src/{domain,server}.
  • Monorepo is chosen so the contract-coupled web/worker/shared can change atomically, avoiding cross-repo version drift.

🧪 Self-test - think about the design

1. Langfuse mandates that dependencies go only web/worker/ee → shared, and shared depends on none. What's the main benefit of this 'narrow waist' rule?
  1. It lets shared call web's React components directly
  2. It slows builds so caching kicks in
  3. The two containers evolve/deploy independently yet share one set of domain models and queue contracts, defined in one place so they can't drift
  4. It forces web and worker into one process
Show answer & explanation click to expand
Answer: C. web (low-latency, user-facing) and worker (heavy, retryable) are different workloads; letting them depend on each other entangles them. Collecting shared content into a shared that nothing depends on backwards, with only-downward deps, erects a contract wall — what goes through queues and what tables look like are defined in one place.
2. In turbo.json the build task says "dependsOn": ["db:generate", "^build"]. What does that mean?
  1. Before building any package, generate the Prisma client and first build its upstream deps (^ = upstream); Turbo computes order, parallelizes, and skips cache hits
  2. db:generate must be run manually after build
  3. The build task can never be cached
  4. ^build means build the downstream packages
Show answer & explanation click to expand
Answer: A. dependsOn declares the task graph: db:generate before build (need Prisma types first), ^build means build upstream dep packages first. So one pnpm build lets Turbo order, parallelize, and cache-hit unchanged packages — incremental builds even in a big repo.
3. Adding a field to the trace in Langfuse's monorepo roughly takes what steps?
  1. Release three separate repos and manually align versions
  2. Edit prisma/schema.prisma and domain/traces.ts; after db:generate both web and worker pick up the new type from the same @langfuse/shared, in one PR verified together by CI
  3. You must first drop the old ClickHouse table
  4. Only web changes; worker is unaffected
Show answer & explanation click to expand
Answer: B. This is exactly the monorepo + narrow-waist payoff: change the shared structure once, both web/worker pull from @langfuse/shared, done atomically in one PR through CI together. Polyrepo would need cross-repo releases and version alignment, inviting drift.
💭 Open questions (no single right answer - just think or try)
  • If your own project had both a 'user-facing service' and a 'background worker', would you keep them in one repo or split? Borrowing Langfuse's narrow waist, what would you pull into a shared layer?