Vedic Mitra

A modern Android companion for Vedic timekeeping — panchanga, muhurta, and astronomy-aware reminders — built with Kotlin, Jetpack Compose, and Clean Architecture.

Screenshots

Home hub	Daily Panchang	Calendar
Festivals	Upcoming festivals	Events
Muhurat	Reminders	Rashifal
Kundali	Kundali Matching	Japa
Meditation	Stotra

Status: The roadmap below is an expanded, 12-phase vision for the project. Phase 1 (Foundation) is done; Phases 2–9 and 11 are partially built, with the astrology arc (Phase 6) now largely complete. The app computes today's Panchang (tithi, nakshatra, yoga, karana, paksha, vara, ayana, ritu, maasa, samvatsara), Brahma/Abhijit Muhurta, Dur Muhurta, Varjyam, the inauspicious kalams (Rahu, Yamaganda, Gulika), the sixteen Choghadiya windows, sunrise/sunset, moonrise/moonset, Moon phase, golden-hour windows, and the graha rashi positions (Sun/Moon/Guru/Shukra) with their next pravesh — for any saved or GPS location, with offline timezone/DST detection. It derives upcoming festivals, lunar observances (Ekadashi, Purnima, Amavasya, Sankashti Chaturthi, Pradosh, …) and Sankrantis, and schedules reboot-survivable, per-event-configurable reminders for muhurta, Choghadiya, and tithi events. It shows all of this on a home dashboard and a browsable monthly Panchang calendar (tap any day for its full panchang; notable days are highlighted), wrapped in a golden/maroon brand theme drawn from the app emblem, navigated via a bottom bar. Calculations — including the sunrise-tithi convention by which the day is named — are cross-checked against published almanacs and an independent reference implementation before shipping. The astrology arc (Phase 6) is now largely built — natal charts, seventeen divisional charts, three dasha systems, ashtakavarga, matchmaking and muhurta — while Phases 10 and 12 remain aspirational. See the Roadmap for the full picture and current progress.

---

Project Vision

Vedic Mitra ("Vedic Friend") aims to make traditional Vedic timekeeping genuinely useful on a modern phone. Rather than static almanac tables, it computes the panchanga (tithi, nakshatra, yoga, karana, vara) and auspicious windows (muhurta) for the user's exact location and time, and lets them set astronomy-aware reminders and alarms around those windows.

Guiding principles:

• Accuracy first — astronomy is computed, not looked up, from the observer's coordinates.
• Offline-friendly — core calculations run on-device.
• Respectful, uncluttered UX — Material 3, light/dark, dynamic colour.
• Maintainable by many — strict modular Clean Architecture so features stay independent.

Architecture

Vedic Mitra follows Clean Architecture with a feature-first, multi-module layout, using MVVM for presentation, the Repository pattern for data, and Hilt for dependency injection.

Layer rules

UI (Compose)  →  ViewModel (MVVM)  →  UseCase / Domain  →  Repository  →  Data source / Port

• Dependencies point inwards: UI depends on domain abstractions, never the reverse.
• Features never depend on other features — only on :core:* modules.
• Cross-cutting capabilities (astronomy, scheduling, notifications, location) are exposed as ports (interfaces) in :core, so implementations are swappable and testable.

Module graph

                              ┌─────────┐
                              │  :app   │  (Hilt root, single Activity, nav host)
                              └────┬────┘
      ┌──────────────────────┬─────┴──────┬──────────────────────┐
 ┌────▼─────┐         ┌──────▼─────┐ ┌────▼──────┐        ┌──────▼──────┐
 │ Daily    │         │ Astrology  │ │ Devotion  │        │ Support     │
 │ home     │         │ kundali    │ │ japa      │        │ settings    │
 │ calendar │         │ muhurat    │ │ meditation│        │ location    │
 │ alarm    │         │ matchmaking│ │ stotra    │        │ profile     │
 │          │         │ rashifal   │ │           │        │             │
 └────┬─────┘         └──────┬─────┘ └────┬──────┘        └──────┬──────┘
      └──────────────────────┴─────┬──────┴──────────────────────┘
                    features depend on core ports only
 ┌─────────────────────────────────┴────────────────────────────────────┐
 │ :core:common   :core:ui   :core:designsystem   :core:datastore       │
 │ :core:astronomy   :core:domain   :core:scheduler   :core:alarm       │
 │ :core:notifications   :core:location                                 │
 └──────────────────────────────────────────────────────────────────────┘

