Rituals (Andromida)

Rituals is a paid, offline-first habit tracker built around customizable "ritual" arcs. It focuses on steady, daily check-ins with a calm visual language, zero paid backend dependencies, and optional iCloud sync for settings.

Overview

• Concept: Habits are grouped into ritual arcs (7-365 days) rather than endless streaks.
• Tech: SwiftUI + SwiftData, Clean Architecture layering, Bedrock design system.
• Data: Local persistence with SwiftData; settings sync via Bedrock CloudSyncManager (NSUbiquitousKeyValueStore).
• No paid APIs: No external services required.

Feature Set

Today Tab

• Focus ritual cards with progress rings
• Tap-to-complete habit check-ins with haptic/sound feedback
• Time-of-day filtering (morning, midday, afternoon, evening, night, anytime)
• Smart empty states (distinguishes "no rituals" from "no rituals for this time")
• Fresh install starts clean (no pre-seeded rituals)

Rituals Tab

• View all active rituals
• Create new rituals from scratch or browse preset library
• 14 categorized presets (Health, Productivity, Mindfulness, Self-Care)
• Full ritual management: edit, enable/disable, archive, delete
• Drag-to-reorder habits within rituals

Ritual Detail View

• Progress card with day count and completion summary
• Time remaining countdown ("12 days remaining")
• Ritual-specific streak tracking
• Milestone achievements (Day 1, Week 1, Halfway, Complete)
• Habit performance breakdown with completion rates
• Status badges (time of day, category, enabled/disabled)
• Action menu for edit, archive, and delete

Ritual Editor

• Custom ritual creation with title, theme, notes
• Icon picker with 50+ categorized SF Symbols and search
• Habit icon picker with 100+ icons organized by category
• Custom category input (beyond preset categories)
• Flexible duration: slider (7-365 days) + quick presets + custom input
• Time-of-day scheduling (morning, midday, afternoon, evening, night, anytime)
• Drag-to-reorder habits

History Tab

• Scrollable month calendar grid
• Daily progress rings with color coding (green=100%, accent=50%+, gray=<50%)
• Filter by ritual using horizontal pill picker
• "All" mode includes historical data from completed and archived arcs
• Tap any day for detail sheet showing:
  • Progress ring with percentage
  • Comparison to weekly average
  • Streak context (if part of a streak)
  • Motivational message
  • Grouped habit list by ritual

Insights Tab

• Tappable insight cards with full-screen detail sheets
• Active Rituals: Count with per-ritual breakdown
• Streak: Current and longest perfect-day streak tracking (100% completion days)
• Habits Today: Completed count with per-ritual breakdown
• Completion: Today's percentage with 7-day trend chart
• Days Active: Total active days with detailed breakdown (first check-in, most recent, per-ritual counts)
• 7-Day Avg: Weekly average completion percentage with trend chart
• Total Check-ins: All-time habit completions across all rituals
• Best Ritual: Highest-performing ritual by completion rate in the current arc
• Trend indicators (up/down/stable) with week-over-week comparison
• Contextual tips based on performance

Settings Tab

• Smart reminders based on ritual time-of-day (morning/midday/evening)
• Haptics and sound toggles (wired to habit check-ins)
• iCloud settings sync
• Debug tools: reset onboarding, app icon generation, branding preview

Widget Behavior Notes

• "Next ritual" messaging explicitly distinguishes later-today vs tomorrow scheduling.
• Timeline calculations use in-progress arc detection for the target date.

Onboarding

• Setup wizard on first launch (goal, time, ritual preview, first check-in)
• Ends with a quick orientation to Today, Rituals, and Insights
• Debug reset available in Settings

Branding & Launch

• Bedrock AppLaunchView with custom theme
• Native LaunchScreen.storyboard (no white flash)
• Dark theme enforced throughout
• Centralized branding config (colors, icons, launch)

Architecture

This project follows Clean Architecture and protocol-first design:

• Views: SwiftUI UI only, no business logic
• State: @Observable stores with app logic
• Services: Stateless logic and data seeding
• Models: SwiftData models and plain structs. The architecture is built around Ritual Arcs, allowing rituals to be renewed while preserving historical accuracy.
• Protocols: Abstractions for stores/services

Project Structure

Andromida/
├── Andromida/                      # App target
│   ├── App/
│   │   ├── Models/                  # SwiftData + DTOs
│   │   │   ├── Ritual.swift
│   │   │   ├── RitualArc.swift
│   │   │   ├── ArcHabit.swift
│   │   │   ├── HabitCompletion.swift
│   │   │   ├── InsightCard.swift
│   │   │   ├── Milestone.swift
│   │   │   ├── TrendDirection.swift
│   │   │   └── RitualPresets.swift
│   │   ├── Protocols/               # Interfaces for stores/services
│   │   │   ├── RitualStoreProviding.swift
│   │   │   ├── RitualSeedProviding.swift
│   │   │   └── InsightTipsProviding.swift
│   │   ├── Services/                # Stateless logic
│   │   │   └── RitualSeedService.swift
│   │   ├── State/                   # @Observable stores
│   │   │   ├── RitualStore.swift
│   │   │   ├── CategoryStore.swift
│   │   │   └── SettingsStore.swift
│   │   └── Views/                   # SwiftUI features + components
│   │       ├── Today/
│   │       ├── Rituals/
│   │       ├── History/
│   │       ├── Insights/
│   │       └── Settings/
│   ├── Shared/                      # Bedrock theme + branding config
│   └── Resources/                   # LaunchScreen.storyboard
├── AndromidaTests/                  # Unit tests
└── AndromidaUITests/                # UI tests

