Monorepo Architecture Overview

Platform Structure (Example)

• •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 components

Core Packages (Example)

• •packages/core/ - Core business logic, cryptography, protocol implementations
• •packages/kit/ - Application logic, state management, API integrations
• •packages/kit-bg/ - Background services and workers
• •packages/components/ - Cross-platform UI components
• •packages/shared/ - Platform abstractions, utilities, build configurations

Key Architectural Patterns

• •Cross-platform UI: Universal components with platform-specific adaptations
• •Platform-specific files: Use .native.ts, .desktop.ts, .web.ts, .ext.ts suffixes
• •State management: Atomic state management (e.g., Jotai, Zustand)
• •Package isolation: Clear boundaries between packages

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: @{scope}/components, @{scope}/core, @{scope}/kit
• •Platform detection via shared utilities
• •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):

• •@{scope}/shared - FORBIDDEN to import from any other internal packages
• •@{scope}/components - ONLY allowed to import from shared
• •@{scope}/kit-bg - ONLY allowed to import from shared and core (NEVER components or kit)
• •@{scope}/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 type check to validate no circular dependency introduced
4. •If unsure, find an alternative approach that respects the hierarchy

COMMON VIOLATIONS TO AVOID:

• •❌ Importing from kit in components
• •❌ Importing from components in kit-bg
• •❌ Importing from kit in core
• •❌ Any "upward" imports in the hierarchy

Component Structure

• •UI components in packages/components/src/
• •Business logic in packages/kit/src/
• •Domain-specific code in packages/core/src/

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
• • Error handling follows established patterns
• • State management patterns consistently applied
• • UI component patterns followed
• • Translation patterns properly implemented (if applicable)
• • Testing patterns maintained and extended