# niranjan-0/meditrack architecture

> Architecture diagram of the GitHub repository niranjan-0/meditrack, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niranjan-0/meditrack
- Repository: https://github.com/niranjan-0/meditrack

## Overview

1. **Overall shape**
   MediTrack is a single-process Android app written in Java, with a mostly **local-first architecture**. The core app runs on-device, persists data in **Room** (SQLite), and uses a small set of external APIs only for AI chat and nearby clinic lookup.

2. **Entry and navigation flow**
   `SplashActivity` is the entry point and performs the initial session check through `SessionManager`. From there, users are routed to either `LoginActivity`/`RegisterActivity`/`ForgotPasswordActivity` or into `MainActivity`, which acts as the host for the main bottom-navigation experience.

3. **Primary user-facing modules**
   The main experience is split into five feature areas hosted as fragments inside `MainActivity`: `HomeFragment`, `MedicinesFragment`, `HealthFragment`, `ContactsFragment`, and `NearbyFragment`. Separate activities handle focused workflows such as adding a medicine, adding a health log, and chatting with the AI assistant.

4. **Persistence boundary**
   The app’s state is stored locally via `AppDatabase` and DAOs for `User`, `Medicine`, `MedLog`, `HealthLog`, and `EmergencyContact`. This is the main data backbone of the app: UI screens read from Room, and create/update flows write back into Room.

5. **UI rendering layer**
   Lists and cards are rendered through RecyclerView adapters such as `MedicineAdapter`, `HealthLogAdapter`, `MedLogAdapter`, `ContactsAdapter`, `ClinicAdapter`, and `ChatAdapter`. Data Binding is used heavily, which reduces direct view lookups and keeps activity/fragment code focused on behavior rather than manual widget wiring.

6. **Medicine reminder workflow**
   `AddMedicineActivity` captures a medicine schedule and stores it locally. `AlarmHelper` schedules reminders, `AlarmReceiver` fires at the right time, and `NotificationHelper` displays the reminder notification. `MedActionReceiver` handles reminder actions, so the reminder loop is: user input → Room → alarm scheduling → broadcast receiver → notification/action handling.

7. **Boot-resilience and reminder persistence**
   `BootReceiver` restores alarm state after device reboot, which is important because reminders would otherwise be lost. This makes the reminder subsystem durable across restarts and distinguishes the app from a simple in-memory scheduler.

8. **Health tracking workflow**
   `AddHealthLogActivity` creates log records for measurements like blood pressure, sugar, and weight. `HealthFragment` consumes those records for history views and charts, and the app uses **MPAndroidChart** for graphing. This is a classic write-local, read-local analytics loop with no server dependency.

9. **Authentication and account safety**
   Login, registration, and password reset are handled on-device with `User` data stored in Room. `HashUtils` suggests credentials or security answers are hashed locally rather than stored in plain text. The `ForgotPasswordActivity` implements a multi-step recovery flow rather than a simple reset link model, which fits an offline/mobile-only account system.

10. **Emergency contacts subsystem**
   `ContactsFragment` manages emergency contacts, and `ContactsAdapter` exposes actions like call, SMS, edit, and delete. This subsystem bridges local contact data with device capabilities such as calling and texting, so it sits at the boundary between app data and phone-native actions.

11. **AI assistant integration**
   `ChatActivity` provides the AI health assistant experience through the Google Generative AI SDK (Gemini, per README). The `ChatAdapter` renders the conversation, and the app includes a fallback/demo mode when no API key is configured. This is an external service boundary: prompts go out to Gemini, but the chat UI remains usable without live access.

12. **Nearby clinics and maps integration**
   `NearbyFragment` combines Google Maps and Places-style clinic discovery with a `ClinicAdapter` for list presentation. The flow is location in → nearby facility search → map/list output → one-tap navigation. The README indicates a fallback demo dataset when GPS or API access is unavailable, so the feature is intentionally failure-tolerant.

13. **Cross-cutting app services**
   `NotificationHelper`, `AlarmHelper`, `SessionManager`, and `HashUtils` are the main utility services supporting the app. They centralize notification setup, scheduling, session state, and hashing so the feature screens stay thin and do not duplicate infrastructure logic.

14. **Important architectural boundaries to diagram**
   The most important separation is between:
   - **Presentation**: activities, fragments, adapters, data binding
   - **Local domain/storage**: models, Room entities/DAOs/database
   - **Device/system integration**: alarms, notifications, boot receiver, phone actions
   - **Cloud integration**: Gemini chat and Google Maps/Places lookup  
   The app is therefore best drawn as a client app centered on local persistence, with two external integration branches for AI and maps.

