renaissance-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Renaissance Architecture

文艺复兴式架构

Build genuinely new things. Not "X but for Y."

打造真正的创新事物，而非“面向Y场景的X复刻”。

Core Philosophy

核心理念

The problem isn't modern tools. It's building commentaries instead of creations.

Medieval scholars wrote commentaries on Aristotle instead of new philosophy. We build Star Wars spin-offs instead of new sci-fi. We add AI to existing workflows instead of asking what workflows become possible.

Renaissance architecture means:

First-principles thinking about WHAT to build
Pragmatic choices about HOW to build it
Creating new paradigms, not extending old ones
Using modern tools to make genuinely new things possible

问题不在于现代工具，而在于我们一直在做评论而非创造。

中世纪学者只会对亚里士多德的著作做注释，而非提出新哲学；我们只会制作星球大战衍生作品，而非创造新的科幻IP；我们只会在现有工作流中加入AI，而非思考AI能让哪些全新工作流成为可能。

文艺复兴式架构意味着：

从第一性原理出发思考要构建什么
基于务实选择确定如何构建
创造新范式，而非扩展旧范式
利用现代工具实现真正的创新

Architecture Principles

架构原则

1. Simplicity as Default, Complexity When Earned

1. 以简洁为默认，必要时才引入复杂度

Start simple, add complexity when pain is measurable.

Start With	Move To	When
SQLite	Postgres	>10 concurrent writers, >100GB, need PostGIS/full-text
Single file	Multiple files	File exceeds ~500 LOC or has multiple responsibilities
Monolith	Services	Team can't work on same codebase, or genuine scale isolation needed
Static hosting	Server	Need auth, real-time, or server-side computation
Local state	Cloud sync	Multi-device is a real user need, not assumed

Not dogma, but defaults. Violate with documented reasoning.

从简单开始，仅当可衡量的痛点出现时再增加复杂度。

初始选择	升级方向	升级时机
SQLite	Postgres	并发写入>10、数据量>100GB，或需要PostGIS/全文检索功能
单文件	多文件	文件代码量超过约500 LOC，或承担多项职责
单体应用	微服务	团队无法在同一代码库协作，或确实需要按规模隔离
静态托管	服务器	需要认证、实时功能或服务端计算
本地状态	云端同步	多设备支持是真实的用户需求，而非假设

这不是教条，而是默认准则。若要违反，请记录理由。

2. Framework Choices

2. 框架选择

Use frameworks when they provide genuine leverage.

Framework	When to Use	When to Avoid
Next.js	Full-stack React apps, SSR matters, team knows it	Simple static sites, non-React teams
Remix	Data-heavy apps, progressive enhancement priority	Simple SPAs, unfamiliar teams
Astro	Content sites, partial hydration valuable	Highly interactive apps
SvelteKit	Smaller bundles critical, team willing to learn	Large existing React codebases
Rails/Django	Rapid CRUD apps, admin panels, proven patterns	Real-time heavy, team prefers JS
FastAPI	Python APIs, async matters	Simple scripts, team prefers other languages
Hono/Elysia	Edge functions, lightweight APIs	Complex apps needing full framework

The question isn't "framework or not" but "does this framework serve the thing we're creating, or are we creating something that serves the framework?"

仅当框架能提供真正的效率增益时才使用。

框架	使用场景	避免场景
Next.js	全栈React应用、SSR需求明确、团队熟悉该框架	简单静态站点、非React技术栈团队
Remix	数据密集型应用、优先考虑渐进增强	简单SPA、团队不熟悉该框架
Astro	内容类站点、部分 hydration 能带来价值	高交互性应用
SvelteKit	需最小化包体积、团队愿意学习新框架	已有大型React代码库
Rails/Django	快速搭建CRUD应用、后台管理面板、使用成熟模式	实时性要求高、团队偏好JS技术栈
FastAPI	Python API、需要异步能力	简单脚本、团队偏好其他语言
Hono/Elysia	边缘函数、轻量级API	需要完整框架支持的复杂应用

