NKoMathLab - Project Handoff Document

NKoMathLab - Project Handoff Document

Generated: 2026-05-31
Project: NKoMathLab - Educational Mathematics App for N'Ko Speech/Gesture Systems
Handoff To: Codex (or continuation agent)
Handoff From: OpenCode (qwen3.5:397b)

---

1. Executive Summary

NKoMathLab is a comprehensive educational mathematics application built in SwiftUI for iOS. It teaches the mathematical foundations underlying:

• FAC (Featural Acoustic Coding) - Speech feature extraction system
• N'Ko - West African writing system with tonal syllables (3,024 entries)
• AirDeck - Gesture-based DJ control system
• Computational Choreography - Body motion as computation
• Anticipatory Transformers - Predictive sequence models

Current Status: ✅ COMPLETE (Phase 1)

• 11 comprehensive lessons written (5,000-10,000+ words each)
• iOS app built and deployed to simulator
• All core files created with full educational content
• Ready for user testing and content expansion

---

2. What's Been Accomplished

2.1 Lesson Content (11 Topics)

Total Content: ~99,000 words of educational material

2.2 Lesson Structure (Each Lesson Has 8 Sections)

1. Core Idea — Conceptual introduction with real-world analogies
2. Formal Section — Rigorous mathematics (definitions, theorems, proofs)
3. Intuition Section — Geometric/physical intuition, visual metaphors
4. Embodied Section — Physical exercises to feel the concepts
5. Architecture Section — Direct mapping to FAC/N'Ko/AirDeck systems
6. Worked Examples — 3-4 complete problems with step-by-step solutions
7. Failure Modes — 5-7 common mistakes and mitigation strategies
8. Practice Problems — 4 problems with hints and full solutions

2.3 App Features Implemented

• SwiftUI NavigationStack with lesson list and detail views
• Section picker (8 sections per lesson)
• Markdown rendering for mathematical content
• Search functionality across all lessons
• Persistent storage via SwiftData (practice tracking, mastery)
• Enhanced Fourier Lab with real-time synthesis and spectrum visualization
• N'Ko Script Support with Unicode rendering and syllable structure docs
• Deep lesson view with scrollable, formatted content

2.4 Deployment Status

---

3. Project Architecture

3.1 File Structure

[home]/Desktop/NKoMathLab/
├── NKoMathLab/
│   ├── NKoMathLabApp.swift       # App entry point
│   ├── ContentView.swift         # Main navigation view
│   ├── LessonListView.swift      # Lesson list with search
│   ├── DeepLessonView.swift      # 8-section lesson viewer
│   ├── DeepLessonContent.swift   # ALL lesson content (11 lessons)
│   ├── Persistence.swift         # SwiftData models & store
│   ├── FourierLabEnhanced.swift  # Interactive Fourier lab
│   ├── NKoSupport.swift          # N'Ko Unicode, syllable docs
│   ├── Models.swift              # Data models (Lesson, Section, etc.)
│   └── Assets.xcassets/          # Images, colors, icons
├── ExportOptions.plist           # Xcode export config
├── TESTFLIGHT.md                 # TestFlight deployment guide
├── README.md                     # Project documentation
├── HANDOFF.md                    # This file
└── NKoMathLab.xcodeproj/         # Xcode project

3.2 Key Files to Know

3.3 Data Models

// From Models.swift
struct Lesson: Identifiable {
    let id: String           // topicID
    let title: String
    let sections: [Section]
}

struct Section: Identifiable {
    let id: String           // core-idea, formal, intuition, etc.
    let title: String
    let content: String      // Markdown content
}

// From Persistence.swift (SwiftData)
@Model class PracticeAttempt {
    var lessonId: String
    var problemId: String
    var correct: Bool
    var timestamp: Date
}

@Model class DailySession {
    var date: Date
    var lessonsCompleted: Int
    var problemsAttempted: Int
}

3.4 Content Architecture

// From DeepLessonContent.swift
struct ComprehensiveLesson {
    let topicID: String
    let title: String
    let coreIdea: String           // Markdown
    let formalSection: String      // Markdown
    let intuitionSection: String   // Markdown
    let embodiedSection: String    // Markdown
    let architectureSection: String // Markdown
    let workedExamples: [WorkedExample]
    let failureModes: [FailureMode]
    let practiceProblems: [PracticeProblem]
}

