架构概览

Raypx 的架构设计遵循分层解耦的原则，每一层都有明确的职责边界。

系统分层

展示层

展示层负责 UI 渲染和用户交互，基于以下技术构建：

• TanStack Router — 类型安全的文件路由，支持 SSR、SSG 和客户端渲染
• React 19 — 配合 React Compiler 实现自动性能优化
• Tailwind CSS 4 — 原子化 CSS 框架
• shadcn/ui — 基于 Radix UI 的无障碍组件库
• Fumadocs — 文档站 UI 和搜索功能

API 层

API 层提供类型安全的接口，确保前后端数据契约一致：

• oRPC — 类型安全的 RPC 框架，与 TanStack Start 深度集成
• Zod — Schema 定义和运行时校验，提供端到端的类型推导
• Better Auth API — 认证相关的 RESTful 接口

业务逻辑层

业务逻辑层处理核心业务规则和认证流程：

• Better Auth — 用户注册、登录、OAuth、会话管理等
• Server Functions — TanStack Start 的服务端函数，直接在路由中调用

数据访问层

数据访问层负责数据库交互：

• Drizzle ORM — 类型安全的 SQL 查询构建器
• PostgreSQL — 关系型数据库，提供事务支持和复杂查询能力

基础设施层

基础设施层提供运行环境和部署能力：

• Nitro — 服务端运行时，处理 SSR 和 API 路由
• Vite 8 — 构建工具和开发服务器
• Docker — 容器化部署

设计原则

Raypx 遵循以下核心设计原则：

类型安全优先

从数据库 Schema 到 API 接口再到 UI 组件，全链路保持类型安全：

Drizzle Schema → oRPC Contract → React 组件 Props

Zod Schema 作为唯一的数据源，自动推导 TypeScript 类型，确保各层数据结构一致。

关注点分离

每一层只负责自己的职责：

• 展示层不直接访问数据库
• API 层不包含业务逻辑
• 数据访问层不关心 HTTP 请求细节

约定优于配置

遵循框架的约定来减少配置：

• 文件路由——按目录结构自动生成路由
• 环境变量——统一的 .env 文件管理配置
• 代码规范——Biome 统一格式化和检查规则

可扩展性

通过 Monorepo 和模块化设计支持扩展：

• 新增业务包只需在 packages/ 下创建新目录
• 新增 API 端点只需在路由文件中导出函数
• 新增数据库表只需在 Drizzle Schema 中定义

数据流

一个典型的请求处理流程如下：

浏览器请求
  ↓
中间件链（i18n → auth）
  ↓
路由匹配
  ↓
Server Function / oRPC Handler
  ↓
Drizzle ORM 查询
  ↓
PostgreSQL
  ↓
响应返回

Monorepo 架构

项目使用 pnpm workspaces 管理内部包，通过 Turborepo 优化构建性能：

• 11 个内部包——按业务领域划分，职责单一
• Turborepo 管道——并行构建，增量缓存
• 严格依赖关系——包之间通过显式依赖引用，禁止循环依赖

相关文档

• 技术栈 — 完整的技术选型列表
• 内部包 — 11 个 Monorepo 包详解
• 请求生命周期 — 请求处理流程