Keychat is a secure messaging app with a unique architecture. When explaining or working with the codebase, understand these key components:

Core Technologies

Package Structure

packages/
├── app/                    # Main Flutter app
├── keychat_ecash/          # Ecash wallet functionality
└── keychat_rust_ffi_plugin/ # Native crypto via Rust

Key Services (packages/app/lib/service/)

• signal_chat.service.dart - Signal protocol session management
• mls_group.service.dart - MLS group key operations
• websocket.service.dart - Nostr relay connections
• chat.service.dart - High-level message routing
• relay.service.dart - Relay management
• identity.service.dart - User identity management

State Management

Uses GetX pattern:

• Controllers in lib/controller/
• Services are singleton instances
• Reactive state with .obs observables

Database

Uses Isar (NoSQL for Flutter):

• Models in lib/models/
• Models use @collection annotation
• Generated code via build_runner (*.g.dart, *.isar.dart)

Rust FFI Bridge

Native crypto operations use flutter_rust_bridge:

• Rust code: packages/keychat_rust_ffi_plugin/rust/src/
• Generated Dart bindings: packages/keychat_rust_ffi_plugin/lib/
• Key APIs: Cashu, Nostr, Signal, MLS

Message Flow

1. User composes message
2. Signal/MLS encrypts content
3. Message wrapped in Nostr event
4. Ecash stamp attached (if relay requires payment)
5. Sent via WebSocket to Nostr relay
6. Recipient receives, decrypts, displays

Batch

Research and plan a large-scale change, then execute it in parallel across isolated worktree agents.

Workflow

Phase 1: Research & Plan

1. Understand the requested change thoroughly
2. Identify all files and modules that need modification
3. Group changes into independent, parallelizable units (max 10 units)
4. Present the plan to the user for approval before proceeding

Phase 2: Execute

1. For each unit of work, launch an Agent with isolation: "worktree" to make the changes independently
2. Run agents in parallel where possible (up to 5 concurrent agents)
3. Each agent should:
   • Make the required changes
   • Run relevant tests or lint checks
   • Commit changes with a clear message

Phase 3: Review & Merge

1. Collect results from all agents
2. Report successes and failures
3. For successful changes, present diffs for user review
4. Help merge changes back to the main branch

Rules

• Always get user approval before executing changes
• Never modify more than what was requested
• If a unit fails, continue with others and report the failure
• Keep the user informed of progress throughout

Set up the Keychat development environment from scratch.

Steps

1. Update git submodules

   git submodule update --init --recursive
   

2. Ensure melos is installed

   dart pub global activate melos 7.3.0
   

3. Bootstrap all packages

   melos bootstrap
   

4. Check for .env file If packages/app/.env doesn't exist, remind the user:

   • Copy .env.example to .env
   • Configure FCM keys for push notifications

Success criteria

• All submodules are cloned
• Melos bootstrap completes without errors
• Dependencies are resolved for all packages

Flutter Check

Run a comprehensive Flutter quality check pipeline for the Keychat project.

Steps

1. Analyze: Run melos run analyze to check for Dart analyzer warnings and errors
2. Format Check: Run dart format --set-exit-if-changed . to verify formatting
3. Test: Run melos run test:flutter to execute Flutter unit tests
4. Generated Code: Check if generated files (.g.dart) are up to date by running melos run build:runner and verifying no diff

Behavior

• Run all steps sequentially
• Report results for each step clearly
• If any step fails, continue running remaining steps but report all failures at the end
• Provide actionable fix suggestions for any issues found

Run code generation for the Keychat project.

Arguments

• $ARGUMENTS - Optional: type of generation (all, dart, flutter, intl, runner)

Generation Commands

Common scenarios

After modifying Isar model files

Run melos run build:runner to regenerate database schemas.

After adding new translations

Run melos run intl:generate to regenerate localization files.

After modifying any model with @JsonSerializable

Run melos run generate:all to regenerate JSON serialization code.

Workflow

1. If no argument, run melos run generate:all
2. If specific type provided, run the corresponding command
3. Report any errors encountered during generation

Run code quality checks on the Keychat project.

Arguments

