Andromida (Rituals) - Product Requirements Document
Version: 1.0
Last Updated: February 2026
Status: Active Development
1. Overview
1.1 Product Vision
Andromida (branded as "Rituals") is a premium, offline-first habit tracker built around customizable "ritual arcs" rather than endless streaks. The app focuses on steady, daily check-ins with a calm visual language, zero paid backend dependencies, and optional iCloud sync.
1.2 Target Audience
- Health-conscious individuals seeking structured daily routines
- Productivity enthusiasts who prefer time-bound goals over infinite streaks
- Users who value privacy and offline-first functionality
- Apple ecosystem users who want seamless iCloud integration
1.3 Key Differentiators
- Arc-Based Approach: Habits are grouped into ritual arcs (7-365 days) with defined start and end dates, allowing for natural cycles of focus and renewal
- No Paid APIs: Entirely self-contained with no external service dependencies
- Offline-First: Full functionality without network connectivity
- Privacy-Focused: All data stored locally with optional iCloud sync
2. User Goals
| Goal |
Description |
| Build Habits |
Establish and maintain daily rituals through consistent check-ins |
| Track Progress |
Visualize completion rates, streaks, and historical performance |
| Stay Motivated |
Receive milestone achievements and contextual insights |
| Customize Experience |
Create personalized rituals with flexible scheduling |
| Maintain Privacy |
Keep personal data local with optional cloud backup |
3. Functional Requirements
3.1 Today Tab
The primary daily interaction surface for habit check-ins.
| Requirement |
Description |
| FR-TODAY-01 |
Display focus ritual cards with circular progress rings showing completion percentage |
| FR-TODAY-02 |
Enable tap-to-complete habit check-ins with haptic and sound feedback |
| FR-TODAY-03 |
Filter rituals by time of day (morning, midday, afternoon, evening, night, anytime) |
| FR-TODAY-04 |
Show smart empty states distinguishing "no rituals" from "no rituals for this time" |
| FR-TODAY-05 |
Display arc renewal prompts when ritual arcs complete |
| FR-TODAY-06 |
Support adaptive 2-column grid layout on iPad and landscape orientations |
| FR-TODAY-07 |
Fresh install starts clean with no pre-seeded rituals |
3.2 Rituals Tab
Ritual creation and management interface.
| Requirement |
Description |
| FR-RITUALS-01 |
Display all active rituals with card-based UI |
| FR-RITUALS-02 |
Create rituals from scratch or browse preset library |
| FR-RITUALS-03 |
Provide 14 categorized presets across 4 categories (Health, Productivity, Mindfulness, Self-Care) |
| FR-RITUALS-04 |
Support full ritual lifecycle: create, edit, delete |
| FR-RITUALS-05 |
Enable drag-to-reorder habits within rituals |
3.2.1 Ritual Detail View
| Requirement |
Description |
| FR-DETAIL-01 |
Show progress card with day count and completion summary |
| FR-DETAIL-02 |
Display time remaining countdown (e.g., "12 days remaining") |
| FR-DETAIL-03 |
Track ritual-specific streaks |
| FR-DETAIL-04 |
Show milestone achievements (First Day, One Week, Halfway, Three Weeks, Complete) |
| FR-DETAIL-05 |
Display habit performance breakdown with per-habit completion rates |
| FR-DETAIL-06 |
Show status badges for time of day and category |
| FR-DETAIL-07 |
Provide action menu for edit, end arc/start new arc, and delete |
3.2.2 Ritual Editor
| Requirement |
Description |
| FR-EDITOR-01 |
Support custom ritual creation with title, theme, and notes |
| FR-EDITOR-02 |
Provide icon picker with 50+ categorized SF Symbols and search |
| FR-EDITOR-03 |
Provide habit icon picker with 100+ icons organized by category |
| FR-EDITOR-04 |
Allow custom category input beyond preset categories |
| FR-EDITOR-05 |
Support flexible duration: slider (7-365 days), quick presets, and custom input |
| FR-EDITOR-06 |
Enable time-of-day scheduling (morning, midday, afternoon, evening, night, anytime) |
| FR-EDITOR-07 |
Support drag-to-reorder habits |
3.2.3 Arc Renewal System
| Requirement |
Description |
| FR-RENEWAL-01 |
Allow rituals to be renewed when arcs complete |
| FR-RENEWAL-02 |
Preserve historical data (old arcs remain frozen and accessible) |
| FR-RENEWAL-03 |
Copy habits from previous arc to new arc during renewal |
| FR-RENEWAL-04 |
Display renewal prompts automatically when arcs complete |
3.3 History Tab
Historical view of past completions and performance.
| Requirement |
Description |
| FR-HISTORY-01 |
Display scrollable month calendar grid (expandable to 12 months) |
| FR-HISTORY-02 |
Show daily progress rings with color coding (green=100%, accent=50%+, gray=<50%) |
| FR-HISTORY-03 |
Enable filtering by ritual using horizontal pill picker |
| FR-HISTORY-04 |
Support tap on any day to open detail sheet |
| FR-HISTORY-05 |
Detail sheet shows: progress ring with percentage, comparison to weekly average, streak context, motivational message, grouped habit list by ritual |
| FR-HISTORY-06 |
Support adaptive 2-column grid layout on iPad and landscape |
| FR-HISTORY-07 |
In "All" filter mode, calculations must include completed and archived arcs (not only currently active arcs) |
3.4 Insights Tab
Analytics and trend visualization.
| Requirement |
Description |
| FR-INSIGHTS-01 |
Display 8 tappable insight cards with full-screen detail sheets |
| FR-INSIGHTS-02 |
Active Rituals: Count with per-ritual breakdown |
| FR-INSIGHTS-03 |
Streak: Current and longest perfect-day streak tracking (100% completion days) |
| FR-INSIGHTS-04 |
Habits Today: Completed count with per-ritual breakdown |
| FR-INSIGHTS-05 |
Completion: Today's percentage with 7-day trend chart |
| FR-INSIGHTS-06 |
Days Active: Total active days with detailed breakdown |
| FR-INSIGHTS-07 |
7-Day Avg: Weekly average completion percentage with trend chart |
| FR-INSIGHTS-08 |
Total Check-ins: All-time habit completions across all rituals |
| FR-INSIGHTS-09 |
Best Ritual: Highest-performing ritual by completion rate |
| FR-INSIGHTS-10 |
Show trend indicators (up/down/stable) with week-over-week comparison |
| FR-INSIGHTS-11 |
Display contextual tips based on performance |
| FR-INSIGHTS-12 |
Enable drag-and-drop card reordering in edit mode |
| FR-INSIGHTS-13 |
Show sparkline charts for trend visualization |
3.5 Settings Tab
Application configuration and preferences.
| Requirement |
Description |
| FR-SETTINGS-01 |
Configure smart reminders based on ritual time slots (morning 7:00 AM, midday 12:00 PM, evening 6:00 PM) |
| FR-SETTINGS-02 |
Toggle haptic feedback for habit check-ins |
| FR-SETTINGS-03 |
Toggle sound feedback for habit check-ins |
| FR-SETTINGS-04 |
Select theme (light, dark, system) |
| FR-SETTINGS-05 |
Enable/disable iCloud settings sync |
| FR-SETTINGS-06 |
Manage categories (create, edit, delete user categories) |
| FR-SETTINGS-07 |
Provide debug tools in DEBUG builds: reset onboarding, app icon generation, branding preview, preload demo data, clear all completions, simulate arc completion |
3.6 Widget
Home screen widget for at-a-glance progress.
| Requirement |
Description |
| FR-WIDGET-01 |
Support small, medium, and large widget sizes |
| FR-WIDGET-02 |
Display today's completion rate |
| FR-WIDGET-03 |
Show current streak |
| FR-WIDGET-04 |
List next habits (up to 4) |
| FR-WIDGET-05 |
Indicate current time of day |
| FR-WIDGET-06 |
Show next ritual information |
| FR-WIDGET-07 |
Support App Intents for widget configuration |
| FR-WIDGET-08 |
Update widget content every 15 minutes |
| FR-WIDGET-09 |
Use App Group shared container for SwiftData access |
| FR-WIDGET-10 |
"Next ritual" label must correctly distinguish "later today" vs "tomorrow" based on target timeline date |
3.7 Onboarding
First-launch setup wizard.
| Requirement |
Description |
| FR-ONBOARD-01 |
Welcome: Introduction to the app |
| FR-ONBOARD-02 |
Goal Selection: Choose from predefined goals |
| FR-ONBOARD-03 |
Time Selection: Select preferred ritual times (morning/evening/both) |
| FR-ONBOARD-04 |
Ritual Preview: Preview and optionally create preset rituals |
| FR-ONBOARD-05 |
First Check-In: Complete first habit check-in |
| FR-ONBOARD-06 |
Notifications: Set up reminder permissions |
| FR-ONBOARD-07 |
What's Next: Orientation to Today, Rituals, and Insights tabs |
| FR-ONBOARD-08 |
Allow onboarding reset from Settings (DEBUG builds) |
3.8 Deep Linking
URL scheme support for navigation.
| Requirement |
Description |
| FR-DEEPLINK-01 |
Support andromida://today to navigate to Today tab |
| FR-DEEPLINK-02 |
Support andromida://rituals to navigate to Rituals tab |
| FR-DEEPLINK-03 |
Support andromida://insights to navigate to Insights tab |
| FR-DEEPLINK-04 |
Support andromida://history to navigate to History tab |
4. Non-Functional Requirements
4.1 Performance
| Requirement |
Description |
| NFR-PERF-01 |
Analytics calculations must use caching to avoid recalculation on each access |
| NFR-PERF-02 |
History view must cache progress data for smooth scrolling |
| NFR-PERF-03 |
App launch must complete without white flash using native LaunchScreen.storyboard |
| NFR-PERF-04 |
Widget updates must complete within WidgetKit timeline constraints |
4.2 Accessibility
| Requirement |
Description |
| NFR-A11Y-01 |
Support Dynamic Type for all text elements |
| NFR-A11Y-02 |
Provide VoiceOver accessibility labels and hints |
| NFR-A11Y-03 |
Ensure sufficient color contrast ratios |
| NFR-A11Y-04 |
Support reduced motion preferences |
Implementation note: Onboarding flows and root-level shell transitions should avoid motion-heavy animations when iOS Reduce Motion is enabled.
4.3 Localization
| Requirement |
Description |
| NFR-L10N-01 |
All user-facing strings must be localized using String Catalogs |
| NFR-L10N-02 |
Support English (en), Spanish (es-MX), and French (fr-CA) |
| NFR-L10N-03 |
Use locale-appropriate date and number formatting |
4.4 Privacy & Security
| Requirement |
Description |
| NFR-PRIV-01 |
All user data must be stored locally on device |
| NFR-PRIV-02 |
iCloud sync must be opt-in and clearly disclosed |
| NFR-PRIV-03 |
No user data may be transmitted to external services |
| NFR-PRIV-04 |
App must function fully offline |
5. Technical Requirements
5.1 Platform
| Requirement |
Description |
| TR-PLAT-01 |
iOS 18.6+ minimum deployment target |
| TR-PLAT-02 |
Swift 5 with modern concurrency (async/await, actors) |
| TR-PLAT-03 |
SwiftUI for all user interface |
| TR-PLAT-04 |
SwiftData for persistence with @Observable pattern |
| TR-PLAT-05 |
WidgetKit for Home screen widgets |
5.2 Architecture
| Requirement |
Description |
| TR-ARCH-01 |
Follow Clean Architecture with separation: Views, State, Services, Models |
| TR-ARCH-02 |
Use protocol-oriented design for testability |
| TR-ARCH-03 |
Implement @Observable stores (not ObservableObject) |
| TR-ARCH-04 |
Use dependency injection via protocols |
5.3 Data Persistence
| Requirement |
Description |
| TR-DATA-01 |
Use SwiftData with optional CloudKit sync for ritual data |
| TR-DATA-02 |
Use NSUbiquitousKeyValueStore (via Bedrock CloudSyncManager) for settings sync |
| TR-DATA-03 |
Use UserDefaults for user-created categories and preferences |
| TR-DATA-04 |
Use App Group shared container for widget data access |
| TR-DATA-05 |
Run a startup integrity migration to normalize arc date ranges, in-progress arc state, and persisted sort indexes |
| TR-DATA-06 |
Enable iCloud runtime compatibility by shipping com.apple.developer.ubiquity-kvstore-identifier and remote-notification background mode when CloudKit/KVS sync is enabled |
5.4 Third-Party Dependencies
| Requirement |
Description |
| TR-DEPS-01 |
Bedrock design system package (internal) for theming, branding, and common UI components |
| TR-DEPS-02 |
No external third-party frameworks without explicit approval |
6. Data Model
6.1 Core Entities
Ritual
Primary entity representing a habit collection.
| Property |
Type |
Description |
| id |
UUID |
Unique identifier |
| title |
String |
Ritual name |
| theme |
String |
Visual theme identifier |
| notes |
String? |
Optional user notes |
| defaultDurationDays |
Int |
Default arc duration (7-365) |
| timeOfDay |
TimeOfDay |
Scheduling preference |
| iconName |
String |
SF Symbol name |
| category |
String |
Category identifier |
| sortIndex |
Int |
Display order |
| arcs |
[RitualArc] |
Related arcs (one-to-many, cascade delete) |
Computed Properties: currentArc, hasActiveArc, sortedArcs, latestArc, completedArcCount, habits
RitualArc
Time-bound period for a ritual.
| Property |
Type |
Description |
| id |
UUID |
Unique identifier |
| startDate |
Date |
Arc start date |
| endDate |
Date |
Arc end date |
| arcNumber |
Int |
Sequential arc number |
| isActive |
Bool |
Whether arc is currently active |
| habits |
[ArcHabit] |
Related habits (one-to-many, cascade delete) |
| ritual |
Ritual |
Parent ritual (inverse relationship) |
Computed Properties: durationDays, Methods: contains(date:), dayIndex(for:), createRenewalArc()
ArcHabit
Individual habit within an arc.
| Property |
Type |
Description |
| id |
UUID |
Unique identifier |
| title |
String |
Habit name |
| symbolName |
String |
SF Symbol name |
| goal |
Int |
Target completions |
| completedDayIDs |
[String] |
Array of date identifiers |
| sortIndex |
Int |
Display order |
| arc |
RitualArc |
Parent arc (inverse relationship) |
Methods: copyForNewArc()
6.2 Supporting Models
Category
User-defined or preset category.
| Property |
Type |
Description |
| id |
String |
Unique identifier |
| name |
String |
Display name |
| colorName |
String |
Color identifier (13 available colors) |
| isPreset |
Bool |
Whether system-defined |
Preset Categories: Health, Productivity, Mindfulness, Self-Care
TimeOfDay
Scheduling enumeration.
| Case |
Time Range |
| morning |
Before 11:00 AM |
| midday |
11:00 AM - 2:00 PM |
| afternoon |
2:00 PM - 5:00 PM |
| evening |
5:00 PM - 9:00 PM |
| night |
After 9:00 PM |
| anytime |
Flexible timing |
InsightCard
Analytics display card.
| Type |
Description |
| Active |
Active ritual count with breakdown |
| Streak |
Current and longest perfect-day streak (100% completion days) |
| HabitsToday |
Today's completed habits |
| Completion |
Today's percentage with trend |
| DaysActive |
Total active days |
| SevenDayAvg |
Weekly average percentage |
| TotalCheckins |
All-time completions |
| BestRitual |
Top-performing ritual |
Milestone
Achievement markers.
| Milestone |
Description |
| First Day |
First day completed (day 1) |
| One Week |
First week completed (day 7) |
| Halfway |
50% of arc completed (dynamic based on arc duration) |
| Three Weeks |
21 days completed |
| Complete |
Full arc completed |
6.3 Entity Relationships
Ritual (1) ──────< RitualArc (many)
│
└────< ArcHabit (many)
- Ritual → RitualArc: One-to-many with cascade delete
- RitualArc → ArcHabit: One-to-many with cascade delete
- RitualArc → Ritual: Inverse relationship
7. Design System
7.1 Theme Integration
The app uses the Bedrock design system with a custom RitualsTheme providing:
- Surface Colors: primary, secondary, tertiary, card backgrounds
- Text Colors: primary, secondary, tertiary, disabled, inverse
- Accent Colors: primary, light, dark, secondary
- Status Colors: success, warning, error, info
- Border Colors: subtle, standard, emphasized, selected
- Interactive Colors: selected, hover, pressed, focus
7.2 Color Assets
| Asset |
Purpose |
| Background, BackgroundAlt, BackgroundTertiary |
Surface backgrounds |
| Card |
Card backgrounds |
| Divider |
Separator lines |
| Accent, AccentLight, AccentDark, AccentSecondary, AccentSoft |
Brand and interactive colors |
| TextPrimary, TextSecondary, TextTertiary, TextDisabled |
Typography |
| Success, Warning, Error, Info |
Status indicators |
7.3 Branding
| Element |
Specification |
| App Name |
Andromida (displayed as "Rituals") |
| Bundle ID |
com.mbrucedogs.Andromida |
| App Group |
group.com.mbrucedogs.Andromida |
| CloudKit Container |
iCloud.com.mbrucedogs.Andromida |
7.4 Adaptive Layout
| Requirement |
Description |
| Max content width constraints for iPad and landscape |
|
| 2-column grid layouts where appropriate |
|
| Responsive spacing and typography |
|
8. Preset Library
8.1 Health (3 presets)
- Morning Hydration
- Midday Movement
- Sleep Preparation
8.2 Productivity (3 presets)
- Deep Work Prep
- End-of-Day Review
- Focus Reset
8.3 Mindfulness (4 presets)
- Morning Meditation
- Gratitude Practice
- Breathwork
- Evening Reflection
8.4 Self-Care (4 presets)
- Morning Skincare
- Digital Detox
- Evening Wind-Down
- Weekly Reset
9. TODO
Remaining features and enhancements to be implemented.
9.1 HealthKit Integration
Sync habit completions to Apple Health for relevant habit types.
| Item |
Description |
| Water tracking |
Sync hydration habits to HealthKit water intake |
| Mindfulness |
Sync meditation/breathwork habits to HealthKit mindful minutes |
| Exercise |
Sync movement habits to HealthKit activity |
| Implementation plan |
See .cursor/plans/healthkit_integration_plan_ce4f933c.plan.md |
9.2 Watch App
Companion watchOS app for quick habit check-ins.
| Item |
Description |
| Quick check-ins |
Allow habit completion directly from Apple Watch |
| Complications |
Show today's progress on watch face |
| Sync |
Real-time sync with iOS app via WatchConnectivity |
9.3 Export/Import
Backup and restore ritual data.
| Item |
Description |
| Export format |
JSON or other portable format for ritual data |
| Import |
Restore rituals from backup file |
| Share |
Share ritual templates with others |
9.4 Statistics
Extended analytics with longer time horizons.
| Item |
Description |
| Monthly summary |
Aggregate completion stats by month |
| Yearly summary |
Year-in-review style analytics |
| Trend analysis |
Long-term habit formation insights |
10. Project Structure
Andromida/
├── Andromida/ # App target
│ ├── App/
│ │ ├── Localization/ # String catalogs
│ │ ├── Models/ # SwiftData + DTOs
│ │ │ ├── Ritual.swift
│ │ │ ├── RitualArc.swift
│ │ │ ├── ArcHabit.swift
│ │ │ ├── Category.swift
│ │ │ ├── InsightCard.swift
│ │ │ ├── Milestone.swift
│ │ │ ├── OnboardingGoal.swift
│ │ │ └── RitualPresets.swift
│ │ ├── Protocols/ # Interfaces for stores/services
│ │ │ ├── RitualStoreProviding.swift
│ │ │ ├── RitualSeedProviding.swift
│ │ │ └── InsightTipsProviding.swift
│ │ ├── Services/ # Stateless logic
│ │ │ ├── ReminderScheduler.swift
│ │ │ └── RitualSeedService.swift
│ │ ├── State/ # @Observable stores
│ │ │ ├── RitualStore.swift
│ │ │ ├── CategoryStore.swift
│ │ │ └── SettingsStore.swift
│ │ └── Views/ # SwiftUI features
│ │ ├── Today/
│ │ ├── Rituals/
│ │ ├── History/
│ │ ├── Insights/
│ │ ├── Settings/
│ │ └── Onboarding/
│ ├── Shared/ # Theme + branding + analytics
│ │ ├── Configuration/ # xcconfig files
│ │ ├── Services/ # RitualAnalytics
│ │ └── Theme/ # RitualsTheme
│ └── Resources/ # LaunchScreen.storyboard
├── AndromidaWidget/ # Widget extension
│ ├── Intents/ # App Intents
│ ├── Models/ # Widget-specific models
│ ├── Providers/ # Timeline provider
│ └── Views/ # Widget views
├── AndromidaTests/ # Unit tests
├── AndromidaUITests/ # UI tests
└── Bedrock/ # Shared design system package
11. Key Files Reference
| File |
Purpose |
Andromida/AndromidaApp.swift |
App entry point |
Andromida/Shared/Theme/RitualsTheme.swift |
Bedrock theme configuration |
Andromida/Shared/BrandingConfig.swift |
Branding constants |
Andromida/Shared/Configuration/Base.xcconfig |
Build configuration source of truth |
Andromida/Resources/LaunchScreen.storyboard |
Native launch screen |
Andromida/App/State/RitualStore.swift |
Primary data store |
Andromida/App/State/SettingsStore.swift |
Settings with cloud sync |
Andromida/App/State/CategoryStore.swift |
Category management |
Andromida/App/Services/ReminderScheduler.swift |
Notification scheduling |
AndromidaWidget/AndromidaWidget.swift |
Widget entry point |
12. Testing Requirements
| Requirement |
Description |
Unit tests in AndromidaTests/ covering store logic and analytics |
|
UI tests in AndromidaUITests/ for critical user flows |
|
| Unit-test harness should use deterministic in-memory SwiftData setup to prevent host-app test instability |
|
UI-test harness should run app launches with deterministic flags (UITEST_MODE, optional reset/onboarding overrides) and in-memory SwiftData |
|
| UI launch coverage should prioritize stable smoke validation over exhaustive simulator configuration matrices |
|
| UI coverage should include onboarding state transition validation and ritual creation flow from the Rituals tab |
|
Test command: xcodebuild test -scheme Andromida -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=26.2' |
|
Revision History
| Version |
Date |
Description |
| 1.0 |
February 2026 |
Initial PRD based on implemented features |
| 1.1 |
February 2026 |
Fixed time-of-day refresh bug in Today view and Widget; added debug time simulation |
| 1.2 |
February 2026 |
Added deterministic UI-test launch harness and expanded critical UI flow coverage |
