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:

1. Verify the import respects the hierarchy above
2. Check if the import creates a circular dependency
3. 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):

1. 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

2. 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

3. 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

4. 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:

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

WHEN MODIFYING EXISTING CODE:

1. Understand Context: Read surrounding code and imports
2. Preserve Patterns: Maintain existing architectural decisions
3. Consistent Style: Match existing code style and structure
4. 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