Forgeb · Harmonize

You are what you repeatedly do.

Forge is an iOS habit tracker where your identity grows as a living organism — a breathing tree rendered entirely with custom Bézier curves in SwiftUI's Canvas. Each branch is a life domain. Each leaf is a habit you chose. Consistency makes limbs bloom and shimmer. Neglect makes them curl inward and rest — quiet, never punishing. The organism never judges. It waits.

---

What makes it different

Most habit apps	Forge
Scoreboards and streaks	A living organism that breathes
Red when you fail	Limbs sleep, not die
Generic encouragement	Coach grounded in your real analytics
Static UI	Shimmer, sway, particle motes, wake bloom
Fake motivation	Companion posture — it waits for you

---

The Organism

The whole app is one screen. No tab bar. The organism is the interface.

        ✦ ·  shimmer dot traveling
       /  \     along thriving limb
      ●    ●   ← domain buds
     /|    |\
    / |    | \
   /  |    |  \  ← habit sub-branches
  ·   |    |   ·
      │    │      ← trunk (Bézier)
      │    │
      ●────●      ← core (purple nucleus)

Bézier geometry — every limb is a cubic Bézier curve:

• ctrl1 lifts proportionally to 7-day consistency → thriving limbs reach upward
• ctrl2 for dormant limbs (vitality < 0.30) pulls inward → tip curls back toward trunk, reads as sleeping
• Limb length, thickness, and opacity all encode domain health simultaneously

Vitality → visual mapping

Vitality	State	Opacity	Effect
≥ 0.70	Thriving	0.82 – 1.0	Glow halo + shimmer dot travels the limb
0.30 – 0.70	Fading	0.38 – 0.82	Warm amber pulse ring appears
< 0.30	Dormant	0.16 – 0.38	18% shorter, curled inward, small closed bud
Rest day	Resting	0.42	Even, calm — no alarm, no urgency

Animation layers

Layer	Driver	Period
Breathing	withAnimation repeatForever	3.2 s
Sway	withAnimation repeatForever	5.1 s ±2.5 pt
Shimmer	TimelineView 15 fps	8 s cycle per limb
Particle motes	TimelineView 15 fps	~11 s loop, 5 motes
Wake bloom	One-shot on first layout	1.15 s easeOut
Growth tween	Animatable + spring	0.65 s
Touch ripple	withAnimation easeOut	0.55 s
Habit spark	withAnimation easeOut	0.52 s

Haptics

Moment	Generator	Style
Limb tap	UIImpactFeedbackGenerator	.soft
Habit logged	UIImpactFeedbackGenerator	.light
Score hits 100	UINotificationFeedbackGenerator	.success

---

Architecture

Forge/
├── App/
│   ├── ForgeApp.swift              # ModelContainer + environment injection
│   └── RootView.swift              # Onboarding gate → OrganismHomeView
│
├── Views/
│   ├── Onboarding/                 # 3-step builder: name → domains → weights
│   └── IdentityTab/                # Identity settings + Developer tools
│
├── Forms/Organism/
│   ├── OrganismHomeView.swift      # Full-screen flagship — all animation state lives here
│   ├── OrganismGeometry.swift      # Pure Bézier geometry builder (no SwiftUI)
│   └── QuickLogSheet.swift         # Focused micro-sheet for urgent domains
│
├── Health/
│   ├── HealthKitManager.swift      # HKHealthStore queries (steps, sleep, workouts, HR)
│   ├── LiveHealthProvider.swift    # Foreground-only refresh — works with free dev account
│   └── MockHealthProvider.swift    # Simulator fallback with seeded 30-day history
│
├── Pipeline/
│   ├── SignalNormalizer.swift      # Aggregates sensor + manual signals → 0–1 per domain
│   ├── LiveSensorDataSource.swift  # 30-day HKStatisticsCollectionQuery history
│   └── DataSource.swift            # Protocol + ActiveDataSource typealias
│
├── Coach/
│   ├── CoachProvider.swift         # Protocol + CoachMessage struct
│   ├── TemplateCoachProvider.swift # Free, always-on; splitmix64 day-stable picker
│   └── CoachProviderStubs.swift    # FoundationModel + Claude API stubs (ready to swap)
│
└── Analytics/
    ├── AnalyticsEngine.swift       # DomainTrend, BookProjection, IdentityTrend
    └── NudgeEngine.swift           # Priority-ranked nudge list

---

Coach system

The coach speaks from real computed analytics — never generic platitudes.

protocol CoachProvider: AnyObject {
    func dailyMessage(report: AnalyticsReport, nudges: [Nudge], isRestDay: Bool) -> CoachMessage?
}

Priority order for the daily message:

1. Biggest domain decline ≥ 15% → warn specifically
2. Biggest domain gain ≥ 10% → reinforce momentum
3. Book pace slip ≥ 5 days → concrete deadline risk
4. Identity trend ±5% week-over-week → context

Templates use a splitmix64-style day-stable hash: same message tone all day, different phrasing each day. Swap the ActiveCoachProvider typealias to upgrade to on-device Foundation Models or Claude API — stubs are already in place.

---

HealthKit integration

Foreground-read only. No background delivery — works with a free Apple Developer account.

Signal	Query	Cadence
Steps	HKStatisticsCollectionQuery daily buckets	Scene active
Workouts	HKSampleQuery sum per day	Scene active
Sleep	HKSampleQuery with asleep-value filter	Scene active
Heart rate	HKSampleQuery latest	Scene active

On simulator → MockDataSource fallback automatically.

---

Getting started

Requirements: Xcode 15.2+, iOS 17+ simulator or device, free Apple Developer account.

git clone https://github.com/sanjeevi0078/Forgeb.git
cd Forgeb
open Forge.xcodeproj

If you add or remove Swift files, regenerate the project:

xcodegen generate --spec project.yml

Select the Forge scheme → your device or simulator → ▶ Run.

First launch: A 3-step onboarding flow collects your identity name, domains, and weights — no fake data auto-loaded. Grant HealthKit permissions and real signal history populates immediately.

Developer tools: Identity tab → scroll to bottom → Load Demo Data or Clear All Data.

---

Roadmap

• FoundationModelCoachProvider — on-device LLM coaching (iOS 18+)
• ClaudeAPICoachProvider — expressive coaching via Anthropic API
• watchOS complication — live score + top nudge on watch face
• Home Screen widget — organism thumbnail + today's score
• Background delivery — auto-log workouts via HK observer (paid team required)
• Social snapshot — share a day-snapshot of your organism

---

Phases shipped

Phase	Theme
1 – 4	Canvas renderer, Bézier geometry, SwiftData schema, analytics engine
Upgrade A + B	Ghost projections (trend forecasts), urgency rings, graph view
Make It True	Real onboarding, live HealthKit, Coach protocol, rest-day toggle
Phase 7	Companion posture — dormant state, wake bloom, idle life, completion sparks

---

Built with SwiftUI · SwiftData · HealthKit · Canvas