Archery Apprentice Documentation

Phase 3B: iOS Navigation Architecture & Authentication Deferral

10 min read

Phase 3B: iOS Navigation Architecture & Authentication Deferral

Session Overview

Date: 2025-11-20 Session Type: Phase 3B iOS Implementation & Architectural Pivot Original Goal: Implement Google Sign-In on iOS Actual Outcome: iOS tab navigation architecture + authentication deferred to Phase 5

What Happened

The session began with the goal of implementing Google Sign-In for iOS (Phase 3B), building on the Firebase OAuth setup from Phase 3A. However, during implementation, critical infrastructure gaps were discovered that made proceeding with authentication premature.

Session Flow:

  1. ✅ Firebase Console OAuth setup complete
  2. ✅ iOS app builds with sign-in UI shell
  3. ⚠️ Discovery: Missing Kotlin iosMain infrastructure
    • No dependency injection setup
    • GitLive Firebase KMP not wired for Swift
    • KMP-NativeCoroutines not configured
  4. 🔄 Decision: Defer full authentication to Phase 5
  5. ✅ Pivot: Implement proper iOS tab navigation instead
  6. 📋 Outcome: iOS app structure complete, ready for Phase 2 features

This represents a smart pivot rather than a setback—the discovery and plan reordering sets the project up for faster feature delivery by leveraging existing shared KMP code first.

Technical Discovery

Infrastructure Gaps Identified

During the authentication implementation attempt, several critical gaps in the Kotlin iosMain infrastructure were discovered:

1. Missing Dependency Injection Setup

Problem:

  • No IosDependencies singleton created
  • No Kotlin iosMain DI module configured
  • Swift cannot access KMP services

Impact:

  • Cannot instantiate FirebaseAuthRepository from Swift
  • Cannot wire up auth state flows
  • Blocks any KMP service integration from iOS

2. GitLive Firebase KMP Integration

Problem:

  • GitLive Firebase KMP library added to dependencies but not wired for Swift consumption
  • No proper bridging between Kotlin and Swift for Firebase services
  • Auth state flows not exposed to iOS

Impact:

  • Cannot use shared authentication logic
  • Forces platform-specific implementations
  • Defeats purpose of KMP architecture

3. KMP-NativeCoroutines Configuration

Problem:

  • KMP-NativeCoroutines library not properly configured
  • Kotlin Flow types cannot be consumed as async sequences in Swift
  • No coroutine bridging for iOS

Impact:

  • Auth state updates (Flows) unusable in Swift
  • Real-time data streams blocked
  • Async patterns don’t bridge to Swift properly

Root Cause Analysis

Core Issue: Infrastructure setup was assumed complete, but Phase 1 focused on Android-first development. The iOS bridge layer for KMP services was never established.

Should Have Been Done:

  • Phase 1 should have included basic iOS KMP bridging
  • GitLive Firebase + KMP-NativeCoroutines should have been validated end-to-end
  • IosDependencies singleton should have been created during infrastructure phase

Lesson: Infrastructure phases need platform parity checks, not just “builds successfully” validation.

iOS Plan Reordering

Previous Phase Order

The original iOS development plan front-loaded authentication:

  1. Phase 1: Infrastructure ✅ COMPLETE
  2. Phase 2: Authentication & Settings (Weeks 4-5) ← BLOCKED
  3. Phase 3: Round Scoring (Weeks 6-9)
  4. Phase 4: Equipment (Weeks 10-13)
  5. Phase 5: Analytics & Tournaments (Weeks 14-20)
  6. Phase 6: Polish & Release (Weeks 21-24)

Problem: Authentication blocked all feature development due to infrastructure gaps.

New Phase Order (2025-11-20)

The reordered plan prioritizes features with maximum shared KMP code:

  1. Phase 1: Infrastructure ✅ COMPLETE
  2. Phase 2: Round Scoring MVP (4 weeks) ← NEXT
    • 90-95% shared KMP code
    • High-value core feature
    • Minimal iOS-specific work
  3. Phase 3: Equipment Management (3 weeks)
    • 90%+ shared KMP code
    • Critical feature for users
    • Straightforward data management
  4. Phase 4: Tournaments & Analytics (4 weeks)
    • 85-90% shared KMP code
    • Already proven on Android
    • High user value
  5. Phase 5: Authentication & Settings (2 weeks) ← MOVED
    • Complex infrastructure work
    • Can be done after features ship
    • Not blocking core functionality
  6. Phase 6: Polish & Release (3 weeks)
    • Final testing
    • App Store submission
    • Release preparation