核心问题不是“用不用框架”，而是“框架是为我们的创新服务，还是我们的创新要适配框架？”

3. Human-Legible Systems

3. 易于人类理解的系统

Configuration

YAML/JSON are fine - the format isn't the problem
Problem is: 500-line configs with nested conditionals
Good: Config a new team member can read and modify in 10 minutes
Document non-obvious settings inline

Error messages that teach

What happened
Why it happened
What to do about it
Link to docs if complex

Logs you can understand

Structured logging (JSON) for machines
Human-readable format for development
Timestamps, context, severity
Searchable without specialized tools

Documentation lives WITH code

README in each significant directory
API docs generated from code
Architecture decisions recorded (ADRs)
External wikis for onboarding/process only

配置

YAML/JSON格式没问题——问题不在格式本身
问题在于：包含嵌套条件的500行配置文件
良好实践：新团队成员能在10分钟内读懂并修改的配置
对非显性配置项添加内联文档

具备指导性的错误提示

说明发生了什么
解释原因
给出解决方法
复杂场景提供文档链接

可读性强的日志

机器可读的结构化日志（JSON格式）
开发环境使用人类可读格式
包含时间戳、上下文、严重级别
无需专用工具即可搜索

文档与代码共存

每个重要目录下都有README
从代码自动生成API文档
记录架构决策（ADRs）
外部Wiki仅用于新员工入职/流程说明

4. Local-First Where It Matters

4. 关键场景优先本地化

Not "never use cloud" but "don't require cloud unnecessarily."

Feature	Local-First Approach	Cloud When
Core functionality	Works offline	Never required for core
Data storage	SQLite/local storage	Sync, backup, multi-device
Computation	Client-side where possible	Heavy processing, shared resources
Auth	Local sessions work	OAuth for third-party, enterprise SSO

State should be inspectable

Serialize state to file for debugging
State machines explicit, not implicit
Reproducible from snapshot

Sync as enhancement

Local is source of truth where possible
Sync failures don't break the app
Conflict resolution explicit, user-controlled

不是“绝不使用云端”，而是“不不必要地依赖云端”。

功能	优先本地化方案	使用云端的场景
核心功能	支持离线使用	核心功能绝不强制依赖云端
数据存储	SQLite/本地存储	同步、备份、多设备支持
计算	尽可能在客户端执行	重型计算、共享资源场景
认证	本地会话生效	第三方OAuth、企业SSO

状态需可查

将状态序列化为文件以便调试
状态机需显式定义，而非隐式存在
可通过快照重现状态

同步作为增强功能

尽可能以本地为数据可信源
同步失败不影响应用正常使用
冲突解决逻辑显式且由用户控制

5. Composition Mindset

5. 组合式思维

Libraries over frameworks when:

You need one capability, not an ecosystem
You want to control the architecture
Exit cost matters more than speed

Frameworks over libraries when:

Team expertise exists
Time-to-market critical
Convention over configuration is valuable
The framework's opinions align with your needs

APIs expose primitives

Convenience methods are fine
But power users can access lower levels
Don't hide the machine

Minimize exit costs

Data exportable in standard formats
Avoid proprietary lock-in where practical
Document the exit path even if you never use it

优先选择库而非框架的场景：

仅需要单一能力，而非整个生态
希望自主控制架构
退出成本比开发速度更重要

优先选择框架而非库的场景：

团队具备相关技术经验
上市时间至关重要
“约定大于配置”能带来价值
框架的设计理念与需求匹配

API需暴露基础原语

可提供便捷方法
但高级用户能访问底层能力
不要隐藏底层逻辑

最小化退出成本

数据可导出为标准格式
尽可能避免专有锁定
即使暂不使用，也要记录退出路径

Cloud & Infrastructure

云端与基础设施

When Cloud Makes Sense

云端适用场景

