# Software Requirements Specification (SRS) Project: Try-English — AI English Learning Platform Revision: 1.1 Date: 2025-11-27 Prepared by: Automated repository analysis --- ## Table of Contents - 1. Introduction - 2. Overall Description - 3. External Interfaces - 4. Functional Requirements - 5. Non-Functional Requirements - 6. Data Model Summary - 7. Use Cases - 8. Sequence Diagrams - 9. UI Mockups (wireframes) - 10. Test Cases - 11. Deployment and Operational Notes - 12. Glossary - 13. Appendix: Key Files & Libraries --- ## 1. Introduction ### 1.1 Purpose This document provides a comprehensive Software Requirements Specification (SRS) for Try-English, an AI-assisted web platform to teach and assess English (reading, writing, speaking). It is intended for developers, QA engineers, product owners and deployment engineers. ### 1.2 Scope Try-English is a Flask-based web application that delivers a 3-stage learning workflow (Reading, Writing, Speaking) with AI-assisted assessments, vocabulary management, user roles (Student/Teacher/Admin), progress tracking and email workflows for registration and approval. ### 1.3 References - Project repository (local): `c:\Users\SO\OneDrive - Higher Education Commission\Desktop\prot-final` - Key files: `app/config.py`, `app/__init__.py`, `app/services/ai_assessment.py`, `app/templates/*`, `requirements.txt`, `run_ngrok.py` --- ## 2. Overall Description High-level overview, target users, environment and constraints are described here. See the shortened summary in repository README; this document expands requirements with use cases, diagrams and testing scenarios. ### 2.1 Product Context Try-English is built with server-rendered templates (Jinja2) and client-side enhancements (Web Speech API). AI features optionally call external Gemini API. The application uses SQLAlchemy with SQLite by default and supports migrations via Flask-Migrate. ### 2.2 User Roles - Student: consume content, submit writing, record speaking, save vocabulary. - Teacher: create/edit topics, assign students, view analytics. - Admin: manage users, approvals, site configuration. --- ## 3. External Interfaces - Browser: modern Chrome/Edge/Firefox for TTS and recording. - SMTP server: for email (Flask-Mail). Configured in `.env`. - Optional Gemini API: `GEMINI_API_KEY` in `.env` for advanced generation and transcription. - FFmpeg executable: required for audio processing; paths configured in `app/config.py`. - Optional ngrok for exposing local server: `run_ngrok.py` available. --- ## 4. Functional Requirements (detailed) Each requirement is enumerated for traceability. - FR-001: User registration (fields: username, email, password, role). New users created with `is_approved=false`; notification email sent to admin. - FR-002: Login/Logout with `Flask-Login` and secure password hashing. - FR-003: Role-based access controls; teachers and admins can view management pages; students see assigned topics. - FR-004: Reading Stage — present reading content, TTS (client), comprehension questions (generated), progress recorded. - FR-005: Writing Stage — students submit writing; system runs grammar checks (TextBlob/LanguageTool) and returns structured feedback. - FR-006: Speaking Stage — record audio in browser, send to server as WAV/MP3; server runs FLAC/FFmpeg conversion and optionally transcribes via Gemini. - FR-007: Vocabulary Manager — CRUD for student vocabulary entries. - FR-008: Course and Topic management — short and learning courses; teachers can CRUD and order topics. - FR-009: Notifications — email templates under `app/templates/email` used for signup, approval, rejection. - FR-010: Reporting — progress and analytics in teacher/admin dashboards. - FR-011: TTS speed controls and playback behavior. For each FR, acceptance criteria are enumerated in section 10 (Test Cases). --- ## 5. Non-Functional Requirements - Performance: Page loads under 1s in local environment; AI requests have best-effort SLA depending on external API. - Security: All sensitive configuration in `.env`; CSRF protection enabled; hashing for passwords. - Maintainability: Modular Flask blueprints and services. - Availability: Deploy with WSGI server (gunicorn) and reverse proxy for production. --- ## 6. Data Model Summary Key tables and main fields (abbreviated): - `users`: id, username, email, password_hash, role, is_approved, created_at, teacher_id, streak fields. - `topics`: id, title, reading_content, writing_prompt, speaking_prompt, teacher_id, course_type. - `vocabulary`: id, student_id, word, pronunciation, definition, context, synonyms, antonyms, example. - `progress`: links student_id, topic_id, stage status, scores, timestamps. Detailed models are in `app/models/*.py`. --- ## 7. Use Cases (detailed) Use Case 1 (UC-001): Student Registration and Approval - Primary Actor: Student - Precondition: Student has access to registration page - Trigger: Student submits registration form - Main Flow: 1. Student fills registration form (username, email, password, role). 2. System stores user with `is_approved=false`. 3. System sends `new_signup` notification email to admin(s). 4. Admin receives email and approves user via admin UI. 5. System sets `is_approved=true` and sends `account_approved` email to student. 6. Student can now log in. - Alternate Flows: - If email fails, system logs error and retries; admin can manually approve. Use Case 2 (UC-002): Student completes Reading Stage - Primary Actor: Student - Preconditions: Student is enrolled and assigned topic - Main Flow: 1. Student opens reading stage page for a topic. 2. Student reads content; optionally clicks client TTS to play text. 3. System displays comprehension questions (AI generated or pre-created). 4. Student answers questions; system auto-grades simple types and records progress. 5. Student proceeds to Writing stage when reading stage completed. Use Case 3 (UC-003): Teacher creates topic and assigns to students - Primary Actor: Teacher - Main Flow: 1. Teacher navigates to topic creation UI. 2. Teacher fills title, reading content, writing prompt, speaking prompt and assigns course type. 3. System persists topic; teacher can optionally generate comprehension/speaking questions via AI. 4. Topic appears in assigned students' dashboards. Use Case 4 (UC-004): Student records speaking submission - Primary Actor: Student - Preconditions: Student on Speaking stage and microphone access allowed - Main Flow: 1. Student clicks record; browser captures audio via MediaRecorder API. 2. Audio is uploaded to server endpoint. 3. Server converts audio (FFmpeg if needed) and stores file. 4. If AI transcription enabled, server sends audio to Gemini and retrieves transcription and assessment scores. 5. System stores assessment results and provides feedback to student. --- ## 8. Sequence Diagrams The following sequence diagrams are provided in Mermaid syntax (renderable in supporting tools). ### 8.1 Registration and Approval ```mermaid sequenceDiagram participant Student participant WebApp participant Admin participant EmailServer Student->>WebApp: POST /auth/register WebApp-->>DB: create user (is_approved=false) WebApp->>EmailServer: send new_signup email to Admin EmailServer-->>Admin: deliver email Admin->>WebApp: Approve user (admin UI) WebApp-->>DB: update user is_approved=true WebApp->>EmailServer: send account_approved email to Student EmailServer-->>Student: deliver email ``` ### 8.2 Speaking Submission Flow ```mermaid sequenceDiagram participant Student participant Browser participant WebApp participant FFmpeg participant Gemini Student->>Browser: Click record Browser->>Browser: capture audio (MediaRecorder) Browser->>WebApp: POST /student/speaking/upload (audio) WebApp->>FFmpeg: convert/process audio WebApp->>DB: store audio path & submission meta WebApp->>Gemini: (optional) send audio for transcription/assessment Gemini-->>WebApp: transcription + scores WebApp-->>DB: store assessment results WebApp-->>Browser: return feedback ``` --- ## 9. UI Mockups (wireframes) Below are textual wireframes describing critical screens. For printable PDF, replace with images/screenshots if available. ### 9.1 Landing / Course Selection - Two cards: Short Courses (blue) and Learning Courses (green), each with title, short description and CTA. ### 9.2 Student Dashboard - Header: user info, quick links. Main area: assigned topics, progress cards, daily dictionary with TTS. ### 9.3 Reading Stage - Left: reading text with pagination. Right: TTS controls (speed) and progress bar. Below: comprehension questions. ### 9.4 Writing Stage - Editor area with word count and submit button. After submit: AI feedback panel with grammar suggestions and score. ### 9.5 Speaking Stage - Recording controls (record/pause/stop), visualization (waveform), submit button, and results/feedback panel. --- ## 10. Test Cases (Representative) TC-001: Registration flow - Steps: Fill registration form -> submit -> verify user created with `is_approved=false` -> check admin email - Expected: user exists; admin receives `new_signup` email TC-002: Approval flow - Steps: Admin approves user -> verify `is_approved=true` and student receives `account_approved` email - Expected: student can log in TC-003: Reading stage progression - Steps: Access topic -> play TTS -> answer questions -> complete stage - Expected: progress record saved; next stage unlocked TC-004: Writing assessment - Steps: Submit a writing sample -> receive grammar suggestions and a score - Expected: feedback contains grammar edits and a numeric score TC-005: Speaking submission (audio) - Steps: Record in browser -> upload -> server stores file -> (if enabled) AI returns transcription - Expected: uploaded file present on server; transcription result recorded when enabled TC-006: Vocabulary CRUD - Steps: Add word -> edit word -> delete - Expected: DB reflects changes --- ## 11. Deployment and Operational Notes - Local development: `python -m venv`, `pip install -r requirements.txt`, set `.env` and run `flask run` or `python run.py`. - FFmpeg: required. `app/config.py` expects Windows path `ffmpeg/ffmpeg.exe` by default in repo. - Expose local server via `run_ngrok.py` (script included) or `ngrok.exe` directly. - Production: Deploy behind reverse proxy (Nginx) with `gunicorn` workers and persistent database. --- ## 12. Glossary - TTS: Text-to-Speech - AI: Artificial Intelligence (Gemini) - FFmpeg: multimedia processing utility - DB: Database --- ## 13. Appendix: Key Files & Libraries - `requirements.txt` — dependency manifest - `app/config.py` — configuration (FFmpeg, GEMINI key, mail) - `app/__init__.py` — app factory and extension initialization - `app/services/ai_assessment.py` — AI generation and assessment logic - `run_ngrok.py` — helper to start ngrok for HTTPS tunneling (dev) - `app/templates/` — UI templates --- End of SRS document.