• $ARGUMENTS - Optional: "fix" to auto-fix formatting issues

Commands

Run all checks (analyze + format check)

melos run lint:all

Run analyzer only

melos run analyze

Check formatting

dart format --set-exit-if-changed .

Fix formatting

dart format .

Workflow

1. If $ARGUMENTS is "fix":

   • Run dart format . to fix formatting
   • Then run melos run analyze to check for remaining issues

2. Otherwise:

   • Run melos run lint:all to check everything
   • Report any issues found

Analysis configuration

The project uses very_good_analysis rules defined in analysis_options.yaml.

Update and install CocoaPods dependencies for iOS and macOS builds.

Command

Run the melos pods script:

melos run pod:install

This will:

1. Navigate to packages/app/ios
2. Run pod update && pod install --repo-update
3. Navigate to packages/app/macos
4. Run pod update && pod install --repo-update

When to use

• After adding new native iOS/macOS dependencies
• When Podfile.lock is out of sync
• After upgrading Flutter or plugins
• When getting "pod not found" errors

Troubleshooting

If pods fail to install:

1. Try cleaning first: cd packages/app/ios && rm -rf Pods Podfile.lock
2. Update CocoaPods: gem install cocoapods
3. Clear pod cache: pod cache clean --all

Clean build artifacts and reset the project state.

Commands

Full clean with melos

melos run clean:flutter

This runs in all Flutter packages:

• flutter clean
• flutter pub get
• Removes ios/Podfile.lock
• Runs pod repo update && pod install

Quick clean for app only

cd packages/app && flutter clean && flutter pub get

Clean generated files

cd packages/app && rm -rf lib/**/*.g.dart lib/**/*.isar.dart

When to use

• Build errors after updating Flutter
• Inconsistent state between packages
• After major dependency changes
• Xcode or Gradle cache issues

After cleaning

Remember to:

1. Run melos bootstrap to restore dependencies
2. Run melos run generate:all to regenerate code
3. Run melos run pod:install for iOS/macOS

Run the Keychat app on a device or simulator.

Arguments

• $ARGUMENTS - Optional: device ID to run on

Workflow

1. First list available devices:

   flutter devices
   

2. If $ARGUMENTS is provided, run on that device:

   cd packages/app && flutter run -d $ARGUMENTS
   

3. If no device specified:

   • If only one device is available, use it
   • If multiple devices, show the list and ask user to specify

Alternative entry points

The app has multiple entry points for different environments:

• lib/main.dart - Production
• lib/main_dev1.dart - Development 1
• lib/main_dev2.dart - Development 2
• lib/main_dev3.dart - Development 3

To run with a specific entry point:

cd packages/app && flutter run -d <device> -t lib/main_dev1.dart

Build the Rust native libraries for the keychat_rust_ffi_plugin.

Arguments

• $ARGUMENTS - Target platform: ios, android, linux, windows, macos

Prerequisites

Ensure flutter_rust_bridge codegen is installed:

cargo install flutter_rust_bridge_codegen@2.11.1

For Linux, install system dependencies:

apt install protobuf-compiler libsecret-1-dev

Target Setup and Build Commands

Workflow

1. Change to the Rust plugin directory:

   cd packages/keychat_rust_ffi_plugin/rust
   

2. If no target specified, ask which platform to build for

3. Add the rustup target if not already added:

   rustup target add <target>
   

4. Build the library:

   cargo build --target <target> --release --target-dir target
   

5. Report build success or any errors

Regenerating Dart Bindings

After modifying Rust API files, regenerate the Dart bindings:

cd packages/keychat_rust_ffi_plugin
flutter_rust_bridge_codegen generate

Run tests for the Keychat project.

Arguments

• $ARGUMENTS - Optional: specific test file path or package name

Test Commands

Run all tests

melos run test:all

Run Flutter tests only

melos run test:flutter

Run Dart tests only

melos run test:dart

Run a specific test file

cd packages/app
flutter test $ARGUMENTS

Workflow

1. If no arguments provided, run melos run test:all
2. If a file path is provided (ends with .dart), run that specific test
3. Report test results clearly, including any failures