NeuroRead

A comprehensive dyslexia-friendly reading and learning application designed to make text content more accessible through AI-powered text simplification, OCR, and specialized intervention tools.

Table of Contents

• Overview
• Features
• Architecture
• Technology Stack
• Installation
  • Prerequisites
  • Backend Setup
  • Frontend Setup
• Configuration
• Usage
• API Documentation
• Project Structure
• Development
• Machine Learning Model
• Contributing
• License

Overview

NeuroRead is an assistive technology application specifically designed for individuals with dyslexia. It combines multiple features to enhance reading comprehension and provide targeted learning interventions:

• Intelligent Text Simplification: Uses a fine-tuned BART model to convert complex text into dyslexia-friendly summaries
• OCR Capabilities: Extract text from images and documents using EasyOCR
• Reading Practice: Speech-to-text analysis with detailed performance metrics
• Phonics Lessons: Interactive flashcards for grapheme-phoneme correspondence
• Spelling Practice: Auditory spelling exercises with immediate feedback
• Typing Practice: Speed and accuracy improvement exercises
• Progress Tracking: Comprehensive statistics and historical performance data
• Customizable Reading Interface: Adjustable font, spacing, themes, and text-to-speech

Features

Core Reading Features

Text Simplification

• AI-powered text simplification using fine-tuned BART-Large-CNN model
• Converts complex sentences into shorter, more comprehensible text
• Real-time processing through backend API
• Maintains meaning while reducing cognitive load

Adaptive Reader Interface

• Font Options: Standard fonts or OpenDyslexic font
• Customizable Spacing: Adjustable line spacing and paragraph spacing
• Font Size Control: Variable text size (12-32px)
• Theme Support: Light and dark mode
• Text-to-Speech: Built-in audio narration with word-level highlighting
• Chunked Reading: Text split into manageable sentence segments
• Short Line Width: Optional narrow column layout for easier tracking

OCR Integration

• Extract text from images via camera or photo library
• Support for PDF and plain text document imports
• Powered by EasyOCR with English language support
• Direct integration with simplification pipeline

Intervention Modules

Reading Practice

• Record audio of reading target text
• Transcription using Groq Whisper API (whisper-large-v3 model)
• Detailed analysis including:
  • Word-level accuracy (correct, skipped, substituted, repeated)
  • Speech rate (words per minute)
  • Pause detection and duration
  • Duration ratio per word
• Visual feedback with color-coded results
• Session history and performance tracking

Phonics Lessons

• Interactive flashcard system
• Grapheme-phoneme correspondence training
• Audio pronunciation using text-to-speech
• Covers common graphemes: or, y, ph, ch, sh, th
• Mark lessons as learned for progress tracking

Spelling Practice

• Auditory spelling quiz
• Commonly misspelled words database
• Immediate feedback on correctness
• Score tracking and session history
• Words included: believe, receive, necessary, separate, definitely, calendar, embarrass

Typing Practice

• Timed typing exercises
• Real-time WPM (words per minute) calculation
• Accuracy measurement
• Historical performance tracking

Progress Tracking

• Comprehensive dashboard showing:
  • Total sessions completed
  • Average spelling score
  • Average typing speed
  • Practice reading WPM
• Session history with timestamps
• Activity breakdown by intervention type
• Refresh to reload latest data

Architecture

NeuroRead follows a client-server architecture:

┌─────────────────────────────────────┐
│     React Native Mobile App         │
│   (Expo Router + TypeScript)        │
│                                      │
│  - Reader Interface                  │
│  - Intervention Modules              │
│  - Progress Dashboard                │
│  - OCR Camera Integration            │
└──────────────┬──────────────────────┘
               │
               │ HTTP/REST API
               │
┌──────────────▼──────────────────────┐
│      FastAPI Backend Server         │
│         (Python 3.8+)               │
│                                      │
│  - Text Simplification (BART)       │
│  - OCR Processing (EasyOCR)         │
│  - Practice Audio Analysis (Groq)   │
│  - Session Data Management          │
└─────────────────────────────────────┘

Data Flow

1. Text Simplification: Frontend sends text → Backend processes with fine-tuned BART model → Returns simplified text
2. OCR: Frontend captures image → Backend extracts text with EasyOCR → Returns plain text
3. Practice Analysis: Frontend records audio → Backend transcribes with Groq → Analyzes speech patterns → Returns detailed metrics

Technology Stack

Frontend

• Framework: React Native 0.81.5 with Expo SDK 54
• Navigation: Expo Router 6.0
• Language: TypeScript 5.9
• UI Components: Custom themed components
• Audio: expo-av for recording, expo-speech for TTS
• Camera: expo-camera for OCR scanning
• Storage: AsyncStorage for local data persistence
• Fonts: OpenDyslexic font integration

