# luckycoder07/message-notification-router architecture

> Architecture diagram of the GitHub repository luckycoder07/message-notification-router, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/luckycoder07/message-notification-router
- Repository: https://github.com/luckycoder07/message-notification-router

## Overview

Message Notification Router takes messages from Android/WhatsApp and a web tester, enriches them with media, history, and semantics, then selects notify, digest, or mute. The backend’s documented authority is the personalized LearningRouter behind a confidence/validity gate, with deterministic rules as fallback; Gemini enriches rather than decides. Feedback is stored and used for learning, while the web UI exposes testing, analytics, and live events. The README describes these capabilities; sampled source confirms several key call paths, but not every service implementation detail.

Main entry points: [`code/api/service.py`](https://github.com/luckycoder07/message-notification-router/blob/main/code/api/service.py) (API service), [`code/api/main.py`](https://github.com/luckycoder07/message-notification-router/blob/main/code/api/main.py) (FastAPI endpoints), [`code/static/app.js`](https://github.com/luckycoder07/message-notification-router/blob/main/code/static/app.js) (Web visualizer), [`mobile/app/src/main/java/com/msgrouter/app/WhatsAppNotificationService.kt`](https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/WhatsAppNotificationService.kt) (Notification listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Message clients"]
  node_android_listener["Notification listener"]
  node_android_settings[("App settings<br/>[SettingsManager.kt]")]
  node_android_api["API client<br/>[ApiClient.kt]"]
  node_api_contract["API contract<br/>[ApiService.kt]"]
  node_message_repository["Prediction repository"]
end

subgraph group_api["API and orchestration"]
  node_fastapi["FastAPI endpoints<br/>[main.py]"]
  node_api_service["API service<br/>[service.py]"]
  node_event_broadcaster["Event broadcaster<br/>[broadcaster.py]"]
end

subgraph group_routing["Routing pipeline"]
  node_prediction_engine["Prediction engine<br/>[engine.py]"]
  node_message_router["Rule router<br/>[router.py]"]
  node_preprocess["Feature extraction<br/>[preprocess.py]"]
  node_media["Media enrichment<br/>[media.py]"]
  node_history[("User history<br/>[history.py]")]
  node_rules["Safety rules<br/>[rules.py]"]
  node_gemini["Gemini enrichment<br/>[gemini.py]"]
  node_prediction_output["Prediction output<br/>[output.py]"]
end

subgraph group_learning["Feedback and learning"]
  node_learning_router["Learning router<br/>[learning.py]"]
  node_feedback_store[("Feedback store<br/>[feedback.py]")]
end

subgraph group_interfaces["Web interface"]
  node_web_ui["Web visualizer<br/>[app.js]"]
end

node_whatsapp(("WhatsApp"))
node_web_user(("Web user"))
node_user(("Message sender"))

node_whatsapp -->|"posts notification"| node_android_listener
node_android_listener -->|"reads settings"| node_android_settings
node_android_listener -->|"creates client"| node_android_api
node_android_api -->|"builds service"| node_api_contract
node_android_listener -->|"submits message"| node_api_contract
node_api_contract -->|"POST predict"| node_fastapi
node_fastapi -->|"dispatches request"| node_api_service
node_api_service -->|"routes message"| node_prediction_engine
node_prediction_engine -->|"calls router"| node_message_router
node_message_router -->|"extracts features"| node_preprocess
node_message_router -->|"processes media"| node_media
node_message_router -->|"reads history"| node_history
node_message_router -->|"evaluates rules"| node_rules
node_api_service -->|"requests enrichment"| node_gemini
node_api_service -->|"predicts action"| node_learning_router
node_api_service -->|"reads preferences"| node_feedback_store
node_api_service -->|"records prediction"| node_feedback_store
node_learning_router -->|"returns prediction"| node_api_service
node_api_service -->|"publishes events"| node_event_broadcaster
node_api_service -->|"stores feedback"| node_feedback_store
node_api_service -->|"returns result"| node_fastapi
node_fastapi -->|"serves interface"| node_web_ui
node_web_user -->|"uses tester"| node_web_ui
node_web_ui -->|"requests predictions"| node_fastapi
node_web_ui -->|"requests analytics"| node_fastapi
node_web_ui -->|"opens event stream"| node_fastapi
node_event_broadcaster -->|"streams events"| node_fastapi
node_web_ui -->|"receives events"| node_event_broadcaster
node_fastapi -->|"submits feedback"| node_api_service
node_android_listener -->|"records prediction"| node_message_repository
node_user -->|"sends message"| node_whatsapp

click node_android_listener "https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/WhatsAppNotificationService.kt"
click node_android_settings "https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/SettingsManager.kt"
click node_android_api "https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/ApiClient.kt"
click node_api_contract "https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/ApiService.kt"
click node_message_repository "https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/MessageRepository.kt"
click node_web_ui "https://github.com/luckycoder07/message-notification-router/blob/main/code/static/app.js"
click node_fastapi "https://github.com/luckycoder07/message-notification-router/blob/main/code/api/main.py"
click node_api_service "https://github.com/luckycoder07/message-notification-router/blob/main/code/api/service.py"
click node_event_broadcaster "https://github.com/luckycoder07/message-notification-router/blob/main/code/api/broadcaster.py"
click node_prediction_engine "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/engine.py"
click node_message_router "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/router.py"
click node_preprocess "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/preprocess.py"
click node_media "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/media.py"
click node_history "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/history.py"
click node_rules "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/rules.py"
click node_gemini "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/gemini.py"
click node_learning_router "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/learning.py"
click node_feedback_store "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/feedback.py"
click node_prediction_output "https://github.com/luckycoder07/message-notification-router/blob/main/code/src/output.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_android_listener,node_android_settings,node_android_api,node_api_contract,node_message_repository,node_web_user toneBlue
class node_fastapi,node_api_service,node_event_broadcaster toneAmber
class node_prediction_engine,node_message_router,node_preprocess,node_media,node_history,node_rules,node_gemini,node_prediction_output toneMint
class node_learning_router,node_feedback_store toneRose
class node_web_ui,node_whatsapp,node_user toneIndigo
```

## Components

### Message clients

- [Notification listener](https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/WhatsAppNotificationService.kt): `mobile/app/src/main/java/com/msgrouter/app/WhatsAppNotificationService.kt`
- [App settings](https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/SettingsManager.kt): `mobile/app/src/main/java/com/msgrouter/app/SettingsManager.kt`
- [API client](https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/ApiClient.kt): `mobile/app/src/main/java/com/msgrouter/app/ApiClient.kt`
- [API contract](https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/ApiService.kt): `mobile/app/src/main/java/com/msgrouter/app/ApiService.kt`
- [Prediction repository](https://github.com/luckycoder07/message-notification-router/blob/main/mobile/app/src/main/java/com/msgrouter/app/MessageRepository.kt): `mobile/app/src/main/java/com/msgrouter/app/MessageRepository.kt`

### API and orchestration

- [FastAPI endpoints](https://github.com/luckycoder07/message-notification-router/blob/main/code/api/main.py): `code/api/main.py`
- [API service](https://github.com/luckycoder07/message-notification-router/blob/main/code/api/service.py): `code/api/service.py`
- [Event broadcaster](https://github.com/luckycoder07/message-notification-router/blob/main/code/api/broadcaster.py): `code/api/broadcaster.py`

### Routing pipeline

- [Prediction engine](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/engine.py): `code/src/engine.py`
- [Rule router](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/router.py): `code/src/router.py`
- [Feature extraction](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/preprocess.py): `code/src/preprocess.py`
- [Media enrichment](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/media.py): `code/src/media.py`
- [User history](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/history.py): `code/src/history.py`
- [Safety rules](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/rules.py): `code/src/rules.py`
- [Gemini enrichment](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/gemini.py): `code/src/gemini.py`
- [Prediction output](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/output.py): `code/src/output.py`

### Feedback and learning

- [Learning router](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/learning.py): `code/src/learning.py`
- [Feedback store](https://github.com/luckycoder07/message-notification-router/blob/main/code/src/feedback.py): `code/src/feedback.py`

### Web interface

- [Web visualizer](https://github.com/luckycoder07/message-notification-router/blob/main/code/static/app.js): `code/static/app.js`

### Other components

- **WhatsApp**
- **Web user**
- **Message sender**

## Connections

- WhatsApp → Notification listener: posts notification
- Notification listener → App settings: reads settings
- Notification listener → API client: creates client
- API client → API contract: builds service
- Notification listener → API contract: submits message
- API contract → FastAPI endpoints: POST predict
- FastAPI endpoints → API service: dispatches request
- API service → Prediction engine: routes message
- Prediction engine → Rule router: calls router
- Rule router → Feature extraction: extracts features
- Rule router → Media enrichment: processes media
- Rule router → User history: reads history
- Rule router → Safety rules: evaluates rules
- API service → Gemini enrichment: requests enrichment
- API service → Learning router: predicts action
- API service → Feedback store: reads preferences
- API service → Feedback store: records prediction
- Learning router → API service: returns prediction
- API service → Event broadcaster: publishes events
- API service → Feedback store: stores feedback
- API service → FastAPI endpoints: returns result
- FastAPI endpoints → Web visualizer: serves interface
- Web user → Web visualizer: uses tester
- Web visualizer → FastAPI endpoints: requests predictions
- Web visualizer → FastAPI endpoints: requests analytics
- Web visualizer → FastAPI endpoints: opens event stream
- Event broadcaster → FastAPI endpoints: streams events
- Web visualizer → Event broadcaster: receives events
- FastAPI endpoints → API service: submits feedback
- Notification listener → Prediction repository: records prediction
- Message sender → WhatsApp: sends message