Skip to content

Requirements and Specifications

Jump to bottom
Jaewoong Choi edited this page Dec 7, 2025 · 14 revisions

Project: LingoFit

1. Document Revision History

Version Date Description
V 1.0 2025-10-05 Initial release of requirements specification.
V 1.1 2025-10-18 Iteration 2: User Interface requirements update.
V 1.2 2025-11-02 Iteration 3: User Interface requirements update.
V 1.3 2025-11-16 Iteration 4: UI/UX revisions following heuristic evaluation.
V 1.4 2025-11-30 Iteration 5: Unification of Diagram Design and Tone.

2. Project Abstract

2.1 Context & Motivation

The landscape of English education in South Korea is shifting from a traditional focus on grammar and reading toward practical communication skills. This transition is driven by the Ministry of Education's 2025 revised curriculum, which emphasizes communicative competence and increases the weight of speaking assessments. Consequently, there is a growing demand for effective listening and speaking practice tools.

2.2 The LingoFit Solution

LingoFit leverages the widespread adoption of mobile learning and AI personalization to address the gap in foundational listening skills. By providing AI-generated audio content tailored to the user's proficiency level and interests, LingoFit offers a low-pressure, non-intrusive learning experience. This approach allows users to practice daily during commutes or downtime, directly supporting the national goal of enhanced communicative competence.

3. Customer Segments

Segment Description Needs & Goals
Casual Learner Students or professionals with limited dedicated study time. Needs: Flexible, bite-sized practice tools.
Goal: Maintain or improve basic listening skills during daily "downtime" (commutes, breaks).
Dedicated Learner Individuals preparing for exams (TOEFL/IELTS) or career advancement. Needs: High-relevance, industry-specific content.
Goal: Intensive, focused practice to achieve measurable proficiency gains.

4. Competitive Landscape

The following analysis contrasts LingoFit's architecture against key competitors in the Korean market. While services like Speak utilize high-end AI, they focus on Output (Speaking). LingoFit dominates the Input (Listening) niche by utilizing granular, implicit signals that standard apps ignore.

Technical Feature EBS Smart Listening Duolingo Speak LingoFit
Decoupled Level Evaluation
(Lexical vs. Syntactic) 		❌
(Single Grade Level) 		❌
(Linear Progression) 		⚠️
(Adaptive but unified) 		✅
(Can mix C1 Vocab + A2 Grammar)
Implicit Adaptation
(Pause/Rewind Analysis) 		❌
(Explicit Quiz Scores only) 		❌
(Right/Wrong answers) 		❌
(Speech accuracy) 		✅
(Adapts to behavioral friction)
Context-Locked Dictionary
(LLM-generated Definition) 		⚠️
(Generic Lemma Lookup) 		⚠️
(Generic Translation) 		⚠️
(Context-aware translation) 		✅
(Definitions generated for specific sentence)
Passive-First Design
(Hands-Free) 		⚠️
(Requires focus) 		❌
(Requires screen interaction) 		❌
(Requires active speaking) 		✅
(Full narrative audio)

Core Differentiators (Technical Breakdown)

1. Dual-Targeting Generation Pipeline

Most competitors use a single "Difficulty" metric (e.g., "Intermediate"). LingoFit's Generation Pipeline explicitly decouples Lexical (Vocabulary) and Syntactic (Grammar) levels.

  • The Advantage: We can generate content with "Advanced Vocabulary (C1)" but "Simple Sentence Structures (A2)". This allows users to acquire high-level industry terms without getting lost in complex grammar—a nuance impossible in standard linear curriculums.
  • Implementation: The LLM prompt injects strict statistical tables (Average Sentence Length & Word Frequency %) to force adherence to specific CEFR targets.

2. Implicit Behavioral Feedback Loop

Standard apps rely on explicit user input (e.g., "Was this hard?" or quiz scores). LingoFit captures implicit friction signals during the passive listening session.

  • The Advantage: Users often overestimate their ability or skip feedback. By tracking Pause Counts (processing difficulty) and Rewind Counts (missed information) separately, our 6x3 Weight Matrix adjusts the specific difficulty dimension (Speed vs. Syntax) that caused the struggle, without user intervention.

3. Context-Locked Dictionary

Standard dictionaries look up the "base form" (lemma) of a word (e.g., clicking "running" shows "run").

  • The Advantage: LingoFit saves the Exact Form and generates a definition specific to that exact sentence context (e.g., distinguishing "Bank" as a river edge vs. a financial institution). This prevents the "dictionary disconnect" often found in generic translation tools.

