nkbmusic/docs/NK_IMPLEMENTATION_PLAN.md

# Nanga Kathai (NK) — Implementation Plan

*"Nanga Kathai" = "Our Song" in Badaga. A modern music app for the Badaga community of the Nilgiris, Tamil Nadu.*

Last updated: 2026-10-27

---

## 1. Why this app, and what makes it different

**The gap**
- No Badaga music app exists on iOS. The one or two on Android are low quality.
- The largest existing archive, ibaduga.com, has 1,000+ Badaga songs, but it's a website and a Mixcloud page, not a native app.
- Badaga has no Unicode script of its own. People write it in Tamil script (most common), in Kannada script, or in Latin transliteration. The Badugu script has been proposed to Unicode but isn't encoded yet. So search and lyrics must handle **all three writing systems**.

**Positioning:** Spotify/Amazon-level playback and UX, plus features no global app offers:
1. **Occasions:** Badaga songs are tied to life events: *huttu* (birth), *habba* (festivals, e.g. Hethai Habba), *madhuvae* (marriage), *saavu* (funerals), devotional. Browse by occasion is a top-level feature.
2. **Hatti (village) identity:** singers and songs tagged by village, so people can browse "songs from my hatti".
3. **Trilingual lyrics:** Tamil script, Latin transliteration, and English meaning, side by side and synced.
4. **Diaspora:** Badagas in Bengaluru, Chennai, the Gulf, the US and the UK reach the culture through this app. That means offline use, sharing and festival reminders.
5. **Low bandwidth:** the Nilgiris hills have patchy 4G, so offline-first design and a data-saver mode are essential.

---

## 2. Feature research: what the leading apps do, and what NK adopts

