1k Architecture

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