1k-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OneKey Architecture Overview

OneKey 架构概述

Platform Structure

平台结构

apps/desktop/
- Electron desktop app (Windows, macOS, Linux)
apps/mobile/
- React Native mobile app (iOS, Android)
apps/ext/
- Browser extension (Chrome, Firefox, Edge, Brave)
apps/web/
- Progressive web application
apps/web-embed/
- Embeddable wallet components

apps/desktop/
- Electron 桌面应用（Windows、macOS、Linux）
apps/mobile/
- React Native 移动应用（iOS、Android）
apps/ext/
- 浏览器扩展（Chrome、Firefox、Edge、Brave）
apps/web/
- 渐进式Web应用
apps/web-embed/
- 可嵌入钱包组件

Core Packages

核心包

packages/core/
- Blockchain protocol implementations, cryptography, hardware wallet communication
packages/kit/
- Application logic, state management, API integrations
packages/kit-bg/
- Background services and workers
packages/components/
- Tamagui-based cross-platform UI components
packages/shared/
- Platform abstractions, utilities, build configurations
packages/qr-wallet-sdk/
- Air-gapped wallet QR communication

packages/core/
- 区块链协议实现、密码学、硬件钱包通信
packages/kit/
- 应用逻辑、状态管理、API 集成
packages/kit-bg/
- 后台服务与工作线程
packages/components/
- 基于 Tamagui 的跨平台 UI 组件
packages/shared/
- 平台抽象、工具函数、构建配置
packages/qr-wallet-sdk/
- 离线钱包二维码通信

Key Architectural Patterns

关键架构模式

Multi-chain support: 40+ blockchains with pluggable chain implementations
Cross-platform UI: Tamagui for universal components with platform-specific adaptations
Platform-specific files: Use
```
.native.ts
```
,
```
.desktop.ts
```
,
```
.web.ts
```
,
```
.ext.ts
```
suffixes
Hardware wallet integration: Custom
```
@onekeyfe/hd-*
```
SDK packages
State management: Jotai for atomic state management

多链支持：可插拔的链实现，支持 40+ 条区块链
跨平台 UI：使用 Tamagui 实现通用组件，支持平台特定适配
平台特定文件：使用
```
.native.ts
```
、
```
.desktop.ts
```
、
```
.web.ts
```
、
```
.ext.ts
```
后缀
硬件钱包集成：自定义
```
@onekeyfe/hd-*
```
SDK 包
状态管理：使用 Jotai 实现原子状态管理

Code Organization

代码组织

File Naming Conventions

文件命名规范

Platform-specific implementations use suffixes:
```
.native.ts
```
,
```
.web.ts
```
,
```
.desktop.ts
```
,
```
.ext.ts
```
Component files use PascalCase:
```
ComponentName.tsx
```
Hook files use camelCase with
```
use
```
prefix:
```
useHookName.ts
```
Utility files use camelCase:
```
utilityName.ts
```

平台特定实现使用后缀：
```
.native.ts
```
、
```
.web.ts
```
、
```
.desktop.ts
```
、
```
.ext.ts
```
组件文件使用大驼峰命名：
```
ComponentName.tsx
```
Hook 文件使用小驼峰命名，带
```
use
```
前缀：
```
useHookName.ts
```
工具文件使用小驼峰命名：
```
utilityName.ts
```

Import Patterns

导入模式

Use workspace references:

@onekeyhq/components

@onekeyhq/core

@onekeyhq/kit

Platform detection via
```
@onekeyhq/shared/src/platformEnv
```
Conditional imports based on platform capabilities

使用工作区引用：

@onekeyhq/components

、

@onekeyhq/core

、

@onekeyhq/kit

通过
```
@onekeyhq/shared/src/platformEnv
```
检测平台
根据平台能力进行条件导入

Import Hierarchy Rules - STRICTLY ENFORCED

导入层级规则 - 严格强制执行

CRITICAL: Violating these rules WILL break the build and cause circular dependencies.

HIERARCHY (NEVER violate this order):

```
@onekeyhq/shared
```
- FORBIDDEN to import from any other OneKey packages
```
@onekeyhq/components
```
- ONLY allowed to import from
```
shared
```
```
@onekeyhq/kit-bg
```
- ONLY allowed to import from
```
shared
```
and
```
core
```
(NEVER
```
components
```
or
```
kit
```
)
```
@onekeyhq/kit
```
- Can import from
```
shared
```
,
```
components
```
, and
```
kit-bg
```
Apps (desktop/mobile/ext/web) - Can import from all packages

BEFORE ADDING ANY IMPORT:

Verify the import respects the hierarchy above
Check if the import creates a circular dependency
If unsure, find an alternative approach that respects the hierarchy

COMMON VIOLATIONS TO AVOID:

