mklat.news — developer README

mklat.news is a Hebrew-first Flutter mobile app for Israeli emergency-alert status and nearby news context.

Safety notice

This project is not an official emergency-alert system. Do not use it as a primary life-safety source.

User-facing download and install docs live in GitHub Pages:

• mklat.news user site
• GitHub Releases

This repository contains the Flutter mobile app, user docs, and Android release automation.

Repo map

lib/
├── application/        # App session and polling orchestration
├── core/               # Endpoints, constants, theme, strings, utility seams
├── data/               # Models, codecs, mappers, services
├── domain/             # Alert state machine and domain rules
└── presentation/       # Providers, screens, widgets, presentation models

test/                   # Unit, widget, and fixture-based integration tests
integration_test/       # Emulator-backed Flutter integration tests
tool/                   # Fixture generation and maintenance scripts
docs/                   # User-facing GitHub Pages docs
.agent/                 # Product specs and implementation notes

Tooling

Tool versions are managed by mise:

mise install
flutter --version
flutter doctor
flutter pub get

Current expected versions:

• Flutter 3.38.7 stable
• Dart 3.10.7
• Java 21 for Android builds

Android SDK is not managed by mise. Install Android Studio or Android command-line tools and accept licenses:

flutter doctor --android-licenses

Run locally

flutter run

Run on a specific device:

flutter devices
flutter run -d <device-id>

Validate changes

Fast release gate, no emulator:

make release-check

Full local check, including emulator integration tests:

make check

Useful individual commands:

dart format --set-exit-if-changed .
flutter analyze
flutter test
make test-unit
make test-integration

Regenerate Mockito mocks:

dart run build_runner build --delete-conflicting-outputs

Regenerate fixture constants after changing raw fixture bytes:

make fixtures

Build APK locally

make release-apk

Override build metadata:

make release-apk BUILD_NAME=1.0.1 BUILD_NUMBER=2

Outputs:

dist/mklat-news-<version>-android.apk
build/app/outputs/flutter-apk/app-release.apk

Cut a release

GitHub Actions publishes an APK to a GitHub Release when a tag matching v* or android-v* is pushed.

git tag -a android-v1.0.0 -m "mklat.news android v1.0.0"
git push origin android-v1.0.0

The Android APK workflow validates, builds, uploads an Actions artifact, and attaches the APK to the release.

Manual publishing is also available from Actions → Android APK → Run workflow with publish_release enabled.

CI uses the GitHub workflow run number as Android versionCode, so each release APK can update over the previous APK.

Tagged Android releases are signed with the stable release keystore stored in GitHub Actions secrets. Local release builds use debug signing unless ANDROID_KEYSTORE_PATH, ANDROID_KEYSTORE_PASSWORD, ANDROID_KEY_ALIAS, and ANDROID_KEY_PASSWORD are exported.

CI workflows

• Android APK: validates and builds APKs on relevant main pushes and release tags. Uses per-ref concurrency.
• GitHub Pages publishes docs/ as the user-facing install and safety site.

Architecture boundaries

• Data services fetch and parse remote data; they do not own polling timers.
• Mappers/codecs translate OREF/RSS/cache shapes into app values.
• Domain code owns alert-state rules.
• Presentation models own Hebrew display copy and UI projection.
• Providers expose app state to widgets through provider / ChangeNotifier.
• AppSession wires services, providers, and polling together.

Data sources

Configured in lib/core/api_endpoints.dart:

• OREF current alerts
• OREF alert history
• OREF districts and shelter times
• OREF cities fallback
• RSS news from Ynet, Maariv, and Haaretz

OREF requests require browser-like headers. Check HttpClient and OREF service tests before changing API behavior.

Testing strategy

1. Unit and widget tests under test/unit/ and test/widget/.
2. Fixture-based integration tests under test/integration/, using captured HTTP response bytes and mocked http.Client.
3. Emulator-backed Flutter integration tests under integration_test/.

Fixture bytes live under test/fixtures/responses/. Keep raw bytes when testing decoding, charset, BOM, or Hebrew mojibake behavior.

License

MIT. See LICENSE.