Skip to content

CLAUDE.md

Latest commit

 

History

History
260 lines (199 loc) · 6.85 KB

CLAUDE.md

File metadata and controls

260 lines (199 loc) · 6.85 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Gem Wallet Android - Claude Code Reference

Project Overview

Gem Wallet is an open-source, multi-chain cryptocurrency wallet for Android built with Kotlin/Compose. The app provides secure self-custody wallet functionality with support for multiple blockchains including Ethereum, Bitcoin, Solana, and many others.

Key Technologies:

  • Frontend: Kotlin, Jetpack Compose, Android SDK
  • Backend: Rust Core library for cryptographic operations
  • Build System: Gradle with Kotlin DSL
  • Task Runner: Just (justfile)
  • Docker: Multi-stage builds for CI/CD

Repository Structure

gem-android/
├── app/                     # Main Android application module
├── core/                    # Rust core library (submodule)
├── gemcore/                 # JNI bindings for Rust core
├── ui/                      # UI components and screens
├── data/                    # Data layer (repositories, services)
├── blockchain/              # Blockchain-specific implementations
├── features/                # Feature modules (NFT, recipient, etc.)
├── flavors/                 # Build flavors (Google, Samsung, etc.)
├── Dockerfile               # Base Docker image for Android development
├── reproducible/            # Reproducible build tooling (Dockerfile, verify script, docs)
└── justfile                 # Task definitions

Development Setup

Prerequisites

  1. Android Studio (latest version)
  2. JDK 17 (preferably via SDKMAN)
  3. Just task runner (brew install just)
  4. GitHub Personal Access Token with read:packages permission

Initial Setup

# Install development dependencies
just bootstrap

# Generate GitHub token and add to local.properties:
echo "gpr.username=<your-github-username>" >> local.properties
echo "gpr.token=<your-github-personal-token>" >> local.properties

# Generate models (optional)
just generate

Common Commands

Development

# List all available commands
just list

# Bootstrap development environment
just bootstrap

# Generate TypeShare models from Rust
just generate

# Generate models only
just generate-models

# Update core submodule
just core-upgrade

# Localize strings
just localize

Building

# Build debug APK
./gradlew assembleGoogleDebug

# Build release bundle (unsigned)
just unsigned-release

# Build all release variants
just release

# Extract universal APK from bundle
just extract-universal-apk

# Clean build
./gradlew clean

Testing

# Run unit tests
./gradlew test

# Run specific test suite
./gradlew :app:testGoogleDebugUnitTest

# Build test APK
./gradlew assembleGoogleDebugAndroidTest

# Run connected Android tests
./gradlew connectedGoogleDebugAndroidTest

# Run all tests
./gradlew check

Docker

# Build base Docker image
just build-base-image

# Build app Docker image
just build-app-image

# Build with specific tag
TAG=feature-branch just build-app-image

# Build app artifacts inside Docker (uses the image above)
just build-app-in-docker

Linting & Quality

# Run lint checks
./gradlew lint

# Run detekt static analysis
./gradlew detekt

# Format code
./gradlew ktlintFormat

Project Architecture

Multi-Module Structure

  • app/: Main application module with Activities and Application class
  • ui/: Shared UI components, themes, and Compose screens
  • data/: Repository pattern implementation, database, network services
  • gemcore/: JNI bindings to Rust core library
  • blockchain/: Blockchain-specific implementations and models
  • features/: Modular features (NFT management, recipient handling, etc.)

Build Flavors

  • google: Google Play Store version with Firebase/FCM
  • huawei: Huawei AppGallery version
  • samsung: Samsung Galaxy Store version
  • solana: Solana-focused variant
  • universal: Universal build

Key Dependencies

  • Jetpack Compose: Modern UI toolkit
  • Hilt: Dependency injection
  • Room: Local database
  • Retrofit: Network layer
  • WalletConnect: dApp connectivity via Reown SDK
  • Rust Core: Cryptographic operations via JNI
  • Wallet Core: TrustWallet core library for blockchain operations
  • Gemstone: Internal library for additional functionality
  • Coil: Image loading
  • Ktor: WebSocket client for real-time data

CI/CD

GitHub Actions

  • ci.yml: Main CI pipeline (tests, lint, build)
  • docker.yml: Docker image builds for releases

Docker Workflow

  1. Base Image: Built from Dockerfile with Android SDK, NDK, JDK
  2. App Image: Built from reproducible/Dockerfile using base image
  3. Artifacts: APK/AAB files uploaded to GitHub releases

Development Guidelines

Code Style

  • Follow Kotlin coding conventions
  • Use Jetpack Compose for UI development
  • Implement repository pattern for data access
  • Use Hilt for dependency injection
  • Write unit tests for business logic

Git Workflow

  • Main Branch: main (stable releases)
  • Feature Branches: feature/description or fix/description
  • Commit Messages: Follow Conventional Commits

Security

  • Never commit secrets or API keys
  • Use local.properties for sensitive configuration
  • Follow Android security best practices
  • Implement proper key management

Troubleshooting

Common Issues

Build Failures:

# Clean and rebuild
./gradlew clean
just bootstrap
./gradlew build

NDK Issues:

# Reinstall NDK
just install-ndk

# Install Rust toolchains
just install-toolchains

Submodule Issues:

# Update core submodule
git submodule update --init --recursive
just core-upgrade

Docker Build Issues:

  • Ensure Docker has sufficient memory (8GB+ recommended)
  • Check base image availability
  • Verify GitHub token permissions

Getting Help

Useful File Locations

  • Main Activity: app/src/main/kotlin/com/gemwallet/android/MainActivity.kt
  • Build Config: app/build.gradle.kts
  • Core Dependencies: gradle/libs.versions.toml
  • Localization: ui/src/main/res/values/
  • Assets: app/src/main/assets/

Performance Notes

  • Rust Core: Heavy cryptographic operations are offloaded to Rust
  • Memory: Configure Android Studio with sufficient heap size
  • Build Cache: Gradle build cache is enabled for faster builds
  • Docker: Multi-stage builds optimize image size and build speed

Development Memories

  • You will use only gradle for tests and build
  • Always run tests
  • remember not write comments to code
  • on each modification clean imports