Archery Apprentice Documentation

Phase 3B: iOS Navigation Foundation & Auth Deferral

8 min read

Phase 3B: iOS Navigation Foundation & Auth Deferral

Date: 2025-11-20 Status: Complete (pivoted from original scope) Week: 29

Overview

Phase 3B was originally scoped as “Google Sign-In implementation” building on Phase 3A’s shared authentication foundation. However, during implementation, critical infrastructure gaps were discovered that made authentication implementation premature.

The session pivoted to:

  • Implement proper iOS tab navigation architecture
  • Defer authentication to Phase 5
  • Reorder iOS phases to prioritize features with proven KMP code

Result: iOS app now has professional navigation foundation, ready for Phase 2 feature implementation.

What Was Originally Planned

Original Phase 3B Scope

Goal: Implement Google Sign-In on iOS

Planned Tasks:

  1. Wire up shared FirebaseAuthRepository to iOS
  2. Implement Google Sign-In UI flow
  3. Handle auth state in SwiftUI
  4. Test sign-in/sign-out flows

Expected Outcome: Working Google Sign-In on iOS using shared KMP auth logic

Estimated Effort: 1 week

What Was Discovered

Infrastructure Gaps

During implementation, several critical issues were identified:

1. Missing Kotlin iosMain Dependency Injection

Problem:

// This doesn't exist yet:
// iosMain/.../IosDependencies.kt
 
// Swift cannot do:
// let authRepo = IosDependencies.shared.authRepository

Impact:

  • Cannot instantiate FirebaseAuthRepository from Swift
  • No bridge between KMP services and iOS app
  • Blocks all shared code consumption

2. GitLive Firebase KMP Not Configured for iOS

Problem:

  • Library added to dependencies but not properly configured
  • No Swift-Kotlin bridging for Firebase types
  • Auth state flows not exposed

Impact:

  • Shared auth logic inaccessible from iOS
  • Would require duplicating auth code in Swift (defeats KMP purpose)

3. KMP-NativeCoroutines Not Set Up

Problem:

  • Kotlin Flow types cannot be consumed in Swift as async sequences
  • No coroutine bridging configured
  • Auth state updates blocked

Impact:

  • Real-time auth state changes unusable from iOS
  • Async patterns don’t bridge properly

Root Cause

Core Issue: Phase 1 infrastructure was Android-first, iOS KMP bridge layer never established.

Should Have Existed: Basic iOS DI setup and KMP bridging should have been part of Phase 1.

The Pivot Decision

Decision Point

When infrastructure gaps were discovered, two options existed:

Option A: Stop and Build Infrastructure First

  • Spend 1-2 weeks building iosMain DI
  • Configure GitLive Firebase + KMP-NativeCoroutines
  • Then implement Google Sign-In
  • Problem: Delays all feature work by 2-3 weeks

Option B: Defer Auth, Ship Features First

  • Reorder phases to prioritize proven KMP features
  • Build navigation foundation for iOS app
  • Come back to auth in Phase 5
  • Benefit: Ship user value immediately, infrastructure when needed

Decision: Option B - Defer Auth to Phase 5

Rationale:

  1. Authentication is not required for core features (rounds, equipment, tournaments)
  2. Proven KMP code exists for rounds/equipment/tournaments (90-95% shared)
  3. Can ship features to users immediately
  4. Auth infrastructure can be built when not blocking features

Approved By: User (project owner)

What Phase 3B Delivered

iOS Tab Navigation Architecture

Phase 3B pivoted to implementing professional iOS navigation foundation:

Implementation

Pattern: Standard iOS bottom tab bar navigation Entry Point: MainTabView.swift Tabs: 4 main sections

TabView {
    RoundsView()
        .tabItem {
            Label("Rounds", systemImage: "target")
        }
 
    EquipmentView()
        .tabItem {
            Label("Equipment", systemImage: "figure.archery")
        }
 
    TournamentsView()
        .tabItem {
            Label("Tournaments", systemImage: "trophy")
        }
 
    SettingsView()
        .tabItem {
            Label("Settings", systemImage: "gear")
        }
}