| Capability | Spotify / Amazon Music / Apple Music / YT Music | NK phase |
|---|---|---|
| Background playback, lock screen, notification controls | All | **MVP** |
| Mini player plus full-screen Now Playing with swipe gestures | All | **MVP** |
| Queue (play next, add to queue, reorder by drag) | All | **MVP** |
| Shuffle and repeat (Spotify's 2026 "fewer repeats" shuffle) | Spotify | **MVP** (smart shuffle that avoids recent repeats) |
| Gapless playback and crossfade | Spotify, Apple | **MVP** gapless, v1.1 crossfade |
| Loudness normalization | All | **MVP** (normalized at ingest to −14 LUFS) |
| Search with typo tolerance and instant results | All | **MVP** (trilingual + transliteration-aware) |
| Library: liked songs, playlists, followed artists | All | **MVP** |
| Offline downloads | All (premium) | **MVP** (free; key need in the hills) |
| Data-saver / quality setting | Spotify, Amazon | **MVP** |
| Synced lyrics, karaoke-style highlighting | Spotify, Apple, Amazon | **v1.1** (static lyrics in MVP) |
| Lyrics translation (Spotify 2026) | Spotify | **v1.1** (Badaga → English) |
| Share card to WhatsApp / Instagram stories, deep links | All | **MVP** (WhatsApp first; it's the community's main channel) |
| Sleep timer | Spotify, Amazon | **MVP** |
| Recently played, Continue listening | All | **MVP** |
| Home sections: new releases, trending, editorial picks | All | **MVP** (curated by admins) |
| Personalized mixes ("Daily Mix", "Made for you") | Spotify | **v1.2** (rule-based first, ML later) |
| Radio / auto-play similar songs when the queue ends | All | **v1.1** |
| Mood/prompt playlists (Spotify Prompted Playlists, Alexa+ DJ) | Spotify, Amazon | **v2** (an LLM over NK's tags) |
| Year-end Wrapped / Replay | Spotify, Apple | **v1.2** ("NK Varusha", a yearly recap) |
| Collaborative playlists | Spotify | **v1.2** (wedding playlists) |
| Listening activity / friends | Spotify 2026 | **v2** |
| Equalizer | Spotify | **v1.1** (Android native EQ; iOS limited) |
| Chromecast, AirPlay | All | **v1.1** (AirPlay comes free on iOS) |
| Android Auto, CarPlay | All | **v2** |
| Home-screen widgets, Live Activities | Apple, Spotify | **v2** |
| Podcasts / stories | Spotify, Amazon | **v2** (Badaga folk tales, oral history) |
| Artist profiles with bio and verified badge | All | **MVP** (bio), **v1.1** (artist claims profile) |
| Artist portal and analytics (Spotify for Artists) | Spotify | **v1.1** (upload with approval workflow, §7) |
| Accessibility: screen reader, dynamic type, contrast | All | **MVP** |

**NK-only features**
- Browse by **Occasion** and by **Hatti**.
- **Festival calendar** (Hethai Habba and others) with push reminders and themed playlists.
- **Dedications**: "Dedicate this song to…", which generates a WhatsApp share card with a message (useful for weddings and birthdays).
- **Trilingual UI**: English, Tamil, and Badaga UI strings in Tamil script.
- **Heritage tag**: archival and rare recordings, marked and preserved.

---

## 3. Tech stack (recommended)

### App (Flutter, one codebase for iOS, Android and web)
| Concern | Choice | Why |
|---|---|---|
| Framework | Flutter (latest stable), Dart 3, Material 3 with a custom theme | iOS and Android from one codebase |
| State | **Riverpod 2/3** (with codegen) | testable and scales well |
| Routing | **go_router** (with a ShellRoute so the mini player stays visible) | deep links for share URLs |
| Audio engine | **just_audio 0.10.x** | gapless playlists, HLS, clipping, caching (experimental) |
| Background / OS media controls | **audio_service** (AudioHandler) | lock screen, notification, headset buttons, Bluetooth; the foundation for CarPlay/Auto later |
| Audio session | **audio_session** | handles interruptions (calls) and ducking |
| Local DB | **drift** (SQLite) | library, downloads index, play history, offline catalog |
| Key-value | shared_preferences / hive_ce | settings |
| Downloads | background_downloader | resumable, survives app kill, works on iOS and Android |
| Images | cached_network_image, palette_generator (dynamic colours from artwork) | Spotify-style tinted Now Playing |
| Animations | flutter_animate, Rive/Lottie for the brand splash | |
| Networking | dio plus the Supabase client | |
| Analytics / crash | Firebase Crashlytics plus PostHog (or Firebase Analytics) | |
| i18n | flutter_localizations, ARB (en, ta, Badaga-in-Tamil-script) | |
| Fonts | Noto Sans Tamil plus a display face (e.g. Outfit / Manrope) | correct Tamil glyph shaping |

> Note: audio_service conflicts with other plugins that also manage media notifications. Use **only** just_audio + audio_service + audio_session for playback.

### Backend
| Concern | Choice | Why |
|---|---|---|
| DB, auth, API | **Supabase** (Postgres, Row-Level Security, Auth with phone OTP, Google and Apple sign-in) | SQL suits a relational music catalog; cheap; open source |
| Search | Postgres `pg_trgm` plus a normalized transliteration column (MVP) → Typesense/Meilisearch (later) | fuzzy and cross-script search |
| Audio and image storage + CDN | **Cloudflare R2** + Cloudflare CDN | **zero egress fees**, which matters most for streaming costs |
| Secure streaming | Signed URLs (short TTL) from a Supabase Edge Function | stops hotlinking and scraping |
| Audio format | AAC (m4a) at 64 kbps (data-saver), 128 kbps (normal), 256 kbps (high). HLS optional in v1.1 | small files, good quality |
| Push | Firebase Cloud Messaging (+ APNs) | festival reminders, new releases |
| Admin / artist portal | Flutter web (shares models) or Next.js + Supabase | |
| Ingest pipeline | Python + ffmpeg scripts (local first, later a worker) | §5 |

**Estimated cost at launch** (around 5k users): Supabase free/Pro ($25/mo), R2 storage roughly $0.015/GB/month (2,000 songs × 3 bitrates ≈ 15 GB ≈ $0.25/mo, no egress fees), Apple developer account $99/yr, Google Play $25 one-time.

---

## 4. Data model (core tables)

```
artists        (id, name_latin, name_tamil, hatti_id, bio, photo_url, verified, claimed_by_user_id)
hattis         (id, name_latin, name_tamil, region, lat, lng)
albums         (id, title_latin, title_tamil, year, cover_url, type[album|single|compilation|archive])
tracks         (id, title_latin, title_tamil, title_en_meaning, album_id, duration_ms,
                occasion[], genre[], mood[], year, language='bfq', explicit=false,
                audio_key_64, audio_key_128, audio_key_256, loudness_lufs,
                status[draft|pending|approved|rejected|taken_down],
                rights_status[legacy_unverified|artist_approved|licensed], source_note,
                search_vector, created_at)
track_artists  (track_id, artist_id, role[singer|lyricist|composer|musician])
lyrics         (track_id, script[tamil|latin|kannada|english], body, synced_lrc)
playlists      (id, owner_id, title, cover_url, is_public, is_editorial, is_collaborative)
playlist_items (playlist_id, track_id, position, added_by)
user_likes     (user_id, track_id | album_id | artist_id, created_at)
play_events    (user_id, track_id, started_at, ms_played, source, offline)  -- powers trending, Wrapped, royalties
festivals      (id, name, date_rule, playlist_id)
submissions    (id, artist_id, track_draft_json, files, consent_doc_url, reviewer_id, status, notes)
consents       (artist_id, track_id, consent_type, signed_at, signature_ref)
takedown_requests (id, track_id, requester, reason, status)
```
`language='bfq'` is the ISO 639-3 code for Badaga.

---

## 5. Phase 0: ingest your existing collection (start here)

This is the critical-path work. App quality depends on catalog quality.

1. **Inventory**: run a script over your folders that outputs a CSV with path, file hash, duration, bitrate, existing ID3 tags and embedded art.
2. **Dedupe**: exact matches by hash, near-duplicates by audio fingerprint (Chromaprint / `fpcalc`).
3. **Metadata sheet** (Google Sheet or Excel, filled by you and community volunteers): title (Tamil script), title (Latin), meaning in English, singer(s), lyricist, composer, hatti, occasion, year or approximate era, album/source, and lyrics if known.
4. **Audio processing** (ffmpeg):
   - Trim silence, normalize loudness to −14 LUFS (`loudnorm` two-pass), store the measured value.
   - Transcode to AAC 64/128/256 kbps.
   - Generate a waveform JSON (optional, for the scrubber UI).
5. **Artwork**: use the original cover where one exists; otherwise generate a branded cover from a template (occasion colour + title in Tamil). One consistent style looks premium.
6. **Upload**: push files to R2 and rows to Supabase via script. Every track gets `rights_status = legacy_unverified`.
7. **Rights**: before going public, contact the singers and families you can reach. Publish a clear **takedown/claim** form in the app. Apple App Review may ask for proof that you have rights to the music, so keep a consent record for each track (§7).

Deliverable: a clean, searchable catalog of N songs with complete metadata and covers.

---

## 6. UX and design direction

**Brand: "Nilgiris at dusk"**
- Dark-first theme (the music-app norm) with a light theme available.
- Palette: deep tea-estate green (#0F2A1F), misty blue-grey, and an accent drawn from the traditional Badaga white cloth with its coloured border (warm red or ochre accent). Now Playing tints dynamically from the artwork.
- Type: a modern geometric sans for Latin text; Noto Sans Tamil, sized slightly larger for legibility.
- Motifs: subtle hill-contour lines and textile border patterns as dividers. Keep them tasteful, not kitsch.

**Navigation** (bottom bar, 4 tabs): **Home · Search · Library · Occasions**
- A persistent **mini player** above the bottom bar. Swipe up to open Now Playing; swipe left or right to skip.

**Key screens**
1. **Splash / onboarding**: pick UI language → pick your hatti (optional) → pick favourite singers/occasions (seeds the home feed) → optional sign-in (guest mode allowed; sign in later to sync).
2. **Home**: greeting by time of day ("Good evening" in Badaga), Continue listening, Festival banner (seasonal), New releases, Trending in Nilgiris, Occasion chips, Featured singers, Heritage collection, Made for you (v1.2).
3. **Search**: instant results as you type. Searches across Tamil script, Latin transliteration and English meaning. Filters: songs, artists, albums, playlists, lyrics. Browse grid of occasions and moods. Recent searches.
4. **Now Playing**: large artwork with a parallax/blurred tinted background, scrubber, controls, like, queue, lyrics panel (pull up), share/dedicate, sleep timer, output device.
5. **Lyrics**: full-screen, script toggle (Tamil / Latin / English), synced highlighting in v1.1.
6. **Artist**: header image, verified badge, play/shuffle, top songs, albums, hatti, bio, "Appears on".
7. **Album / Playlist**: header with a dynamic colour gradient, download toggle, shuffle, track list with swipe actions (queue, like).
8. **Library**: Liked songs, Downloads, Playlists, Artists, Albums, Recently played, with sort and filter.
9. **Occasions**: cards for Huttu, Habba, Madhuvae, Saavu (handled respectfully; muted styling), Devotional, Folk/Dance, Modern.
10. **Settings**: audio quality (Wi-Fi vs mobile), data saver, download quality, storage manager, language, theme, notifications, account, about/credits, report a song.

**UX quality bar** (what makes the leading apps feel good)
- Under 1 s to first audio on a good network: prefetch the next track, show skeleton loaders (no spinners), use optimistic UI for likes and queue changes.
- Hero animations from artwork to Now Playing; haptics on key actions.
- Playback state survives app kill (restore queue and position).
- Full offline mode: the app opens without a network, shows downloads, and syncs likes later.
- Accessibility: semantic labels on every control, dynamic type, minimum 4.5:1 contrast.

---

## 7. New-song workflow with singer approval (v1.1)

```
Singer signs up (phone OTP) ─► Verify identity (admin checks; community reference)
   ─► Artist profile created / existing legacy profile CLAIMED
   ─► Upload: audio (WAV/FLAC/MP3) + cover + metadata + lyrics
   ─► Digital consent: e-sign the distribution agreement (non-exclusive licence,
       revocable, credits shown, royalty terms if any) ─► stored in `consents`
   ─► Status: PENDING ─► Admin moderation queue (quality, metadata, rights check)
   ─► APPROVED ─► automated ffmpeg pipeline ─► scheduled release date ─► push to followers
   └─► REJECTED with notes ─► singer edits and resubmits
```
- **Legacy tracks**: when a singer claims their profile, they review each `legacy_unverified` track and choose **Approve**, **Request edit** or **Take down**. Approval flips `rights_status` to `artist_approved`.
- **Artist dashboard**: plays, listeners, top hattis/cities, saves, playlist adds (from `play_events`).
- **Roles**: listener, artist, moderator, admin, enforced by Supabase Row-Level Security.
- **Future**: royalties or a tip jar (UPI), optional ad-free supporter tier. Have an expert check copyright, IPRS/PPL and payment rules in India before you take any money.

---

## 8. Project structure (Flutter)

```
lib/
  main.dart
  app/            (router, theme, l10n, DI/providers bootstrap)
  core/           (network, db (drift), error, utils, transliteration)
  audio/          (audio_handler.dart, queue, playback_repository, cache)
  features/
    home/ search/ library/ player/ lyrics/ artist/ album/ playlist/
    occasions/ downloads/ settings/ auth/ onboarding/ share/
      data/ (dto, repository)  domain/ (models)  presentation/ (screens, widgets, providers)
  shared/widgets/ (mini_player, track_tile, artwork, shimmer, section_carousel)
tools/ingest/     (python + ffmpeg scripts for Phase 0)
supabase/         (migrations, RLS policies, edge functions)
admin/            (moderation + artist portal, Flutter web)
```

---

## 9. Roadmap

| Phase | Duration (1 dev + you curating) | Scope | Exit criteria |
|---|---|---|---|
| **0. Catalog** | 2–3 wks (runs alongside phase 1) | §5 ingest: metadata sheet, ffmpeg pipeline, R2 + Supabase seed | All legacy songs tagged and playable from the CDN |
| **1. Foundation** | 2 wks | Flutter project, theme/design system, routing, Supabase schema + RLS, auth (guest + phone OTP + Apple/Google) | App shell runs on iOS and Android |
| **2. Playback core** | 2–3 wks | just_audio + audio_service, queue, mini/full player, background + lock screen, gapless, shuffle/repeat, sleep timer, state restore | Plays for 1 hr in background on both OSes, handles calls and Bluetooth |
| **3. Discovery** | 2 wks | Home sections, Search (trilingual, fuzzy), Artist/Album/Playlist screens, Occasions, static lyrics | User can find any song in ≤ 3 taps or by typing |
| **4. Library and offline** | 2 wks | Likes, playlists, downloads manager, offline mode, data saver, recently played, sync | Full use in airplane mode |
| **5. Polish and share** | 1–2 wks | Dynamic colours, animations, WhatsApp share + deep links, dedications, onboarding, accessibility, analytics, crash reporting | Internal beta |
| **6. Beta and launch** | 2 wks | TestFlight + Play internal testing with 50–100 community members, fix issues, store listings (EN/TA screenshots), privacy policy, takedown page | **MVP live on App Store and Play Store** |
| **v1.1** | +4–6 wks | Artist portal + approval workflow, synced lyrics, radio/autoplay, crossfade, EQ, Chromecast, festival push | |
| **v1.2** | +4 wks | Made-for-you mixes, NK Varusha (yearly recap), collaborative playlists | |
| **v2** | later | CarPlay/Android Auto, widgets, stories/podcasts, AI mood playlists, social features, supporter tier | |

**MVP total: about 11–14 weeks.**

---

## 10. Store and compliance checklist
- iOS: `UIBackgroundModes: audio` in Info.plist; Sign in with Apple is required if you offer Google sign-in; privacy nutrition labels.
- Android: foreground media service permissions (Android 14+ `FOREGROUND_SERVICE_MEDIA_PLAYBACK`), notification permission (Android 13+).
- Apple may ask for proof of music rights. Keep consent records, the source notes and the takedown page ready.
- Privacy policy and terms (Indian DPDP Act 2023), and account deletion in the app (both stores require it).
- Content rating: all ages.

---

## 11. Success metrics
- Day-30 retention ≥ 25%; average listening ≥ 20 min/day for active users.
- Search success rate (a search followed by a play) ≥ 70%.
- Crash-free sessions ≥ 99.5%; time to first audio < 1.5 s at p75.
- Number of singers who claim profiles and approve legacy tracks within 6 months.

---

## 12. Decisions

**Decided 2026-10-27**
- Catalog: a few hundred legacy songs to start.
- Sign-in: **email** (passwordless 6-digit code through Supabase Auth). Listeners can browse before signing in.
- Approval: admins approve every song before listeners can see it.
- Backend: **Supabase + Cloudflare R2**.
- Pricing: legacy songs are **free** at launch. New songs may later move to paid tiers or subscriptions, so the `tracks` table gets a `tier` column (free | premium) from day one.
- Logo: English wordmark "Nanga Kathai" plus an "NK" mark.
- Design canvas: https://claude.ai/artifact/9ZLCbGn4rUTVTqfRXTtMkq

**Original questions**
1. **Collection size and format**: how many songs, what formats, and how much metadata already exists?
2. **Backend**: Supabase + R2 (recommended) or Firebase?
3. **Sign-in**: guest-first with optional login (recommended), or login required?
4. **Admins and curators**: who will tag songs and moderate submissions?
5. **Branding**: logo/wordmark for "Nanga Kathai / NK". Tamil-script wordmark, Latin wordmark, or both?
6. **Monetization intent**: free community app forever, donations, or a supporter tier later?

---

### Sources
- [ibaduga Mixcloud: 1,000+ Badaga songs](https://www.mixcloud.com/ibaduga/badauga/)
- [Badaga language (Wikipedia)](https://en.wikipedia.org/wiki/Badaga_language) · [Badagas (Wikipedia)](https://en.wikipedia.org/wiki/Badagas) · [Badugu script proposal (Unicode L2/22-220)](https://www.unicode.org/L2/L2022/22220-introducing-badagu-script.pdf)
- [just_audio on pub.dev](https://pub.dev/packages/just_audio) · [audio_service](https://github.com/michaelspeedcode/audio_service) · [mt_audio (CarPlay/Auto wrapper, beta)](https://pub.dev/packages/mt_audio/versions/0.2.0-beta.5)
- [Best features added to Spotify in 2026 (BGR)](https://www.bgr.com/2179163/best-features-added-spotify-2026/) · [Spotify 2026 changes (inspiredbybeatz)](https://www.inspiredbybeatz.com/spotify-2026-neue-features-aenderungen/) · [TechRadar Spotify coverage](https://www.techradar.com/tag/spotify/page/3)