CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Common Development Commands
6 
7### Frontend Development
8```bash
9# Install dependencies
10cd frontend && npm install
11 
12# Start development server (uses Expo)
13cd frontend && npx expo start
14 
15# Start with specific Starknet environment
16cd frontend && npm run start:devnet   # For local devnet
17cd frontend && npm run start:sepolia  # For Sepolia testnet  
18cd frontend && npm run start:mainnet  # For mainnet
19 
20# Run on specific platforms
21cd frontend && expo run:android
22cd frontend && expo run:ios
23 
24# Linting
25cd frontend && npx expo lint
26cd frontend && npx expo lint --fix
27 
28# Run tests (Jest)
29cd frontend && npm test
30```
31 
32### Smart Contract Development
33```bash
34# Build contracts
35cd onchain && scarb build
36 
37# Run tests
38cd onchain && snforge test
39 
40# Deploy contracts
41cd onchain/scripts && ./deploy-devnet.sh   # Deploy to devnet
42cd onchain/scripts && ./deploy-sepolia.sh  # Deploy to Sepolia
43cd onchain/scripts && ./deploy-mainnet.sh  # Deploy to mainnet
44 
45# Setup contracts after deployment
46cd onchain/scripts && ./setup-contracts.sh
47```
48 
49## Architecture Overview
50 
51### Frontend Architecture
52POW! is a React Native mobile game using Expo Router for file-based navigation. The frontend follows a modular architecture with:
53 
54- **State Management**: Zustand stores in `/frontend/app/stores/` manage game state, user data, blockchain interactions, and UI state
55- **Blockchain Integration**: Multiple React contexts in `/frontend/app/contexts/` handle different blockchain connections (StarknetJS, AVNU SDK)
56- **Game Logic**: Custom hooks in `/frontend/app/hooks/` encapsulate game mechanics, timers, and state calculations
57- **Component Structure**: Page components use store observers for reactive updates and delegate logic to hooks
58 
59Key architectural patterns:
60- Store observers trigger re-renders when relevant state changes
61- Hooks calculate derived state from stores and manage game intervals
62- Context providers wrap the app to provide blockchain connectivity
63- Environment variables control which blockchain network to connect to
64 
65### Smart Contract Architecture
66The onchain contracts use Cairo and follow a modular component-based design:
67 
68- **Core Contract**: `pow_game` contract in `/onchain/src/pow_game.cairo` is the main entry point
69- **Component System**: Separate components for different game features (upgrades, prestige, builders, staking)
70- **Upgradeability**: Uses OpenZeppelin's upgradeable contract pattern
71- **Security**: Leverages OpenZeppelin components for standard security features
72 
73Contract interaction flow:
741. Frontend uses Starknet.js to call contract methods
752. Embedded wallet (AVNU SDK) sponsors gas fees for users
763. Game state is stored on-chain and synced to frontend stores
774. Events emitted by contracts update frontend state
78 
79### Key Integration Points
80- **Account Creation**: Uses OpenZeppelin Smart Account with AVNU paymasters for gasless transactions
81- **State Sync**: Frontend polls blockchain for state updates and caches in Zustand stores
82- **Asset Management**: Game assets (images, sounds, fonts) are bundled with the app
83- **Configuration**: JSON files define game mechanics, balancing, and progression curves