struct WorkedExample {
    let title: String
    let problem: String
    let solution: String
    let keyInsight: String
}

struct FailureMode {
    let title: String
    let description: String
    let howToAvoid: String
}

struct PracticeProblem {
    let question: String
    let hint: String
    let solution: String
}

---

4. Current State & What Works

4.1 Working Features

✅ Lesson Browsing
- List view shows all 11 lessons
- Search filters lessons by title/topic
- Tap to open lesson detail

✅ Lesson Viewing
- 8-section picker (Core Idea, Formal, Intuition, Embodied, Architecture, Examples, Failures, Practice)
- Markdown rendering with math formatting
- Scrollable content
- Section persistence (remembers last viewed section)

✅ Practice Problems
- View problems with hints
- Reveal solutions
- Track attempts (via SwiftData)

✅ Progress Dashboard
- Progress tab shows lesson completion, average self-score, attempts, current/best streak, and due-topic count
- Mastery distribution splits topics into mastered, building, and untouched
- Topic badges show Start/Building/Review/Mastered states
- Due review queue links directly into practice prompts
- Recent attempts summarize saved self-reviews

✅ Fourier Lab
- Real-time waveform synthesis
- Spectrum visualization
- N'Ko tone contour simulation
- FAC feature extraction demo

✅ N'Ko Support
- Unicode rendering (ߡߊ߬, ߔߏ߬, etc.)
- Syllable structure documentation
- Codebook reference (3,024 entries)

4.2 Known Issues/Limitations

⚠️ Physical Device Deployment
- No physical iPhone currently connected
- Requires USB connection or Xcode deploy for iPhone 14 Pro Max

⚠️ Practice Tracking
- The active UI store is still `LearningStore`/UserDefaults
- SwiftData models are defined, but the UI is not fully migrated onto them yet

⚠️ Math Rendering
- Unicode math symbols work (×, ÷, √, Σ, ∫, etc.)
- Complex equations are ASCII-formatted (not LaTeX)
- Consider adding MathJax or KaTeX for better rendering

⚠️ Content Images
- No diagrams or illustrations yet
- Phase portraits, spectrograms, trellis diagrams would help
- Consider adding generated images or SVG diagrams

---

5. Pending Work (Next Steps)

5.1 High Priority (User Experience)

1. Interactive Exercises
- Embedded quizzes in each lesson
- Immediate feedback on answers
- Spaced repetition for review

2. Diagrams & Visualizations
- Vector geometry diagrams
- Phase portraits for dynamical systems
- Attention heatmaps for transformers
- Spectrograms for Fourier lessons

3. SwiftData UI Migration
- Move practice attempts and session tracking from `LearningStore`/UserDefaults into `SwiftDataStore`
- Keep existing dashboard metrics intact after migration
- Add migration path for existing UserDefaults attempts

4. Physical Device Testing
- Deploy to iPhone 14 Pro Max
- Test touch interactions
- Verify font rendering
- Check performance with large lessons

5.2 Medium Priority (Content Expansion)

1. Additional Lessons (Optional)
- Linear Algebra (matrices, transformations)
- Calculus (derivatives, integrals, optimization)
- Graph Theory (for attention mechanisms)
- Information Geometry (for probability manifolds)

2. Glossary
- Define all technical terms
- Cross-reference between lessons
- N'Ko-specific terminology

3. Bibliography
- Link to source materials
- Recommended readings per lesson
- Research papers for advanced topics

5.3 Low Priority (Polish)

1. Accessibility
- VoiceOver support
- Dynamic type sizing
- High contrast mode

2. Offline Support
- Ensure all content works offline
- Pre-cache lesson content

3. Sharing
- Export lesson sections as PDF
- Share practice problems
- Copy equations

---

6. Key Design Decisions

6.1 Why 8 Sections Per Lesson?

Decision: Every lesson follows the same 8-section structure.

Rationale:
- Consistency helps users know what to expect
- Covers all learning modes: conceptual, formal, intuitive, physical, applied
- "Embodied" section is unique — connects abstract math to physical experience
- "Architecture" section ties everything to FAC/N'Ko/AirDeck (practical relevance)

Don't Change This unless you have a compelling reason. The structure is pedagogically sound.

6.2 Why Markdown for Content?

Decision: All lesson content is stored as Markdown strings in Swift code.