Backend

• Framework: FastAPI 0.104.1
• Server: Uvicorn 0.24.0 with hot reload
• ML Framework: PyTorch 2.1.0
• NLP: Transformers 4.35.0 (Hugging Face)
• OCR: EasyOCR 1.7.0
• Audio Processing: Groq API (Whisper Large V3)
• Computer Vision: OpenCV 4.8.1, Pillow 10.1.0
• Data: NumPy, Pandas, SciPy

Machine Learning

• Model: Fine-tuned BART-Large-CNN
• Base Model: facebook/bart-large-cnn
• Fine-tuned Model: elvisbakunzi/dyslexia-friendly-text-simplifier
• Training: 8 epochs, batch size 2
• Metrics: ROUGE score evaluation
• Framework: Hugging Face Transformers with PyTorch

Installation

Prerequisites

System Requirements:

• Python 3.8 or higher
• Node.js 16+ and npm/yarn
• Git
• Android Studio (for Android) or Xcode (for iOS)
• CUDA-capable GPU (optional, for faster inference)

API Keys Required:

• Groq API Key (for speech transcription)

Backend Setup

1. Clone the repository:

   git clone https://github.com/yourusername/NeuroRead.git
   cd NeuroRead

2. Create and activate virtual environment:

   python -m venv venv
   
   # Linux/Mac
   source venv/bin/activate
   
   # Windows
   venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configure environment variables: Create a .env file in the root directory:

   GROQ_API_KEY=your_groq_api_key_here

5. Start the backend server:

   cd backend
   uvicorn main:app --reload --host 0.0.0.0 --port 8000

   The backend will be available at http://localhost:8000

Frontend Setup

1. Navigate to frontend directory:

   cd frontend

2. Install dependencies:

   npm install
   # or
   yarn install

3. Configure API endpoint: Edit frontend/services/api.js and update the API_URL:

   // For development on local network
   const API_URL = 'http://YOUR_LOCAL_IP:8000';
   
   // For emulator/simulator
   // Android Emulator: http://10.0.2.2:8000
   // iOS Simulator: http://localhost:8000

4. Start the development server:

   npm start
   # or
   expo start

5. Run on device/emulator:

   # Android
   npm run android
   
   # iOS (Mac only)
   npm run ios
   
   # Web (experimental)
   npm run web

Configuration

Backend Configuration

Model Configuration (backend/main.py):

MODEL_NAME = "elvisbakunzi/dyslexia-friendly-text-simplifier"

EasyOCR Settings:

• Language: English
• GPU: Auto-detected (CUDA if available)

Groq API Settings:

• Model: whisper-large-v3
• Response Format: verbose_json
• Temperature: 0.0
• Language: en

Frontend Configuration

Theme Customization (frontend/components/ThemeContext.js):

• Light/Dark mode themes
• Font family selection (Standard/OpenDyslexic)
• Font size range: 12-32px
• Line spacing: 1.0-3.0
• Paragraph spacing: 0-40px

Storage Keys:

• currentText: Active text for reader
• sessionHistory: Practice/intervention session data
• Theme preferences stored in context

Usage

Starting the Application

1. Start Backend Server:

   cd backend
   uvicorn main:app --reload

2. Start Mobile App:

   cd frontend
   expo start

3. Scan QR code with Expo Go app (iOS/Android) or run on emulator

Using Core Features

Reading Text

1. Navigate to Home tab
2. Import text via:
   • Manual paste/typing
   • Pick PDF/Text/Image file
   • Scan with camera (OCR)
3. Tap "Start Reading"
4. Use reader controls:
   • Swipe left/right for navigation
   • Tap play button for text-to-speech
   • Toggle "Simplified" for AI-processed text
   • Adjust settings via gear icon

Reading Practice

1. Go to Intervention tab
2. Select "Reading Practice"
3. Read displayed target text aloud
4. Tap microphone to start recording
5. Speak the text clearly
6. Tap stop when finished
7. View detailed analysis:
   • Color-coded words (green=correct, red=skipped, orange=repeated)
   • Speech rate and pause metrics
   • Session statistics

Phonics Lessons

1. Go to Intervention → "Phonics Lessons"
2. View grapheme on flashcard
3. Tap card to flip and see phoneme
4. Tap speaker icon to hear pronunciation
5. Tap checkmark to mark as learned
6. Use "Next Card" to progress

Spelling Practice

1. Go to Intervention → "Spelling Practice"
2. Tap "Hear Word Again" to hear word
3. Type the word in input field
4. Tap "Check" or press enter
5. Review feedback
6. Continue to next word or skip
7. View final score at completion

Tracking Progress

1. Navigate to Progress tab
2. View summary statistics:
   • Total sessions
   • Spelling average
   • Practice WPM
