Orchestrate synchronized human waves worldwide

A Kotlin Multiplatform mobile application orchestrating synchronized human waves through cities worldwide, fostering unity and shared human experience through real-time coordination and location-based services.

WorldWideWaves enables participants to join synchronized wave events at specific times and locations. The app leverages offline maps for 40+ major cities, real-time position tracking, and choreographed animations to create coordinated experiences across devices and geographies.

graph TB
    subgraph "Mobile Apps - Kotlin Multiplatform"
        ANDROID[Android App<br/>Jetpack Compose]
        IOS[iOS App<br/>Compose Multiplatform]
    end

    subgraph "Shared Business Logic - 70% Code Reuse"
        UI[UI Layer<br/>Compose Screens & ViewModels]
        DOMAIN[Domain Layer<br/>Event Observation, Wave Progression]
        DATA[Data Layer<br/>Repositories, Position Management]
    end

    subgraph "Platform Services"
        GPS[Device GPS<br/>CoreLocation / FusedLocation]
        MAPS[MapLibre<br/>Offline Vector Tiles]
        AUDIO[MIDI Audio<br/>AVAudioEngine / AudioTrack]
    end

    subgraph "Backend & Data"
        FIREBASE[Firebase<br/>Analytics & Crashlytics]
        API[Event API<br/>Configuration & Events]
        TILES[Map Data<br/>40+ Cities Offline]
    end

    ANDROID --> UI
    IOS --> UI
    UI --> DOMAIN
    DOMAIN --> DATA

    DATA --> GPS
    DATA --> MAPS
    DATA --> AUDIO

    ANDROID --> FIREBASE
    IOS --> FIREBASE
    DATA --> API
    MAPS --> TILES

    style ANDROID fill:#3DDC84,color:#000
    style IOS fill:#007AFF,color:#fff
    style UI fill:#4285f4,color:#fff
    style DOMAIN fill:#34a853,color:#fff
    style DATA fill:#ea4335,color:#fff

• Offline maps for 40+ global cities using MapLibre
• Real-time event loading with countdown timers
• GPS position tracking with simulation mode for testing
• Synchronized wave choreography with audio coordination
• Cross-platform business logic sharing (70% code reuse)
• Comprehensive CI/CD pipeline with multi-stage quality gates

iOS app running on iPhone 15 Pro simulator

Demo: Animated demo coming soon - watch this space!

WorldWideWaves/
├── composeApp/              # Android app (Compose UI)
├── shared/                  # Kotlin Multiplatform business logic
├── iosApp/                  # iOS app (Compose UI via ComposeUIViewController)
├── maps/                    # 40+ city offline map modules
│   ├── paris_france/
│   ├── new_york_usa/
│   └── ...
├── scripts/                 # Build tools and map generation
├── docs/                    # Documentation
├── .github/workflows/       # CI/CD pipelines
└── .git-hooks/              # Custom git hooks

| composeApp/ | Android app with Compose Multiplatform UI | | shared/ | Cross-platform business logic, ViewModels, and domain layer (70% code reuse) | | iosApp/ | iOS app with Compose UI via ComposeUIViewController | | maps/ | Android Dynamic Feature modules with offline map data (40+ cities) |

Core:

• Kotlin (latest stable)
• Kotlin Multiplatform
• Compose Multiplatform
• Gradle

Android:

• Target SDK 36
• Jetpack Compose
• MapLibre Android
• Koin

iOS:

• Deployment target: iOS 14+
• Compose Multiplatform via ComposeUIViewController
• MapLibre iOS (near feature parity with Android)
• Native Swift wrappers for platform services

Backend:

• Firebase Analytics & Crashlytics

See docs/architecture.md for detailed architecture.

Multi-stage GitHub Actions workflows with quality gates:

• Build Pipelines: Android and iOS compilation verification
• Quality Gates: Linting (ktlint, detekt), comprehensive unit test suite, security scanning
• UI Tests: Emulator-based UI tests with screenshot capture
• E2E Tests: Integration tests and Firebase Test Lab multi-device testing
• Performance Tests: Nightly performance regression detection

See docs/ci-cd.md for pipeline details.

| JDK | 17 (Temurin) | Kotlin compilation | | Android Studio | 2024.1+ | Android development | | Xcode | 15.0+ (macOS only) | iOS development | | Node.js | 16+ | Map generation scripts |