Tab Details

Tab 1: Rounds (Phase 2 Target)

  • Professional “Coming Soon” placeholder
  • Target: Phase 2 implementation (next)
  • Shared code: 90-95% KMP

Tab 2: Equipment (Phase 3 Target)

  • Professional “Coming Soon” placeholder
  • Target: Phase 3 implementation
  • Shared code: 90%+ KMP

Tab 3: Tournaments

  • ✅ Already working (from original iOS spike)
  • Proof point: KMP integration successful
  • Full tournament list and scoring UI

Tab 4: Settings

  • Sign-in UI shell (buttons non-functional)
  • Will wire up in Phase 5
  • Access to app settings and authentication

Benefits Delivered

User Experience:

  • Professional, polished navigation
  • Clear feature roadmap visibility
  • No broken or half-working features
  • Standard iOS patterns (familiar)

Development:

  • Clean foundation for feature additions
  • Easy to swap placeholders for real features
  • Auth accessible but not blocking
  • Simplified app architecture

Technical:

  • Single app entry point
  • iOS-standard navigation
  • No complex routing
  • Ready for Phase 2 features

iOS Plan Reordering

Why Reorder?

Problem: Authentication blocked feature development due to infrastructure gaps.

Solution: Reorder phases to prioritize features with proven KMP code, defer infrastructure-heavy work.

Previous Phase Order

  1. Phase 1: Infrastructure ✅
  2. Phase 2: Authentication & Settings ← BLOCKED
  3. Phase 3: Round Scoring
  4. Phase 4: Equipment
  5. Phase 5: Analytics & Tournaments
  6. Phase 6: Polish & Release

New Phase Order (2025-11-20)

  1. Phase 1: Infrastructure ✅
  2. Phase 2: Round Scoring MVP ← NEXT (90-95% shared KMP)
  3. Phase 3: Equipment Management (90%+ shared KMP)
  4. Phase 4: Tournaments & Analytics (85-90% shared KMP)
  5. Phase 5: Authentication & Settings ← MOVED (complex infrastructure)
  6. Phase 6: Polish & Release

Strategic Benefits

Faster User Value:

  • Ship round scoring immediately (high-value feature)
  • Equipment and tournaments follow quickly
  • Users get working app sooner

Leverage Proven Code:

  • Rounds: Existing KMP code, Android proven
  • Equipment: Existing KMP code, Android proven
  • Tournaments: Already working on iOS

Reduced Risk:

  • Known patterns
  • Proven implementations
  • Minimal iOS-specific work

Flexible Auth:

  • Not required for core features
  • Can be optional in MVP
  • Add in later update

Technical Details

Code Structure

iosApp/ArcheryApprentice/
├── ArcheryApprentice/
│   ├── MainTabView.swift          ← New entry point
│   ├── Screens/
│   │   ├── RoundsView.swift       ← Phase 2 placeholder
│   │   ├── EquipmentView.swift    ← Phase 3 placeholder
│   │   ├── TournamentsView.swift  ← Working ✅
│   │   └── SettingsView.swift     ← Sign-in shell
│   └── SignIn/
│       └── SignInView.swift       ← UI only (Phase 5)

App Launch Flow

Before Phase 3B:

App → ContentView → ?

After Phase 3B:

App → MainTabView → [Rounds|Equipment|Tournaments|Settings]

Benefits:

  • Single entry point
  • Clear navigation hierarchy
  • Easy to reason about
  • Standard iOS pattern

What’s Deferred to Phase 5

The following work is explicitly moved to Phase 5:

Kotlin iosMain Infrastructure (1 week)

Tasks:

  • Create IosDependencies singleton
  • Set up dependency injection module
  • Wire up KMP services for Swift
  • Create proper bridging layer

