Engineering Home

⚙️ Engineering & Architecture Home

Welcome to the Engineering Hub for Selah Scripture Audio Meditation. This space documents system architecture, deployment pipelines, telemetry, audio alignment, and development standards.

---

🏗️ Core Engineering Stack

• Framework: Flutter 3.24+ (Web, iOS, Android)
• State Management: Riverpod 3.0 (Feature-First architecture)
• Audio Engine: just_audio, just_audio_background, flutter_tts (Contemplative pacing 0.44/0.46, Google Speech Services / Neural voice selector)
• Backend & Cloud: Firebase Hosting, Cloud Firestore, Firebase Remote Config (REST & Firestore mirror)
• Telemetry & Feedback: Aptabase privacy-preserving analytics, PostHog, Doorbell.io, private GitHub issue dispatch (njwandroid/selahfeedback)

---

📚 Technical Documentation & Runbooks

1. Firebase Hosting Preview Channels

Ephemeral web preview channels (firebase hosting:channel:deploy <name>) for testing builds before touching production.

2. Feedback Technical Architecture

Cloud Firestore, Doorbell.io, and private GitHub issue dispatch pipelines with secure token injection.

3. Firebase Analytics & Telemetry

Real-time GA4 Web (G-7LFS54TTFM), DebugView, ADB logcat, and custom user properties (k_debug_mode, marionette_driving).

4. Acoustic Calibration User Guide

Python acoustic calibration engine and boundary tuning for Scripture verses.

5. WhisperX Timestamp Alignment ADR

Architecture Decision Record for AI verse alignment and acoustic silence profiling.

6. Releases & Version Roadmap

Release history, SemVer tags (v0.3.0, v0.3.1 (1) Build 42), and soft-launch checklist.

7. Automated Android Release & Distribution Pipeline

Selah includes a fully automated 1-command release compilation and distribution script located at scripts/distribute_android_release.sh:

# Standard release to core-testers with custom release notes
./scripts/distribute_android_release.sh --notes "Release highlights and testing instructions"

# Distribute to specific tester group
./scripts/distribute_android_release.sh --groups core-testers --notes "Testing notes"

# Dry run (compile release APK, verify artifact size, skip Firebase upload)
./scripts/distribute_android_release.sh --dry-run

Pipeline Guarantees

1. Dynamic Environment Injection: Automatically forwards --dart-define=API_BIBLE_KEY=$API_BIBLE_KEY into flutter build apk --release if present in the environment, unlocking live human narrator streams.
2. Version Extraction: Reads SemVer and build number directly from pubspec.yaml (e.g. 0.3.3+44).
3. Tester Notification: Automatically uploads the 78MB+ binary to Firebase App Distribution and emails all testers in core-testers (neilwarner@gmail.com, njwandroid@gmail.com) with instant install links.

---

🔒 Governance & Security Baseline

• Zero Plaintext Secrets: Under NO circumstances are API keys or secrets committed to git. All keys are loaded dynamically from Firebase Remote Config / Firestore, falling back to compile-time --dart-define where desired.
• Master Branch Quarantine: Pushing to master is strictly isolated to this Wiki git repository (selah_prototype_audio_13sep2026.wiki.git).
• Ticket-Driven Commits: Every change mapped to an issue #<id> and merged via pull request (feat/#<id>-<slug>).
• 100% Review Reply Guarantee: All PR review comments (CodeRabbit and human) must receive an explicit threaded API reply (either documenting the resolution or providing a direct tracked GitHub issue link via defer_comments_to_issues.py).