3. Scroll down to see session history
4. Pull down to refresh data

API Documentation

Base URL

http://localhost:8000

Endpoints

Health Check

GET /

Response:

{
  "message": "NeuroRead API"
}

Text Simplification

POST /simplify
Content-Type: application/json

Request Body:

{
  "text": "The photosynthesis process involves the absorption of sunlight by chlorophyll."
}

Response:

{
  "simplified": "Photosynthesis is when plants use sunlight to make food."
}

Parameters:

• text (string, required): Text to simplify (max 512 tokens)

OCR Text Extraction

POST /ocr
Content-Type: multipart/form-data

Request:

• image (file, required): Image file (JPEG, PNG, etc.)

Response:

{
  "text": "Extracted text from image..."
}

Error Response:

{
  "text": "",
  "error": "Error description"
}

Practice Audio Analysis

POST /analyze-practice
Content-Type: multipart/form-data

Request:

• file (file, required): Audio file (.wav, .m4a, etc.)
• expected_text (string, optional): Expected text (default provided)

Response:

{
  "word_data": [
    {
      "word": "the",
      "start": 0.0,
      "end": 0.24,
      "pause_ms": 0,
      "duration_ratio": 0.6,
      "speech_rate_wpm": 0,
      "status": "correct",
      "skipped": false,
      "repetition": false
    }
  ],
  "stats": {
    "skipped_words": 1,
    "repetitions": 0,
    "wpm": 125.5
  }
}

Error Response:

{
  "error": "Groq API key not configured on backend."
}

Status Codes

• 200 OK: Successful request
• 400 Bad Request: Invalid input
• 500 Internal Server Error: Server-side error

Project Structure

Project Structure

NeuroRead/
│
├── backend/                      # FastAPI Backend
│   ├── main.py                   # Main API endpoints
│   ├── data/                     # Persistent storage
│   │   └── session_results.json  # Stored practice sessions (moved from root)
│   ├── requirements.txt          # Python dependencies
│   ├── tests/
│   │   └── test_ocr.py          # OCR unit tests
│   └── README.md                 # Backend documentation
│
├── frontend/                     # React Native App (Expo)
│   ├── app/                      # Expo Router pages
│   │   ├── (tabs)/              # Tab navigation (Home, Intervention, Progress)
│   │   ├── intervention/        # Intervention modules (Practice, Lessons, Masking)
│   │   ├── reader/              # Reader interface
│   │   └── _layout.tsx          # Root layout
│   │
│   ├── components/              # Reusable UI components
│   ├── services/                # Business logic & API integration
│   ├── assets/                  # Static resources (fonts, images)
│   └── ...
│
├── ml/                           # Machine Learning & Research
│   ├── dyslexic_summarizer/      # Text simplification model
│   │   ├── finetune_BART.ipynb  # Training notebook
│   │   └── data.json            # Training data
│   │
│   └── practise_feature/         # Practice mode scripts & experiments
│       ├── practice_script.py   # Standalone analysis script
│       └── ...
│
├── requirements.txt             # Consolidated Python dependencies
├── .env                         # Environment variables (API keys)
├── .gitignore                   # Git ignore rules
└── README.md                    # This file (Project Documentation)

Development

Running Tests

Backend Tests:

cd backend
pytest tests/

Frontend Tests:

cd frontend
npm test

Development Workflow

1. Backend Development:

   • Make changes in backend/main.py
   • Server auto-reloads with --reload flag
   • Test endpoints with curl, Postman, or frontend

2. Frontend Development:

   • Edit files in frontend/app/ or frontend/components/
   • Expo provides hot reload
   • Changes appear instantly on device/simulator

3. Model Development:

   • Use notebooks/finetune_BART.ipynb for model training
   • Upload trained model to Hugging Face
   • Update MODEL_NAME in backend/main.py

Code Style

Python:

• Follow PEP 8
• Use type hints where applicable
• Document functions with docstrings

TypeScript/JavaScript:

• Use TypeScript for type safety
• Follow React/React Native best practices
• Use functional components with hooks

Adding New Features

Backend Endpoint:

1. Add route in backend/main.py
2. Define request/response models with Pydantic
3. Implement business logic
4. Test endpoint

Frontend Screen:

1. Create component in appropriate app/ directory
2. Add navigation route if needed
3. Connect to backend via services/api.js
4. Style with theme context

Machine Learning Model

Model Details

Base Model: facebook/bart-large-cnn

• Pre-trained on CNN/DailyMail dataset
• Designed for abstractive summarization
• 406M parameters

Fine-tuning:

