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 Run yarn tsc:only to validate no circular dependency introduced 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
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