Commit 433723
2026-08-07 11:31:12 admin: init| /dev/null .. 03-frontend-navigation.md | |
| @@ 0,0 1,127 @@ | |
| + | --- |
| + | title: Frontend & Navigation |
| + | aliases: [Navigation Graph, Screen Catalog] |
| + | tags: [3netra/wiki, frontend, navigation, diagrams] |
| + | product: 3netra Meta Android App |
| + | source_repository: 3Netra-ai/3n_meta_android |
| + | source_ref: origin/prod |
| + | source_revision: b48aada8fd5427b5db0c02945569963c4ae543c8 |
| + | last_verified: 2026-08-06 |
| + | up: "[[Home]]" |
| + | --- |
| + | |
| + | # Frontend & Navigation |
| + | |
| + | Single-activity Compose app. Start destination computed in `MainActivity` after Supabase session resolves: |
| + | |
| + | ``` |
| + | user == null → "login" |
| + | !permissions_asked → "permissions" |
| + | !onboarding_complete → "onboarding_welcome" |
| + | else → "main" |
| + | ``` |
| + | |
| + | ## Navigation Graph |
| + | |
| + | ```mermaid |
| + | flowchart TD |
| + | LOGIN[login<br/>LoginScreen] -->|success| PERM{permissions_asked?} |
| + | LOGIN --> SU[signup<br/>SignUpScreen] -->|verify email| LOGIN |
| + | PERM -->|no| PERMISSIONS[permissions<br/>PermissionRationaleScreen] |
| + | PERM -->|yes| ONB{onboarding_complete?} |
| + | PERMISSIONS --> ONB |
| + | ONB -->|no| OW[onboarding_welcome] --> OG[onboarding_grade<br/>legacy K–6 labels in code] --> OP[onboarding_pair<br/>BluetoothPairingScreen] |
| + | OP -->|connect or skip| MAIN |
| + | ONB -->|yes| MAIN |
| + | |
| + | MAIN["main — MainAppScreen (bottom bar)"] |
| + | |
| + | subgraph INNER["Inner NavHost (bottom tabs)"] |
| + | HOME[home_tab<br/>StudentHomeScreen] |
| + | CHAT[chat_tab<br/>AssistantChatScreen 'Be My Eyes'] |
| + | STORY[story_tab<br/>TodaysStoryScreen] |
| + | FRIENDS[classmates_tab<br/>ClassmatesScreen] |
| + | end |
| + | MAIN --> INNER |
| + | |
| + | HOME -->|quick actions| SCENE["scene_description/{mode}<br/>Scene|Read|Classroom|People|Emotions"] |
| + | HOME --> LN[lecture_notes<br/>LectureNotesScreen] |
| + | HOME --> SETTINGS[settings<br/>SettingsScreen] |
| + | SETTINGS --> COMP[companion_select<br/>CompanionSelectScreen] |
| + | FRIENDS -->|FAB + Teacher PIN| FACE[face_registration<br/>FaceRegistrationScreen] |
| + | |
| + | LEGACY["dashboard → glassesConfig / chatHistory<br/>(orphaned legacy routes)"] |
| + | ``` |
| + | |
| + | **Bottom bar (4 tabs):** Home 🏠 · Chat ✈️ · My Story ❤ · Friends 👥. Settings & Lecture Notes are pushed from Home, not tabs. |
| + | |
| + | ## Screen Catalog |
| + | |
| + | | Route | Screen | What it does | |
| + | |---|---|---| |
| + | | `login` | LoginScreen | Email/password, email OTP (6-digit), Google Sign-In | |
| + | | `signup` | SignUpScreen | First/last/email/password; email verification required | |
| + | | `permissions` | PermissionRationaleScreen | Batch request: BT scan/connect, location, camera, mic, notifications; FERPA/COPPA banner | |
| + | | `onboarding_welcome` | OnboardingWelcomeScreen | "Hi! I'm Netra." 🦉 step 1/3 | |
| + | | `onboarding_grade` | GradeSelectionScreen | Persists `student_grade`; source currently presents legacy K–6 grade labels, so it does not implement the higher-education taxonomy in this wiki | |
| + | | `onboarding_pair` | BluetoothPairingScreen | Connect/skip glasses pairing → `onboarding_complete` | |
| + | | `home_tab` | StudentHomeScreen | Greeting hero, glasses connection pill, Academic Mode toggle, 6 quick actions, voice-command receiver | |
| + | | `scene_description/{mode}` | SceneDescriptionScreen | Four mode chips; capture starts only when a chip is tapped (the first-load auto-capture is commented out). It invokes `SupabaseAiService`, whose current client returns fixed success text | |
| + | | `chat_tab` | AssistantChatScreen | Text/gallery media UI → `BluetoothService` → `SupabaseAiService`/`chat-vision`; not the AWS client | |
| + | | `story_tab` | TodaysStoryScreen | Day timeline from session history; "🔊 Read My Day Out Loud" | |
| + | | `classmates_tab` | ClassmatesScreen | Face library (Instructors/Classmates/Family sections), search, FAB → PIN-gated registration | |
| + | | `face_registration` | FaceRegistrationScreen | 2-step: name → CameraX capture → FaceNet embedding → Supabase | |
| + | | `lecture_notes` | LectureNotesScreen | Live dictation transcript (SpeechRecognizer) + "Summarize Now" | |
| + | | `companion_select` | CompanionSelectScreen | Pick guide (Netra/Cosmo/Sage/Ripple — see [[05-Avatars-Companions]]) + nickname | |
| + | | `settings` | SettingsScreen | Profile, companion, speaking speed, high contrast, reduce motion, battery saver, grade, sign out | |
| + | | `dashboard` / `glassesConfig` / `chatHistory` | legacy screens | Orphaned — no code navigates to `dashboard` | |
| + | |
| + | **Home quick actions (2×3 grid):** 🔍 What do I see? · 📖 Read this · 🏫 Classroom · 👤 Who's here? · ❤️ Feelings · 📝 Notes. |
| + | |
| + | ## Frontend Flow Chart (core capture loop) |
| + | |
| + | ```mermaid |
| + | sequenceDiagram |
| + | participant U as Student |
| + | participant H as Home/Scene Screen |
| + | participant B as BluetoothService |
| + | participant W as WearableCameraService |
| + | participant F as FaceNet + EncryptedStore |
| + | participant A as SupabaseAiService |
| + | participant L as Supabase chat-vision |
| + | participant T as Android TTS |
| + | participant S as Supabase |
| + | |
| + | U->>H: tap a scene-mode chip |
| + | H->>W: capturePhoto() |
| + | W->>W: MWDAT session → 15fps stream → photo bytes |
| + | W-->>H: ByteArray (or error "glasses connected?") |
| + | opt People / Emotions mode |
| + | H->>F: embedding → cosine vs Supabase-fetched embeddings (>0.5) |
| + | F-->>H: match → "I see {name}!" (People: done) |
| + | end |
| + | H->>A: analyzeImage(bytes, mode prompt) |
| + | A->>L: invoke chat-vision |
| + | L-->>A: model response (discarded) |
| + | A-->>H: fixed "AI response received" |
| + | H->>B: logLocalSession(mode, text) |
| + | B->>S: insert sessions row |
| + | H->>T: speak(text) via ChildVoicePersonaManager |
| + | T-->>U: audio narration |
| + | ``` |
| + | |
| + | ## State Management |
| + | |
| + | - **Auth:** `MainViewModel` StateFlow over Supabase `SessionStatus` |
| + | - **Connection / chat history:** `BluetoothService` StateFlows (`connectionState`, `chatHistory`) shared app-wide |
| + | - **Prefs (`3n_prefs`):** `permissions_asked`, `onboarding_complete`, `student_grade`, `student_nickname`, `companion_id`, `school_mode_enabled`, `tts_speed`, `high_contrast`, `reduce_motion`, `battery_saver` |
| + | - **Secure prefs:** teacher PIN (`3netra_secure`, BCrypt). `EncryptedFaceStorageManager` exists but is not called by the active face flow. |
| + | |
| + | ## Voice Command Wiring |
| + | |
| + | `VoiceCommandService` can broadcast `com.threenetra.app.VOICE_COMMAND`, and Home registers handlers. At this revision, no source path emits the documented `WHAT_DO_I_SEE`/`CLASSROOM_MODE` broadcasts or connects a DAT long-press callback; `onLongPress()` only starts the Android recognition service when invoked. See [[04-User-Journeys]]. |
| + | |
| + | --- |
| + | |
| + | > [!tip] Navigation |
| + | > ⬅️ [[02-System-Architecture|System Architecture]] · 🏠 [[Home]] · ➡️ [[04-User-Journeys|User Journeys]] |