# joehalliwell/meditation-time architecture

> Architecture diagram of the GitHub repository joehalliwell/meditation-time, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joehalliwell/meditation-time
- Repository: https://github.com/joehalliwell/meditation-time

## Overview

##### Project type and purpose
- This is a single-module Android application (“Meditation Time”) written in Kotlin. Its core functionality is to let users set up timed meditation sessions with optional interval bells, daily alerts, and feedback, and to log session times.

##### File structure
- Top-level: Gradle scripts (build.gradle, settings.gradle), Android wrapper files, a `play-store` folder, and project-wide configs.
- `app/`: the only module. Under `app/src/main`:
- `java/com/joehalliwell/meditationtime`: Kotlin code – `MainActivity`, `PreferencesActivity`, `BaseActivity`, `TimerView`, `TimerViewListener`
- Tests under `androidTest` and `test` packages.
- No external microservices or multi-module divisions.

##### Extract additional insights from README
- Core features: interval bells, full screen, feedback sounds, daily notifications, session logging, UI themes.
- No mention of remote storage or server integration; everything runs locally.

##### Main components
a. UI Layer
- MainActivity (session control screen)
- TimerView (custom view displaying the timer)
- PreferencesActivity (settings screen)
b. Business Logic Layer
- TimerViewListener (handles start/stop/tick events)
- SessionManager (implicit—manages session state, counts interval bells, triggers end)
c. Data Layer
- SharedPreferences (stores user preferences: bell count, durations, daily alert time, themes)
- Local Session Log (e.g. file or SharedPreferences-based logging of past sessions)
d. Android System Services
- AlarmManager (schedules daily alerts)
- NotificationManager (displays alerts if app is backgrounded)
- MediaPlayer/AudioManager (plays `.ogg` files)
e. Resource Layer
- `res/raw` audio assets
- `res/drawable`, `res/layout`, `res/values`

##### Relationships and interactions
- User taps Play → MainActivity instantiates TimerView → TimerViewListener starts a countdown → on each interval boundary, MediaPlayer plays a raw audio resource → TimerView updates UI.
- User opens PreferencesActivity → reads/writes SharedPreferences → AlarmManager is reset to the new daily alert time.
- At daily alert time, AlarmManager fires a PendingIntent → NotificationManager shows a notification → tapping it opens MainActivity.
- At session end, SessionManager logs the session to local storage via SharedPreferences or a simple file.

##### Architectural patterns and design principles
- MVC / MVVM-lite: Activities = controllers, TimerView = view, SessionManager & SharedPreferences = model
- Single Responsibility: custom view separated from Activity logic
- Use of Android system services for scheduling and notifications
- Resource-driven UI: all strings, dimensions, themes in `res/values`

## Diagram (Mermaid)

```mermaid
graph TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        MainActivity["MainActivity"]:::ui
        TimerView["TimerView"]:::ui
        PreferencesActivity["PreferencesActivity"]:::ui
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        TimerViewListener["TimerViewListener"]:::logic
        SessionManager["SessionManager"]:::logic
    end

    %% Data & Services Layer
    subgraph "Data & Services Layer"
        direction TB
        SharedPreferencesNode["SharedPreferences"]:::data
        SessionLog["Session Log"]:::data
        AlarmManagerNode["AlarmManager"]:::service
        NotificationManagerNode["NotificationManager"]:::service
        MediaPlayerNode["MediaPlayer"]:::service
    end

    %% Android Framework
    AndroidFramework["Android Framework / System Services"]:::framework

    %% Resource Manager
    subgraph "Resource Manager"
        direction TB
        RawAudio["res/raw (audio assets)"]:::resource
        Layouts["res/layout"]:::resource
        Drawables["res/drawable"]:::resource
        Values["res/values"]:::resource
    end

    %% Connections
    MainActivity -->|"attach view"| TimerView
    MainActivity -->|"startSession()"| TimerViewListener
    TimerView -->|"onTick"| TimerViewListener
    TimerViewListener -->|"play(ogg)"| MediaPlayerNode
    PreferencesActivity -->|"read/write prefs"| SharedPreferencesNode
    SharedPreferencesNode -->|"setDailyAlert()"| AlarmManagerNode
    AlarmManagerNode -->|"fireNotification()"| NotificationManagerNode
    NotificationManagerNode -->|"openApp()"| MainActivity
    TimerViewListener -->|"logSession()"| SessionLog
    SessionManager -->|"manageState"| SessionLog
    AndroidFramework --> AlarmManagerNode
    AndroidFramework --> NotificationManagerNode
    AndroidFramework --> MediaPlayerNode

    %% Click Events
    click MainActivity "https://github.com/joehalliwell/meditation-time/blob/main/app/src/main/java/com/joehalliwell/meditationtime/MainActivity.kt"
    click PreferencesActivity "https://github.com/joehalliwell/meditation-time/blob/main/app/src/main/java/com/joehalliwell/meditationtime/PreferencesActivity.kt"
    click TimerView "https://github.com/joehalliwell/meditation-time/blob/main/app/src/main/java/com/joehalliwell/meditationtime/TimerView.kt"
    click TimerViewListener "https://github.com/joehalliwell/meditation-time/blob/main/app/src/main/java/com/joehalliwell/meditationtime/TimerViewListener.kt"
    click SharedPreferencesNode "https://github.com/joehalliwell/meditation-time/blob/main/app/src/main/res/xml/preferences.xml"
    click PreferencesActivity "https://github.com/joehalliwell/meditation-time/blob/main/app/src/main/java/com/joehalliwell/meditationtime/PreferencesActivity.kt"
    click SessionLog "https://github.com/joehalliwell/meditation-time/blob/main/app/src/main/java/com/joehalliwell/meditationtime/BaseActivity.kt"
    click RawAudio "https://github.com/joehalliwell/meditation-time/tree/main/app/src/main/res/raw"
    click Layouts "https://github.com/joehalliwell/meditation-time/tree/main/app/src/main/res/layout"
    click Drawables "https://github.com/joehalliwell/meditation-time/tree/main/app/src/main/res/drawable"
    click Values "https://github.com/joehalliwell/meditation-time/tree/main/app/src/main/res/values"

    %% Styles
    classDef ui fill:#AED6F1,stroke:#2E86C1,color:#1B4F72;
    classDef logic fill:#ABEBC6,stroke:#28B463,color:#1D8348;
    classDef data fill:#F9E79F,stroke:#D4AC0D,color:#7D6608;
    classDef service fill:#F5CBA7,stroke:#CD6155,color:#922B21;
    classDef framework fill:#D5DBDB,stroke:#85929E,color:#566573;
    classDef resource fill:#EBDEF0,stroke:#AF7AC5,color:#6C3483;
```
