Spoken English Class App

🏗️ System Components

📦 Recommended Stack

🗄️ Full Schema

-- Students table
CREATE TABLE students (
  id         INT PRIMARY KEY AUTO_INCREMENT,
  name       VARCHAR(100) NOT NULL,
  email      VARCHAR(150) UNIQUE,
  phone      VARCHAR(15) UNIQUE,
  password   VARCHAR(255),      -- bcrypt hash
  batch      VARCHAR(50),       -- e.g. 'Batch A - Morning'
  is_active  TINYINT DEFAULT 1,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Tutorial videos (YouTube)
CREATE TABLE tutorials (
  id           INT PRIMARY KEY AUTO_INCREMENT,
  title        VARCHAR(200) NOT NULL,
  description  TEXT,
  youtube_url  VARCHAR(500) NOT NULL, -- full URL or video ID
  thumbnail    VARCHAR(500),            -- optional custom thumbnail
  category     VARCHAR(100),           -- e.g. 'Grammar', 'Pronunciation'
  sort_order   INT DEFAULT 0,
  is_published TINYINT DEFAULT 1,
  created_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Reading materials (Google Drive links)
CREATE TABLE materials (
  id          INT PRIMARY KEY AUTO_INCREMENT,
  title       VARCHAR(200) NOT NULL,
  description TEXT,
  drive_url   VARCHAR(500) NOT NULL,
  file_type   ENUM('PDF', 'DOC', 'SHEET', 'SLIDE', 'OTHER') DEFAULT 'PDF',
  category    VARCHAR(100),
  sort_order  INT DEFAULT 0,
  is_published TINYINT DEFAULT 1,
  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Assignments (Google Forms)
CREATE TABLE assignments (
  id           INT PRIMARY KEY AUTO_INCREMENT,
  title        VARCHAR(200) NOT NULL,
  description  TEXT,
  form_url     VARCHAR(500) NOT NULL,  -- Google Form link
  due_date     DATE,
  max_marks    INT,
  is_published TINYINT DEFAULT 1,
  created_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- AI correction history (optional, for your records)
CREATE TABLE ai_corrections (
  id              INT PRIMARY KEY AUTO_INCREMENT,
  student_id      INT,
  original_text   TEXT,
  corrected_text  TEXT,
  created_at      TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  FOREIGN KEY (student_id) REFERENCES students(id)
);

📁 Project Structure

spoken-english-api/
├── src/
│   ├── routes/
│   │   ├── auth.js          # login, register
│   │   ├── tutorials.js     # GET /tutorials
│   │   ├── materials.js     # GET /materials
│   │   ├── assignments.js   # GET /assignments
│   │   ├── ai.js            # POST /ai/correct
│   │   └── admin.js         # all CRUD for admin panel
│   ├── middleware/
│   │   ├── auth.js          # JWT verify middleware
│   │   └── adminAuth.js     # admin-only middleware
│   ├── db.js                # MySQL connection pool
│   └── app.js               # Express app setup
├── .env
├── package.json
└── server.js

⚙️ server.js + db.js

// server.js
const app = require('./src/app');
app.listen(3000, () => console.log('API running on port 3000'));

// src/db.js
const mysql = require('mysql2/promise');
const pool = mysql.createPool({
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASS,
  database: process.env.DB_NAME,
  waitForConnections: true,
  connectionLimit: 10
});
module.exports = pool;

// .env
DB_HOST=localhost
DB_USER=root
DB_PASS=yourpassword
DB_NAME=spoken_english
JWT_SECRET=your_jwt_secret_here
GROK_API_KEY=your_grok_api_key_here
ADMIN_USERNAME=admin
ADMIN_PASSWORD_HASH=bcrypt_hash_here

🔗 API Routes Reference

📦 pubspec.yaml — Required Packages

dependencies:
  flutter:
    sdk: flutter

  # HTTP
  dio: ^5.4.0
  flutter_secure_storage: ^9.0.0    # store JWT safely

  # YouTube player
  youtube_player_flutter: ^8.1.2    # plays YT videos in-app

  # Open Drive links in browser
  url_launcher: ^6.2.5

  # Open Google Forms in WebView
  webview_flutter: ^4.7.0

  # State management
  provider: ^6.1.2                  # or use Riverpod

  # UI helpers
  cached_network_image: ^3.3.1
  shimmer: ^3.0.0                   # loading skeleton

📂 App Folder Structure

lib/
├── main.dart
├── core/
│   ├── api_client.dart        # Dio setup with JWT interceptor
│   └── constants.dart         # base URL, colors
├── models/
│   ├── tutorial.dart
│   ├── material.dart
│   └── assignment.dart
├── screens/
│   ├── login_screen.dart
│   ├── home_screen.dart        # bottom nav container
│   ├── tutorials/
│   │   ├── tutorials_list.dart
│   │   └── tutorial_player.dart
│   ├── materials/
│   │   ├── materials_list.dart
│   │   └── material_viewer.dart # opens drive in-app browser
│   ├── assignments/
│   │   ├── assignments_list.dart
│   │   └── assignment_form.dart # webview for Google Form
│   └── ai_correct/
│       └── ai_correct_screen.dart
└── widgets/
    ├── tutorial_card.dart
    ├── material_card.dart
    └── assignment_card.dart

🧭 Bottom Navigation Structure

// home_screen.dart
final screens = [
  TutorialsListScreen(),    // Tab 1: 🎬 Tutorials
  MaterialsListScreen(),    // Tab 2: 📚 Materials
  AssignmentsListScreen(),  // Tab 3: 📝 Assignments
  AiCorrectScreen(),        // Tab 4: 🤖 AI Correct
];

BottomNavigationBar(
  items: [
    BottomNavigationBarItem(icon: Icon(Icons.play_circle), label: 'Tutorials'),
    BottomNavigationBarItem(icon: Icon(Icons.menu_book), label: 'Materials'),
    BottomNavigationBarItem(icon: Icon(Icons.assignment), label: 'Assignments'),
    BottomNavigationBarItem(icon: Icon(Icons.auto_fix_high), label: 'AI Correct'),
  ],
)

▶️ How Unlisted YouTube Videos Work in App

You upload videos to YouTube as Unlisted. The URL is not searchable — only people with the link can watch. You store that URL/video ID in your admin panel. The Flutter app plays it with youtube_player_flutter directly inside the app — no redirect to YouTube app needed.

🎬 Tutorial Player Screen

// tutorial_player.dart
import 'package:youtube_player_flutter/youtube_player_flutter.dart';

class TutorialPlayerScreen extends StatefulWidget {
  final Tutorial tutorial;

  String extractVideoId(String url) {
    // Extracts video ID from full YouTube URL
    return YoutubePlayer.convertUrlToId(url) ?? url;
  }

  @override
  _state createState() {
    final videoId = extractVideoId(widget.tutorial.youtubeUrl);
    final controller = YoutubePlayerController(
      initialVideoId: videoId,
      flags: const YoutubePlayerFlags(
        autoPlay: true,
        mute: false,
        enableCaption: true,
      ),
    );

    // In build():
    return YoutubePlayerBuilder(
      player: YoutubePlayer(controller: controller),
      builder: (context, player) => Scaffold(
        appBar: AppBar(title: Text(widget.tutorial.title)),
        body: Column(children: [
          player,
          Padding(
            padding: const EdgeInsets.all(16),
            child: Text(widget.tutorial.description),
          )
        ]),
      ),
    );
  }
}

🔑 Admin Panel — Add Tutorial

In your admin panel, you paste the full YouTube URL. The backend stores it. The app extracts the video ID automatically using YoutubePlayer.convertUrlToId().

Supported URL formats: https://youtu.be/VIDEO_ID or https://www.youtube.com/watch?v=VIDEO_ID

📄 How Drive Links Work

You share Google Drive files with "Anyone with the link can view" permission. Paste the share link in admin panel. The app opens the file using one of two strategies:

• In-App WebView — opens the Drive preview page inside the app using webview_flutter. Students stay in the app.
• url_launcher — opens in the device browser. Simpler but leaves the app.

Recommendation: Use WebView for PDFs — students stay in your app experience.

🌐 Drive WebView Viewer

// material_viewer.dart
import 'package:webview_flutter/webview_flutter.dart';

class MaterialViewerScreen extends StatefulWidget {
  final LearningMaterial material;

  @override
  State createState() {
    // Convert share URL to direct viewer URL
    // From: https://drive.google.com/file/d/FILE_ID/view?usp=sharing
    // To:   https://drive.google.com/file/d/FILE_ID/preview
    String getPreviewUrl(String driveUrl) {
      final uri = Uri.parse(driveUrl);
      final pathParts = uri.pathSegments; // ['file','d','FILE_ID','view']
      if (pathParts.contains('d')) {
        final fileId = pathParts[pathParts.indexOf('d') + 1];
        return 'https://drive.google.com/file/d/$fileId/preview';
      }
      return driveUrl; // fallback
    }

    final controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..loadRequest(Uri.parse(getPreviewUrl(material.driveUrl)));

    return Scaffold(
      appBar: AppBar(title: Text(material.title)),
      body: WebViewWidget(controller: controller),
    );
  }
}

📝 How Forms Work in the App

You create a Google Form. Students can submit their responses. You copy the form link from admin panel. The app opens it in a WebView — students complete the form inside the app.

🌐 Assignment Form WebView

// assignment_form.dart
class AssignmentFormScreen extends StatefulWidget {
  final Assignment assignment;

  @override
  State createState() {
    // Replace /edit with /viewform for clean submission URL
    String getFormUrl(String url) {
      return url
        .replaceAll('/edit', '/viewform')
        .replaceAll('/closedform', '/viewform');
    }

    final controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..loadRequest(Uri.parse(getFormUrl(assignment.formUrl)));

    return Scaffold(
      appBar: AppBar(title: Text(assignment.title)),
      body: WebViewWidget(controller: controller),
    );
  }
}

🤖 Backend Proxy Route (Node.js)

The Flutter app sends the student's sentence to YOUR backend. Your backend forwards it to Grok API (with your secret key). Response comes back to app. Key is never exposed to app.

// src/routes/ai.js
const express = require('express');
const axios = require('axios');
const authMiddleware = require('../middleware/auth');
const router = express.Router();
const db = require('../db');

router.post('/correct', authMiddleware, async (req, res) => {
  const { sentence } = req.body;

  if (!sentence || sentence.trim().length === 0) {
    return res.status(400).json({ error: 'Sentence is required' });
  }

  const prompt = `You are an English teacher. A student wrote:
"${sentence}"

Please:
1. Correct any grammar, spelling, or punctuation errors.
2. Provide the corrected sentence.
3. Explain each mistake briefly in simple English.
4. Give 1-2 better alternative ways to say the same thing.

Format your response as JSON:
{
  "corrected": "...",
  "mistakes": ["mistake 1", "mistake 2"],
  "alternatives": ["alt 1", "alt 2"]
}`;

  try {
    const response = await axios.post(
      'https://api.x.ai/v1/chat/completions',
      {
        model: 'grok-3',
        messages: [{ role: 'user', content: prompt }],
        temperature: 0.3,
        max_tokens: 500,
      },
      {
        headers: {
          'Authorization': `Bearer ${process.env.GROK_API_KEY}`,
          'Content-Type': 'application/json',
        },
      }
    );

    const content = response.data.choices[0].message.content;
    const cleanJson = content
      .replace(/```json/g, '')
      .replace(/```/g, '')
      .trim();
    const parsed = JSON.parse(cleanJson);

    // Save to history (optional)
    await db.execute(
      'INSERT INTO ai_corrections (student_id, original_text, corrected_text) VALUES (?,?,?)',
      [req.studentId, sentence, parsed.corrected]
    );

    res.json(parsed);
  } catch (err) {
    console.error(err);
    res.status(500).json({ error: 'AI correction failed' });
  }
});

module.exports = router;

📱 Flutter AI Correct Screen

// ai_correct_screen.dart
class AiCorrectScreen extends StatefulWidget {
  final controller = TextEditingController();
  Map<String, dynamic>? result;
  bool isLoading = false;

  Future<void> correctSentence() async {
    setState(() => isLoading = true);
    final response = await ApiClient.instance.post('/ai/correct', {
      'sentence': controller.text
    });
    setState(() {
      result = response.data;
      isLoading = false;
    });
  }

  // UI in build():
  Column(children: [
    TextField(
      controller: controller,
      maxLines: 4,
      decoration: InputDecoration(
        hintText: 'Type your English sentence here...',
        border: OutlineInputBorder(),
      ),
    ),
    ElevatedButton(
      onPressed: correctSentence,
      child: Text('Check & Correct'),
    ),
    if (result != null) ...[
      Card(child: Column(children: [
        Text('✅ Corrected: ${result!["corrected"]}'),
        Text('📌 Mistakes:'),
        ...(result!['mistakes'] as List)
          .map((m) => Text('• $m')),
        Text('💡 Alternatives:'),
        ...(result!['alternatives'] as List)
          .map((a) => Text('→ $a')),
      ])),
    ]
  ])
}

🖥️ Admin Panel Pages

• Login — Single admin login (hardcoded credentials or env var, not in DB)
• Tutorials — List with Add/Edit/Delete. Fields: Title, Description, YouTube URL, Category, Sort Order, Published toggle
• Materials — Same pattern. Fields: Title, Description, Google Drive URL, File Type, Category
• Assignments — Fields: Title, Description, Google Form URL, Due Date, Max Marks
• Students — View registered students, activate/deactivate, reset password

🔐 Admin Auth Strategy

// adminAuth.js middleware
module.exports = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1];
  const decoded = jwt.verify(token, process.env.JWT_SECRET);
  if (!decoded.isAdmin) {
    return res.status(403).json({ error: 'Admin access only' });
  }
  next();
};

// Admin login route — no DB needed, use env vars
router.post('/admin/login', (req, res) => {
  const { username, password } = req.body;
  if (
    username === process.env.ADMIN_USERNAME &&
    bcrypt.compareSync(password, process.env.ADMIN_PASSWORD_HASH)
  ) {
    const token = jwt.sign(
      { isAdmin: true },
      process.env.JWT_SECRET,
      { expiresIn: '12h' }
    );
    res.json({ token });
  } else {
    res.status(401).json({ error: 'Invalid credentials' });
  }
});

🔑 Student Login Flow

// POST /auth/login
router.post('/login', async (req, res) => {
  const { email, password } = req.body;
  const [rows] = await db.execute(
    'SELECT * FROM students WHERE email = ? AND is_active = 1',
    [email]
  );
  if (!rows.length || !bcrypt.compareSync(password, rows[0].password)) {
    return res.status(401).json({ error: 'Invalid credentials' });
  }
  const student = rows[0];
  const token = jwt.sign(
    { studentId: student.id, name: student.name },
    process.env.JWT_SECRET,
    { expiresIn: '30d' }
  );
  res.json({ token, name: student.name });
});

// JWT auth middleware
// src/middleware/auth.js
module.exports = (req, res, next) => {
  try {
    const token = req.headers.authorization.split(' ')[1];
    const decoded = jwt.verify(token, process.env.JWT_SECRET);
    req.studentId = decoded.studentId;
    next();
  } catch {
    res.status(401).json({ error: 'Unauthorized' });
  }
};

👥 Student Onboarding Options

You have two options for how students get accounts:

• Option A — You create accounts manually: In admin panel, you add student name, email, phone and set a password. Share credentials with students. Simplest for a small class.
• Option B — Self registration with approval: Students register in app. You approve them in admin panel. More scalable but requires moderation.

💰 Monthly Cost Breakdown

🏪 Google Play Store — One-Time Cost

📋 Google Licences & Permissions Needed

📱 AndroidManifest.xml — Required Permissions

<!-- android/app/src/main/AndroidManifest.xml -->
<manifest>
  <uses-permission android:name="android.permission.INTERNET"/>
  <!-- For opening Drive/Forms in WebView -->
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

  <application
    android:usesCleartextTraffic="true"   <!-- only if API is HTTP not HTTPS -->
    android:networkSecurityConfig="@xml/network_security_config"
    ...
  >
</manifest>

🚀 Implementation Timeline

• 1

  Database & Backend API (3–4 days)

  Create MySQL schema, set up Node.js project, implement all routes with JWT auth, test with Postman.

• 2

  Admin Panel React App (2–3 days)

  CRUD pages for tutorials, materials, assignments. Simple login. Deploy alongside backend on OCI VM.

• 3

  Flutter App — Auth + Navigation (1–2 days)

  Login screen, JWT storage, bottom nav, API client with interceptor.

• 4

  Tutorials + Materials + Assignments screens (2–3 days)

  YouTube player integration, Drive WebView, Forms WebView.

• 5

  Grok AI Sentence Correction (1 day)

  Backend proxy route + Flutter UI with result display.

• 6

  Testing + APK Build + Distribution (1–2 days)

  Test on real device, build release APK, share via WhatsApp or upload to Play Store.