❌ Importing from
```
@onekeyhq/kit
```
in
```
@onekeyhq/components
```
❌ Importing from
```
@onekeyhq/components
```
in
```
@onekeyhq/kit-bg
```
❌ Importing from
```
@onekeyhq/kit
```
in
```
@onekeyhq/core
```
❌ Any "upward" imports in the hierarchy

重要提示：违反这些规则会破坏构建并导致循环依赖。

层级顺序（绝对不能违反）：

```
@onekeyhq/shared
```
- 禁止从任何其他 OneKey 包导入
```
@onekeyhq/components
```
- 仅允许从
```
shared
```
导入
```
@onekeyhq/kit-bg
```
- 仅允许从
```
shared
```
和
```
core
```
导入（绝对不能从
```
components
```
或
```
kit
```
导入
```
@onekeyhq/kit
```
- 可以从
```
shared
```
、
```
components
```
和
```
kit-bg
```
导入
应用（桌面/移动/扩展/网页） - 可以从所有包导入

添加任何导入之前：

验证导入符合上述层级规则
检查导入是否会造成循环依赖
如果不确定，寻找符合层级规则的替代方案

需要避免的常见违规行为：

❌ 在
```
@onekeyhq/components
```
中导入
```
@onekeyhq/kit
```
❌ 在
```
@onekeyhq/kit-bg
```
中导入
```
@onekeyhq/components
```
❌ 在
```
@onekeyhq/core
```
中导入
```
@onekeyhq/kit
```
❌ 任何层级向上导入

Component Structure

组件结构

UI components in
```
packages/components/src/
```
Business logic in
```
packages/kit/src/
```
Chain-specific code in
```
packages/core/src/chains/
```

UI 组件位于
```
packages/components/src/
```
业务逻辑位于
```
packages/kit/src/
```
链特定代码位于
```
packages/core/src/chains/
```

Deep Analysis & Architecture Consistency Framework

深度分析与架构一致性框架

Pre-Modification Analysis Protocol

修改前分析协议

MANDATORY ANALYSIS STEPS (Execute BEFORE any code changes):

Scope Impact Assessment
- Identify ALL packages/apps affected by the change
- Map dependencies that will be impacted (use
```
yarn why <package>
```
  if needed)
- Evaluate cross-platform implications (desktop/mobile/web/extension)
- Assess backward compatibility requirements
Pattern Consistency Verification
- Examine existing similar implementations in the codebase
- Identify established patterns and conventions used
- Verify new code follows identical patterns
- Check naming conventions align with existing code
Architecture Integrity Check
- Validate against monorepo import hierarchy rules
- Ensure separation of concerns is maintained
- Verify platform-specific code uses correct file extensions
- Check that business logic stays in appropriate packages
Performance Impact Evaluation
- Consider bundle size implications (especially for web/extension)
- Evaluate runtime performance effects
- Assess memory usage implications
- Consider impact on application startup time

必须执行的分析步骤（任何代码修改前执行：

**影响范围评估
- 确定所有受修改影响的包/应用
- 映射受影响的依赖关系（必要时使用
```
yarn why <package>
```
  查询）
- 评估跨平台影响（桌面/移动/网页/扩展）
- 评估向后兼容性要求
模式一致性验证
- 检查代码库中现有的类似实现
- 识别已有的模式和规范
- 验证新代码遵循相同的模式
- 检查命名规范与现有代码一致
架构完整性检查
- 验证符合 monorepo 导入层级规则
- 确保关注点分离
- 验证平台特定代码使用正确的文件扩展名
- 检查业务逻辑位于合适的包中
**性能影响评估
- 考虑包体积影响（尤其是网页/扩展）
- 评估运行时性能影响
- 评估内存使用影响
- 考虑对应用启动时间的影响

Code Pattern Recognition Framework

代码模式识别框架

WHEN ADDING NEW FUNCTIONALITY:

Find Similar Examples: Search codebase for similar implementations
Extract Patterns: Identify common approaches, naming, structure
Follow Conventions: Mirror existing patterns exactly
Validate Consistency: Ensure new code looks like existing code

WHEN MODIFYING EXISTING CODE:

Understand Context: Read surrounding code and imports
Preserve Patterns: Maintain existing architectural decisions
Consistent Style: Match existing code style and structure
Validate Integration: Ensure changes integrate seamlessly

添加新功能时：

查找类似示例：在代码库中搜索类似实现
提取模式：识别通用方法、命名、结构
遵循规范：完全照搬现有模式
验证一致性：确保新代码与现有代码风格一致

修改现有代码时：

理解上下文：阅读周边代码和导入
保留模式：维持现有的架构决策
一致风格：匹配现有代码风格和结构
验证集成：确保修改无缝集成