Rationale for Reordering

Strategic Benefits:

  1. Leverage Existing Code: Features with 90-95% KMP sharing can ship immediately
  2. Defer Complex Work: Authentication infrastructure can be tackled when not blocking features
  3. Faster User Value: Get round scoring, equipment, and tournaments into users’ hands sooner
  4. Reduced Risk: Proven KMP code reduces iOS implementation risk
  5. Optional Auth: Authentication is not required for core features to work

Timeline Impact:

  • Before: Blocked on auth infrastructure work (2-3 weeks) before any features
  • After: Ship features immediately, tackle auth infrastructure later
  • Net Result: Same total timeline, but features ship earlier

Development Philosophy:

“Ship value first, polish infrastructure later.”

Authentication is important but not critical for MVP. Users can get value from the app immediately, and auth can be added in a later update.

iOS Tab Navigation Architecture

Implementation Pattern

Architecture: Standard iOS bottom tab bar navigation Pattern: TabView with 4 main sections Entry Point: MainTabView.swift (simplified app launch)

Tab Structure

┌─────────────────────────────────────┐
│         MainTabView                 │
├─────────────────────────────────────┤
│  ┌──────┐  ┌──────┐  ┌──────┐     │
│  │Rounds│  │Equip │  │Tourn.│ ...│
│  └──────┘  └──────┘  └──────┘     │
└─────────────────────────────────────┘

Tab 1: Rounds (Phase 2)

  • Icon: Target symbol (archery target)
  • Status: Professional “Coming Soon” placeholder
  • Next: Phase 2 implementation (round scoring MVP)
  • KMP Code: 90-95% shared

Tab 2: Equipment (Phase 3)

  • Icon: Figure archery symbol
  • Status: Professional “Coming Soon” placeholder
  • Next: Phase 3 implementation (equipment management)
  • KMP Code: 90%+ shared

Tab 3: Tournaments (Phase 1)

  • Icon: Trophy symbol
  • Status: ✅ Already working (from original iOS spike)
  • Features: Tournament list, scoring interface
  • Proof Point: KMP integration successful

Tab 4: Settings (Phase 5)

  • Icon: Gear symbol
  • Status: Sign-in UI accessible (buttons non-functional)
  • Next: Phase 5 implementation (auth infrastructure + real sign-in)
  • Purpose: Access to authentication and app settings

Benefits of This Architecture

User Experience:

  • Standard iOS navigation pattern (familiar to users)
  • Clear feature roadmap visibility
  • Professional placeholders set expectations
  • No broken or half-working features

Development:

  • Proper foundation for feature additions
  • Easy to add Phase 2/3/4 features (just replace placeholder)
  • Auth accessible but not blocking
  • Clean separation of concerns

Technical:

  • Single app entry point (MainTabView)
  • Simplified navigation flow
  • No complex routing needed
  • iOS-standard patterns throughout

Code Structure

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

Workflow Changes

Previous Workflow: Multi-Agent iOS Development

Process:

  1. Orchestrator creates assignment for Agent 1
  2. Agent 1 implements iOS changes
  3. Agent 1 tests on their simulated environment
  4. Agent 1 creates PR
  5. User reviews and merges

Problems Identified:

  • iOS builds require Xcode on user’s Mac
  • Real-time build feedback needed during development
  • Manual testing on simulator required
  • Agent handoff adds friction and delays
  • Agent 1 cannot run actual iOS builds

New Workflow: Direct Orchestrator-User Collaboration

Process:

  1. Orchestrator works directly with user on iOS changes
  2. Real-time build feedback from Xcode
  3. Immediate testing on simulator
  4. Rapid iteration on issues
  5. PR created when feature complete

Benefits:

  • Faster iteration cycles
  • Real build feedback during development
  • Immediate issue detection
  • No handoff friction
  • Better quality outcomes