5. Functional Requirements (User Stories)

ID Role Feature User Story / Rationale Acceptance Criteria
FR-01 Learner Personalized Audio As a learner, I want personalized AI audio tracks daily so that my practice stays relevant.
(Rationale: Consistency depends on relevance.) 		1. User sets level/interests.
2. Daily refresh generates new track.
3. Audio matches user profile.
FR-02 Growing User Level Adjustment As a growing user, I want to update my level/interests so the content evolves with me.
(Rationale: Adapting to user growth.) 		1. Navigate to 'Statistics'.
2. Retake placement test.
3. System updates profile immediately.
FR-03 User Interactive Transcript As a user, I want to tap words for definitions so I can learn without leaving the app.
(Rationale: Unbroken immersion.) 		1. Tap word in transcript.
2. Audio pauses.
3. Pop-up shows definition & example.
FR-04 Active Learner Vocabulary Saving As a learner, I want to save words with context so I can review them later.
(Rationale: Context aids retention.) 		1. Tap "Save" on word pop-up.
2. Word appears in Vocab tab.
3. Entry includes original sentence.
FR-05 Motivated User Progress Tracking As a user, I want to see my study streaks so I stay motivated.
(Rationale: Visualizing effort.) 		1. Dashboard shows total minutes.
2. Streak counter increments daily.

6. User Interface Specifications

6.1 Overall UI Flow

The following diagram illustrates the complete user navigation path through the application, detailing the transitions between the Authentication, Onboarding, and Main Application layers.

LingoFit


Global Failure Handling:

  • Authentication Failure: If login or signup requests return a 401/400 error, the system displays a distinct error message (e.g., "Login failed. Please check your username or password.").
  • Generation Failure: If the AI service fails to generate audio (503 error), a modal appears: "Audio generation failed. Please try again." with a retry action.
  • Network Interruptions: If the internet connection drops during playback, the player pauses automatically and displays a toast notification: "Connection lost. Attempting to reconnect…"

6.2 Authentication Module

6.2.1 Login Page

The login interface serves as the primary entry point for registered users. It includes logic for persistent session management, enabling auto-login for users with valid tokens.

login-portrait


  • Functionality: Authenticates the user against the backend API. Upon success, stores the Access/Refresh tokens securely.
  • UI Components & Interactions:
    • Username Input: Text field for user ID entry.
    • Password Input: Masked text field for secure password entry.
    • Login Button: Triggers the validation and API request.
  • Error Handling:
    • Invalid Credentials: Displays "Incorrect username or password."
    • Server Unreachable: Displays "Unable to connect. Please try again later."
  • State Transition:
    • On Success $\rightarrow$ Home Screen

6.2.2 Signup Page

The registration interface allows new users to create an account. It performs client-side validation before submitting data to the server.

signup-portrait


  • Functionality: Registers a new user account with a unique username (/api/v1/auth/signup).
  • User Inputs:
    • Nickname: Display name for personalization.
    • Username: Unique identifier (alphanumeric).
    • Password: Masked text field (min 8 chars, must include numbers).
    • Confirm Password: Must match the Password Input exactly.
    • Sign Up Button: Submits the registration form.
  • Failure Case:
    • If username exists, show: "Username already taken."
    • If passwords do not match, show: "Passwords do not match."
  • Transitions:
    • On Success $\rightarrow$ Login Page $\rightarrow$ Home Screen

6.3 Onboarding Survey Module

6.3.1 Welcome & Level Assessment

This multi-step wizard initializes the user's profile. It captures the user's self-assessed CEFR level to seed the initial algorithm.

welcome-portrait     level_assessment-portrait


  • Functionality: Presents the application value proposition and captures the initial listening proficiency.
  • User Inputs:
    • Radio Group (5 Levels): Options ranging from "Beginner (A1)" to "Native Speaker (C2)".
    • Navigation Buttons: Start and Next.
  • Validation:
    • Users cannot proceed without selecting a level option (Show toast: "Please select a level").

6.3.2 Diagnostic Listening Test

An optional but recommended step where users listen to a sample audio track to verify their actual comprehension level.

diagnostic_start-portrait     diagnostic_test-portrait     diagnostic result


  • Functionality: Plays a standard audio clip corresponding to the selected level. The user rates their understanding using a slider.
  • User Inputs:
    • Audio Player: Simple Play/Pause controls for the sample track.
    • Comprehension Slider: Continuous slider (0-100%) visualizing the user's confidence.
    • Action Buttons: Take Test to start or Skip to bypass.
  • Failure Case:
    • If audio fails to load, show: "Audio failed to load. Please check network."
  • Transitions:
    • Steps n through n+1 (Test progression).

