# Tara — Features and Capabilities > Tara is a meditation and mindfulness platform available as a Progressive Web > App (installable from the browser) and as native iOS/Android applications. It > provides guided meditations, breathing exercises, a configurable silent timer, > multi-day courses, offline downloads, progress tracking, and a subscription > model. The Tara application libraries (`libs/tara/`) are built on top of the > platform-agnostic meditation engine in `libs/meditation/`, which handles > audio, timing, breathing, session management, progress, and offline storage. --- Tara's feature set covers the full lifecycle of a meditation practice: first-time users are guided through onboarding and goal-setting; they then discover and play content through a full-featured audio player; their sessions are recorded and surfaced back to them as streaks, statistics, and achievements; and premium content is unlocked through subscriptions managed across web and mobile stores. The domain boundary with Lilith is worth noting for engineers who join the project: Lilith owns the broader consciousness and spiritual experience surface; Tara owns the mainstream, app-store-safe meditation product. --- ## 1. Guided Meditations ### 1.1 Content Categories Tara organizes its library into goal-oriented categories so users can immediately find content relevant to their current need. Categories are the primary entry point for discovery and appear prominently on the home screen and in search filters. The `@tara/api` catalog stores a category on every meditation as the `meditation_category` enum — 15 values: `sleep`, `stress`, `focus`, `anxiety`, `morning`, `evening`, `breathwork`, `body_scan`, `visualization`, `gratitude`, `self_compassion`, `relationships`, `work`, `creativity`, `general`. | Category | Purpose | | ----------------- | -------------------------------------------------------------------------- | | `stress` | Techniques for reducing physical tension and mental anxiety | | `sleep` | Practices that calm the nervous system and prepare for restful sleep | | `focus` | Meditations that sharpen concentration and clear mental clutter | | `anxiety` | Grounding exercises and acceptance-based practices for anxious states | | `self_compassion` | Loving-kindness (metta) practices for building self-acceptance | | `relationships` | Meditations for empathy, forgiveness, and deepening emotional bonds | | `gratitude` | Appreciation practices shown by research to lift mood and wellbeing | | `morning` | Intention-setting and energizing practices to start the day with clarity | | `evening` | Wind-down practices to close the day and transition toward sleep | | `breathwork` | Purely breath-focused guided practices (pranayama and modern techniques) | | `body_scan` | Progressive awareness exercises moving systematically through body regions | | `visualization` | Guided imagery and visualization-based practices | | `work` | Brief practices for staying grounded and focused during the workday | | `creativity` | Practices supporting creative flow and open awareness | | `general` | General-purpose meditations not tied to a single goal | > The richer `@tara/content` library type `MeditationCategory` defines a broader > 25-value vocabulary (adding e.g. `grief`, `pain`, `healing`, `commute`, > `emergency`) used by content tooling and filters. **Metta** (loving-kindness) is a Buddhist meditation practice of systematically extending feelings of goodwill to oneself, loved ones, neutral parties, and difficult people. **Body scan** is a technique of directing attention through each body region in sequence, releasing tension and developing somatic (body-based) awareness. ### 1.2 Content Types Five distinct content formats serve different practice styles and contexts: - **Guided** — Instructor-narrated sessions where a teacher speaks throughout. The most common format for beginners and intermediate practitioners. The teacher explains techniques and gently directs attention. - **Unguided** — Silent sessions with no narration. The user meditates alone, optionally accompanied by ambient sounds and periodic bells to mark elapsed time. Suited for experienced practitioners who need minimal direction. - **Music** — Meditative music compositions designed to create psychological conditions for contemplative states without spoken instruction. Useful as background during journaling, yoga, or quiet work. - **Soundscape** — Pure nature and environmental audio (rain, ocean, forest) without music or narration. Often used for sleep and deep focus. - **Story** — Narrative-based guided visualizations, including sleep stories where a gentle narrator leads the listener through an imaginative journey designed to ease the transition into sleep. ### 1.3 Difficulty Levels | Level | Description | | ------------ | ------------------------------------------------------------------------------ | | Beginner | Simple techniques, shorter sessions (5–10 min), highly detailed instruction | | Intermediate | Moderate complexity, varied techniques, sessions of 10–30 min | | Advanced | Deeper practices requiring familiarity with basic techniques, longer durations | | All Levels | Suitable for anyone regardless of experience | ### 1.4 Session Durations Meditations range from 5-minute quick practices to 60+ minute deep sessions. Duration filter options: Quick (5–10 min), Balanced (10–20 min), Deep (20+ min), Any length. This serves both users who can only spare a few minutes on a busy day and dedicated practitioners with an extended daily practice. ### 1.5 Meditation Metadata Each meditation record (`meditations` table) carries: title, description, category, content type, duration in seconds, audio URL, image URL, instructor name/bio/image, experience level, premium and featured flags, searchable tags, a free-form `metadata` JSON object, play count, average rating, rating count, and a publish timestamp. This metadata drives search, filtering, recommendations, and content discovery across the entire app. ### 1.6 Session Ratings and Notes After completing a meditation, users see a session completion screen showing the session duration, current streak status, and any new achievements earned. They can provide a 1–5 star rating and write free-form notes capturing their experience. These ratings feed content recommendations and help surface highly-rated teachers. --- ## 2. Meditation Timer The timer enables silent, self-timed practice. Users who already know how to meditate can sit for a chosen duration without narration, using bells and ambient sounds to mark time without checking a clock. ### 2.1 Duration Configuration - **Duration presets** — Quick-select buttons for common durations: 1, 5, 10, 15, 20, 30, 45, and 60 minutes. Users can also enter a custom duration. - **Preparation phase** — An optional countdown (e.g., 30 seconds) before the main timer starts, giving the user time to settle into position before the session clock begins. - **Wind-down phase** — A gentle ending phase before the timer completes. The wind-down signals that the session is nearly over without abruptly ending, allowing a natural transition out of the meditative state. - **Timer presets** — Save a complete timer configuration (duration, bells, ambient sounds, phases) as a named preset for one-tap reuse of a favorite setup. ### 2.2 Timer Phases and Controls The `@oshun/meditation-timer` engine defines a state machine with five `TimerState` values — `idle`, `preparing`, `running`, `paused`, `completed` — and, while running, a `TimerPhase` of `preparation`, `meditation`, `interval`, or `wind-down`. Controls include start, pause/resume, stop/end early, and full-screen mode. The timer continues running in the background when the app is minimized, with a system notification showing remaining time. Timing compares against wall-clock timestamps rather than accumulating tick increments, which keeps long sessions accurate even when the device CPU throttles background processes. ### 2.3 Bell System Bells serve as non-verbal time markers that keep the practitioner oriented without breaking concentration. Six built-in bell sounds are available: Tibetan Bowl, Singing Bowl, Gong, Temple Bell, Chime, Soft Tone. - **Start bell** — Sounds when the meditation begins. - **End bell** — Sounds when the timer completes. - **Interval bells** — Recurring bells at configured time intervals (e.g., every 10 minutes during a 30-minute session), helping practitioners track elapsed time without opening their eyes. - **Phase transition bells** — Optional bell at the start of the wind-down phase. - **Independent volume** — Bell volume is controlled separately from ambient sound volume and master volume. - **Preview** — Bell sounds can be previewed before the session starts. ### 2.4 Ambient Sound Integration Ambient sounds play alongside the timer, allowing practitioners to customize their sonic environment. Timer sessions are recorded in the user's session history and count toward streaks and achievements just like guided sessions. Keyboard shortcuts are available on the web app for control without touching the mouse. --- ## 3. Breathing Exercises Breathing exercises are a distinct practice mode where users follow guided breath patterns rather than sitting in silent awareness. Controlled breathing activates the parasympathetic nervous system, reduces heart rate, and modulates stress hormones. Tara provides ten evidence-based and traditional patterns. ### 3.1 Built-In Breathing Patterns The following patterns and their timings are taken directly from `libs/meditation/breathing/src/patterns.ts`. The notation is inhale-holdIn-exhale-holdOut in seconds. | Pattern | Timing (inhale-hold-exhale-hold) | Purpose | | ------------------ | -------------------------------- | --------------------------------------------------------------- | | Box Breathing | 4-4-4-4 | Stress relief; used by military/first responders for rapid calm | | 4-7-8 Technique | 4-7-8-0 | Dr. Andrew Weil's sleep and anxiety relaxation technique | | Coherent Breathing | 5-0-5-0 | Maximizes heart rate variability (HRV) for autonomic health | | Energizing Breath | 2-0-4-0 | Quick inhale, slower exhale to boost energy and alertness | | Calming Breath | 4-0-2-0 | Long inhale, quick exhale to soothe the nervous system | | 2:1 Ratio | 4-0-8-0 | Deep relaxation via a 2:1 exhale-to-inhale ratio | | Alternate Nostril | Multi-phase (Nadi Shodhana) | Pranayama balancing left and right nostril breathing | | Wim Hof Method | Multi-round, with breath holds | Rapid cycles plus breath retention (15 s recovery hold) | | Sleep Breathing | 4-7-8-2 | Sleep-specific variant designed to slow the nervous system | | Focus Breathing | 4-2-4-2 | Balanced pattern with short holds, optimized for concentration | **Pranayama** refers to yogic breath-control practices. **Nadi Shodhana** (alternate nostril) is one of the most ancient, believed to balance the energy channels on each side of the body. **HRV** (heart rate variability) is the variation in time between heartbeats — higher HRV is associated with better cardiovascular health and emotional resilience. **Parasympathetic activation** refers to the "rest and digest" branch of the autonomic nervous system that counteracts the fight-or-flight stress response. ### 3.2 Custom Pattern Builder Users can create breathing patterns with precise control over each phase: inhale duration, hold-after-inhale, exhale duration, hold-after-exhale. A ratio-based constructor accepts specifications like "4:7:8" and builds the pattern automatically. Custom patterns can be named and saved for repeated use. ### 3.3 Visual Guidance An animated breathing circle expands during inhale phases and contracts during exhale phases, providing a visual rhythm to follow without listening. Each phase is color-coded and labeled (Inhale / Hold / Exhale). A phase countdown timer shows seconds remaining in the current phase. A cycle counter tracks completed breath cycles. ### 3.4 Audio and Haptic Guidance Optional audio cues (spoken phase prompts or tonal chimes) synchronize with phase transitions for eyes-closed practice. On mobile, haptic vibration patterns are timed to each phase change so practitioners can feel the cues without looking at the screen — enabling completely screen-free use. ### 3.5 Completion Modes and History Three completion modes are available: stop after a target number of breath cycles, stop after a total elapsed duration, or practice open-endedly until manually stopped. Completed breathing sessions are recorded in the progress history and contribute to streaks and statistics. --- ## 4. Courses and Learning Paths ### 4.1 Course Structure Courses are multi-day structured programs (e.g., "7-Day Stress Relief," "30-Day Mindfulness Foundation") that guide users through a progressive curriculum. Each course has a description, expected outcomes, teacher attribution, total duration, and a sequence of daily meditation lessons. Sequential structure ensures foundational skills are built before more advanced practices are introduced — a user who is new to meditation will not encounter body scan practices before learning basic breath awareness. ### 4.2 Course Progress Tracking The system tracks the user's current day within a course, marks individual lessons as Not Started / In Progress / Completed / Locked (future lessons), calculates an overall completion percentage, and provides start/resume controls. Users receive reminders to return to their course if they skip a day. ### 4.3 Curated Collections Beyond sequenced courses, Tara offers themed collections grouping related meditations (e.g., "Morning Routines," "Sleep Toolkit," "Stress Toolkit"). Collections appear featured on the home screen, allow collection-level progress tracking, and serve as flexible alternatives to fully sequential courses for users who prefer variety within a theme. --- ## 5. Audio Player The full-featured audio player — powered by `@oshun/meditation-player` — handles all sound reproduction for guided meditations, music, soundscapes, and stories. ### 5.1 Playback Controls - **Play/pause, seek/scrub, skip forward 10 s, skip back 10 s** — standard media controls with immediate state updates. - **Previous/next track** — navigate within a queue (e.g., a course playlist). - **Playback speed** — A quality-preserving range. The `@oshun/contracts/tara/playback-rate` policy clamps speed to 0.85x–1.25x in 0.05x steps (`0.85, 0.9, 0.95, 1.0, 1.05, 1.1, 1.15, 1.2, 1.25`) and always requests pitch preservation, since meditation narration tolerates only a narrow time-scale range before breath pacing and tone degrade. - **Resume position** — The playback position in partially completed meditations is saved. The user can close the app and return to the exact position. ### 5.2 Player Display Modes - **Full-screen immersive player** — A distraction-free view showing artwork, title, teacher, waveform or animation, and all controls. - **Persistent mini player bar** — A compact player that stays visible at the bottom of the screen while the user navigates other app areas. - **Lock screen controls** — On iOS and Android, the device lock screen shows now-playing information and playback controls without requiring the user to unlock the device. This uses the iOS MediaPlayer framework and Android MediaSession API respectively. ### 5.3 Streaming and Quality Audio streams from a CDN without requiring a full download first. Users select playback quality (Low / Medium / High) based on data preferences. **Adaptive bitrate streaming** automatically adjusts quality if network conditions degrade, preventing buffering interruptions during meditation. ### 5.4 Audio Focus Management When a meditation starts, Tara requests audio focus from the operating system so other apps (music, podcasts, phone calls) pause. When the meditation ends or is paused, focus is released and the interrupted app resumes automatically. When headphones are disconnected, playback pauses immediately to prevent sudden loud audio from device speakers — a critical comfort and privacy protection. ### 5.5 Background Playback Audio continues when the app is minimized, the screen is locked, or the user switches to another app. This is essential for meditation — users routinely close their eyes and do not actively watch the screen. --- ## 6. Ambient Sounds and Sound Mixer ### 6.1 Sound Library The `@oshun/meditation-timer` ambient library groups built-in sounds into six categories via the `AmbientSoundCategory` type (plus `custom`): | Category | Examples (`AmbientSoundType`) | | ---------- | ------------------------------------------------------------------------------------------------------------------- | | `nature` | Rain, light/heavy rain, ocean, ocean waves, river, stream, waterfall, forest, birds, crickets, wind, fire, campfire | | `weather` | Thunderstorm | | `urban` | Coffee shop, city | | `musical` | Singing bowls, om, temple | | `noise` | White noise, pink noise, brown noise | | `binaural` | Binaural alpha, binaural theta, binaural delta | **White noise** contains equal energy across all audible frequencies, producing a consistent hissing sound. **Brown noise** (also called Brownian noise) is weighted toward lower frequencies, producing a deeper, rumbling quality that many find more soothing than white noise. **Pink noise** is between the two, with a gentler rolloff, and is frequently used in sleep science research. > The `@tara/content` library models sounds more granularly still, with > `AmbientCategory` (10 values), `MusicMood` (17), `BellType` (12), and a > `BinauralFrequency` covering the delta/theta/alpha/beta/gamma bands. ### 6.2 Multi-Layer Sound Mixer Users can combine multiple ambient sounds simultaneously. Each sound layer has an independent volume slider. The visual mixer interface resembles a simple audio mixing board. Layered sounds work alongside guided meditations — the ambient track plays under the instructor's voice, which automatically **ducks** (reduces) the background volume when active so the voice remains clearly audible. This layering also works with the silent timer. --- ## 7. Progress Tracking and Statistics ### 7.1 Core Metrics At-a-glance progress shows total lifetime minutes meditated, total sessions completed, sessions and minutes today, and sessions and minutes this week. A weekly goal progress bar shows progress toward the user's target (`user_progress.weeklyGoalMinutes`, default 60 min/week). ### 7.2 Detailed Analytics - **Calendar heatmap** — Shows daily practice intensity over time, making it easy to see patterns (weekend gaps, daily consistency, high-intensity months). - **Time-of-day distribution** — When during the day the user most often meditates (morning vs. evening patterns). - **Day-of-week distribution** — Which days see the most practice, helping identify scheduling gaps. - **Session type breakdown** — Statistical split between guided / breathing / timer / unguided session types. - **Trend comparisons** — This week vs. last week, this month vs. last month, showing whether practice is growing, stable, or declining. ### 7.3 Session History A full chronological list of all past sessions with per-session details: session type, date and time, duration, completion percentage, personal rating (1–5 stars), and any notes written. Filterable by date range (Today, This Week, This Month, Last 30 Days, All Time). ### 7.4 Data Export and Multi-Device Sync Users can export their complete meditation history and statistics. Progress synchronizes across multiple devices (phone, tablet, web) with conflict detection and configurable resolution strategies (last-write-wins or merge). --- ## 8. Streaks and Motivation ### 8.1 Streak System A streak is the number of consecutive calendar days on which the user completed at least one qualifying meditation session. Streaks are a powerful behavioral driver backed by research on habit formation — the desire not to "break the chain" motivates consistent daily practice. | Feature | Description | | ---------------------- | ------------------------------------------------------------------------------ | | Current streak | Number of consecutive days with at least one meditation | | Longest streak | All-time personal record streak length | | Today's status | Clear visual indicator of whether the user has already practiced today | | At-risk alerts | Notification when fewer than 6 hours remain in the day and no session recorded | | Visual streak calendar | Week-at-a-glance view with completed days, missed days, and today's status | Streak milestones are celebrated at 3, 7, 14, 30, 60, 90, and 365 days. ### 8.2 Streak Protection - **Forgiveness days** — A configurable number of "grace" days per month that do not break the streak when missed, accommodating illness, travel, and life events without feeling punitive. - **Streak freezes** — Users can explicitly freeze their streak before a planned absence (e.g., a camping trip without phone access), preserving the streak without requiring practice or being dishonest about it. - **Minimum duration** — A configurable minimum session length (e.g., 2 minutes) must be met for a session to count toward streak maintenance, preventing accidental brief app opens from maintaining a streak. ### 8.3 Weekly Goals Users set a weekly minute target (`user_progress.weeklyGoalMinutes`, default 60 minutes per week). A visual progress bar tracks progress, resetting at the start of each new week. This frames meditation as accumulating practice time rather than maintaining a binary daily streak. --- ## 9. Achievements and Milestones Achievements are earned badges recognizing meaningful milestones. They provide recognition of progress and serve as long-term motivational targets. **Rarity tiers**: the `@tara/database` `Achievement` model carries an `AchievementRarity` of `COMMON` → `UNCOMMON` → `RARE` → `EPIC` → `LEGENDARY`. Rarity signals how much effort the achievement requires: most users earn Common achievements in their first week, while Legendary achievements require months or years. Achievement requirements map to an `AchievementType` — `STREAK_DAYS`, `TOTAL_SESSIONS`, `TOTAL_MINUTES`, `COURSES_COMPLETED`, `CATEGORY_MASTERY`, or `SPECIAL` — with a numeric `requirement` value. (The `@tara/api` `/achievements` endpoint additionally groups achievements into `streak`/`time`/`sessions`/`courses`/`exploration`/`special` categories with a `bronze`/`silver`/`gold`/`platinum` tier.) The following are illustrative achievements consistent with those requirement types and rarity tiers: | Achievement Example | Requirement | Rarity | | ------------------- | ------------------------------ | --------- | | First Steps | Complete first meditation | Common | | Breathing Believer | Complete 10 breathing sessions | Uncommon | | One Week | 7-day streak | Uncommon | | Explorer | Try 5 different categories | Rare | | Centurion | 100 total sessions | Rare | | Marathon Meditator | 1,000 total minutes | Epic | | Year of Mindfulness | 365-day streak | Legendary | Achievement badges display with unlock date. Session completion screens show animated celebrations scaled to significance — a minor achievement shows a brief sparkle; a Legendary unlock triggers a full celebratory animation. A **reduced-motion variant** is provided for users with vestibular disorders or motion sensitivity. **Milestones** are distinct from achievements: they are numerical progress markers (first session ever, 50 hours total, 100-day streak) that trigger special notifications and are highlighted in the progress history. --- ## 10. Teacher Profiles Each meditation teacher has a dedicated profile with: name, biography, profile photo, certifications and training background, and areas of specialty. Specialty areas include: - **MBSR** (Mindfulness-Based Stress Reduction) — the evidence-based 8-week program developed by Jon Kabat-Zinn, widely used in clinical and hospital settings as a treatment for chronic pain, stress, and anxiety. - **Yoga Nidra** — a deeply relaxing guided meditation bringing practitioners to the threshold between waking and sleep (the hypnagogic state) while remaining conscious. Literally "yogic sleep." - **Zen** — a school of Mahayana Buddhism emphasizing direct experience and seated silent meditation (zazen). - **Trauma-Informed Mindfulness** — meditation instruction adapted for practitioners with trauma histories, emphasizing choice, agency, and safety. - Compassion, Sleep, Breathwork, and Body Scan specialties. The teacher directory is browsable and searchable. Each teacher page lists all their meditations, enabling users to follow a teacher whose voice and style they prefer. --- ## 11. Library, Favorites, and Downloads - **Favorites** — Mark any meditation or course as a favorite for quick retrieval. The favorites list appears in the personal library tab. - **Download library** — Meditations downloaded for offline use are listed in a dedicated section showing file sizes, download dates, and availability status. - **Session history** — Completed sessions are accessible for reference, note review, and re-listening. - **Download queue management** — Priority ordering, retry logic on failure, configurable concurrent download limits, pause/resume capability, and per-download cancellation. Users can set a storage limit to prevent downloads consuming excessive device storage. - **WiFi-only downloads** — An option to prevent downloads from consuming cellular data, useful for users with metered data plans. - **Smart download suggestions** — The app analyzes listening patterns and recommends content to download before going offline, based on recently played sessions, favorite categories, and preferred teachers. --- ## 12. Search and Discovery Full-text search runs across meditation titles, descriptions, teachers, categories, and tags. Faceted filtering is available by: category, content type (guided/unguided/music/etc.), difficulty level, duration range, teacher, premium/free status, and download availability. Results are sortable by relevance, popularity (play count), and rating. The home screen features curated collections, recently played content, featured meditations, and the recommendation engine's current suggestions — ensuring users can discover something relevant without needing to search. --- ## 13. Personalized Recommendations The `@tara/api` recommendations endpoint (`GET /api/v1/recommendations/*`) returns up to a requested `limit` of published meditations, ranked by featured status, then play count, then recency. It applies one of two strategies: - **`category_affinity`** — when a `category` query parameter is supplied, recommendations are filtered to that category. - **`featured_popularity`** — the default strategy when no category is given, surfacing featured and popular content. When no meditations match a requested category, the endpoint falls back to featured + popular content and reports `fallbackUsed: true`. --- ## 14. Onboarding and Goal Setting First-time users complete a brief, guided onboarding flow: 1. **Primary goal selection** — Reducing stress, improving sleep, improving focus, reducing anxiety, self-compassion, or general wellbeing. 2. **Experience level** — Complete beginner, some experience, or regular practitioner. 3. **Preferred session length** — Short (5–10 min), Medium (10–20 min), or Long (20+ min). 4. **Daily reminder time** — Set a preferred time for the daily practice reminder. 5. **Mindfulness assessment** — An optional brief questionnaire that establishes a baseline for tracking wellbeing over time. 6. **App tour** — A short guided tour introducing the key sections of the app. These preferences are used immediately to surface relevant content and configure the weekly goal target. All preferences are adjustable at any time in settings. --- ## 15. Notifications and Reminders | Notification Type | Trigger | | ---------------------------- | ---------------------------------------------------------------- | | Daily practice reminder | User's chosen reminder time if no session has been completed yet | | Streak at-risk alert | Less than 6 hours remain in the day without a session | | Milestone achievement | When a new achievement or milestone is earned | | Weekly summary | Sunday or Monday summary of the prior week's practice | | Course continuation reminder | When a course has been started but no lesson completed recently | All notification types can be enabled or disabled independently. A **quiet hours** setting prevents notifications from arriving during sleep hours regardless of trigger timing. --- ## 16. Subscriptions and Premium Content Tara's content is split between a free tier and a premium subscription. Billing is handled through two completely separate paths depending on platform: Stripe for web users, and RevenueCat for mobile users (which in turn validates receipts against Apple and Google). - **Free tier** — A curated selection of meditations (introductory content from each category), full timer functionality, and basic progress tracking. - **Premium subscription** — Full content library (all meditations, all courses), offline downloads, advanced statistics, and all future new content. - **Subscription tiers** — the subscription tier vocabulary is `free`, `premium`, and `lifetime`; subscription status is `active`, `canceled`, `expired`, `past_due`, or `trialing`. - **Web billing (Stripe)** — `@tara/api` integrates Stripe for the web flow: `POST /subscription/checkout` creates a checkout session, `POST /subscription/portal` returns a customer-portal URL, `POST /subscription/cancel` and `/restore` manage the subscription, and a public `POST /subscription/webhook` endpoint receives Stripe lifecycle events. - **Mobile in-app purchases** — the mobile app uses RevenueCat (`react-native-purchases`). The API verifies store purchases through `POST /subscription/ios/verify` (App Store receipt) and `POST /subscription/android/verify` (Google Play purchase). --- ## 17. User Account and Settings - **Account creation** — Email/password registration with email verification, plus social login (Google, Apple). Password reset via email token. - **Profile settings** — Display name, profile photo, time zone. - **App settings** — Theme (light/dark/system), audio quality preference, playback speed default, download preferences (WiFi-only toggle, storage limit). - **Notification settings** — Per-type enable/disable, reminder times, quiet hours. - **Subscription management** — View subscription status, upgrade/downgrade, and manage billing through App Store, Google Play, or the Stripe web portal. - **Privacy controls** — Data access review, account deletion, and GDPR-compliant data export. --- ## 18. Accessibility - **Screen reader support** — All interactive elements have accessible labels for VoiceOver (iOS) and TalkBack (Android). Player and timer controls are fully operable via screen reader. - **High contrast mode** — Increased contrast color scheme for users with visual impairments. - **Reduced motion** — Disables or simplifies animations (breathing circle, achievement celebrations, page transitions) for users with vestibular disorders or motion sensitivity. Every animation has a reduced-motion variant. - **Adjustable text size** — Respects system text size preferences. - **Keyboard navigation** — Full keyboard operability on the web app, including player controls, navigation, and modal dialogs. Timer and breathing controls have keyboard shortcuts. - **WCAG 2.1 AA compliance** — Target compliance level for all user interface elements. --- ## 19. Internationalization The web app uses `next-intl` for locale-based routing (`/[locale]/...`). The i18n config (`apps/tara/web/src/i18n/config.ts`) declares seven supported locales — English (`en`, default), Spanish (`es`), French (`fr`), German (`de`), Portuguese (`pt`), Japanese (`ja`), and Simplified Chinese (`zh-CN`) — each with a display name, native name, text direction, and font family. All seven are currently configured left-to-right; the config carries a per-locale `direction` field (`ltr`/`rtl`) so a right-to-left locale could be added without code changes. Locale detection runs from browser preferences with user override. Per-locale fonts include Noto Sans JP for Japanese and Noto Sans SC for Chinese. The bundled translation file ships UI strings for the default `en` locale. --- ## 20. Progressive Web App Tara is a full **PWA** (Progressive Web App), meaning it is installable on desktop and mobile from the browser without an App Store. PWA capabilities: - **Offline functionality** via Service Worker caching — downloaded meditations are accessible without an internet connection. - **Install prompt** and home screen icon on supported browsers. - **Full-screen launch mode** — launches without browser chrome for an app-like feel. - **Push notification support** for reminders and achievements. - **Background audio playback** continues when the tab is backgrounded. PWA delivers a near-native experience on platforms where the native mobile app is not installed, and is the primary deployment target for web users. --- ## 21. Mobile Application ### 21.1 Native Features The Tara mobile app is built with React Native and Expo, targeting iOS and Android. Each platform uses its native system APIs for audio, purchases, notifications, and deep linking. **iOS** — Background audio via `AVAudioSession`, push notifications via APNs, in-app purchases via StoreKit (validated with RevenueCat), lock screen controls via MediaPlayer, haptic feedback via CoreHaptics, deep linking via Universal Links. **Android** — Background audio via ExoPlayer, push notifications via FCM, in-app purchases via Google Play Billing (validated with RevenueCat), lock screen controls via MediaSession, haptic feedback via Vibrator API, deep linking via App Links. ### 21.2 Mobile Screens The app includes dedicated screens for: Home/Dashboard, Explore/Browse, Meditation Detail, Full-Screen Player, Timer, Breathing Exercises, Courses, Course Detail, Progress, Profile, Settings, Search, Library/Downloads, Onboarding. ### 21.3 Mobile-Specific Features - **Offline mode** — Full offline playback of downloaded content with complete UI that functions without a network connection. - **Mini player** — A persistent compact player available throughout the app while navigating other screens, so meditation is never interrupted by browsing. - **Share functionality** — Share achievements and streaks to social media and messaging apps. --- ## 22. Backend API The Tara API is a Node.js / Hono 4 (`OpenAPIHono`) server on port 3001 providing all data and business logic for web and mobile clients, with an OpenAPI 3.1 document at `/api/v1/openapi.json` and Swagger UI at `/api/docs`. ### 22.1 Authentication JWT-based authentication with access tokens and refresh tokens. Social OAuth (Google, Apple). Password reset via email token. Multi-device session management. ### 22.2 Content Endpoints Query endpoints for meditations, courses, lessons, teachers, and collections (`/api/v1/meditations`, `/courses`, `/teachers`, `/collections`). A `GET /meditations/{id}/audio` endpoint returns audio URLs; premium audio is delivered through time-limited CloudFront signed URLs generated by the API rather than streamed from the API itself. A `/search` endpoint provides full-text search across meditations, courses, and teachers with a type filter. ### 22.3 Progress Endpoints Session recording (create, update, query). Progress aggregation (streaks, statistics, history). Course progress tracking (per-lesson status). Achievement and milestone management. ### 22.4 User Endpoints Profile management, settings persistence, device registration for push notifications, download tracking, and favorites management. ### 22.5 Subscription Endpoints Subscription status query. iOS App Store receipt validation via RevenueCat. Android Google Play purchase validation via RevenueCat. Webhook handlers for subscription lifecycle events (renewal, cancellation, expiry, billing retry). ### 22.6 Notification Endpoints Push notification preference management. Reminder scheduling. Notification delivery via APNs (iOS) and FCM (Android). --- ## 23. Analytics and A/B Experiments (`@tara/analytics`) `@tara/analytics` provides structured behavioral event tracking, user-level metrics, and controlled A/B experimentation for the entire Tara platform. - **Event tracking** — Typed event definitions for all user actions: session started and completed, course enrolled and completed, achievement earned, subscription upgraded, timer used, breathing exercise completed, content searched, and download initiated. Events carry full context metadata (content ID, duration, category, technique) without including personally identifiable content. - **Pluggable providers** — An analytics provider interface supports an internal (self-hosted) provider, an in-memory provider for testing, and a console provider for development. Any third-party analytics platform (Segment, Mixpanel, Amplitude) can be integrated by implementing the provider interface. - **A/B experiment management** — `ExperimentManager` runs controlled experiments by assigning users to variants (A/B/C) based on configurable traffic allocations. Variant assignments are deterministic per user ID so a user always sees the same variant. Results are tracked against defined success metrics. - **Feature flags** — Runtime feature flag evaluation with per-user, per- segment, and percentage rollout targeting. Flags are evaluated locally against loaded configuration, enabling instant flag evaluation without a network round-trip. Local development overrides allow developers to force specific flags without affecting other users. - **User properties and session context** — Track subscription tier, platform (iOS/Android/web), device type, and locale as persistent user properties enriching every event automatically. --- ## 24. Observability and Error Monitoring (`@tara/monitoring`) `@tara/monitoring` provides production observability for the Tara platform: structured exception capture, breadcrumb trails, and performance measurement. - **Error tracking** — `captureException()` and `captureMessage()` send structured error reports with full stack traces, user context (subscription tier, session ID), and tagged metadata (feature area, meditation ID). Error severity levels: fatal, error, warning, info, debug. - **Breadcrumbs** — Before exceptions fire, breadcrumbs record the sequence of events leading up to the error (e.g., "player loaded → meditation started → seek attempted → decode error"). Typed breadcrumb categories: navigation, UI interaction, network request, audio lifecycle, meditation lifecycle. - **Pluggable providers** — Three providers ship out of the box: a server provider (compatible with Sentry on Node.js), a console provider (logs to stdout for development), and an in-memory provider (for testing). The Sentry peer dependency is optional; the provider interface allows any error tracking backend. - **Performance monitoring** — `PerformanceMonitor` measures the duration of critical operations: audio load time, initial content fetch latency, search response time, and subscription validation round-trip. Transactions and spans are structured identically to distributed traces, enabling correlation across client and server. - **User context propagation** — Setting a user context attaches subscription tier and anonymized user ID to all subsequent errors and performance traces, enabling per-cohort error rate analysis without storing personally identifiable information. --- ## 25. UI Component Library (`@tara/ui`) `@tara/ui` is a purpose-built component library for consistent design across web and mobile. Components are organized in four layers: **Foundational** — Button, IconButton, Typography, Card, Input, Modal, BottomSheet, Toast, Avatar, Badge, Chip, Divider. **Navigation** — TabBar, Header, SegmentedControl, Breadcrumb. **Meditation-Specific** — Components purpose-built for the meditation context: | Component | Description | | ------------------- | ------------------------------------------------------------------- | | MeditationCard | Thumbnail, title, duration, teacher, rating, premium indicator | | AudioPlayer | Full-featured player UI with all controls | | MiniPlayer | Compact persistent player bar | | TimerDisplay | Phase and countdown visualization | | BreathingVisualizer | Animated circle with phase labels and color transitions | | StreakDisplay | Current streak, longest streak, and week-at-a-glance calendar | | ProgressChart | Session history chart with configurable date ranges | | CourseProgress | Course day grid with completion status per lesson | | TeacherCard | Teacher photo, name, specialty | | AchievementBadge | Badge with rarity styling and unlock date | | SoundMixer | Multi-layer ambient sound controls with per-layer volume sliders | | SessionComplete | Post-session screen with duration, streak, achievement celebrations | **Layout** — SafeArea, ScrollView, Grid, Skeleton (loading placeholders). **Animations** — Page transitions, micro-interactions, breathing animations. Every animation provides a reduced-motion variant. **Design tokens** — Colors, typography, spacing, border radii, and shadows defined as tokens. A theme provider delivers tokens in light and dark modes. Dark mode uses warmer, lower-intensity backgrounds to reduce eye strain during evening practice. --- ## 26. Content Management (`@tara/content`) `@tara/content` defines data models and types for all Tara content, and provides React hooks for fetching and caching content: - **Content types** — TypeScript types for MeditationContent, CourseContent, TeacherProfile, Collection, and AudioMetadata. - **Content hooks** — React data-fetching hooks for content queries with loading states, error handling, and local caching. Hooks include `useMeditation`, `useMeditationList`, `useCourse`, `useTeacher`, `useCollection`, `useContent`. - **Offline support** — Content hooks check the offline cache first, falling back to the network, enabling seamless transitions between online and offline. - **Content versioning** — Downloaded content carries a version, allowing the offline manager to detect when remote content has been updated and offer re-download. - **Search integration** — Content search hooks with debouncing, facet management, and result pagination. --- ## 27. App Configuration (`@tara/config`) `@tara/config` provides centralized configuration management for all Tara apps: - **Environment configuration** — Type-safe environment variable schemas for development, staging, and production environments. - **Feature flags client** — Client-side feature flag evaluation with local overrides for development, enabling developers to enable unreleased features during local development without affecting other users. - **Remote config integration** — Polling or push-based configuration updates from the server without requiring a new app release. - **App settings management** — Persistent user settings with default values, validation, and change notifications. --- ## 28. Database (`@tara/database`) `@tara/database` provides the Prisma ORM client, schema definitions, and TypeScript types for all Tara server-side data persistence. Note that this is a **separate** package from the `@tara/api` Drizzle schema — the two co-exist because `@tara/database` serves library tooling and rich domain modeling, while the API runtime uses Drizzle for its own query needs. - **Prisma schema** — Relational schema covering all Tara domain entities: users, profiles, subscriptions, meditations, courses, lessons, teachers, collections, sessions, streaks, achievements, milestones, downloads, favorites, and notification preferences. - **Type-safe client** — `taraDbClient` is a fully type-safe Prisma Client instance. Every query is type-checked at compile time: the TypeScript compiler rejects invalid field names, incorrect filter types, and missing required includes. - **Connection lifecycle** — `connect()`, `disconnect()`, and `healthCheck()` manage the database connection pool, ensuring clean startup and shutdown sequences and providing a health endpoint for liveness probes in Kubernetes or similar orchestration environments. - **Generated types** — Prisma generates TypeScript interfaces for every model and every Prisma input/output type (e.g., `MeditationCreateInput`, `UserWhereUniqueInput`). - **Schema migrations** — Database migrations are managed through Prisma Migrate, with migration history tracked in version control (`prisma/migrations/`) alongside the schema definition. > `@tara/database` is an independent Prisma package. The `@tara/api` runtime > does **not** use it — the API defines and migrates its own Drizzle schema > (`apps/tara/api/src/db/schema.ts`, migrations in `apps/tara/api/drizzle/`). > The two schemas are documented separately in `specifications.md`.