🪢 Langfuse 图解教程Langfuse Visual Guide 第四部分 · 查询链路Part 4 · The Read Path 20 / 55
第四部分 · 查询链路Part 4 · The Read Path

web 应用架构The web app architecture

🧭 读前Before you start
先读 第4课 的 monorepo 全景,本课聚焦 web 这个工作区的内部架构。
Read Lesson 4 on the monorepo map; this lesson zooms into the web workspace's architecture.

前三部分顺着写入走完了:数据怎么进来、存哪、怎么合并落盘。从这一部分起,我们反向追读取——UI 和 SDK 怎么把数据查出来。 第一站是 web 应用的骨架。Langfuse 的前端是个 Next.js 应用,绝大多数页面用老牌的 Pages Router, 并行跑着三种 API 风格:给自家 UI 用的 tRPC、给 SDK 用的公共 REST、以及给流式/Webhook 用的少量 App-Router 处理器。看懂这张「门牌图」,后面七课才不会迷路。

🏢 生活类比
把 web 应用想成一栋大楼(Next.js)。大楼开了三道门,迎接三类访客:员工通道(tRPC——只给自家 UI 走,类型安全、内部直达)、 公共前台(REST /api/public——给外部 SDK 走,稳定、带版本号),还有一个特殊装卸口(App-Router / SSE 处理器——给需要流式推送、Webhook 回调的特殊货物走)。 三道门通向同一栋楼、同一批数据,但各服务各的客:员工不用走前台登记,外部访客也进不了员工通道。分清这三道门,就分清了 Langfuse 所有对外接口的脉络。

一栋楼、三道门

先看整体。web/ 是一个 Next.js 应用,web/src 下分几大块:features/(按功能切的纵向模块,数十个)、 components/(共享 UI,含表格系统)、server/(鉴权 + tRPC)、pages/(页面与 API 路由)、还有少量 app/(App Router)。 而对外的接口,正是开篇说的三道门:

features/纵向功能模块(数十个)
按业务功能切分的「竖切片」:traces、search-bar、public-api、batch-exports… 每个功能把自己的页面、组件、server 逻辑收在一处。Langfuse 绝大多数代码住在这里。
components/共享 UI
跨功能复用的通用组件,最重要的是 components/table/ 那套表格系统(第 24 课)——列表、过滤、分页、列控制、行选择全靠它,是整个后台界面的骨架。
server/鉴权 + tRPC
server/api/{root,trpc}.ts 是 tRPC 的根与中间件、procedure 定义(第 21 课);server/auth.ts 是 NextAuth 会话。这是「员工通道」的安检处。
pages/ · app/路由
pages/ 是主干(UI 页面 + API 路由),app/ 仅 4 个文件兜特殊语义。还有 hooks/、ee/(企业版)等。

这里值得停一下看 features/ 的组织哲学:它是按「功能」而非按「技术层」切分的。传统做法可能把所有页面塞 pages/、所有组件塞 components/、所有接口塞 api/—— 找一个功能的代码得在三四个目录间来回跳。Langfuse 反过来,每个功能(比如 search-bar、batch-exports)是一个自包含的竖切片,把它的前端组件、状态 hook、server 端逻辑、甚至说明 README 都收在 features/<功能>/ 一处。好处是:读懂或修改一个功能,主要只需看一个目录;功能之间边界清晰,不易互相牵连。这也是为什么后面每讲一课,我们几乎都能精准地指向一个 features/ 子目录,而不必满仓库地翻找散落各处的代码。

