Critical Maps iOS App

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 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 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:

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:

# 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

# 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.
• 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.

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. We're following the standard of Keep a Changelog
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:

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:

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

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

Copyright & License

Copyright (c) 2025 headione - Released under the MIT license.