Rationale:
- Simple to edit (no external CMS)
- Version controlled with code
- SwiftUI has native Markdown support
- Easy to export/regenerate

Trade-offs:
- No WYSIWYG editing
- Math rendering is limited to Unicode
- Large content file (~3,500 lines)

If You Change This: Consider JSON or external files, but Markdown is working well.

6.3 Why SwiftData?

Decision: Use SwiftData (not CoreData, not Realm) for persistence.

Rationale:
- Native Apple framework (iOS 17+)
- Simple API (just annotate with `@Model`)
- Automatic schema migration
- Integrates with SwiftUI

Trade-offs:
- iOS 17+ only (but that's the deployment target anyway)
- Less flexible than CoreData for complex queries

6.4 Why No Backend?

Decision: All content is bundled in the app. No server, no API.

Rationale:
- Works offline (critical for learning)
- No latency
- No server costs
- Simpler deployment

If Content Updates Needed: Ship app updates. For dynamic content, consider adding a simple JSON endpoint later.

---

7. Technical Details

7.1 Build Configuration

Project: NKoMathLab
Bundle ID: com.lume.NKoMathLab
Deployment Target: iOS 18.0
Minimum Device: iPhone 14 Pro Max (for physical testing)
Swift Version: 5.9+

7.2 Dependencies

No external packages (no Swift Package Manager dependencies).

7.3 Build Commands

# Build for simulator
xcodebuild -scheme NKoMathLab \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max' \
  -configuration Debug \
  build

# Build for physical device (Release)
xcodebuild -scheme NKoMathLab \
  -destination 'generic/platform=iOS' \
  -configuration Release \
  build

# Deploy to simulator
xcrun simctl install "iPhone 17 Pro Max" \
  [home]/Library/Developer/Xcode/DerivedData/NKoMathLab-<hash>/Build/Products/Debug-iphonesimulator/NKoMathLab.app

# Launch on simulator
xcrun simctl launch "iPhone 17 Pro Max" com.lume.NKoMathLab

7.4 Deploy to Physical Device

# 1. Connect iPhone via USB
# 2. Get device UDID
/Applications/Xcode.app/Contents/Developer/usr/bin/devicectl device info details --timeout 5

# 3. Deploy
/Applications/Xcode.app/Contents/Developer/usr/bin/devicectl device install \
  --device <UDID> \
  [home]/Desktop/NKoMathLab/Build/Products/Release-iphoneos/NKoMathLab.app

Or use Xcode GUI (easier):
1. Open `NKoMathLab.xcodeproj` in Xcode
2. Select iPhone from device dropdown
3. Press ⌘R

---

8. Content Quality Standards

8.1 What Makes a Good Lesson?

Each lesson should have:

1. Concrete Examples — Abstract math tied to FAC/N'Ko/AirDeck
2. Worked Problems — Step-by-step solutions, not just answers
3. Failure Modes — What goes wrong and how to avoid it
4. Embodied Exercises — Physical ways to feel the concepts
5. Architecture Mappings — "This is where you use it in your systems"

8.2 Tone & Style

• Direct — No fluff, get to the point
• Rigorous — Math is correct, proofs are valid
• Accessible — Intuition before formalism
• Practical — Always tie back to FAC/N'Ko/AirDeck

8.3 Math Formatting

• Use Unicode symbols: ×, ÷, √, Σ, ∫, ∂, ∇, ∈, ⊂, →
• ASCII equations for complex formulas
• Code blocks for algorithms
• Tables for comparisons

Example:

Dot Product: u · v = Σᵢ uᵢvᵢ

Cosine Similarity: cos(θ) = (u · v) / (||u|| × ||v||)

---

9. Testing Checklist

9.1 Functional Testing

• [ ] All 11 lessons load without crashes
• [ ] Section picker works for all lessons
• [ ] Search finds relevant lessons
• [ ] Practice problems display correctly
• [ ] Fourier Lab renders waveform and spectrum
• [ ] N'Ko text renders correctly (ߡߊ߬, etc.)
• [ ] App survives background/foreground transitions
• [ ] No memory warnings during extended use

9.2 Content Testing

• [ ] No typos in lesson content
• [ ] All equations render correctly
• [ ] Worked examples have complete solutions
• [ ] Practice problem hints are helpful (not spoilers)
• [ ] Architecture sections are accurate for FAC/N'Ko

9.3 Performance Testing

• [ ] Lesson load time < 1 second
• [ ] Section switching is instant
• [ ] Search results appear as you type
• [ ] Fourier Lab runs at 60 FPS
• [ ] No crashes after 30+ minutes of use

---

10. Common Issues & Solutions

10.1 "App Crashes on Launch"

Cause: Usually a SwiftData schema mismatch or missing entitlement.

Fix:

# Clean build folder
rm -rf [home-path]

# Rebuild
xcodebuild -scheme NKoMathLab -configuration Debug clean build

10.2 "Lesson Content Not Showing"

Cause: `DeepLessonContent.swift` not compiled or lesson ID mismatch.

Fix:
1. Check `LessonDatabase.allLessons` has the lesson
2. Verify `topicID` matches what `ContentView` expects
3. Rebuild app

10.3 "Math Symbols Display as Boxes"

Cause: Font doesn't support Unicode math symbols.

Fix: Use system font (SF Pro) which supports all symbols:

Text(content)
  .font(.system(.body, design: .default))

10.4 "Physical Device Won't Deploy"

Cause: Device not trusted, or provisioning issue.

Fix:
1. Unlock iPhone, tap "Trust This Computer"
2. In Xcode: Window → Devices and Simulators
3. Select device, click "Show Provisioning Profiles"
4. Add/refresh profiles
5. Retry deploy

---

11. Future Roadmap

### Phase 1: Core Content ✅ (Complete)
- 11 comprehensive lessons
- Basic navigation UI
- Practice problems

### Phase 2: Interactive Features (Next)
- Quizzes with immediate feedback
- Progress tracking dashboard
- Spaced repetition system
- Bookmarks & notes

### Phase 3: Visual Enhancements
- Diagrams for each lesson
- Interactive visualizations
- Animated explanations
- 3D models for geometry

### Phase 4: Social & Sharing
- Share progress with friends
- Study groups
- Export notes as PDF
- Anki deck generation

### Phase 5: Advanced Content
- Graduate-level topics
- Research paper summaries
- Implementation tutorials
- Video lectures

---

12. Contact & Resources

12.1 Project Locations

12.2 Related Projects

• FAC (Featural Acoustic Coding) — Speech feature extraction
• N'Ko Recognition — Tonal syllable classifier
• AirDeck — Gesture-based DJ control
• Computational Choreography — Body motion as computation

12.3 Key People

• Mohamed Diomande — Project owner, N'Ko expert
• OpenCode (qwen3.5:397b) — Initial development (Phase 1)
• Codex — Continuation agent (you!)

---

13. Quick Start for Codex

13.1 First Steps

1. Read this file — You now have full context
2. Test the app — Launch on simulator, browse lessons
3. Check content quality — Spot-check a few lessons
4. Review pending work — See Section 5 for next steps

13.2 If User Says "Continue Development"

Start with High Priority items from Section 5.1:
1. Interactive Exercises
2. Diagrams & Visualizations
3. SwiftData UI Migration

13.3 If User Says "Fix a Bug"

1. Reproduce the bug
2. Check relevant file (usually `DeepLessonView.swift` or `ContentView.swift`)
3. Fix and test
4. Document the fix in this file

13.4 If User Says "Add a Lesson"

1. Follow the 8-section structure
2. Match the style of existing lessons
3. Add to `LessonDatabase.allLessons`
4. Test in app

13.5 If User Says "Deploy to iPhone"

1. Connect iPhone via USB
2. Get UDID with `devicectl device info details`
3. Deploy with `devicectl device install`
4. Or use Xcode GUI (⌘R)

---

14. Summary

What You're Inheriting:
- ✅ 11 comprehensive mathematics lessons (~99,000 words)
- ✅ Working iOS app (SwiftUI, SwiftData)
- ✅ Deployed to simulator
- ✅ Full documentation

What Needs Doing:
- ⏳ Deploy to physical iPhone
- 📋 Progress dashboard
- 📋 Interactive exercises
- 📋 Diagrams and visualizations

How to Succeed:
- Keep the 8-section lesson structure
- Maintain content quality (rigorous + accessible)
- Always tie math back to FAC/N'Ko/AirDeck
- Test on physical device before shipping

Good luck! You're continuing important work — making advanced mathematics accessible to people building speech and gesture recognition systems for African languages.

---

Last Updated: 2026-05-31
Generated By: OpenCode (qwen3.5:397b)
Handoff To: Codex