源码索引

这一页把书里出现的关键源码入口集中列出来。阅读时建议打开对应文件，对照章节中的运行链路看。

根配置

文件	读它是为了理解什么
`package.json`	根脚本、Node 版本、pnpm 版本、Turbo 入口。
`pnpm-workspace.yaml`	哪些目录被纳入 workspace。
`turbo.json`	build、dev、lint、typecheck、test 的任务关系和缓存策略。
`.agents/ARCHITECTURE_PRINCIPLES.md`	仓库内的架构原则和约束。

Web 层

文件或目录	读它是为了理解什么
`web/src/pages`	Next.js pages router 入口。
`web/src/features`	主要业务功能的 UI 和局部服务端组织。
`web/src/components/table/data-table.tsx`	通用表格抽象。
`web/src/components/table/types.ts`	表格列、状态和行为类型。
`web/src/features/tracing-tables/README.md`	tracing tables 的组织原则。
`web/src/features/search-bar/README.md`	搜索语法、`FilterState` 和跨视图扩展契约。
`web/src/styles/globals.css`	Tailwind token、颜色变量和基础样式。
`web/src/server/api/root.ts`	tRPC router 聚合入口。
`web/src/server/api/trpc.ts`	procedure、context、鉴权和项目权限约束。
`web/src/features/public-api/server/withMiddlewares.ts`	Public API 的 method、CORS、错误处理包装。
`web/src/features/public-api/server/createAuthedProjectAPIRoute.ts`	API key、scope、rate limit 和 schema 校验入口。
`web/src/features/public-api/README.md`	新增 Public API 的开发流程。

Shared 契约层

文件或目录	读它是为了理解什么
`packages/shared/src/domain/observations.ts`	observation domain model。
`packages/shared/src/domain/traces.ts`	trace domain model。
`packages/shared/src/domain/scores.ts`	score domain model。
`packages/shared/src/server/queues.ts`	队列名、job 名、payload schema。
`packages/shared/src/server/redis/**`	BullMQ queue class、sharding、Redis 短期状态。
`packages/shared/src/server/ingestion/processEventBatch.ts`	ingestion 请求侧批量处理和入队。
`packages/shared/src/interfaces/filters.ts`	`FilterState`、filter operator 和事件表筛选结构。
`packages/shared/src/server/queries/clickhouse-sql/event-query-builder.ts`	v4 events 查询构造器。
`packages/shared/src/server/repositories/definitions.ts`	ClickHouse record read/insert schema。
`packages/shared/prisma/schema.prisma`	Postgres schema 源头。
`packages/shared/clickhouse/migrations`	ClickHouse schema 迁移。

Worker 层

文件或目录	读它是为了理解什么
`worker/src/app.ts`	worker 启动和队列注册。
`worker/src/queues`	各队列 processor。
`worker/src/queues/workerManager.ts`	BullMQ Worker 注册、metrics、OpenTelemetry 和 failed/stalled hooks。
`worker/src/queues/ingestionQueue.ts`	ingestion job 消费流程。
`worker/src/services/IngestionService/index.ts`	事件转换和写入准备。
`worker/src/services/ClickhouseWriter/index.ts`	ClickHouse 批量写入队列。

API Contract 和生成文件

文件或目录	读它是为了理解什么
`fern/apis`	Public API 定义源头。
`generated`	生成后的 API client 或产物，只读。
`web/src/features/public-api/types`	Web 侧 Public API 类型桥接。
`web/src/pages/api/public`	Public API route 入口。

文档站点本身

文件或目录	读它是为了理解什么
`.vitepress/config.mts`	本书站点的导航、sidebar、搜索和主题配置。
`index.md`	站点首页。
`part00-preface` 到 `part08-labs`	按参考教程结构拆分的正文和实验课。
`architecture/langfuse-current-architecture.drawio`	中文 draw.io 架构图 XML 源文件。
`public/architecture/langfuse-current-architecture.drawio`	在线站点可直接访问的 draw.io XML。
`langfuse-repo-guide.md`	早期单页长文版，可作为浓缩参考。