Key Files

• App entry & launch: Andromida/Andromida/AndromidaApp.swift
• Bedrock theme: Andromida/Andromida/Shared/Theme/RitualsTheme.swift
• Branding config: Andromida/Andromida/Shared/BrandingConfig.swift
• Launch screen: Andromida/Andromida/Resources/LaunchScreen.storyboard
• Ritual store: Andromida/Andromida/App/State/RitualStore.swift
• Settings store: Andromida/Andromida/App/State/SettingsStore.swift
• Settings UI: Andromida/Andromida/App/Views/Settings/SettingsView.swift

Data Model

• Ritual: Title, theme, notes, defaultDurationDays, timeOfDay, iconName, category, sortIndex, arcs (relationship)
• RitualArc: Start date, end date, arc number, isActive, habits (relationship)
• ArcHabit: Title, symbolName, goal, completedDayIDs, sortIndex
• Milestone: Day, title, symbolName, isAchieved
• Settings: Stored via Bedrock CloudSyncManager (NSUbiquitousKeyValueStore)

Bedrock Integration

• Theming: App-specific color providers + AppSurface, AppAccent, etc.
• Branding: AppLaunchView, AppIconConfig, LaunchScreenConfig
• Settings UI: SettingsCard owns row insets; use SettingsDivider between rows, SettingsCardRow for custom rows, and SettingsNavigationRow(backgroundColor: .clear) for in-card navigation
• Cloud Sync: iCloud sync for settings using CloudSyncManager
• Onboarding: Custom SetupWizardView flow (Sherpa integration pending)

Localization

String catalogs are used for English (en), Spanish (es-MX), and French (fr-CA):

• Andromida/Andromida/App/Localization/Localizable.xcstrings

Requirements

• iOS 18.6+
• Swift 5 (Bedrock requires Swift 6 in package; app builds under Swift 5 with modern concurrency)

Running

1. Open Andromida.xcodeproj in Xcode.
2. Build and run on iOS 18+ simulator or device.

Tests

• Unit tests in AndromidaTests/
• Run via Xcode Test navigator or:
  • xcodebuild test -scheme Andromida -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=26.2'
• XCTest runs disable SwiftData CloudKit mirroring in the host app to keep simulator tests deterministic.
• RitualStoreTests use a shared in-memory SwiftData container with per-test cleanup to avoid host-process container churn.
• AndromidaUITestsLaunchTests runs a single launch configuration to reduce flaky simulator timeouts.
• AndromidaUITests launch with UITEST_MODE=1, forcing in-memory SwiftData and optional launch-state overrides (UITEST_RESET_USER_DEFAULTS, UITEST_HAS_COMPLETED_SETUP_WIZARD) for deterministic UI runs.
• UI coverage includes stable onboarding-state transition validation and ritual creation from the Rituals tab.

Notes

• App is configured with a dark theme; the root view enforces .preferredColorScheme(.dark) to ensure semantic text legibility.
• Setup wizard and root shell animations respect the iOS Reduce Motion accessibility setting.
• The launch storyboard matches the branding primary color to avoid a white flash.
• iCloud sync configuration includes com.apple.developer.ubiquity-kvstore-identifier; enable remote-notification background mode via Xcode Capabilities when CloudKit push handling is needed.
• App icon generation is available in DEBUG builds from Settings.
• Fresh installs start with no rituals; users create their own from scratch or presets.
• A startup data-integrity migration normalizes arc date ranges, in-progress arc state, and sort indexes.
• Date-sensitive analytics in RitualStore are driven by an injectable time source for deterministic tests.

CloudKit Sync Verification

Use this checklist when validating SwiftData sync between iPhone and iPad:

1. Confirm both devices are signed in to the same Apple ID and running the same app flavor (Debug vs TestFlight/App Store).
2. On Device A, change ritual data (for example, toggle a habit completion).
3. Keep Device B open; verify the update appears without force-quitting.
4. If needed, background Device B and return to foreground once to trigger safety-net refresh.
5. In Xcode Console, filter for CloudKitSync to verify remote change logs from RitualStore.
6. In CloudKit Console, inspect container iCloud.com.mbrucedogs.Andromida in the private database and confirm recent record updates.

Important sync scope:

• Ritual/arcs/habits data syncs via SwiftData + CloudKit private database.
• Settings sync is separate and uses NSUbiquitousKeyValueStore (Bedrock CloudSyncManager).