Use Case	Cloud Appropriate	Local/Edge Better
Auth	Enterprise SSO, OAuth providers	Simple username/password
Storage	Multi-device sync, collaboration	Single-user, offline-capable
Compute	Heavy ML inference, video processing	Text processing, simple transforms
Database	Multi-writer, global distribution	Single user, local-first
Real-time	Multi-user collaboration	Single-user state

场景	适合云端	本地/边缘更优
认证	企业SSO、OAuth提供商	简单用户名/密码认证
存储	多设备同步、协作	单用户、支持离线
计算	重型ML推理、视频处理	文本处理、简单转换
数据库	多写入者、全球分布式部署	单用户、优先本地化
实时功能	多用户协作	单用户状态管理

Cloud Pragmatically

务实使用云端

Serverless for spiky, unpredictable loads
Edge functions for latency-sensitive operations
Managed databases when ops overhead > cost
Self-hosted when control/cost/compliance require it

The question: Does cloud serve your users, or does it serve your assumptions about scale you don't have?

Serverless 适用于流量波动大、不可预测的负载
边缘函数 适用于对延迟敏感的操作
当运维开销大于成本时，选择托管数据库
当控制/成本/合规性有要求时，选择自托管

核心问题：云端是为用户服务，还是为你对未实现规模的假设服务？

UI/UX Philosophy

UI/UX 理念

1. Immediate Feedback

1. 即时反馈

<100ms for user actions, honest progress for longer operations

Optimistic updates where safe (can rollback)
Progress indicators that reflect actual work
Spinners are fine - they indicate honest work
Skeleton screens for predictable loading patterns

Loading states should:

Show what's happening
Estimate time when possible
Allow cancellation for long operations
Never fake progress

用户操作反馈<100ms，长耗时操作需如实展示进度

在安全场景下使用乐观更新（可回滚）
进度指示器需反映真实工作进度
加载动画没问题——它代表正在真实处理
可预测的加载场景使用骨架屏

加载状态需满足：

展示当前正在进行的操作
尽可能预估耗时
长耗时操作允许取消
绝不伪造进度

2. Visible State

2. 状态可见

User always knows what the system is doing

Status visible without digging
Background processes surfaced
Errors prominent, not hidden
System explains its decisions when non-obvious

No black boxes

User can understand why something happened
Audit trail for important actions
State inspectable in dev tools

用户始终知晓系统当前状态

状态无需深入查找即可查看
后台进程需显性展示
错误需突出显示，而非隐藏
当系统决策不明显时，需给出解释

拒绝黑箱

用户能理解事情发生的原因
重要操作需有审计轨迹
状态可在开发者工具中查看

3. Spatial Consistency

3. 空间一致性

Things stay where you put them

No layout shifts after load
No rearranging "for the user"
Muscle memory works
Consistent component placement

Predictable navigation

Back button works
URLs are bookmarkable and shareable
State survives refresh
Deep linking works

元素位置保持固定

加载完成后不发生布局偏移
不要“为用户”重新排列元素
符合用户肌肉记忆
组件位置保持一致

可预测的导航

返回按钮正常工作
URL可收藏和分享
刷新后状态保留
深度链接正常工作

4. Undo & Recovery

4. 撤销与恢复

Implemented at the data layer, not just UI

Soft delete by default
Versioned state where valuable
Recovery path documented
"Are you sure?" is not a substitute for undo

Destructive actions

Confirmation for irreversible operations
Grace period before permanent deletion
Clear communication of consequences

在数据层实现，而非仅在UI层

默认使用软删除
重要场景使用版本化状态
恢复路径需文档化
“你确定吗？”不能替代撤销功能

破坏性操作

不可逆操作需确认
永久删除前设置宽限期
清晰告知操作后果

5. Respect Attention

5. 尊重用户注意力

Notifications

User opts in explicitly
Meaningful, not engagement-driven
Batched where appropriate
Easy to adjust or disable

Modals & Interruptions

User-initiated, not system-initiated
Dismissable
Don't trap focus unnecessarily
Keyboard accessible

Autoplay