Main entry points: [`app/src/main/java/com/meditrack/activities/MainActivity.java`](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/MainActivity.java) (Main hub), [`app/src/main/java/com/meditrack/database/AppDatabase.java`](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/database/AppDatabase.java) (Room DB), [`app/src/main/java/com/meditrack/adapters/MedicineAdapter.java`](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/adapters/MedicineAdapter.java) (Adapters), [`app/src/main/java/com/meditrack/activities/SplashActivity.java`](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/SplashActivity.java) (Splash)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_splash["Splash<br/>entry activity"]
  node_auth["Auth flow<br/>account activities<br/>[LoginActivity.java]"]
  node_main["Main hub<br/>nav host<br/>[MainActivity.java]"]
  node_home["Home<br/>dashboard fragment<br/>[HomeFragment.java]"]
  node_meds["Medicines<br/>meds fragment"]
  node_health["Health"]
  node_contacts["Contacts"]
  node_nearby["Nearby<br/>clinic fragment"]
  node_add_medicine["Add medicine<br/>workflow activity"]
  node_add_health["Add health<br/>workflow activity"]
  node_session{{"Session<br/>state helper"}}
  node_adapters["Adapters"]
end

subgraph group_data["Local data"]
  node_db[("Room DB<br/>database<br/>[AppDatabase.java]")]
  node_models["Domain models<br/>entities<br/>[User.java]"]
  node_security{{"Hashing<br/>security util<br/>[HashUtils.java]"}}
end

subgraph group_device["Device integration"]
  node_reminders{{"Reminders<br/>scheduler<br/>[AlarmHelper.java]"}}
  node_notify{{"Notifications<br/>notification helper"}}
  node_receivers{{"Receivers<br/>[AlarmReceiver.java]"}}
end

subgraph group_cloud["Cloud services"]
  node_chat["Chat AI<br/>assistant activity<br/>[ChatActivity.java]"]
  node_gemini(("Gemini<br/>ai api"))
  node_places(("Maps lookup<br/>location api"))
end

node_splash -->|"checks session"| node_session
node_splash -->|"guest flow"| node_auth
node_splash -->|"signed in"| node_main
node_main -->|"hosts"| node_home
node_main -->|"hosts"| node_meds
node_main -->|"hosts"| node_health
node_main -->|"hosts"| node_contacts
node_main -->|"hosts"| node_nearby
node_meds -->|"reads/writes"| node_db
node_health -->|"reads/writes"| node_db
node_contacts -->|"reads/writes"| node_db
node_auth -->|"accounts"| node_db
node_auth -->|"hashes"| node_security
node_add_medicine -->|"stores"| node_db
node_add_medicine -->|"schedules"| node_reminders
node_reminders -->|"fires"| node_receivers
node_receivers -->|"notifies"| node_notify
node_receivers -->|"restores state"| node_db
node_notify -->|"alerts"| node_meds
node_add_health -->|"stores"| node_db
node_health -->|"renders"| node_adapters
node_contacts -->|"renders"| node_adapters
node_nearby -->|"renders"| node_adapters
node_chat -->|"renders"| node_adapters
node_chat -->|"AI prompts"| node_gemini
node_nearby -->|"location search"| node_places