GitLive Firebase KMP Integration (3-4 days)

Tasks:

  • Configure GitLive Firebase for iOS
  • Expose Firebase services to Swift
  • Set up auth state flow bridging
  • Test end-to-end auth flows

KMP-NativeCoroutines Setup (2-3 days)

Tasks:

  • Configure compiler plugin
  • Add @NativeCoroutines annotations
  • Test Swift async sequence consumption
  • Verify coroutine scope bridging

Real Authentication Implementation (1 week)

Tasks:

  • Wire up real FirebaseAuthRepository
  • Implement Google Sign-In flow
  • Implement Apple Sign-In flow
  • Add auth state persistence
  • Handle sign-out

Total Phase 5 Effort: ~2 weeks (as originally estimated)

Lessons Learned

1. Infrastructure Validation Needs Platform Parity

Problem: “Phase 1 complete” didn’t validate iOS bridge layer.

Lesson: Infrastructure phases need platform parity checks:

  • ✅ Does it build?
  • ✅ Does it run?
  • ❌ Can it access shared code? ← Should have validated

Future: Add platform parity to Phase 1 acceptance criteria.

2. Break Complex Phases into Substeps

Problem: “Phase 3B: Google Sign-In” hid infrastructure prerequisite.

Better Breakdown:

  • Phase 3B-1: Kotlin iosMain DI infrastructure
  • Phase 3B-2: iOS UI integration

Future: Break phases into infrastructure + implementation substeps.

3. Match Agent Workflow to Feedback Loops

Problem: Multi-agent handoff added friction when real-time Xcode feedback needed.

Lesson:

  • Android: Agent can test → Agent-led OK ✅
  • iOS: Requires Xcode → Direct orchestrator-user better ✅

Future: Assign agents based on feedback loop requirements.

4. Plan Changes are Engineering Intelligence

Problem: Viewing plan changes as “failure.”

Lesson: Reordering phases based on discovered blockers is smart engineering:

  • Maximizes delivered value
  • Reduces risk
  • Improves efficiency

Future: Embrace plan changes as project intelligence.

Success Metrics

Phase 3B Delivered (Achieved)

✅ iOS app builds and runs ✅ Tab navigation functional ✅ Sign-in UI displays (non-functional buttons) ✅ Tournaments feature still works ✅ Professional placeholders for future phases

Phase 5 Targets (Future)

⏳ Kotlin iosMain DI infrastructure working ⏳ GitLive Firebase KMP wired for iOS ⏳ KMP-NativeCoroutines configured ⏳ Google Sign-In working end-to-end ⏳ Apple Sign-In working end-to-end ⏳ Auth state persistence implemented

Internal Sessions

iOS Guides

GitHub References

Next Steps

Immediate: Phase 2 - Round Scoring MVP

Target: 4 weeks Shared Code: 90-95% KMP Focus: Get core round scoring working on iOS

Tasks:

  1. Wire up existing round repository to iOS
  2. Implement round list view
  3. Implement scoring interface
  4. Test end-to-end round creation and scoring

Blocker Status: ✅ None - shared code proven on Android

Future: Phase 5 - Authentication

Target: ~12-16 weeks from now (after Phases 2-4) Effort: 2 weeks Focus: Build iOS infrastructure, wire up authentication

Prerequisite: Phases 2-4 features shipped to users first

Conclusion

Phase 3B represents a smart architectural pivot. By discovering infrastructure gaps early and reordering the plan, the project is now positioned to:

  1. Ship high-value features immediately (Phases 2-4)
  2. Leverage proven shared KMP code (90-95% code reuse)
  3. Defer complex infrastructure work to appropriate phase
  4. Get working app in users’ hands faster

The iOS app now has a professional navigation foundation and clear path to feature development. Authentication will be added in Phase 5 when it doesn’t block feature delivery.

Status: ✅ Foundation complete, ready for Phase 2 features

Graph View