ߒߞߏ N'Ko Unified Platform — Master Integration Plan
``` ┌─────────────────────────────────────────────────────────────────┐ │ N'KO UNIFIED PLATFORM │ │ ═══════════════════ │ │ │ │ ┌──────────────────────── APPS ────────────────────────────┐ │ │ │ │ │ │ │ 📱 iOS App 🖥 macOS MenuBar 🌐 PWA/Web │ │ │ │ (Keyboard + (SpeakFlow + (Bridge + │ │ │ │ Voice + Quick Translate) Demo) │ │ │ │ Bridge) │ │ │ │ │ │ │ │ 🤖 Telegram Bot 🔌 Chrome Ext ⌨️ Raycast │ │ │ │ (Translate + (Inline Bridge) (Quick Convert) │ │ │ │ Cultural) │ │ │ └───────────────────────────┬─────────────────
Full Public Reader
# ߒߞߏ N'Ko Unified Platform — Master Integration Plan
## From 13 Scattered Projects → 1 Unified System
---
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐
│ N'KO UNIFIED PLATFORM │
│ ═══════════════════ │
│ │
│ ┌──────────────────────── APPS ────────────────────────────┐ │
│ │ │ │
│ │ 📱 iOS App 🖥 macOS MenuBar 🌐 PWA/Web │ │
│ │ (Keyboard + (SpeakFlow + (Bridge + │ │
│ │ Voice + Quick Translate) Demo) │ │
│ │ Bridge) │ │
│ │ │ │
│ │ 🤖 Telegram Bot 🔌 Chrome Ext ⌨️ Raycast │ │
│ │ (Translate + (Inline Bridge) (Quick Convert) │ │
│ │ Cultural) │ │
│ └───────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌───────────────── SWIFT CORE (SPM) ───────────────────────┐ │
│ │ │ │
│ │ NKoTransliterator NKoPrediction NKoVoice │ │
│ │ (bridge.py → Swift) (neural → Swift) (STT/TTS Swift) │ │
│ │ │ │
│ │ NKoCulture NKoPhonetics NKoMorphology │ │
│ │ (proverbs, calendar) (IPA, tones) (word structure) │ │
│ │ │ │
│ └───────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌──────────────── PYTHON CORE (pip) ───────────────────────┐ │
│ │ │ │
│ │ nko.transliterate nko.predict nko.audio │ │
│ │ (bridge + scripts) (24 engines) (sigils + TTS) │ │
│ │ │ │
│ │ nko.culture nko.morphology nko.dialect │ │
│ │ (proverbs, events) (word analysis) (regional vars) │ │
│ │ │ │
│ │ nko.quality nko.memory nko.pipeline │ │
│ │ (validation) (learning) (processing) │ │
│ │ │ │
│ └───────────────────────────┬───────────────────────────────┘ │
│ │ │
│ ┌─────────────────── DATA LAYER ───────────────────────────┐ │
│ │ │ │
│ │ nko_map.json cognates.json vocabulary.json │ │
│ │ proverbs.json nko_vocab.json sigils.json │ │
│ │ corpus/ cultural_cal/ user_data/ │ │
│ │ │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────┘---
Redundancy Elimination Plan
### R1: Transliteration (3 implementations → 1)
| Current | Location | Lines | Action |
|---------|----------|-------|--------|
| Python Bridge | cross-script-bridge/core/ | ~400 | KEEP as canonical |
| Python Translation Bridge | nko-keyboard-ai/lib/translation_bridge.py | ~200 | DELETE — redirect imports to core bridge |
| Swift Transliterator | ios-keyboard/Sources/NKoCore/ | ~150 | REWRITE — port canonical Python to Swift natively |
Result: 1 Python implementation, 1 Swift implementation, same logic.
### R2: Phonetics/IPA (scattered across 13 files → 1 module)
| Current | Action |
|---------|--------|
| Inline IPA maps in bridge.py, nko.py, arabic.py | EXTRACT into `core/phonetics/ipa.py` |
| IPA references in 10 keyboard engines | IMPORT from shared phonetics module |
| Tone handling in prosody_engine.py | MERGE into phonetics module |
Result: `nko.phonetics` — single source of truth for IPA mappings, tone marks, diacritics.
### R3: Cultural Data (3 sources → 1)
| Current | Location | Action |
|---------|----------|--------|
| cultural_engine.py | nko-keyboard-ai | KEEP — richest implementation |
| proverbs.json | nko-code-comments | MERGE into unified `data/proverbs/` |
| Manding Proverbs API | 28-days-of-code | ABSORB — data into proverbs/, API logic into core |
Result: `data/proverbs/unified-proverbs.json` + `nko.culture` module.
### R4: Voice/TTS (2 implementations → 1 per platform)
| Current | Action |
|---------|--------|
| Python tts_engine.py + voice_engine.py | MERGE into `core/voice/` |
| Swift SpeechService.swift (SpeakFlow) | KEEP as Swift voice module |
Result: Python voice module for server/CLI, Swift voice module for iOS/macOS. Shared audio format.
### R5: Morphology (2 implementations → 1)
| Current | Location | Action |
|---------|----------|--------|
| morphological_engine.py | nko-keyboard-ai | Richer, more features |
| morphology/ | cross-script-bridge | More structured |
Merge best of both into `core/morphology/`. Single API surface.
### R6: NKo Character Maps (2+ JSON files → 1)
| Current | Action |
|---------|--------|
| nko_map.json (cross-script-bridge) | CANONICAL — most complete |
| vocabulary.json (nko-keyboard-ai) | SUPPLEMENT — merge unique entries |
| nko_vocab.json (linguistic-dna) | SUPPLEMENT — merge unique entries |
Result: `data/mappings/nko-unified.json` — single character/vocab database.
---
Integration Phases
### Phase 1: UNIFY (Week 1) ✅ Started
- [x] Create monorepo at `Desktop/NKo/`
- [x] Copy all components in
- [ ] Initialize git
- [ ] Set up Python package structure (`pyproject.toml`)
- [ ] Set up Swift Package (`Package.swift`)
- [ ] Merge duplicate JSON data files
- [ ] Create unified import paths
### Phase 2: DEDUPLICATE (Week 2)
- [ ] R1 Extract canonical transliteration into `nko.transliterate`
- [ ] R2 Build `nko.phonetics` — single IPA/tone module
- [ ] R3 Merge all proverb data into `data/proverbs/unified-proverbs.json`
- [ ] R4 Merge voice engines into `nko.voice`
- [ ] R5 Merge morphology into `nko.morphology`
- [ ] R6 Merge character maps into `data/mappings/nko-unified.json`
- [ ] Update all internal imports to use unified paths
- [ ] Run existing tests against new structure
### Phase 3: SWIFT CORE (Week 3)
- [ ] Create `NKoCore` Swift Package with targets:
- `NKoTransliteration` — port bridge.py to Swift
- `NKoPrediction` — port neural_predictor.py to Swift (CoreML)
- `NKoPhonetics` — port IPA mappings to Swift
- `NKoMorphology` — port word analysis to Swift
- `NKoCulture` — proverbs, calendar, blessings in Swift
- [ ] Write Swift tests mirroring Python tests
- [ ] Ensure feature parity: Python CLI ↔ Swift framework
### Phase 4: iOS APP (Week 4)
- [ ] Single unified iOS app with 3 modes:
- Keyboard — custom keyboard extension using NKoCore
- Bridge — standalone transliteration UI (type in any script → see all 3)
- Voice — hold-to-speak Manding → text (SpeakFlow integration)
- [ ] Keyboard features from NKo-AI:
- Predictive text (CoreML model)
- Swipe typing
- Smart compose
- Cultural suggestions (auto-blessing on life events)
- Grammar checking
- [ ] Settings: script preference, prediction aggressiveness, voice language
- [ ] TestFlight build
### Phase 5: CORPUS BUILDING (Week 5-6)
- [ ] Scrape/collect real N'Ko text:
- N'Ko Wikipedia articles
- WhatsApp N'Ko groups (with consent)
- Facebook N'Ko pages
- N'Ko Academy publications
- Existing digitized texts
- [ ] Build training dataset for CoreML prediction model
- [ ] Train on-device model (CoreML) from corpus
- [ ] Validate with native speakers
### Phase 6: ECOSYSTEM (Week 7-8)
- [ ] Ship iOS app to App Store
- [ ] Launch PWA for web access
- [ ] Publish Python package to PyPI (`pip install nko`)
- [ ] Publish Swift package to SPM registry
- [ ] Chrome extension to Chrome Web Store
- [ ] VS Code extension to marketplace
- [ ] Telegram bot live
- [ ] Community feedback loop
---
Module Dependency Graph (Post-Dedup)
nko.phonetics ──────────────────┐
↑ │
│ ▼
nko.transliterate ←──── nko.morphology
↑ │
│ ▼
nko.predict ←──── nko.context ←── nko.culture
↑ │
│ ▼
nko.voice ←──── nko.audio ←──── nko.sigils
↑
│
nko.keyboard (orchestrator — imports all above)Key principle: Every module depends DOWN, never UP. `nko.phonetics` is the bedrock — everything builds on correct IPA/tone representation.
---
File Count Projections (Post-Dedup)
| Layer | Current Files | After Dedup | Reduction |
|---|---|---|---|
| Core Python | 89 source | ~45 | -49 |
| Core Swift | 4 | ~25 (new) | +21 (port) |
| Data/JSON | 27 | ~10 | -63 |
| Tests | 29 | ~35 | +6 (new Swift) |
| Tools | 20 | ~15 | -25 |
| Apps | 44 Swift + misc | ~50 | unified |
| Total | 213 | ~180 | **-15 |
---
Priority Ranking
| # | Task | Impact | Effort | Ship Value |
|---|---|---|---|---|
| 1 | Merge JSON data files | High — single truth | Low | Foundation |
| 2 | Build nko.phonetics | High — everything depends on it | Medium | Foundation |
| 3 | Build nko.transliterate (clean) | High — core feature | Medium | Demo-ready |
| 4 | Port to Swift (NKoCore SPM) | Critical — iOS needs it | High | App-ready |
| 5 | iOS Keyboard Extension | Critical — main product | High | Ship |
| 6 | CoreML prediction model | High — keyboard quality | High | Quality |
| 7 | Voice integration | Medium — SpeakFlow merge | Medium | Feature |
| 8 | Corpus collection | High — model quality | Ongoing | Quality |
| 9 | PWA/Web | Medium — accessibility | Medium | Reach |
| 10 | App Store | Critical — distribution | Medium | Ship |
---
Quick Wins (Can Do Today)
1. Merge JSON data — combine nko_map.json + vocabulary.json + nko_vocab.json into one canonical file
2. Git init + first commit — make the monorepo real
3. pyproject.toml — set up `nko` as an installable Python package
4. Package.swift — set up NKoCore as a Swift package
5. README.md — unified project README with vision statement
---
ߊ ߞߊ߬ ߛߓߍ ߞߎ ߘߐ — "It is written in the beginning"
Promotion Decision
Keep in the searchable backlog until it intersects a live paper or system.
Source Anchor
NKo/MASTER-PLAN.md
Detected Structure
Method · References · Code Anchors · Architecture