Module	Responsibility
:app	Application shell: Hilt root, single Activity, navigation host, module assembly.
:core:common	Framework-agnostic building blocks: AppResult, dispatcher abstractions, value types.
:core:ui	Reusable Compose widgets and preview tooling.
:core:designsystem	Material 3 theme: colour, typography, shapes, spacing tokens, shared tables and icons.
:core:astronomy	Panchanga and jyotisha engine: Meeus ephemeris, Lahiri ayanamsa, muhurta windows, natal charts, vargas, dashas, ashtakavarga, matchmaking.
:core:domain	Use cases shared by more than one feature (e.g. resolving which location to compute for).
:core:scheduler	AlarmManager-backed exact scheduling of reminder notifications.
:core:alarm	Ringing-alarm playback and its lifecycle.
:core:notifications	NotificationManagerCompat-backed channels and notification posting.
:core:location	Device location via Play Services fused provider, plus offline coordinate → time-zone resolution.
:core:datastore	Persisted preferences and birth profiles on Jetpack DataStore.
:feature:home	Landing hub: today's panchanga hero, category tabs, shortcut grid.
:feature:calendar	Browsable monthly panchang grid; tap a day for its full panchang.
:feature:alarm	Reminders: schedule notifications for muhurta windows, Choghadiya and custom tithis.
:feature:location	Location picking: GPS, city search, manual coordinates, saved locations.
:feature:profile	Birth profiles — the prerequisite for every chart-based feature.
:feature:kundali	The chart book: charts, jataka, grahas, yogas, dashas, reading.
:feature:muhurat	Electional muhurta: ranked windows for an activity, optionally personalised.
:feature:matchmaking	Kundali matching: Ashtakoota, the four porutham, Mangal dosha.
:feature:rashifal	Computed daily and weekly outlook by rashi.
:feature:japa	108-bead mala counter with a daily streak.
:feature:meditation	Meditation timer with a daily streak.
:feature:stotra	Offline stotra library.
:feature:settings	Settings: theme, and the Support screen.

Build configuration is not copy-pasted between modules — it lives in convention plugins under build-logic/, applied by id (e.g. vedicmitra.android.feature). See docs/architecture.md and docs/module-guide.md.

Tech Stack

Area	Choice
Language	Kotlin 2.3.10 (JDK 21)
UI	Jetpack Compose, Material 3
Architecture	Clean Architecture, MVVM, Repository pattern
DI	Hilt (+ KSP)
Async	Kotlin Coroutines / Flow
Build	AGP 9.3.1 on Gradle 9.6.1 (Kotlin DSL), Version Catalog, convention plugins
Quality	Detekt, Spotless, Ktlint
Testing	JUnit4, Truth, MockK, Turbine, Coroutines-test
CI	GitHub Actions

Roadmap

A longer-range, 12-phase roadmap that balances a solid MVP with progressively richer features. Status marks reflect what's actually implemented today, verified against the code — not aspiration.

Astrology arc — build order. Profile (Phase 5) → the chart-computation layer in :core:astronomy (Lagna/houses, D9/D10, Vimshottari dasha, transits — Phase 6) → Kundali display → Rashifal → Muhurta (Phase 6). General (panchang) Muhurta needs none of this — it runs on today's engine and can ship independently as a quick win.

✅ Phase 1 — Foundation

Engineering

• Clean Architecture
• Modular project structure
• Jetpack Compose
• Material 3
• Hilt
• Room
• WorkManager
• Offline-first architecture
• GitHub Actions CI/CD
• Unit testing framework
• Documentation
• AI development guidelines (AGENTS.md)

Note: the shipped app doesn't use Room or WorkManager. Persistence is on Jetpack DataStore (:core:datastore), and scheduling is on AlarmManager — exact alarms plus a reboot-survivable BootReceiver (:core:scheduler, :feature:alarm) — not deferred/constrained background work. Revisit this pairing only if a future phase genuinely needs a relational store or WorkManager's constraint-based scheduling.

🟡 Phase 2 — Daily Timings (MVP)

Astronomical Calculations

• Sunrise
• Sunset
• Moonrise
• Moonset
• Moon phase
• Golden Hour
• Brahma Muhurta
• Abhijit Muhurta
• Rahu Kalam
• Yamagandam
• Gulika Kalam
• Dur Muhurta
• Varjyam

Smart Alarms