Never for audio
Video only with explicit user intent
Motion respects prefers-reduced-motion

Defaults over customization

Good defaults eliminate settings
Power user options available but not required
Complexity progressive

通知

用户需主动开启
有实际意义，而非为了提升活跃度
可批量发送
易于调整或关闭

模态框与干扰项

由用户触发，而非系统主动发起
可关闭
不必要时不锁定焦点
支持键盘操作

自动播放

音频绝不自动播放
视频仅在用户明确允许时自动播放
动效需遵循 prefers-reduced-motion 配置

默认配置优先于自定义

良好的默认配置可减少设置项
为高级用户提供选项，但不强制要求
复杂度逐步递增

What This Rejects

拒绝的理念

Derivative Thinking

衍生思维

"X but for Y" without asking if Y needs X
Features because competitors have them
Patterns because tutorials use them
Architecture because FAANG does it

不问Y是否需要X，直接做“面向Y的X”
只因竞品有某功能就跟风添加
只因教程使用就照搬模式
只因大厂使用就模仿架构

Cargo Cult Engineering

盲目跟风式工程

"Best practices" from different-scale companies
Microservices for 3-person teams
Kubernetes for single-server loads
OAuth for internal tools

照搬不同规模公司的“最佳实践”
3人团队使用微服务
单服务器负载使用Kubernetes
内部工具使用OAuth

Premature Complexity

过早引入复杂度

Abstraction layers "for future flexibility"
Scale architecture before scale problems
Features before foundations work
Real-time before single-user works

为“未来灵活性”添加抽象层
在出现规模问题前就搭建规模化架构
基础功能未完善就添加新特性
单用户功能未实现就做实时功能

Process Over Thinking

流程替代思考

Scrum ceremonies replacing actual thought
Documentation for compliance, not clarity
Meetings about meetings
Roadmaps pretending to predict

用Scrum仪式替代实际思考
为合规而非清晰性编写文档
开会议论会议
用路线图假装能预测未来

Application

实践方法

When Reviewing Designs

设计评审时

When Generating Solutions

生成解决方案时

Start by asking:

What genuinely new thing are we creating?
What's the simplest architecture that enables it?
What complexity is earned by real constraints?

Default to:

Simplest tool that works
Framework if team knows it and it fits
Local-first where possible
Cloud where genuinely needed

Add complexity when:

Pain is measurable, not theoretical
Team agrees on the tradeoff
The path back to simple is documented

首先问自己：

我们要创造什么全新事物？
实现它的最简架构是什么？
哪些复杂度是由真实约束带来的？

默认选择：

选用能解决问题的最简工具
若团队熟悉且适配场景，则使用框架
尽可能优先本地化
仅在真正需要时使用云端

添加复杂度的时机：

痛点可衡量，而非理论上的
团队一致认可权衡方案
记录回归简洁方案的路径

Threshold Triggers

阈值触发条件

When to upgrade from defaults:

From	To	Trigger
SQLite	Postgres	>10 concurrent writers OR >100GB data OR need PostGIS/full-text search
Monolith	Services	Team can't work on same codebase OR genuine scale isolation needed
Static	Server	Need auth, real-time, or server-side computation
Local storage	Cloud sync	Multi-device is validated user need, not assumption
Library	Framework	Team expertise exists AND time-to-market critical AND framework opinions align
Simple	Complex	Pain is measurable, not theoretical

从默认方案升级的时机：

从	到	触发条件
SQLite	Postgres	并发写入>10 或数据量>100GB 或需要PostGIS/全文检索
单体应用	微服务	团队无法在同一代码库协作或确实需要按规模隔离
静态托管	服务器	需要认证、实时功能或服务端计算
本地存储	云端同步	多设备支持是已验证的用户需求，而非假设
库	框架	团队具备相关经验且上市时间至关重要且框架理念与需求匹配
简单方案	复杂方案	痛点可衡量，而非理论上的

Justified Exceptions

合理例外

Complexity is acceptable when:

