1k-architecture

name	1k-architecture
description	OneKey monorepo architecture and code organization. Use when understanding project structure, package relationships, import rules, or component organization. Triggers on architecture, structure, packages, imports, hierarchy, dependencies, monorepo, organization.
allowed-tools	Read, Grep, Glob

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