• Brahma Muhurta alarm (as one of the scheduled muhurta reminders)
• Sunrise reminder
• Sunset reminder
• Custom reminder offsets (configurable lead time)
• Exact alarms
• Daily automatic rescheduling (reboot-survivable via BootReceiver)

Home Dashboard

• Current time
• Today's Panchang summary
• Upcoming events
• Current moon phase
• Next alarm

🟡 Phase 3 — Panchang

Hindu Calendar

• Daily Panchang screen with calendar navigation
• Monthly calendar
• Grid calendar
• List calendar
• Yearly overview

Panchang Details

• Tithi
• Nakshatra
• Yoga
• Karana
• Paksha
• Maas
• Ritu
• Samvatsara
• Ayana

Celestial Information

• Sunrise
• Sunset
• Moonrise
• Moonset
• Moon phase
• Planetary positions
• Zodiac transitions

🟡 Phase 4 — Festivals & Vrats

Festival Calendar

• Major Hindu festivals
• Regional festivals
• Sankranti
• Ekadashi
• Purnima
• Amavasya
• Chaturthi
• Pradosham
• Shivaratri
• Navaratri
• Diwali
• Holi
• Janmashtami
• Rama Navami
• Guru Purnima

Vrat Support

• Fasting days (Ekadashi and Pradosh, computed from the tithi)
• Parana timings
• Festival descriptions (PanchangaGlossary — a significance blurb per entry; the major festivals and every recurring observance are covered, the long tail is not)
• Ritual guidance
• Important observances

Notifications

• Festival reminders
• Vrat reminders
• Panchang alerts
• Upcoming observances

🟡 Phase 5 — Personalization

User Profile (multiple profiles — yourself + family/friends, one primary "Self"; prerequisite for the Phase 6 astrology features)

• Name
• Date of Birth
• Time of Birth (exact — Lagna, houses and divisional charts collapse without it)
• Place of Birth (geocoded to coordinates + IANA time zone, which is what a chart needs)

Saved Information

• Personal tithis
• Family birthdays
• Spiritual milestones
• Favorite festivals
• Frequently observed vrats

Custom Tracking

• Daily sadhana
• Meditation streak (:feature:meditation — timer plus a daily streak)
• Japa counter (:feature:japa — 108-bead mala counter with a daily streak)
• Reading tracker
• Temple visits

🟡 Phase 6 — Astrology

Led with the chart-computation layer — the shared foundation for Kundali, Rashifal and Muhurta — and that layer is now built and reference-checked. What remains here is reporting and the longer Rashifal horizons, not calculation.

Chart-Computation Layer (build once, on :core:astronomy)

• Lagna / ascendant (whole-sign houses; degree-based cusps are not computed — see Bhava chalit below)
• Whole-chart planetary rasi + degree (Spashta Graha, to the arcminute)
• Navamsa (D9)
• Dasamsa (D10) — and seventeen divisional charts in all, from one expression
• Vimshottari dasha state at an arbitrary date (three levels deep)
• Transit snapshot at an arbitrary date (planetaryPositionsAt)
• Pure natalChartAt(birth) API — offline, deterministic, reference-checked
• Astangata (combustion) — classical BPHS orbs
• Graha drishti — whole-sign Parashari aspects
• Named yogas — Gajakesari, Budhaditya, Chandra-Mangala, the five Panchamahapurusha
• Ashtakavarga — binnashtakavarga per graha and the sarvashtakavarga
• Jataka properties — varna, vashya, yoni, gana, nadi, the samvats and the ayanamsa at birth
• Ashtottari and Yogini dasha (alongside Vimshottari)
• Bhava chalit / degree-based house cusps

Kundli (consumes the chart layer)

• Birth chart (North-Indian, lagna and Chandra framings)
• Planetary positions (Spashta Graha + ashtakavarga bindus)
• Lagna
• Navamsa (and every other varga, behind one chip row)
• Dasha overview (mahadasha → antardasha → pratyantardasha)
• Birth report (nothing exports or shares a chart yet)

Horoscope (Rashifal)

• Daily Rashifal (computed, not editorial: Chandrabala and, when personalised, Tarabala)
• Weekly Rashifal (a seven-day strip on the same grading)
• Monthly Rashifal
• Yearly Rashifal

Muhurta (Electional) (picking auspicious times for events)

• General / panchang muhurta — tithi · nakshatra · yoga · karana · Choghadiya/Hora · avoiding Rahu/Yamaganda/Gulika · Abhijit
• Personalized muhurta — Tarabala / Chandrabala relative to a profile's birth Moon
• Event-type presets (marriage, housewarming, travel, purchase, …)

