Andromida/README.md

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: SettingsToggle, SettingsSlider, SettingsSegmentedPicker, SettingsCard
• 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.