Cline rules

1# WalletPro Mobile - Complete Project Rules Guide
2 
3This document serves as the definitive guide for LLMs working on the WalletPro Mobile project. It outlines all architectural patterns, coding standards, and operational rules that must be followed.
4 
5## 📋 Table of Contents
6 
71. [Project Overview](#project-overview)
82. [Architecture & Structure Rules](#architecture--structure-rules)
93. [Development Rules](#development-rules)
104. [Blockchain Integration Rules](#blockchain-integration-rules)
115. [UI/UX Rules](#uiux-rules)
126. [State Management Rules](#state-management-rules)
137. [Security Rules](#security-rules)
148. [Build & Deployment Rules](#build--deployment-rules)
159. [Testing Rules](#testing-rules)
1610. [Performance Rules](#performance-rules)
17 
18---
19 
20## 🎯 Project Overview
21 
22**WalletPro Mobile** is a React Native cryptocurrency wallet built with Expo and Alchemy's Account Kit. It enables users to manage smart accounts across multiple blockchain networks with a focus on security, usability, and modern mobile UX.
23 
24### Core Technologies
25- **React Native 0.76.9** + **Expo 52.0.47**
26- **TypeScript** for type safety
27- **Alchemy Account Kit** for smart account management
28- **Zustand** for state management
29- **NativeWind** (Tailwind CSS) for styling
30- **HeroUI Native** component library
31 
32---
33 
34## 🏗️ Architecture & Structure Rules
35 
36### File Organization
37```
38walletpro-mobile/
39├── app/                    # Expo Router pages
40│   ├── (main)/            # Main app sections
41│   ├── accounts/          # Account management
42│   ├── send/              # Transaction sending
43│   ├── history/           # Transaction history
44│   └── settings/          # App settings
45├── src/
46│   ├── components/        # Reusable UI components
47│   │   └── ui/           # HeroUI Native primitives
48│   ├── config/           # Configuration files
49│   ├── context/          # React contexts
50│   ├── hooks/            # Custom hooks
51│   ├── lib/              # Utility libraries
52│   ├── store/            # Zustand stores
53│   ├── types/            # TypeScript type definitions
54│   └── utils/            # Utility functions
55├── assets/               # Static assets
56└── docs/                 # Project documentation
57```
58 
59### Component Creation Rules
601. **Always use TypeScript interfaces** for props
612. **Follow HeroUI Native patterns** for UI components
623. **Use NativeWind classes** for styling, never inline styles
634. **Create components in `src/components/`** for reusability
645. **Use PascalCase for component names**
656. **Export components as named exports**
66 
67```typescript
68// ✅ Correct
69interface ButtonProps {
70  title: string;
71  onPress: () => void;
72  variant?: 'primary' | 'secondary';
73}
74 
75export const CustomButton: React.FC<ButtonProps> = ({ 
76  title, 
77  onPress, 
78  variant = 'primary' 
79}) => {
80  return (
81    <Button 
82      className="bg-primary text-primary-foreground"
83      onPress={onPress}
84    >
85      <Text>{title}</Text>
86    </Button>
87  );
88};
89```
90 
91### Navigation Structure
921. **Use Expo Router** for all navigation
932. **File-based routing** in the `app/` directory
943. **Layout files** (_layout.tsx) define shared UI
954. **Modal presentations** use specific stack screen options
965. **Always use safe area insets** for mobile layouts
97 
98```typescript
99// ✅ Correct modal setup
100<Stack.Screen
101  name="otp-modal"
102  options={{
103    presentation: Platform.OS === "ios" ? "formSheet" : "containedTransparentModal",
104    animation: Platform.OS === "android" ? "slide_from_bottom" : "default",
105  }}
106/>
107```
108 
109---
110 
111## 💻 Development Rules
112 
113### TypeScript Standards
1141. **Strict TypeScript configuration** - no `any` types allowed
1152. **Use Viem types** for blockchain-related types
1163. **Create interfaces** for all complex data structures
1174. **Use type guards** for runtime type checking
1185. **Export types** from dedicated files in `src/types/`
119 
120```typescript
121// ✅ Correct typing
122import type { Address, Chain } from "viem";
123 
124export interface WalletAccount {
125  id: string;
126  name: string;
127  address: Address;  // Use Viem Address type
128  privateKey: string; // Encrypted in storage
129  createdAt: number;
130  lastUsed: number;
131  accountType?: 'smart' | 'imported';
132}
133```
134 
135### Code Style Rules
1361. **Use PNPM** as package manager
1372. **Follow ESLint and Prettier** configurations
1383. **Use functional components** with hooks
1394. **Prefer named exports** over default exports
1405. **Use const** for all declarations unless reassignment is needed
1416. **Implement error boundaries** for all major screens
142 
143### Import Organization
144```typescript
145// ✅ Correct import order
1461. React & React Native imports
1472. Third-party library imports
1483. Expo imports
1494. Account Kit imports
1505. Internal imports (src/*)
1516. Relative imports
152```
153 
154### Hook Usage Patterns
1551. **Custom hooks go in `src/hooks/`**
1562. **Use naming convention**: `use` + descriptive name
1573. **Always return consistent shape** from custom hooks
1584. **Handle loading and error states** in all async hooks
159 
160```typescript
161// ✅ Correct hook pattern
162export const useAccountBalance = (address: Address) => {
163  const [balance, setBalance] = useState<bigint>();
164  const [isLoading, setIsLoading] = useState(true);
165  const [error, setError] = useState<Error>();
166 
167  useEffect(() => {
168    // Implementation
169  }, [address]);
170 
171  return { balance, isLoading, error };
172};
173```
174 
175---
176 
177## ⛓️ Blockchain Integration Rules
178 
179### Account Kit Integration
1801. **Use AlchemyAuthSessionProvider** at app root
1812. **Always use ModularAccountV2** account type
1823. **Session expiration**: 24 hours default
1834. **Policy ID** from environment variables for all chains
184 
185```typescript
186// ✅ Correct Account Kit setup
187const config = createConfig({
188  chain: defaultAlchemyChain,
189  sessionConfig: {
190    expirationTimeMs: 1000 * 60 * 60 * 24, // 24 hours
191  },
192  transport: alchemy({
193    apiKey: Constants.expoConfig?.extra?.EXPO_PUBLIC_ALCHEMY_API_KEY!,
194  }),
195});
196```
197 
198### Multi-Chain Support
1991. **Use chains from `@account-kit/infra`** for supported networks
2002. **Default chain**: Sepolia for development
2013. **Custom networks** stored in local storage
2024. **Network status monitoring** for all chains
2035. **Gas sponsorship** where available
204 
205```typescript
206// ✅ Correct chain configuration
207export const alchemyChains = [
208  sepolia,     // Default
209  mainnet,
210  arbitrum,
211  base,
212  optimism,
213  // ... other supported chains
214];
215```
216 
217### Transaction Management
2181. **Always estimate gas** before sending transactions
2192. **Use gas sponsorship** when available
2203. **Implement proper error handling** for failed transactions
2214. **Store transaction history** locally with chain info
2225. **Refresh balances** after successful transactions
223 
224### Balance Tracking
2251. **Use reactive balance version** for updates
2262. **Fetch both native and token balances**
2273. **Implement USD price conversion** where possible
2284. **Cache balances** with TTL for performance
229 
230---
231 
232## 🎨 UI/UX Rules
233 
234### Theme System
2351. **Use HSL color tokens** defined in Tailwind config
2362. **Support system, light, and dark themes**
2373. **Theme detection** via `useColorScheme` hook
2384. **All components** must support theme switching
239 
240```typescript
241// ✅ Correct theme usage
242const { colorScheme, isDarkColorScheme } = useColorScheme();
243const theme = isDarkColorScheme ? DARK_THEME : LIGHT_THEME;
244```
245 
246### Component Library Rules
2471. **Use HeroUI Native primitives** from `@rn-primitives/*`
2482. **Follow established patterns** from existing components
2493. **Never style HeroUI components** with conflicting styles
2504. **Use semantic variants** (primary, secondary, destructive)
251 
252```typescript
253// ✅ Correct component usage
254import { Button } from '@src/components/ui/button';
255import { Card, CardContent, CardHeader } from '@src/components/ui/card';
256 
257<Button variant="primary" size="lg">
258  <Text>Send Transaction</Text>
259</Button>
260```
261 
262### Layout & Responsive Design
2631. **Always use SafeAreaView** for mobile layouts
2642. **Use flexbox layouts** with NativeWind classes
2653. **Implement proper spacing** using Tailwind spacing scale
2664. **Handle platform differences** with Platform.OS checks
2675. **Use hairline borders** for subtle dividers
268 
269### Navigation Patterns
2701. **Bottom navigation** for main sections
2712. **Stack navigation** for detail screens
2723. **Modal presentations** for overlays
2734. **Consistent header patterns** across screens
2745. **Deep linking support** via Expo Router
275 
276---
277 
278## 🗃️ State Management Rules
279 
280### Zustand Store Architecture
2811. **Single UI store** for all application state
2822. **Use subscribeWithSelector middleware** for optimization
2833. **Organize state by domain** (network, accounts, theme, etc.)
2844. **Create action functions** for all state updates
2855. **Use selectors** for optimized re-renders
286 
287```typescript
288// ✅ Correct store pattern
289interface UIStore {
290  // State
291  selectedNetwork: Chain;
292  activeAccount: WalletAccount | null;
293  
294  // Actions
295  setSelectedNetwork: (chain: Chain) => void;
296  setActiveAccount: (account: WalletAccount | null) => void;
297}
298 
299// Selectors for optimization
300export const useSelectedNetwork = () => useUIStore((state) => state.selectedNetwork);
301```
302 
303### State Synchronization
3041. **Use storage-sync middleware** for persistence
3052. **Sync critical state** (accounts, settings, theme)
3063. **Handle sync conflicts** gracefully
3074. **Implement versioning** for store migrations
308 
309### Background Communication
3101. **Use background bridge** for cross-process communication
3112. **Message types** follow strict naming convention
3123. **Handle all message types** in background bridge
3134. **Acknowledge all messages** from background processes
314 
315---
316 
317## 🔒 Security Rules
318 
319### Private Key Management
3201. **Never store private keys** in plain text
3212. **Use encrypted storage** (react-native-mmkv)
3223. **Implement wallet locking** mechanism
3234. **Secure key derivation** for account creation
3245. **Memory cleanup** after key operations
325 
326### Authentication & Session
3271. **Session expiration** after 24 hours
3282. **Secure session storage** in device storage
3293. **Biometric authentication** where available
3304. **Session invalidation** on app backgrounding
331 
332### Input Validation
3331. **Validate all addresses** using Viem utilities
3342. **Sanitize all user inputs** before processing
3353. **Implement transaction signing** confirmations
3364. **Validate chain IDs** before network switches
337 
338### Secure Storage
3391. **Use react-native-mmkv** for encrypted storage
3402. **Separate sensitive data** from general storage
3413. **Implement storage cleanup** on logout
3424. **Backup encryption keys** securely
343 
344---
345 
346## 🚀 Build & Deployment Rules
347 
348### Environment Configuration
3491. **Use app.json extra section** for environment variables
3502. **Never commit sensitive values** to version control
3513. **Required variables**: `EXPO_PUBLIC_ALCHEMY_API_KEY`, `EXPO_PUBLIC_ALCHEMY_POLICY_ID`
3524. **Platform-specific builds** via EAS Build
353 
354```json
355// ✅ Correct environment setup
356{
357  "expo": {
358    "extra": {
359      "EXPO_PUBLIC_ALCHEMY_API_KEY": "your-key-here",
360      "EXPO_PUBLIC_ALCHEMY_POLICY_ID": "your-policy-id-here"
361    }
362  }
363}
364```
365 
366### Build Requirements
3671. **Expo SDK 52.0.47** - exact version required
3682. **React Native 0.76.9** - exact version required
3693. **Node.js 18+** for development
3704. **PNPM 10.15.0+** as package manager
371 
372### Platform Considerations
3731. **iOS**: Support iOS 13+ with proper Info.plist configuration
3742. **Android**: Target API 33+ with proper permissions
3753. **Universal builds** for both platforms
3764. **App Store optimization** with proper metadata
377 
378### Version Management
3791. **Semantic versioning** for releases
3802. **Changelog maintenance** for all releases
3813. **Branch protection** for main branch
3824. **Automated builds** via GitHub Actions
383 
384---
385 
386## 🧪 Testing Rules
387 
388### Component Testing
3891. **Test all components** with React Native Testing Library
3902. **Mock external dependencies** (Account Kit, navigation)
3913. **Test user interactions** and state changes
3924. **Coverage requirement**: 80% minimum
393 
394### Integration Testing
3951. **Test store interactions** with mock data
3962. **Test navigation flows** between screens
3973. **Test blockchain integrations** with testnet data
3984. **Test error scenarios** and edge cases
399 
400### Test Organization
401```
402src/
403├── components/
404│   └── __tests__/       # Component tests
405├── store/
406│   └── __tests__/       # Store tests
407├── utils/
408│   └── __tests__/       # Utility tests
409└── __mocks__/          # Mock definitions
410```
411 
412### Mock Patterns
4131. **Mock Account Kit** for wallet operations
4142. **Mock Viem** for blockchain interactions
4153. **Mock navigation** for routing tests
4164. **Mock AsyncStorage** for storage tests
417 
418---
419 
420## ⚡ Performance Rules
421 
422### Component Optimization
4231. **Use React.memo** for expensive components
4242. **Implement virtual lists** for long lists
4253. **Optimize re-renders** with proper selectors
4264. **Use useCallback** and **useMemo** strategically
427 
428### Bundle Optimization
4291. **Tree-shake unused imports**
4302. **Lazy load heavy components**
4313. **Optimize image assets** with proper sizing
4324. **Use Hermes engine** for Android performance
433 
434### Memory Management
4351. **Cleanup listeners** in useEffect return functions
4362. **Avoid memory leaks** in long-lived components
4373. **Implement proper cache invalidation**
4384. **Monitor memory usage** in development
439 
440### Network Optimization
4411. **Implement request caching** for API calls
4422. **Use WebSocket connections** for real-time updates
4433. **Batch multiple operations** where possible
4444. **Implement offline support** with local storage
445 
446---
447 
448## 📝 Development Workflow Rules
449 
450### Git Workflow
4511. **Feature branches** from main branch
4522. **Descriptive commit messages** following conventional commits
4533. **Pull request reviews** required for all changes
4544. **Automated tests** must pass before merge
455 
456### Code Review Checklist
457- [ ] TypeScript types are correct
458- [ ] Components follow established patterns
459- [ ] Security best practices are followed
460- [ ] Tests are written and passing
461- [ ] Documentation is updated
462- [ ] Performance implications considered
463 
464### Release Process
4651. **Version bump** in package.json
4662. **Update changelog** with new features
4673. **Create release tag** in Git
4684. **Deploy to staging** for final testing
4695. **Deploy to production** after approval
470 
471---
472 
473## 🚨 Critical Rules (Must Follow)
474 
475### NEVER DO These:
4761. **NEVER store private keys** in plain text
4772. **NEVER commit API keys** to version control
4783. **NEVER use `any` type** in TypeScript
4794. **NEVER skip error handling** in async operations
4805. **NEVER modify HeroUI components** directly
4816. **NEVER use inline styles** instead of Tailwind classes
4827. **NEVER skip type safety** for blockchain operations
483 
484### ALWAYS DO These:
4851. **ALWAYS validate addresses** before transactions
4862. **ALWAYS handle loading states** in async operations
4873. **ALWAYS use selectors** for store subscriptions
4884. **ALWAYS implement error boundaries** for major screens
4895. **ALWAYS test on both platforms** before release
4906. **ALWAYS follow the established patterns** in this guide
4917. **ALWAYS update documentation** for API changes
492 
493---
494 
495## 🔍 Troubleshooting Guide
496 
497### Common Issues
4981. **Build failures**: Check package versions match requirements
4992. **Type errors**: Ensure proper Viem types are used
5003. **Theme issues**: Verify theme tokens are properly applied
5014. **Store issues**: Check selector usage and action calls
5025. **Navigation issues**: Verify file-based routing structure
503 
504### Debug Patterns
5051. **Use Flipper** for React Native debugging
5062. **Enable React DevTools** for component inspection
5073. **Use console logs** with proper context
5084. **Test with different device sizes**
5095. **Verify network connectivity** for blockchain operations
510 
511---
512 
513This document serves as the single source of truth for all development activities in the WalletPro Mobile project. All LLMs working on this project must follow these rules to maintain code quality, security, and consistency.
514 
515**Last Updated**: January 14, 2026
516**Version**: 1.0.0
517