Match Making

• Kundli matching
• Compatibility score (36 gunas, with each koota's working shown)
• Guna Milan — plus Mangal dosha with its parihara, and the four additional porutham (Mahendra, Vedha, Rajju, Sthree Dheerga)

Reports

• Planetary transit report (positions are computed; nothing narrates them over time)
• Personalized recommendations

🟡 Phase 7 — Location & Astronomy

Location Support

• GPS location
• City selection
• Custom latitude/longitude
• Multiple saved locations

Offline Engine

• Offline astronomical calculations (on-device Meeus ephemeris, no network)
• Automatic timezone detection
• DST support
• Regional Panchang support

🟡 Phase 8 — Reminders & Automation

Daily Notifications

• Sunrise (covered as a muhurta reminder, not a dedicated toggle)
• Sunset (covered as a muhurta reminder, not a dedicated toggle)
• Brahma Muhurta
• Ringing alarms (a reminder can ring like a clock alarm rather than posting a notification; see ADR 0009)
• Sandhyavandanam
• Festival reminders
• Vrat reminders
• Meditation reminders

Smart Scheduling

• Dynamic daily alarms
• Snooze options
• Repeat schedules
• Wear OS notifications (future)

🟡 Phase 9 — UI & User Experience

Calendar Views

• Monthly grid
• Agenda view
• Timeline view
• Festival highlights
• Color-coded observances

Cosmic Clock (a family of clock faces; see ADR 0015)

• Panchanga clock — the five limbs as concentric cycles, current division picked out
• Plain-language explanations of the limbs, enforced by the build
• Spoken summary and a limb list, so the face is readable without seeing it
• Day clock — sunrise/sunset ground with the day's windows as arcs
• Graha clock — the sidereal zodiac and planetary positions
• Time scrubbing — drag to a moment and watch every cycle turn

Dashboard

• Clean, modern UI
• Material You support
• Dark mode
• Dynamic colors
• Home screen widgets

Landing hub (new default Home — hero + categorised shortcut grid; see ADR 0013)

• Contextual "today" hero (panchang glance + auspicious-now strip) → opens the daily Panchang
• Category tabs: Daily · Astrology · Devotion
• Shortcut grid — tiles map to roadmap phases; unbuilt features show a "coming/unlock" state
• Bottom nav: Home · Panchang · Reminders · Explore · Profile (Settings moves under Profile)
• Panchang dashboard preserved as the Panchang destination (reachable from the hero + tab)

Accessibility

• Large text mode
• High contrast
• Screen reader support
• Multiple themes

⬜ Phase 10 — Languages

Localization

• English
• Hindi
• Sanskrit
• Telugu
• Tamil
• Kannada
• Malayalam
• Marathi
• Gujarati
• Bengali
• Odia

Future community contributions can expand this list.

🟡 Phase 11 — Knowledge & Devotion

Learning

• Daily shloka
• Daily quote
• Festival significance
• Panchang explanations (PanchangaGlossary for named windows, observances and festivals; PanchangaPrimer for the limbs and the ideas behind them)
• Beginner guides

Devotional Tools

• Stotra library (:feature:stotra)
• Chant counter (:feature:japa)
• Meditation timer (:feature:meditation)
• Audio support (text only — nothing plays)
• Offline content (everything ships in the APK; the app makes no network calls)

⬜ Phase 12 — Ecosystem

Integrations

• Wear OS
• Android Auto (notifications)
• Calendar export (.ics)
• Backup & restore
• Cloud sync (optional and privacy-focused)

Open Platform

• Plugin architecture
• Public calculation library
• REST API (future)
• Desktop companion (future)

Long-Term Vision (V2+)

Transform Vedic Mitra into a complete Digital Vedic Companion by combining:

• 🕉 Accurate Panchang
• 🌞 Offline astronomical calculations
• 📅 Hindu calendar
• 🙏 Festival and vrat guidance
• 🔔 Intelligent reminders
• 🌙 Celestial information
• ⭐ Astrology tools
• 📖 Spiritual learning
• 👤 Personalized experience
• 🌍 Multi-language support
• 🔒 Privacy-first, offline-first design
• 🌐 Open-source community contributions

Suggested feature tiers

To keep the project focused as it grows, features are classified into three tiers:

• Core (Offline): Panchang, astronomy, reminders, calendar, location, personalization. These should work entirely offline after installation.
• Enhanced (Optional Online): Horoscope, planetary transit reports, and rich content updates. These can use online services but should degrade gracefully if offline.
• Community Extensions: Stotra packs, regional festival data, additional languages, and plugins. This keeps the core app lightweight while allowing the ecosystem to grow.

Build Instructions

Android Studio is not required. The project is command-line/CI-first — build it from a terminal, from VS Code tasks, or entirely on GitHub. Full setup (including installing the Android SDK command-line tools without Android Studio) is in docs/getting-started.md.

Build on GitHub (no local setup)

• Push a branch → the CI workflow builds the APK and uploads it as an artifact on the Actions run.
• Push a v* tag → the release workflow attaches an installable (debug-signed) APK to a GitHub Release.

Prerequisites (local CLI build)

• JDK 21 — Gradle runs on it (auto-detected; a local JDK 21 is recommended).
• Android SDK command-line tools with platform API 36 and build-tools;36.0.0 — install via sdkmanager, no Android Studio needed. Set ANDROID_HOME or create local.properties with sdk.dir=....

Common commands

# Build the debug APK
./gradlew assembleDebug

# Run unit tests
./gradlew testDebugUnitTest

# Formatting + static analysis (the CI quality gate)
./gradlew spotlessCheck detekt

# Auto-fix formatting
./gradlew spotlessApply

# List all modules
./gradlew projects

Convenience wrappers live in scripts/ (format and check).

The debug APK is written to app/build/outputs/apk/debug/.

Release builds (installable, updatable)

For a signed release that updates an already-installed copy in place, see docs/RELEASING.md. In short: create a release keystore once with keytool, copy keystore.properties.example to keystore.properties (both the keystore and this file are gitignored), bump version.properties, then build :app:assembleRelease (APK) or :app:bundleRelease (AAB for Play). The design is recorded in ADR 0010.

The v* tag release workflow currently attaches a debug-signed APK for convenience. Debug-signed builds cannot update a keystore-signed install (different certificate), so use a locally signed release build for real distribution until CI is wired to sign with the release keystore.

Contribution Guide

Contributions are welcome! Please read CONTRIBUTING.md for the workflow, coding standards, and the Definition of Done, and AGENTS.md for the detailed conventions (also used to brief AI coding assistants). By participating you agree to the Code of Conduct.

In short:

1. Fork and branch (feat/…, fix/…).
2. Follow the architecture and naming conventions.
3. Keep spotlessCheck, detekt, and tests green.
4. Use Conventional Commits.
5. Open a PR using the template.

Support the project

Vedic Mitra is free and always will be — every feature, for everyone, with no ads, no tracking, and no account. Nothing is paywalled, and nothing here unlocks anything. If it's useful to you, this is how you can keep it going.

Donate

• GitHub Sponsors — one-off or monthly.
• Ko-fi — a one-off tip by card or PayPal.
• UPI — skylab@upi (India).

For businesses

The AGPL requires anything built on Vedic Mitra — including hosted services — to share its source under the same terms. If that doesn't work for your product, a commercial license lifts the obligation: see pricing and tiers, or email skylabs.in@gmail.com. The :core:astronomy engine is licensable on its own.

Costs nothing

• ⭐ Star the repo — it's the single biggest help for discovery.
• 🐛 Report a bug, or a panchanga timing that disagrees with your almanac.
• 🌐 Contribute a translation, or regional festival data — see CONTRIBUTING.md.
• 💬 Tell someone who'd find it useful.

Author

Jayvardhan Potabatti — Creator, Owner, Designer & Lead Developer.

• GitHub: @imskylab
• LinkedIn: linkedin.com/in/imskylab

See AUTHORS.md for the full list, and CONTRIBUTING.md to get involved.

License

Vedic Mitra is dual-licensed — see LICENSING.md:

• GNU AGPL-3.0-or-later for open-source use (note: the AGPL requires network/SaaS deployments to offer their source to users), with one additional permission under AGPL section 7 for linking against proprietary platform libraries such as Google Play services.
• A commercial license for proprietary/closed-source use, without the AGPL's copyleft obligations — see LICENSE-COMMERCIAL.md for terms.

Vedic Mitra collects no data and has no servers; see the Privacy Policy.

Third-party components are listed in THIRD-PARTY-NOTICES.md.

© 2026 Jayvardhan Potabatti.