• Dataset: Custom dyslexia-friendly text pairs
• Training Data: 752 examples (data.json + data_1.json)
• Epochs: 8
• Batch Size: 2
• Learning Rate: 5e-5
• Evaluation Metric: ROUGE scores
• Hardware: GPU recommended (Google Colab)

Model Repository:

• Hugging Face: elvisbakunzi/dyslexia-friendly-text-simplifier
• License: Same as BART base model

Training Process

1. Data Preparation:

   • Collected complex text samples
   • Created dyslexia-friendly summaries
   • Formatted as JSON pairs

2. Fine-tuning:

   • Used Hugging Face Trainer API
   • Applied generation parameters:
     • max_length: 256
     • num_beams: 3
     • length_penalty: 0.8
     • no_repeat_ngram_size: 2

3. Evaluation:

   • Computed ROUGE-1, ROUGE-2, ROUGE-L scores
   • Manual quality assessment
   • Tested on held-out examples

Inference Parameters

outputs = model.generate(
    **inputs,
    max_length=256,
    num_beams=3,
    length_penalty=0.8,
    early_stopping=True,
    no_repeat_ngram_size=2,
)

Re-training the Model

To retrain with new data:

1. Prepare data in JSON format:

   [
     {
       "input_text": "Complex sentence...",
       "summary": "Simple sentence..."
     }
   ]

2. Open notebooks/finetune_BART.ipynb in Jupyter/Colab

3. Update file paths and configuration

4. Run all cells to train

5. Save and upload to Hugging Face

6. Update MODEL_NAME in backend

Environment Variables

Create a .env file in the root directory:

# Groq API Configuration
GROQ_API_KEY=your_groq_api_key_here

# Optional: Database configuration (if using)
# DATABASE_URL=postgresql://user:password@localhost/neuroread

# Optional: Debug settings
# DEBUG=True

Important: Never commit .env file to version control.

Troubleshooting

Backend Issues

Problem: Model loading fails

• Solution: Ensure sufficient RAM (4GB+ free), download may take time on first run

Problem: OCR not working

• Solution: Check EasyOCR installation, ensure GPU drivers if using CUDA

Problem: Groq API errors

• Solution: Verify API key in .env, check rate limits

Frontend Issues

Problem: Cannot connect to backend

• Solution: Update API_URL in frontend/services/api.js with correct IP address

Problem: Expo app crashes on launch

• Solution: Clear cache with expo start -c, reinstall dependencies

Problem: Fonts not loading

• Solution: Ensure font files exist in frontend/assets/fonts/

Problem: Audio recording fails

• Solution: Check device permissions for microphone access

Common Errors

"Network request failed"

• Backend not running or wrong IP address
• Check firewall settings
• Verify device and computer on same network

"GROQ_API_KEY not found"

• Missing or incorrect .env file
• Restart backend after adding key

"Module not found"

• Missing dependencies
• Run pip install -r requirements.txt or npm install

Performance Optimization

Backend Optimization

• Model Caching: Model loaded once at startup
• GPU Acceleration: Auto-detects CUDA for faster inference
• Async Processing: FastAPI handles concurrent requests
• Consider: Implement model quantization for faster CPU inference

Frontend Optimization

• Lazy Loading: Components loaded on-demand
• Memoization: React.memo for expensive components
• Debouncing: User input debounced for API calls
• Offline Support: AsyncStorage for offline data access

Security Considerations

1. API Keys: Never commit keys to repository
2. Input Validation: Backend validates all inputs
3. File Upload: Size and type restrictions on uploads
4. CORS: Configure appropriately for production
5. HTTPS: Use SSL/TLS in production environment
6. Data Privacy: Audio recordings and session data should be encrypted

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Commit changes: git commit -am 'Add new feature'
4. Push to branch: git push origin feature/your-feature
5. Submit a pull request

Contribution Guidelines

• Follow existing code style
• Add tests for new features
• Update documentation
• Ensure all tests pass
• Keep commits atomic and well-described

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• BART Model: Facebook AI Research
• Fine-tuned Model: elvisbakunzi/dyslexia-friendly-text-simplifier
• EasyOCR: JaidedAI
• Groq: Whisper API provider
• OpenDyslexic Font: Abelardo Gonzalez
• Expo: Expo team for React Native framework
• FastAPI: Sebastián Ramírez

Contact

For questions, issues, or suggestions:

• GitHub Issues: Create an issue
• Email: your.email@example.com

Citation

If you use NeuroRead in your research, please cite:

@software{neuroread2026,
  title={NeuroRead: An AI-Powered Dyslexia-Friendly Reading Application},
  author={Your Name},
  year={2026},
  url={https://github.com/yourusername/NeuroRead}
}

---

Note: NeuroRead is an assistive tool and should not replace professional diagnosis or intervention by qualified specialists. Always consult with educational and medical professionals for comprehensive dyslexia support.