https://github.com/criticalmaps/criticalmaps-ios

Critical Maps iOS App 🚲✊
https://github.com/criticalmaps/criticalmaps-ios

bike bike-data composable-architecture criticalmaps criticalmass swiftui tca

Last synced: 2 months ago
JSON representation

Critical Maps iOS App 🚲✊

Host: GitHub
URL: https://github.com/criticalmaps/criticalmaps-ios
Owner: criticalmaps
License: mit
Created: 2014-09-09T12:04:17.000Z (over 11 years ago)
Default Branch: main
Last Pushed: 2025-12-29T20:03:43.000Z (3 months ago)
Last Synced: 2026-01-01T06:36:00.556Z (3 months ago)
Topics: bike, bike-data, composable-architecture, criticalmaps, criticalmass, swiftui, tca
Language: Swift
Homepage: http://www.criticalmaps.net
Size: 103 MB
Stars: 310
Watchers: 8
Forks: 42
Open Issues: 3
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

fucking-open-source-ios-apps - Critical Maps
awesome-starred - criticalmaps/criticalmaps-ios - Critical Maps iOS App 🚲✊ (swiftui)

README

## Critical Maps iOS App

[![CI](https://github.com/criticalmaps/criticalmaps-ios/actions/workflows/tests.yml/badge.svg)](https://github.com/criticalmaps/criticalmaps-ios/actions/workflows/tests.yml)

## What's "Critical Mass"?

> Critical Mass has been described as 'monthly political-protest rides', and characterized as being part of a social movement.

http://en.wikipedia.org/wiki/Critical_Mass_(cycling)

## What's this app?

This iOS app is made for Critical Maps. It tracks your location and shares it with all other participants of the Critical Mass bicycle protest.

## How the App Works

Critical Maps connects cyclists during Critical Mass rides through real-time location sharing and communication.

### Core Functionality
- **🗺️ Real-time Location Tracking**: Your location is shared anonymously with other riders on an interactive map
- **💬 Live Chat System**: Communicate with all participants in real-time during rides
- **📅 Next Ride Events**: Discover upcoming Critical Mass events in your area
- **🌐 Social Integration**: Stay connected through an integrated Mastodon feed
- **🔒 Privacy-Focused**: Anonymous participation with observationmode. Additional protection through privacy zones.
- **🎨 Customizable Experience**: Personalize your rider appearance and app settings

## Project Setup

The iOS client's logic is built in the [`The Composable Architecture`](https://github.com/pointfreeco/swift-composable-architecture) and the UI is built in SwiftUI.

**Minimum platform requirements**: iOS 17.0

### Architecture Overview

#### Modular Design Philosophy
The application follows a hyper-modularized architecture with feature modules:

**Core Features:**
- `AppFeature` - Main app coordination and navigation
- `MapFeature` - Interactive map with real-time rider locations
- `ChatFeature` - Real-time messaging system
- `NextRideFeature` - Event discovery and management
- `SettingsFeature` - User preferences and app configuration
- `SocialFeature` - Mastodon feed integration

**Supporting Modules:**
- `ApiClient` - Network layer and API communication
- `SharedModels` - Data structures (e.g. `Rider`, `Location`, `Coordinate`)
- `Styleguide` - Design system and UI components
- `L10n` - Internationalization and localization
- `IDProvider` - Unique identifier generation for anonymous riders

#### Benefits of Modularization
- **Faster Build Times**: Work on individual features without building the entire app
- **Improved SwiftUI Previews**: More stable preview environments for each feature
- **Independent Development**: Features can be developed and tested in isolation
- **Mini-Apps**: Each feature can be built as a standalone app for development
- **Scalable Architecture**: Easy to add new features without affecting existing code

#### Data Flow & State Management
The app uses TCA's unidirectional data flow:
1. **Actions** represent user interactions and system events
2. **Reducers** handle state mutations and side effects
3. **Effects** manage asynchronous operations (API calls, location services)
4. **State** is the single source of truth for each feature

Example: Location sharing flow
```
User enables tracking → LocationAction → LocationReducer → API Effect → State Update → UI Re-render
```

### Getting Started

This repo contains both the client for running the entire [Critical Maps](https://itunes.apple.com/app/critical-maps/id918669647) application, as well as an extensive test suite.

#### Quick Start
1. **Clone the repository**:
2. **Open the Xcode project**: `CriticalMaps.xcodeproj`
3. **Run the app**: Select the `Critical Maps` target in Xcode and run (`⌘R`)

Install dependencies individually:
```sh
make bootstrap # Install Swift tools (SwiftLint, SwiftFormat, SwiftGen)
make ruby # Install Ruby dependencies (bundler, fastlane)
```

### Assets & Code Generation

#### SwiftGen Integration
The project uses type-safe assets generated with [SwiftGen](https://github.com/SwiftGen/SwiftGen):

```sh
# After adding new images or localization strings
make assets
```

This generates strongly-typed Swift code for:
- **Images**: `Asset.Images.iconName` instead of `"icon-name"`
- **Localizations**: `L10n.buttonSave` instead of `NSLocalizedString`

### Testing

The project includes comprehensive testing across all feature modules:

#### Running Tests
```sh
# Run all tests
⌘U in Xcode

# Run specific feature tests
xcodebuild test -scheme MapFeatureTests -destination 'platform=iOS Simulator,name=iPhone 17 Pro'
```

#### Test Architecture
- **Unit Tests**: Logic and reducer testing with TCA's testing utilities
- **Snapshot Tests**: UI component visual regression testing
- **Integration Tests**: Feature-level behavior testing

**Test Coverage by Module:**
- `AppFeatureTests` - Main app flow and navigation
- `ChatFeatureTests` - Messaging functionality
- `MapFeatureTests` - Location and map interactions
- `SettingsFeatureTests` - User preference management
- And more...

## Contribute

- Please report bugs or feature requests with GitHub [issues](https://github.com/CriticalMaps/criticalmaps-ios/issues).
- If you can code please check the build & contribute guide below.
- If you have some coins left you can help to finance the project on [Open Collective](https://opencollective.com/criticalmaps).

### How to contribute

In general, we follow the "fork-and-pull" Git workflow.

1. **Fork** the repo on GitHub
2. **Clone** the project to your own machine
3. **Commit** changes to your own branch. Please add your changes also to the [`CHANGELOG`](CHANGELOG.md). We're following the standard of [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
4. **Push** your work back up to your fork
5. Submit a **Pull request** so that we can review your changes

#### Development Guidelines
- Follow the existing code style and SwiftLint rules but not a hard rule
- Write tests for new features and bug fixes
- Run `make assets` after adding new images or localization strings
- Ensure all CI checks pass before requesting review

#### Pre-commit Hooks
The project uses pre-commit hooks to automatically format and lint code before commits:

**Manual Setup:**
```sh
make install-pre-commit # Install hooks only
```

**What runs on each commit:**
- **SwiftFormat** - Automatically formats Swift code
- **SwiftLint Auto-fix** - Fixes violations that can be corrected automatically
- **SwiftLint** - Reports remaining violations (warnings only, won't block commits)

> [!NOTE]
> Pre-commit hooks currently only process Swift files. Other file types (YAML, JSON, etc.) are not automatically processed.

**Manual pre-commit run:**
```sh
make pre-commit-run # Run on all files
pre-commit run --files changed_file.swift # Run on specific files
```

**Notes**:
- Be sure to merge the latest from "upstream" before making a pull request!
- For significant changes, consider opening an issue first to discuss the approach
- Pre-commit hooks ensure code consistency across all contributors

## Open Source & Copying

CriticalMaps is licensed under the MIT License, which means you can freely use, modify, and distribute the code.

**However, we kindly request** that you don't republish this exact app on the App Store under your own account. Instead, we encourage you to:
- Contribute improvements back to this project
- Fork it to create something new and different
- Support the project on [Open Collective](https://opencollective.com/criticalmaps)

This is a community request, not a legal restriction.

## Credits

_{Leo Thomas}

_{Malte Bünz}

_{Norman Sander}

_{Felizia Bernutz}

_I5glu

_{Maxim Tsvetkov}

_{Bernardo Silva}

_{Stephan Lindauer}

_{Jacqueline Alves}

_Joscha

_Null

_{Justus Kandzi}

_{Peter Amende}

_{Ravi Aggarwal}

_{Alban Sagouis}

_Henry

_{Knut Hühne}

_{Mikhail Akopov}

_Loris