duct-tape2/ai-language-partner

mobile: document mock mode indicators

Open

#16 opened on Jul 8, 2026

View on GitHub
 (2 comments) (0 reactions) (0 assignees)TypeScript (2 forks)auto 404
docsfirst-timers-onlygood first issuehelp wantedmobileup-for-grabs

Repository metrics

Stars
 (2 stars)
PR merge metrics
 (PR metrics pending)

Description

Goal

Document exactly how the mobile app signals fixture-backed mock mode versus API-backed real mode, including the important distinction between the selected mode and actual backend health.

Scope

  • Edit only docs/ARCHITECTURE.md.
  • Add a short subsection near Runtime data flow or the mobile module map.
  • Explain the source-of-truth switch: USE_MOCK is true unless EXPO_PUBLIC_USE_MOCK_API=false.
  • Document these visible indicators:
    • Daily Talk shows STRINGS.dailyTalk.demoBadge in mock mode and STRINGS.dailyTalk.liveBadge in real mode.
    • Courses shows 학습 코스 (오프라인 미리보기) in mock mode.
    • Settings shows the raw API mode, base URL, and health check only when SHOW_DEV_TOOLS is enabled in a development build; this panel is not an end-user production indicator.
  • Document the behavior behind the labels:
    • Mock mode returns shared fixtures immediately and loads the bundled dialogue pack, with device TTS used when fixture audio is absent.
    • Real mode attempts API_BASE. Read-style calls may use their checked-in fixture fallback after network or HTTP failure.
    • Mutations or personal-data calls marked noFallbackInReal surface the error instead of pretending fixture-backed success.
  • State explicitly that the liveBadge reports the selected client mode; it does not by itself prove the backend or a local STT/TTS engine is healthy. The development health check is the separate diagnostic.
  • Use apps/mobile/src/api/client.ts, apps/mobile/src/devConfig.ts, apps/mobile/src/screens/DailyTalkScreen.tsx, apps/mobile/src/screens/CoursesScreen.tsx, and apps/mobile/src/screens/SettingsScreen.tsx as read-only sources of truth.
  • Do not change application code, translations, screenshots, generated Pages files, or other docs.

Acceptance Criteria

  • A small table or equivalent compact section distinguishes mock, real with healthy API, and real with a read fallback.
  • Every documented label and fallback statement matches current source behavior.
  • The documentation does not imply that selecting real mode guarantees a live speech engine.
  • The PR changes only docs/ARCHITECTURE.md and includes Closes #16.

Suggested Verification

This is a browser-editable docs task. No Expo, backend, speech engine, or API key is required.

python3 scripts/check_public_tree.py
git diff --check

Direct edit link: https://github.com/duct-tape2/ai-language-partner/edit/main/docs/ARCHITECTURE.md

Contributor guide