• CPU: 4+ cores (8+ recommended)
• RAM: 8 GB (16-32 GB recommended)
• Disk: 20 GB free (50 GB on SSD recommended)

See docs/environment-setup.md for complete setup instructions.

git clone https://github.com/mglcel/WorldWideWaves.git
cd WorldWideWaves

Create local.properties in project root:

sdk.dir=/path/to/android/sdk

FIREBASE_PROJECT_ID=your-project-id
FIREBASE_PROJECT_NUMBER=123456789012
FIREBASE_MOBILE_SDK_APP_ID=1:123456789012:android:abcdef1234567890
FIREBASE_API_KEY=AIzaSyABCDEF1234567890

Generate Firebase configuration:

./gradlew generateFirebaseConfig

./gradlew build

# Launch emulator
emulator -avd Pixel_3a_API_30 &

# Install and run
./gradlew :composeApp:installDebug

# Build framework
./gradlew :shared:linkDebugFrameworkIosSimulatorArm64

# Open and run in Xcode
open iosApp/worldwidewaves.xcodeproj

./dev/setup-git-hooks.sh

Enables automatic emulator launch, translation updates, and pre-push tests.

# Unit tests (comprehensive suite)
./gradlew :shared:testDebugUnitTest

# Android UI tests
./gradlew :composeApp:connectedDebugAndroidTest

# Lint and static analysis
./gradlew ktlintCheck detekt

# All quality checks
./gradlew :shared:testDebugUnitTest ktlintCheck detekt

1. Make code changes in shared/ or composeApp/
2. Android: Compose hot reload applies changes instantly
3. iOS: Rebuild framework with ./gradlew :shared:linkDebugFrameworkIosSimulatorArm64
4. Run tests to verify changes
5. Commit using Conventional Commits

See docs/development.md for detailed workflows and troubleshooting.

We welcome contributions. Please follow these guidelines:

1. Read docs/contributing.md
2. Check existing issues
3. Fork repository and create feature branch
4. Follow commit convention: <type>(<scope>): <subject>
5. Add tests for new functionality
6. Ensure all CI checks pass
7. Submit pull request with clear description

feat/add-feature-name
fix/fix-bug-name
docs/update-documentation
test/add-test-coverage

feat(maps): add Tokyo offline map module
fix(position): prevent duplicate emissions
docs: update environment setup guide
test: add choreography integration tests

See docs/contributing.md for complete guidelines.

"Test Real Code, Not Mocks"

• Focus on business logic and integration points
• Use real implementations where possible
• Mock only external dependencies (network, sensors)
• Never disable tests - always fix root causes
• Tests validate business requirements, not implementation details

# Unit tests
./gradlew :shared:testDebugUnitTest

# Android instrumented tests
./gradlew :composeApp:connectedDebugAndroidTest

# iOS safety verification
./scripts/dev/verification/verify-ios-safety.sh

# All quality checks
./gradlew :shared:testDebugUnitTest ktlintCheck detekt

See docs/testing-strategy.md for complete testing approach.

Comprehensive documentation is available in the docs/ directory.

• CLAUDE.md - Complete project development guide (start here for development)
• CLAUDE_iOS.md - iOS-specific development rules and deadlock prevention
• API Documentation - Complete API reference (Dokka-generated, auto-updated)
• Environment Setup - Development environment configuration (macOS, Linux, Windows)

• Architecture - System design, component responsibilities, data flows
• Development Workflow - Local dev loop, testing, debugging
• Contributing - Contribution guidelines, code standards, review process
• CI/CD Pipeline - Workflow details, quality gates, release process

• iOS Development - iOS-specific guides, debugging, and accessibility
  • iOS Cinterop Memory Safety - Memory pinning & struct access
  • Swift-Kotlin Bridging Guide - Type conversions & protocols
  • Platform API Usage Guide - UIKit/Foundation/CoreLocation
• Android Development - Android MapLibre implementation reference

• Testing Strategy - Test architecture and approach
• Accessibility Guide - WCAG 2.1 Level AA compliance
• Firebase Setup - Firebase project configuration and security
• Map Architecture - Shared vs platform-specific map system design
• Operations Guide - Runtime config, monitoring, deployment, incident response

See docs/README.md for complete documentation map.

Copyright 2025 DrWave

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

See LICENSE for full text.