OneKey Architecture Overview

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

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

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

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

Import Patterns

• Use workspace references: @onekeyhq/components , @onekeyhq/core , @onekeyhq/kit

• Platform detection via @onekeyhq/shared/src/platformEnv

• Conditional imports based on platform capabilities

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

Component Structure

• UI components in packages/components/src/

• Business logic in packages/kit/src/

• Chain-specific code in 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

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

Architecture Validation Checklist

BEFORE COMMITTING ANY CHANGES:

• Import hierarchy rules respected (no upward imports)

• Platform-specific files use correct extensions

• Security patterns maintained (especially for crypto operations)

• Error handling follows established patterns

• State management patterns consistently applied

• UI component patterns followed (Tamagui usage)

• Translation patterns properly implemented

• Testing patterns maintained and extended