click node_splash "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/SplashActivity.java"
click node_auth "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/LoginActivity.java"
click node_main "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/MainActivity.java"
click node_home "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/HomeFragment.java"
click node_meds "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/MedicinesFragment.java"
click node_health "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/HealthFragment.java"
click node_contacts "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/ContactsFragment.java"
click node_nearby "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/NearbyFragment.java"
click node_add_medicine "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/AddMedicineActivity.java"
click node_add_health "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/AddHealthLogActivity.java"
click node_chat "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/ChatActivity.java"
click node_db "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/database/AppDatabase.java"
click node_models "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/models/User.java"
click node_reminders "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/utils/AlarmHelper.java"
click node_notify "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/utils/NotificationHelper.java"
click node_session "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/utils/SessionManager.java"
click node_security "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/utils/HashUtils.java"
click node_receivers "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/receivers/AlarmReceiver.java"
click node_adapters "https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/adapters/MedicineAdapter.java"

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_splash,node_auth,node_main,node_home,node_meds,node_health,node_contacts,node_nearby,node_add_medicine,node_add_health,node_session,node_adapters toneBlue
class node_db,node_models,node_security toneAmber
class node_reminders,node_notify,node_receivers toneMint
class node_chat,node_gemini,node_places toneRose
```

## Components

### Presentation

Activities, fragments, adapters, and session/navigation UI.

- [Splash](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/SplashActivity.java): entry activity · App entry that checks session state and routes users onward. · `app/src/main/java/com/meditrack/activities/SplashActivity.java`
- [Auth flow](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/LoginActivity.java): account activities · Login, registration, and password recovery screens. · `app/src/main/java/com/meditrack/activities/LoginActivity.java`
- [Main hub](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/MainActivity.java): nav host · Hosts bottom navigation and the core in-app experience. · `app/src/main/java/com/meditrack/activities/MainActivity.java`
- [Home](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/HomeFragment.java): dashboard fragment · Landing fragment summarizing the app state. · `app/src/main/java/com/meditrack/fragments/HomeFragment.java`
- [Medicines](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/MedicinesFragment.java): meds fragment · Medicine list and reminder-oriented management view. · `app/src/main/java/com/meditrack/fragments/MedicinesFragment.java`
- [Health](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/HealthFragment.java): health fragment · Health log history and charting view. · `app/src/main/java/com/meditrack/fragments/HealthFragment.java`
- [Contacts](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/ContactsFragment.java): contacts fragment · Emergency contacts management and device actions. · `app/src/main/java/com/meditrack/fragments/ContactsFragment.java`
- [Nearby](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/fragments/NearbyFragment.java): clinic fragment · Nearby clinic discovery and map/list view. · `app/src/main/java/com/meditrack/fragments/NearbyFragment.java`
- [Add medicine](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/AddMedicineActivity.java): workflow activity · Captures medicine schedules and saves them locally. · `app/src/main/java/com/meditrack/activities/AddMedicineActivity.java`
- [Add health](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/AddHealthLogActivity.java): workflow activity · Creates local health measurement log records. · `app/src/main/java/com/meditrack/activities/AddHealthLogActivity.java`
- [Session](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/utils/SessionManager.java): state helper · Tracks login state and session persistence. · `app/src/main/java/com/meditrack/utils/SessionManager.java`
- [Adapters](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/adapters/MedicineAdapter.java): ui adapters · RecyclerView adapters for medicines, logs, contacts, clinics, and chat. · `app/src/main/java/com/meditrack/adapters/MedicineAdapter.java`

### Local data

Room-backed models, database, and hashing.

- [Room DB](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/database/AppDatabase.java): database · AppDatabase and generated DAO implementations back local persistence. · `app/src/main/java/com/meditrack/database/AppDatabase.java`
- [Domain models](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/models/User.java): entities · User, medicine, logs, contacts, chat, and clinic data models. · `app/src/main/java/com/meditrack/models/User.java`
- [Hashing](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/utils/HashUtils.java): security util · Hashes credentials or recovery data locally. · `app/src/main/java/com/meditrack/utils/HashUtils.java`

### Device integration

Alarms, notifications, boot persistence, and phone-native actions.

- [Reminders](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/utils/AlarmHelper.java): scheduler · Schedules medicine alerts and restores them after reboot. · `app/src/main/java/com/meditrack/utils/AlarmHelper.java`
- [Notifications](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/utils/NotificationHelper.java): notification helper · Builds and displays reminder notifications. · `app/src/main/java/com/meditrack/utils/NotificationHelper.java`
- [Receivers](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/receivers/AlarmReceiver.java): broadcast receivers · Alarm, boot, and reminder action receivers. · `app/src/main/java/com/meditrack/receivers/AlarmReceiver.java`

### Cloud services

AI assistant and nearby clinic lookup integrations.

- [Chat AI](https://github.com/niranjan-0/meditrack/blob/main/app/src/main/java/com/meditrack/activities/ChatActivity.java): assistant activity · AI health assistant chat experience. · `app/src/main/java/com/meditrack/activities/ChatActivity.java`
- **Gemini**: ai api · Generative AI backend used by the chat assistant.
- **Maps lookup**: location api · Nearby clinic discovery and map/list lookup backend.

## Connections

- Splash → Session: checks session · Splash routes based on stored login state.
- Splash → Auth flow: guest flow · Unauthenticated users are sent to account screens.
- Splash → Main hub: signed in · Authenticated users enter the main experience.
- Main hub → Home: hosts · MainActivity swaps in the home fragment.
- Main hub → Medicines: hosts · MainActivity swaps in the medicines fragment.
- Main hub → Health: hosts · MainActivity swaps in the health fragment.
- Main hub → Contacts: hosts · MainActivity swaps in the contacts fragment.
- Main hub → Nearby: hosts · MainActivity swaps in the nearby clinics fragment.
- Medicines → Room DB: reads/writes · Medicine screens persist schedules and load local data.
- Health → Room DB: reads/writes · Health screens persist and query health logs.
- Contacts → Room DB: reads/writes · Contacts management is backed by Room.
- Auth flow → Room DB: accounts · Login and registration operate on local user data.
- Auth flow → Hashing: hashes · Sensitive account data is hashed locally.
- Add medicine → Room DB: stores · Medicine creation writes a schedule into Room.
- Add medicine → Reminders: schedules · Saved medicine schedules are turned into alarms.
- Reminders → Receivers: fires · Alarm broadcasts are handled by receivers.
- Receivers → Notifications: notifies · Receivers trigger reminder notifications.
- Receivers → Room DB: restores state · Boot handling reloads persisted reminder data.
- Notifications → Medicines: alerts · Notifications surface medicine reminder actions.
- Add health → Room DB: stores · Health measurements are written locally.
- Health → Adapters: renders · RecyclerView adapters render log history and charts support.
- Contacts → Adapters: renders · Adapters provide call, SMS, edit, and delete actions.
- Nearby → Adapters: renders · Clinic results are listed through an adapter.
- Chat AI → Adapters: renders · Chat messages are shown in a conversation list.
- Chat AI → Gemini: AI prompts · Chat exchanges prompts with the AI service.
- Nearby → Maps lookup: location search · Nearby clinic lookup depends on external location/search services.