6.3.3 Topic Preference

The final step of onboarding where users select themes to personalize their daily content generation.

topic-portrait     walkthrough page


  • Functionality: Updates the user's interest vector in the database (/api/v1/user/me/interests).
  • User Inputs:
    • Multi-Select Chips: Grid of topics categorized by "Personal Stories", "Lifestyle", "Culture", and "News".
    • Selection Counter: Visual indicator (e.g., "0/3 Selected").
    • Complete Button: Finalizes onboarding.
  • Transitions:
    • On Complete $\rightarrow$ Home Screen

6.4 Main Application Features

6.4.1 Home Screen

The central hub providing access to the core features and navigation tabs.

home-screen


  • Functionality: Displays the user's current status and provides the primary call-to-action for learning.
  • User Inputs:
    • Topic/Style Selectors: Users pick the specific theme (e.g., Philosophy) and Tone (e.g., Speech) for the current session.
    • "Create My Audio" Button: Triggers the AI generation pipeline via WebSocket.
    • Bottom Navigation: Access to History, Vocabulary, and Settings.
  • Failure Case:
    • If generation service is down (503), show a Retry Modal.
  • Transitions:
    • "Create Audio" $\rightarrow$ Listening Session

6.4.2 Listening Session (Player) & Exit

The core learning interface featuring synchronized audio and text.

listening screen     exit confirmation     session completed


  • Functionality: Streams the AI-generated audio content while displaying the interactive transcript. The currently spoken sentence is highlighted.
  • User Inputs:
    • Interactive Text: Tappable words for dictionary lookup.
    • Player Controls: Play, Pause, Seek bar.
    • Back Button: Triggers the Exit Confirmation Modal.
  • Exit Logic:
    • Exit Modal: Warns the user "Progress will not be saved."
    • Destructive Action: "Exit" (Red) discards the session.
    • Cancel Action: "Continue" (White) returns to the player.

6.4.3 Contextual Dictionary (Lookup & Save)

A modal interface that appears when a user interacts with the transcript to bridge lexical gaps.

dictionary pop-up     vocab saved


  • Functionality: Pauses audio playback and fetches the definition of the tapped word. It provides the translation relevant to the specific context of the sentence.
  • User Inputs:
    • Definition Card: Shows word, part of speech, and meaning.
    • Bookmark Icon: Tapping this saves the word and the entire current sentence to the vocabulary list.
    • Visual Feedback: The icon turns blue to indicate the word is saved.
  • Failure Case:
    • If lookup fails (404/500), show: "Word details unavailable."

6.4.4 Session Feedback & History

After completion, the system closes the feedback loop to refine the user's proficiency model.

feedback screen     history screen


  • Functionality:
    • Feedback Form: Collects explicit signals on difficulty (Comprehension/Speed) to update the user's level via the Level Management System.
    • History List: Displays a log of all previously generated audios, allowing users to replay past content.
  • User Inputs:
    • Likert Scale: 5-point rating for difficulty.
    • Play Button (History): Re-opens the player with the selected old session.
  • Transitions:
    • On Feedback Submit $\rightarrow$ Home Screen (Level Updated)

6.5 Data & Settings Modules

6.5.1 Vocabulary Screen

A repository of all saved learning materials.

vocabulary screen


  • Functionality: Lists saved words with their definitions and the original example sentences from the audio.
  • User Inputs:
    • Context Playback: "Listen to Example" button plays the specific sentence audio.
    • Delete: Trash icon removes the word from the list.
  • Failure Case:
    • If list fails to load, show: "Error loading vocabulary."

6.5.2 Statistics Screen

The gamification hub designed to drive retention through visual progress tracking.

level update     stats screen


  • Functionality:
    • Proficiency Radar: Displays the user's current CEFR level (e.g., B1) across three dimensions: Vocabulary, Grammar, Listening.
    • Weekly Activity: Bar chart showing study time (minutes per day).
    • Badges: Grid of unlocked achievements.
    • Level Update Modal: Appears after feedback to show exact point gains (e.g., $\uparrow$ 7.4).

6.5.3 Profile & Settings

Central management for account security and data privacy.

profile screen


  • Functionality: Provides access to authentication management and data deletion.
  • User Inputs:
    • Logout: Triggers confirmation modal before clearing tokens.
    • Delete Account: High-friction action to permanently remove user data (/api/v1/auth/delete-account).

Clone this wiki locally