Alcove — Technology Stack & Architecture

Technology Stack & Architecture

技术栈与架构分层 · diagram 02 of 03

DOC / 02
v0.1.0 · 2026.04

§ 01 — Tech Stack by Function · 按职能分类的技术选型

[ 01 ] Framework · 框架基座

Next.js 16 React 19 TypeScript 5

App Router 路由 · Server Actions 处理纯 CPU 任务 · 全量类型覆盖（卡片数据用判别联合，无 any 逃逸）。

[ 02 ] UI System · 视觉与组件

Tailwind v4 shadcn 4.x @base-ui/react @radix-ui/react-slot @phosphor-icons/react lucide-react

@theme + CSS 变量定义设计系统 · shadcn 与项目语义 token 精细合并 · Phosphor 用于 UI chrome。

[ 03 ] Rich Text · 笔记编辑器

Tiptap 2.27 Novel tiptap-markdown

Note Card 富文本核心 · Markdown 快捷键 + `/` 菜单 + 双向 markdown 转换 · 自定义 schema 防御 PM joinBackward 列表 bug。

[ 04 ] Code Highlight · 代码处理

Shiki 4.0 highlight.js 11 node-html-parser

Code Card 服务端高亮（Server Action）· hljs 用于检测器多信号评分 · node-html-parser 用于链接元数据抓取。

[ 05 ] Image & Color · 图像与配色

node-vibrant 4.0 @paper-design/shaders-react

从图片/海报提取 5 色调色板 → 卡片占位主色（零 CLS）· Movie Card 票根背景配色 · Shaders 预留高级视觉。

[ 06 ] Layout & Animation · 布局与动画

masonic 4.1 Framer Motion 12.38 tw-animate-css

瀑布流布局核心 · 卡片高度预计算（图片纵横比 / 代码行高 / 票根固定）· 浮层 enter/exit 动画 + 焦点管理。

[ 07 ] Canvas · 白板

tldraw 4.5

Constellation Card 底层 · 自定义形状与连线 · 状态以 Store snapshot 持久化 · 隐藏默认 chrome，只保留编辑核心。

[ 08 ] Utilities · 实用组件

sonner class-variance-authority tailwind-merge input-otp react-barcode masonic

Toast 通知（反爬降级提示等）· `cn()` 样式合并 · OTP 输入（认证预留）· 电影票根条码生成。

§ 02 — 5-Layer Architecture · 五层架构图

UI Layer

用户界面层

主产品页（瀑布流网格 + 输入框 + 标签栏 + 顶部搜索），以及 6 种卡片组件 + 各自的展开/预览态。纯渲染，零数据逻辑。

MasonryGrid · InputCard
TagFilterBar · 6 cards

props · CardData[]

Card Registry

卡片注册表

type → Component 映射。每种卡片在自己目录的 register.ts 自注册，新增卡片类型零侵入分发逻辑。

card-registry.ts
card-renderer.tsx

type · CardType

Content Detection

内容检测器（纯工具层）

用户输入经过优先级队列（12 → −1）多检测器评分，输出最高 confidence 的类型 + 解析数据。无 React 依赖，可单测。

content-detector-registry
5 detectors

DetectionResult

Data Repository

数据访问层

CardRepository 接口定义 CRUD + 查询。当前实现：MockCardRepository（内存数组）。未来：SupabaseCardRepository — UI 层零改动可切换。

CardRepository (interface)
useCards · useTags hooks

HTTP / fetch

alcove-agent

独立后端服务（Node.js）

外部 API 抓取（TMDb / GitHub / 链接元数据）+ 跨进程共享缓存 + 反爬降级（豆瓣 302 检测）。Server Action 做不了的事都搬到这里。

modules/movies
lib/external-cache

§ 03 — Engineering Discipline · 工程严谨度的四个证据

[ 01 ] AI Skill Lockfile

Skill 锁定，约束代码生成质量

通过 skills-lock.json 锁定 6 项官方 skill（Vercel React Best Practices · GSAP Core 等），CLAUDE.md 明确要求新增代码前必读对应 skill。把工程规范外化为可校验的依赖，而非口头约定。

[ 02 ] Design Pitfall Library

沉淀 1000+ 行真实踩坑笔记

CLAUDE.md 系统记录了 Tailwind v4 preflight 字体重置陷阱、ProseMirror schema 列表错配 bug、Portal 浮层 hover 追踪丢失、Tiptap Placeholder CSS 等真实问题与正确做法。非教科书理论，是产品演进过程沉淀。

[ 03 ] Server Action Boundary

明文规定前后端分工

纯 CPU 任务（代码高亮 / Markdown 解析）留在 Next.js Server Action；涉及外部 API 配额、跨用户缓存、反爬对抗的全部搬到 alcove-agent。fetch-movie-metadata 的搬迁是真实执行过的演进，决策依据在文档中可追溯。

[ 04 ] Migration Path

数据源可热替换

Repository 接口 + React Context 注入隔离了所有数据源细节。从 Mock 切换到 Supabase 只需新增一个实现类、修改一行 Provider 默认值。UI 组件零改动，可灰度验证。