Agent 1 Status

Current Role: Sidelined for iOS work Available For: Android development, backend features, KMP shared code Reason: Cannot execute iOS builds, adds overhead for iOS-specific work

Not Eliminated: Agent 1 still valuable for:

  • Android-specific features
  • Backend API development
  • KMP shared code modules
  • Features that don’t require platform-specific testing

What’s Deferred to Phase 5

The following work is explicitly deferred to Phase 5 (Authentication & Settings phase):

Kotlin iosMain Infrastructure

Tasks:

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

Estimated Effort: 1 week

GitLive Firebase KMP Integration

Tasks:

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

Estimated Effort: 3-4 days

KMP-NativeCoroutines Setup

Tasks:

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

Estimated Effort: 2-3 days

Real Authentication Implementation

Tasks:

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

Estimated Effort: 1 week

Total Phase 5 Effort: ~2 weeks (as planned)

Success Metrics

Phase 3B UI Shell (Achieved)

✅ iOS app builds and runs

  • Clean build in Xcode
  • No runtime crashes
  • Proper app lifecycle

✅ Tab navigation functional

  • All 4 tabs accessible
  • Smooth transitions
  • iOS-standard behavior

✅ Sign-in UI displays

  • Professional layout
  • Accessible via Settings tab
  • Buttons present (non-functional)

✅ Tournaments feature works

  • Existing feature still functional
  • KMP integration proven
  • Proof point for other features

✅ Professional placeholders

  • Clear “Coming Soon” messaging
  • User expectations set
  • No broken experiences

Phase 5 Targets (Future)

Milestone: Authentication infrastructure complete

  • ⏳ 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
  • ⏳ Sign-out flow functional

Timeline: Phase 5 (after Phases 2-4 complete)

Lessons Learned

1. Infrastructure Validation is Critical

Problem: Infrastructure phase marked “complete” but iOS bridge layer never validated.

Lesson: Infrastructure phases need platform parity checks:

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

Action Item: Add platform parity validation to Phase 1 completion criteria for future modules.

2. Phase Breakdown Needs Substeps

Problem: “Phase 3B: Google Sign-In” was too coarse-grained, hiding infrastructure prerequisite.

Lesson: Complex phases should be broken into substeps:

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

Action Item: Break large phases into infrastructure + implementation substeps in future planning.

3. Agent Workflow Mismatch

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

Lesson: Agent workflows should match feedback loop requirements:

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

Action Item: Match agent assignment to feedback loop needs, not just task type.

4. Flexible Planning is Smart, Not Failure

Problem: Tendency to view plan changes as “failure” or “setback.”

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

  • Maximizes delivered value
  • Reduces risk
  • Improves efficiency

Action Item: Embrace plan changes as engineering intelligence, not project problems.

5. Single-Agent Implementation Requires Proven Infrastructure

Problem: Agent 1 assigned to iOS feature that depended on unproven infrastructure.

Lesson: Single-agent implementation works best when:

  • Infrastructure is proven end-to-end
  • Patterns are established
  • Blockers are unlikely

Action Item: Validate infrastructure with orchestrator before assigning to single agent.

Session Files

iOS Planning

Code References

Pull Requests

  • PR #283: iOS tab navigation and app structure (pending review)

Timeline

  • Session Date: 2025-11-20
  • Documentation Date: 2025-11-20
  • Phase 3B Status: UI shell complete, auth deferred
  • Next Phase: Phase 2 (Round Scoring MVP)
  • Phase 5 Target: After Phases 2-4 complete (~12-16 weeks)

Conclusion

Phase 3B represents a productive architectural pivot that sets the iOS application up for success. By discovering infrastructure gaps early and reordering the plan to prioritize high-value features with proven shared code, the project is positioned to deliver user value faster while deferring complex infrastructure work to a more appropriate phase.

The iOS app now has a solid navigation foundation, professional UI structure, and clear path forward for feature development. Authentication will be added in Phase 5 when it doesn’t block feature delivery, resulting in a better overall development experience and faster time-to-value for users.

Status: Smart pivot executed, iOS ready for Phase 2 features. ✅

Graph View

Backlinks