SpamShield

An Android SMS client that replaces your default messaging app and scores every incoming message for spam risk — on device.

Most spam filters run in the cloud and see your messages. SpamShield registers as a full default SMS handler and does its scoring locally, so message content never has to leave the phone for the core filtering path to work.

---

Why this is non-trivial

Becoming the default SMS app on Android isn't a permission you request — the OS requires you to implement a specific set of four components, or your app won't even appear in the picker. SpamShield implements all of them:

Component	Responsibility
SmsReceiver	Receives SMS_DELIVER broadcasts (only the default app gets these)
MmsReceiver	Handles incoming WAP_PUSH_DELIVER MMS
SmsDeliverReceiver	Handles delivery reports for sent messages
RespondViaMessageService	Serves the "reply with message" action from the dialer

Miss any one and Android silently refuses to list the app as a candidate default.

---

Features

• On-device spam scoring — SpamScorer evaluates each message and emits a RiskResult
• Full conversation UI — threaded chat view, conversation list, compose and send
• Risk dashboard — aggregate view of flagged messages and filtering activity
• OTP verification flow — phone-number verification at onboarding
• Granular permission handling — Permissions.kt walks the user through the SMS/contacts grants Android requires
• Session management — persistent login via SessionManager

Architecture

SpamShieldCore ──> SpamScorer ──> RiskResult
       │
SmsRepository ──> MessagesViewModel ──> MessagesFragment / ChatActivity
       │
AccessManager / SessionManager / Permissions

MVVM throughout: receivers write to SmsRepository, the repository feeds MessagesViewModel, and the UI observes it. Scoring is isolated in SpamScorer so the heuristic can be swapped for an ML model without touching the SMS plumbing.

Tech Stack

Kotlin · Android SDK · MVVM · ViewModel + LiveData · Fragments · BroadcastReceiver

Getting Started

git clone https://github.com/lokeshtheprogrammer/spamshield.git

1. Open in Android Studio (Giraffe or newer)
2. Set your backend endpoint in ApiConfig.kt
3. Run on a physical device — the emulator can't be set as default SMS handler
4. On first launch, accept the prompt to make SpamShield your default SMS app

Note: requires READ_SMS, RECEIVE_SMS, SEND_SMS and READ_CONTACTS. The app will not function as a filter until it is set as the default SMS application.

Roadmap

• Replace the heuristic scorer with an on-device TFLite classifier
• User-trainable allow/block lists
• Exportable spam reports

License

MIT