Frameworks: Team expertise exists AND problem fits framework opinions AND time-to-market matters
Cloud dependencies: Multi-user collaboration OR heavy compute OR compliance requires it
Microservices: Teams can't coordinate on monolith OR genuine scale isolation needed
Heavy tooling: Build time investment pays off in development velocity

Document the reasoning. Future you will thank present you.

在以下场景中，复杂度是可接受的：

框架：团队具备深厚经验且问题场景适配框架理念且上市时间至关重要
云端依赖：多用户协作或重型计算或合规要求
微服务：团队无法在单体应用上协同或确实需要按规模隔离
重型工具链：构建阶段的投入能提升开发速度

请记录理由。未来的你会感谢现在的自己。

Pragmatic Defaults

务实默认准则

Start simple, add complexity when pain is measurable.

Begin with the simplest architecture that could work
Wait for real problems, not imagined ones
Measure before optimizing
Document why you're adding complexity
Ensure the path back to simple exists

Premature complexity is technical debt with interest.

从简单开始，仅当痛点可衡量时再增加复杂度。

从可能有效的最简架构开始
等待真实问题出现，而非假想问题
先衡量再优化
记录添加复杂度的原因
确保回归简洁方案的路径存在

过早引入复杂度是带利息的技术债务。

Anti-Dogma Clause

反教条条款

These are defaults, not laws. Violate with documented reasoning.

Every principle here has valid exceptions. The goal isn't purity - it's intentionality.

Valid reasons to deviate:

Team expertise strongly favors different approach
Business timeline requires faster path
Regulatory/compliance requirements
Measured performance needs
User research contradicts assumption

Invalid reasons to deviate:

"Everyone does it this way"
"We might need it someday"
"The tutorial used this"
"It's best practice" (without understanding why)

When you deviate, write down why. One sentence in a comment, ADR, or README.

这些是默认准则，而非定律。若要违反，请记录理由。

此处的每一条原则都有合理的例外。目标不是纯粹性——而是目的性。

合理的偏离理由：

团队经验强烈倾向不同方案
业务 timeline 要求更快路径
监管/合规要求
可衡量的性能需求
用户研究与假设矛盾

不合理的偏离理由：

“大家都这么做”
“我们可能以后需要”
“教程用的是这个”
“这是最佳实践”（但不理解背后原因）

当你偏离准则时，请写下理由。可以是注释、ADR或README中的一句话。

Quick Reference

快速参考

Dimension	Default	Upgrade When
Storage	SQLite	Concurrent writes, scale, features
Framework	Yes, if team knows it	Build from scratch if simpler
Cloud	Where genuinely needed	Don't assume, validate
Config	YAML/JSON, well-documented	-
Errors	Teaching messages	-
Loading	Spinners with honest progress	-
State	Visible, inspectable	-
Undo	Data-layer versioning	-
Complexity	Earned, not assumed	Document reasoning

维度	默认方案	升级时机
存储	SQLite	并发写入、规模扩展、功能需求
框架	是，若团队熟悉	若最简方案是从零构建
云端	仅在真正需要时使用	不假设，需验证
配置	YAML/JSON，带完善文档	-
错误提示	具备指导性	-
加载状态	如实展示进度的加载动画	-
状态	可见、可查	-
撤销	数据层版本化	-
复杂度	必要时才引入，而非假设	记录理由

The Core Question

核心问题

When designing anything, ask:

"Am I creating something new, or commenting on something that exists?"

Renaissance architecture isn't about rejecting modern tools. It's about using them to build genuinely new things - not just another variation on established patterns.

Medieval scholars could only write commentaries because they believed truth was revealed in the past. We have no such limitation. We can create.

在设计任何事物时，请自问：

“我是在创造新事物，还是在对现有事物做评论？”

文艺复兴式架构不是要拒绝现代工具，而是要利用它们构建真正的创新事物——而非只是现有模式的又一个变体。

中世纪学者只能做注释，因为他们认为真理存在于过去。我们没有这样的限制。我们可以创造。