Langfuse web 应用:一栋楼,三道门 Next.js 应用(web/)· 以 Pages Router 为主UI 页面 pages/project/[projectId]/…(traces / sessions / dashboards / datasets …)src 目录:features/ · components/ · server/ · hooks/ · ee/ ① 员工通道 · tRPCpages/api/trpc/[trpc].ts给自家 UI · 类型安全~62 个 feature 路由第 21 课 ② 公共前台 · RESTpages/api/public/**给外部 SDK · 稳定带版本v1 / v2 / v3 + Fern 契约第 27 课 ③ 装卸口 · 特殊语义app/api/**(仅 4 个文件)+ dashboard/execute-query-stream流式 SSE · webhook
三道门各服务各的客:tRPC(pages/api/trpc/[trpc].ts)给自家 UI、类型安全;REST(pages/api/public/**)给外部 SDK、稳定带版本;特殊语义(App Router app/api/** 4 文件 + Pages Router 流式 SSE 端点)给 webhook 与流式。源码:web/src/server/api/root.ts、web/src/features/public-api/、web/src/app/。
示例:一次 web 请求穿过的分层 浏览器 / React UI用户交互、渲染 Next.js pages / /api 路由SSR + REST 入口 tRPC 路由器 + 中间件protectedProjectProcedure 先校验归属 仓储层 repository封装 SQL,跨 PG/CH 取数 Postgres · ClickHouse配置 + 宽事件
请求逐层下穿(依据 web/src/server/api 与 web/src/pages):浏览器的动作经 Next.js 页面//api 进来,落到 tRPC 路由器;中间件 protectedProjectProcedure 先校验你属不属于这个 project,才进 仓储层去 Postgres/ClickHouse 取数。每层只跨一道清晰边界,便于测试与替换。
web/src/pages/api/ & web/src/app/三种 API 入口
// ① tRPC:UI 的类型安全后端,一个文件接住全部 ~62 个路由
web/src/pages/api/trpc/[trpc].ts        // → appRouter(第 21 课)

// ② 公共 REST:给 SDK 的稳定接口,按资源 + 版本分文件夹
web/src/pages/api/public/traces/index.ts
web/src/pages/api/public/v2/scores/…    // 文件夹即版本(第 27 课)

// ③ App Router:只有 4 个文件,专给需要原始 Request/流式/webhook 的端点
web/src/app/api/billing/stripe-webhook/route.ts
web/src/app/api/chatCompletion/route.ts
web/src/app/api/in-app-agent/route.ts
web/src/pages/api/dashboard/execute-query-stream.ts  // SSE 流式仪表盘

为什么几乎全是 Pages Router

你可能注意到一个反差:明明 Next.js 早就推出了 App Router,Langfuse 却几乎全用老的 Pages Router——App Router 下统共只有 4 个文件。 这不是落伍,而是务实的取舍。

Pages Router 主干 · App Router 仅作特例 Pages Router(主干 · 99%) UI 页面pages/project/[projectId]/… API 路由pages/api/**(tRPC + REST) UI 用 tRPC + React Query,类型从后端一路贯穿到组件 长期沉淀的成熟路线,团队约定俗成 App Router(仅 4 文件)layout.tsx(根布局)stripe-webhook/route.tschatCompletion/route.tsin-app-agent/route.ts只为「原始 Request / 流式 / webhook」
务实而非落伍:Pages Router 承载几乎全部 UI 与 API(tRPC + REST);App Router 只保留 4 个文件,专给需要原始 Request、流式响应、webhook 回调这类 Pages Router 不擅长的语义。源码:web/src/app/(layout + 3 个 route.ts)。
这道门给谁用在哪为什么
tRPC自家 UI(React)pages/api/trpc/[trpc].ts类型从后端贯穿到前端,改一处全链路报错;内部接口无需对外稳定
公共 REST外部 SDK / 用户脚本pages/api/public/**对外契约要稳定、带版本,由 Fern 生成多语言 SDK(第 27 课)
特殊语义(App Router + SSE)webhook 源 · 流式仪表盘App Router app/api/**(webhook 等)+ Pages Router 的流式 SSE 端点需要原始 Request、text/event-stream 等普通 Pages Router 路由不顺手的语义

这套划分背后是一条清晰的边界:对内求「类型安全、改得快」,对外求「契约稳定、版本可控」。UI 和后端是同一个团队、同一个仓库,用 tRPC 把类型一路打通, 重构时编译器即时报错;而 SDK 面向千千万万外部用户,接口一旦发布就不能随意改,于是用 REST + 版本号 + Fern 契约严格约束。同一批数据,两种对外姿态—— 内部接口可以天天演进,外部契约必须长期稳定,把它们放进同一种 API 反而会互相掣肘。这正是 Part 4 要展开的读取链路的总纲。

预告一下整条读取链路:无论从哪道门进来,一次「查数据」的请求大致都要走这么几步。后面七课会逐站深入:

一次「查数据」请求要走的 5 站(Part 4 路线图) ① 入口 tRPC / REST 先鉴权 L21 / L27 ② 过滤 FilterState → 参数化 SQL L23 ③ 仓储层 queryClickhouse 重试 / 打 tag L22 ④ 读模型 列表双查询 / 详情观测树 L24 / L25 ⑤ 返回渲染 URL 状态 列预设 / 分享 L24 无论从哪道门进来,读取链路殊途同归;sessions(L26)是在 trace 之上再加一层「对话」视角
1

入口(tRPC 或 REST)

UI 发 tRPC 调用、SDK 发 REST 请求;各自的入口先做鉴权,确认你能读这个 project(第 21、27 课)。

2

过滤与查询构建

把 UI 的 FilterState(或 SDK 的查询参数)编译成参数化 SQL,并带上强制的 project_id 与时间窗(第 23 课)。

3

仓储层执行

经过统一的 ClickHouse 执行器:打 OTel span、贴查询 tag、失败退避重试、把资源错误翻成友好提示(第 22 课)。

4

读模型塑形

列表走「紧凑行 + 懒加载指标」的双查询,详情走「整棵观测树」的全量取——按场景选不同读模型(第 24、25 课)。

5

返回 + 前端渲染

结果回到 UI,表格系统用 URL 状态、列预设、行选择把它快速且可分享地渲染出来(第 24 课)。

🎯 设计取舍
为什么不赶时髦全面迁到 App Router、或者干脆只用 REST 一种 API? 因为架构选择要服务于团队现实,而非追新。Langfuse 在 App Router 成熟之前 就用 Pages Router + tRPC 立了稳固的根基——tRPC 让前后端共享同一套类型,是这个全栈团队迭代飞快的关键,贸然迁移收益小、风险大。至于 API: 对内和对外是两类截然不同的需求。对内(UI)追求的是「改一处、全链路类型即时校验」,tRPC 完美契合;对外(SDK)追求的是「我两年前写的集成代码今天还能跑」, 这就必须有稳定契约、显式版本。硬把两者统一成一种 API,要么牺牲内部的开发速度,要么牺牲外部的稳定性。Langfuse 的答案是不强求统一,按受众分而治之—— 再用 App Router 兜住少数特殊语义。合适,比统一更重要。
🎯 本课要点
  • Langfuse 前端是 Next.js 应用,绝大多数用 Pages Router;App Router 仅 4 个文件,专给原始 Request/流式/webhook。
  • 三种 API 风格并存:tRPC(UI,类型安全)、公共 REST(SDK,稳定带版本)、特殊语义端点(App Router 处理器 + Pages Router 流式 SSE,供 webhook/流式)。
  • web/src 分层:features/(数十个纵向功能模块)、components/(共享 UI)、server/(鉴权+tRPC)、pages/、app/。
  • 核心边界:对内求类型安全与迭代速度(tRPC),对外求契约稳定与版本可控(REST + Fern)——同一批数据、两种对外姿态。
  • 这是 Part 4「读取链路」的总览图;接下来七课将分别钻进 tRPC 骨架、仓储层、过滤、表格、详情、sessions、公共 REST。

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

1. Langfuse 的 web 应用为什么并存三种 API 风格(tRPC、公共 REST、App-Router/SSE),而不是统一成一种?
  1. 因为开发者忘了删旧代码
  2. 因为对内和对外是两类需求:UI 要类型安全、改得快(tRPC,前后端共享类型);SDK 要契约稳定、带版本(REST + Fern);少数流式/webhook 要原始 Request 语义(App-Router)。硬统一会牺牲其一
  3. 因为 Next.js 强制要求三种都用
  4. 因为三种 API 各自更快
看答案与解析 点击展开
答案:B。核心边界是“对内求类型安全与迭代速度、对外求契约稳定与版本可控”。UI 和后端同仓同队,tRPC 把类型贯穿、重构即时报错;SDK 面向外部用户,接口发布后不能随意改,需 REST+版本+Fern。同一批数据、两种对外姿态——按受众分而治之,比强求统一更合适。
2. Langfuse 几乎全用老的 Pages Router,App Router 下只有 4 个文件。这说明了什么?
  1. 务实的取舍:Pages Router + tRPC 是 App Router 成熟前就立的稳固根基,贸然迁移收益小风险大;App Router 只保留给需要原始 Request/流式/webhook 这类 Pages Router 不擅长的语义
  2. 代码库已经过时、无人维护
  3. 团队不知道 App Router 存在
  4. App Router 完全不能用
看答案与解析 点击展开
答案:A。架构选择服务于团队现实而非追新。tRPC 让前后端共享类型,是全栈团队快速迭代的关键;迁移成本高、收益小。App Router 的 4 个文件(layout + stripe-webhook/chatCompletion/in-app-agent)正是那些需要原始 Request、流式或 webhook 语义的特例——合适比统一更重要。
3. Langfuse 的 web/src 用 features/ 按“功能”切分(约 80 个纵向模块),而不是按“技术层”(全部页面/全部组件/全部接口各一目录)。这样组织的主要好处是?
  1. 每个功能是自包含的竖切片,把它的组件、状态、server 逻辑收在一处;读懂或改一个功能主要只看一个目录,功能之间边界清晰、不易牵连
  2. 强制所有功能共享代码
  3. 让目录数量更少
  4. 让构建更快
看答案与解析 点击展开
答案:A。按功能切分(vertical slice)让一个功能的全部代码聚在 features/<功能>/ 一处,避免在 pages/components/api 三四个目录间来回跳。修改局部化、边界清晰,是大型前端可维护性的关键——这也是为什么后面每课几乎都能指向一个 features/ 子目录。
💭 发散思考(没有标准答案,动手或动脑想想)
  • “对内类型安全、对外契约稳定”——同一批数据用两种 API 姿态对待。你做过的系统里,内部调用和对外接口是混在一起还是分开的?如果分开,你会怎么划界?tRPC 这种“前后端共享类型”的收益,在什么规模/团队结构下最划算?

The first three parts followed the write direction: how data comes in, where it's stored, how it's merged and persisted. From this part on we trace reads in reverse — how the UI and SDKs query data back out. First stop: the web app's skeleton. Langfuse's frontend is a Next.js app, with the vast majority of pages on the veteran Pages Router, running three API styles in parallel: tRPC for its own UI, a public REST API for SDKs, and a handful of App-Router handlers for streaming/webhooks. Grasp this "door map" and the next seven lessons won't get you lost.

🏢 Analogy
Think of the web app as a building (Next.js) with three doors for three kinds of visitors: a staff entrance (tRPC — only for its own UI, type-safe, direct internal access), a public reception (REST /api/public — for external SDKs, stable, versioned), and a special loading dock (App-Router / SSE handlers — for special cargo needing streaming pushes or webhook callbacks). All three doors lead into the same building, the same data, but each serves its own crowd: staff skip reception, external visitors can't use the staff entrance. Sort out these three doors and you've sorted out every Langfuse external interface.

One building, three doors

The big picture first. web/ is a Next.js app; under web/src sit a few big areas: features/ (vertical, by-feature modules, dozens of them), components/ (shared UI, including the table system), server/ (auth + tRPC), pages/ (pages and API routes), plus a small app/ (App Router). And the external interfaces are exactly the three doors from the intro:

features/vertical feature modules (dozens)
"Vertical slices" cut by business feature: traces, search-bar, public-api, batch-exports… each gathers its own pages, components, and server logic in one place. Most Langfuse code lives here.
components/shared UI
Cross-feature reusable components, most importantly components/table/ (Lesson 24) — lists, filtering, pagination, column control, row selection, the skeleton of the whole back-office UI.
server/auth + tRPC
server/api/{root,trpc}.ts is the tRPC root, middleware, and procedure definitions (Lesson 21); server/auth.ts is the NextAuth session. The "staff entrance" security check.
pages/ · app/routing
pages/ is the trunk (UI pages + API routes), app/ is just 4 files for special semantics. Plus hooks/, ee/ (enterprise), etc.

Pause on features/'s organizing philosophy: it's cut by "feature", not by "technical layer". A traditional layout might dump all pages in pages/, all components in components/, all endpoints in api/ — finding one feature's code means hopping across three or four directories. Langfuse inverts this: each feature (say search-bar, batch-exports) is a self-contained vertical slice gathering its frontend components, state hooks, server logic, even a README under one features/<feature>/. The payoff: to understand or change a feature you mostly read just one directory; boundaries between features are clear, so they don't entangle. That's why nearly every later lesson can point precisely at a features/ subfolder.

The Langfuse web app: one building, three doors Next.js app (web/) · primarily Pages RouterUI pages pages/project/[projectId]/… (traces / sessions / dashboards / datasets …)src dirs: features/ · components/ · server/ · hooks/ · ee/ ① staff entrance · tRPCpages/api/trpc/[trpc].tsown UI · type-safe~62 feature routersLesson 21 ② public reception · RESTpages/api/public/**external SDK · stable, versionedv1 / v2 / v3 + Fern contractLesson 27 ③ loading dock · special semanticsapp/api/** (only 4 files)+ dashboard/execute-query-streamstreaming SSE · webhook
Three doors, each serving its own crowd: tRPC (pages/api/trpc/[trpc].ts) for the UI, type-safe; REST (pages/api/public/**) for external SDKs, stable and versioned; special semantics (App Router app/api/** 4 files + a Pages-Router streaming SSE endpoint) for webhooks and streaming. Source: web/src/server/api/root.ts, web/src/features/public-api/, web/src/app/.
Example: the layers one web request crosses browser / React UIuser interaction, render Next.js pages / /api routesSSR + REST entry tRPC routers + middlewareprotectedProjectProcedure checks membership first repository layerwraps SQL, reads PG/CH Postgres · ClickHouseconfig + wide events
The request descends layer by layer (per web/src/server/api and web/src/pages): a browser action enters via Next.js pages//api and lands on the tRPC routers; the protectedProjectProcedure middleware checks project membership first, then the repository layer reads Postgres/ClickHouse. Each layer crosses one clear boundary — easy to test and swap.
web/src/pages/api/ & web/src/app/three API entries
// ① tRPC: the UI's type-safe backend, one file catches all ~62 routers
web/src/pages/api/trpc/[trpc].ts        // → appRouter (Lesson 21)

// ② public REST: the stable interface for SDKs, by resource + version folder
web/src/pages/api/public/traces/index.ts
web/src/pages/api/public/v2/scores/…    // folder = version (Lesson 27)

// ③ App Router: only 4 files, for endpoints needing raw Request/streaming/webhook
web/src/app/api/billing/stripe-webhook/route.ts
web/src/app/api/chatCompletion/route.ts
web/src/app/api/in-app-agent/route.ts
web/src/pages/api/dashboard/execute-query-stream.ts  // SSE streaming dashboards

Why it's almost all Pages Router

You may notice a contrast: even though Next.js shipped the App Router long ago, Langfuse uses the old Pages Router for almost everything — the App Router has all of 4 files. This isn't being behind the times; it's a pragmatic choice.

Pages Router trunk · App Router only for special cases Pages Router (trunk · 99%) UI pagespages/project/[projectId]/… API routespages/api/** (tRPC + REST) UI uses tRPC + React Query, types flow from backend to component a mature, long-settled path the team standardized on App Router (4 files only)layout.tsx (root layout)stripe-webhook/route.tschatCompletion/route.tsin-app-agent/route.tsonly for "raw Request / streaming / webhook"
Pragmatic, not behind: Pages Router carries nearly all UI and APIs (tRPC + REST); App Router keeps just 4 files, for endpoints needing raw Request, streaming responses, webhook callbacks — semantics Pages Router handles awkwardly. Source: web/src/app/ (layout + 3 route.ts).
this doorfor whomwherewhy
tRPCown UI (React)pages/api/trpc/[trpc].tstypes flow backend → frontend, change one spot and the whole chain errors; internal API needn't be externally stable
public RESTexternal SDK / user scriptspages/api/public/**the external contract must be stable, versioned, with Fern generating multi-language SDKs (Lesson 27)
special semantics (App Router + SSE)webhook sources · streaming dashboardsApp Router app/api/** (webhooks etc.) + a Pages-Router streaming SSE endpointneeds raw Request, text/event-stream, etc. — semantics a plain Pages-Router route handles awkwardly

Behind this split is a clear boundary: internally, seek "type-safe, fast to change"; externally, seek "stable contract, controlled versions". The UI and backend are one team, one repo, so tRPC threads types end to end — the compiler errors instantly on refactors; whereas the SDK faces countless external users, where a published interface can't change freely, so REST + version numbers + the Fern contract enforce strict stability. Same data, two external postures — the internal API can evolve daily, the external contract must stay stable for years; forcing them into one API style would only hobble each other. This is the master plan of Part 4's read path.

A preview of the whole read path: whichever door you enter, a "query data" request roughly takes these steps. The next seven lessons dive into each stop:

The 5 stations of a "query data" request (Part 4 roadmap) 1 entry tRPC / REST auth first L21 / L27 2 filter FilterState → param SQL L23 3 repository queryClickhouse retry / tag L22 4 read model list two-query / detail tree L24 / L25 5 render URL state presets / share L24 whichever door you enter, the read path converges; sessions (L26) add a "conversation" lens on top of traces
1

entry (tRPC or REST)

The UI fires a tRPC call, the SDK a REST request; each entry first does auth, confirming you can read this project (Lessons 21, 27).

2

filter & query build

The UI's FilterState (or SDK query params) is compiled into parameterized SQL, with the mandatory project_id and time window (Lesson 23).

3

repository executes

Through a unified ClickHouse executor: OTel span, query tags, backoff retry on failure, resource errors turned into friendly messages (Lesson 22).

4

read-model shaping

Lists use a "compact rows + lazy metrics" dual query; details fetch the "whole observation tree" — different read models per scenario (Lessons 24, 25).

5

return + frontend render

Results return to the UI, where the table system renders them fast and shareably with URL state, column presets, row selection (Lesson 24).

🎯 Design trade-off
Why not chase the trend and migrate fully to App Router, or just use REST as the one API? Because architecture choices should serve team reality, not novelty. Langfuse laid a solid foundation on Pages Router + tRPC before the App Router matured — tRPC lets front and back share one type system, the key to this full-stack team iterating fast; a rash migration is low-reward, high-risk. As for the API: internal and external are two utterly different needs. Internal (UI) wants "change one spot, instant type-check across the chain" — tRPC fits perfectly; external (SDK) wants "the integration I wrote two years ago still runs today" — which demands a stable contract and explicit versions. Force the two into one API and you sacrifice either internal velocity or external stability. Langfuse's answer is don't force unity; divide and conquer by audience — with App Router catching the few special semantics. Fit matters more than uniformity.
🎯 Key points
  • Langfuse's frontend is a Next.js app, mostly Pages Router; App Router is just 4 files for raw Request/streaming/webhook.
  • Three API styles coexist: tRPC (UI, type-safe), public REST (SDK, stable+versioned), special-semantics endpoints (App Router handlers + a Pages-Router streaming SSE, for webhook/streaming).
  • web/src layers: features/ (dozens of vertical feature modules), components/ (shared UI), server/ (auth+tRPC), pages/, app/.
  • Core boundary: internally seek type-safety and iteration speed (tRPC), externally seek contract stability and version control (REST + Fern) — same data, two external postures.
  • This is Part 4's read-path overview; the next seven lessons drill into the tRPC backbone, repository layer, filtering, tables, detail, sessions, and the public REST API.

🧪 Self-test - think about the design

1. Why does Langfuse's web app run three API styles (tRPC, public REST, App-Router/SSE) rather than unifying into one?
  1. because developers forgot to delete old code
  2. because internal and external are two needs: the UI wants type-safety and fast change (tRPC, shared types front-to-back); SDKs want a stable, versioned contract (REST + Fern); a few streaming/webhook cases need raw Request semantics (App-Router). Forcing unity sacrifices one of them
  3. because Next.js mandates all three
  4. because each API is individually faster
Show answer & explanation click to expand
Answer: B. The core boundary: internally seek type-safety and iteration speed, externally seek a stable, versioned contract. UI and backend share one repo/team, so tRPC threads types and errors instantly on refactor; the SDK faces external users where published interfaces can't change freely, needing REST+versions+Fern. Same data, two external postures — dividing by audience fits better than forced uniformity.
2. Langfuse uses the old Pages Router for almost everything, with only 4 files under App Router. What does this show?
  1. a pragmatic choice: Pages Router + tRPC is a solid foundation laid before App Router matured, so a rash migration is low-reward/high-risk; App Router is kept only for raw Request/streaming/webhook semantics Pages Router handles awkwardly
  2. the codebase is outdated and unmaintained
  3. the team doesn't know App Router exists
  4. App Router is completely unusable
Show answer & explanation click to expand
Answer: A. Architecture serves team reality, not novelty. tRPC's shared types are key to fast full-stack iteration; migration is costly and low-reward. App Router's 4 files (layout + stripe-webhook/chatCompletion/in-app-agent) are exactly the cases needing raw Request, streaming, or webhook semantics — fit matters more than uniformity.
3. Langfuse's web/src cuts by 'feature' under features/ (~80 vertical modules) rather than by 'technical layer' (all pages/all components/all APIs each in one dir). The main benefit?
  1. each feature is a self-contained vertical slice gathering its components, state, and server logic in one place; to understand or change a feature you mostly read one directory, with clear boundaries that don't entangle
  2. to force all features to share code
  3. to have fewer directories
  4. to make builds faster
Show answer & explanation click to expand
Answer: A. By-feature (vertical-slice) organization gathers a feature's whole code under features//, avoiding hops across pages/components/api. Localized changes and clear boundaries are key to large-frontend maintainability — which is why nearly every later lesson points at a features/ subfolder.
💭 Open questions (no single right answer - just think or try)
  • 'Internal type-safety, external stable contract' — the same data treated with two API postures. In systems you've built, are internal calls and external interfaces mixed or separated? If separated, how would you draw the line? At what scale/team structure does tRPC's 'shared types front-to-back' pay off most?