Moodle Passkey Mobile App

A production-ready React Native mobile application that integrates with Moodle Learning Management System (LMS) to provide seamless passkey authentication and access to course content through a native mobile interface.

🎯 Problem Statement

Traditional mobile access to Moodle requires users to:

• Navigate through complex web interfaces designed for desktop
• Manually enter credentials repeatedly
• Deal with inconsistent mobile web experiences
• Lose context when switching between browser and app

This app solves these issues by providing:

• Native mobile experience with optimized UI/UX
• Seamless passkey authentication using WebAuthn standards
• Persistent session management across app launches
• Offline-capable content access through WebView integration

🛠 Tech Stack

Core Framework

• React Native 0.79.6 - Cross-platform mobile development
• Expo SDK 52 - Development toolchain and deployment platform
• TypeScript - Type-safe JavaScript development

Authentication & Security

• expo-web-browser - Secure authentication sessions (ASWebAuthenticationSession on iOS, Chrome Custom Tabs on Android)
• expo-auth-session - OAuth 2.0 and OpenID Connect support
• WebAuthn/Passkey - Modern passwordless authentication

UI & Navigation

• React Native WebView - Embedded web content rendering
• React Native Paper - Material Design components
• React Hooks - Modern state management and lifecycle handling

Development Tools

• Metro Bundler - JavaScript bundling and hot reloading
• ESLint - Code linting and style enforcement
• Prettier - Code formatting
• Jest - Unit testing framework

Why These Technologies?

• React Native + Expo: Rapid development with native performance and easy deployment
• TypeScript: Prevents runtime errors and improves developer experience
• WebAuthn/Passkey: Future-proof authentication that's more secure than passwords
• WebView Integration: Leverages existing Moodle web interface while providing native app benefits

🏗 System Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Mobile App    │    │   Moodle LMS     │    │   WebAuthn      │
│                 │    │                  │    │   Provider      │
│ ┌─────────────┐ │    │ ┌──────────────┐ │    │                 │
│ │  WebView    │ │◄───┤ │  Login Page  │ │    │                 │
│ │  Component  │ │    │ │              │ │    │                 │
│ └─────────────┘ │    │ └──────────────┘ │    │                 │
│ ┌─────────────┐ │    │ ┌──────────────┐ │    │                 │
│ │ Deep Link   │ │◄───┤ │ OAuth        │ │◄───┤                 │
│ │ Handler     │ │    │ │ Redirect     │ │    │                 │
│ └─────────────┘ │    │ └──────────────┘ │    │                 │
│ ┌─────────────┐ │    │ ┌──────────────┐ │    │                 │
│ │ Auth        │ │    │ │ Course       │ │    │                 │
│ │ Manager     │ │◄───┤ │ Content      │ │    │                 │
│ └─────────────┘ │    │ └──────────────┘ │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Data Flow

1. App Launch → Auto-triggers authentication flow
2. Browser Opens → User completes passkey authentication
3. OAuth Redirect → Backend redirects to custom scheme
4. Deep Link Handler → Parses authentication parameters
5. WebView Loads → Authenticated Moodle content display

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Expo CLI (npm install -g @expo/cli)
• iOS Simulator (for iOS development)
• Android Studio (for Android development)

Installation

# Clone the repository
git clone <repository-url>
cd MoodlePasskeyApp

# Install dependencies
npm install

# Install Expo CLI globally (if not already installed)
npm install -g @expo/cli

Configuration

1. Environment Setup

   # Copy environment template
   cp .env.example .env
   
   # Edit configuration
   nano .env

2. Moodle Configuration

   • Configure your Moodle instance to support OAuth redirects
   • Add myapp://callback to allowed redirect URIs
   • Enable WebAuthn/Passkey authentication

3. App Configuration

   // app.json
   {
     "expo": {
       "scheme": "myapp",
       "ios": {
         "bundleIdentifier": "com.yourcompany.moodlepasskey"
       },
       "android": {
         "package": "com.yourcompany.moodlepasskey"
       }
     }
   }

Running the App

# Start development server
npm start

# Run on iOS simulator
npm run ios

# Run on Android emulator
npm run android

# Run on physical device
# Scan QR code with Expo Go app

📱 Usage Examples

Basic Authentication Flow

// The app automatically handles the entire flow
// 1. App launches → WebView loads Moodle
// 2. After 1 second → Browser opens for authentication
// 3. User completes passkey login
// 4. App receives redirect and returns to WebView

Custom Deep Link Handling

import { DeepLinkHandler } from './src/services/DeepLinkHandler';

const handler = DeepLinkHandler.getInstance();
handler.addListener((data) => {
  if (data.oauthCode) {
    console.log('Authentication successful:', data.oauthCode);
    // Handle successful authentication
  }
});

Testing Deep Links

# Test OAuth success flow
xcrun simctl openurl booted "myapp://callback?code=TEST123&state=state456"

# Test OAuth error flow
xcrun simctl openurl booted "myapp://callback?error=access_denied&error_description=User%20denied%20access"

🧪 Testing

Unit Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Integration Tests

# Test deep link handling
npm run test:integration

# Test authentication flow
npm run test:auth

Manual Testing

1. QR Code Testing

   • Generate QR codes with test deep links
   • Scan with device camera
   • Verify app opens and parses parameters

2. Real Device Testing

   • Deploy to physical device
   • Test complete authentication flow
   • Verify WebView content loads correctly

📁 Project Structure

MoodlePasskeyApp/
├── src/                          # Source code
│   ├── components/               # React components
│   │   ├── WebViewComponent.tsx  # Main WebView wrapper
│   │   └── AuthStatusCard.tsx   # Authentication status display
│   ├── services/                 # Business logic services
│   │   ├── DeepLinkHandler.ts   # Deep link parsing and handling
│   │   ├── AuthManager.ts       # Authentication state management
│   │   └── MoodleService.ts     # Moodle API integration
│   ├── utils/                    # Utility functions
│   │   ├── urlParser.ts         # URL parsing utilities
│   │   └── logger.ts            # Logging utilities
│   ├── types/                    # TypeScript type definitions
│   │   ├── auth.ts              # Authentication types
│   │   └── deepLink.ts          # Deep link types
│   └── config/                   # Configuration files
│       ├── constants.ts         # App constants
│       └── environment.ts       # Environment configuration
├── docs/                         # Documentation
│   ├── architecture.md          # Technical architecture
│   ├── api.md                   # API documentation
│   └── deployment.md            # Deployment guide
├── tests/                        # Test files
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── __mocks__/               # Test mocks
├── .env.example                 # Environment variables template
├── .env                         # Environment variables (gitignored)
├── app.json                     # Expo configuration
├── package.json                 # Dependencies and scripts
└── README.md                    # This file

🔧 Configuration

Environment Variables

# .env
MOODLE_BASE_URL=https://moodle.hm.edu/
MOODLE_LOGIN_URL=https://moodle.hm.edu/login/index.php
REDIRECT_SCHEME=myapp
REDIRECT_PATH=auth
DEBUG_MODE=true
LOG_LEVEL=info

App Configuration

{
  "expo": {
    "name": "Moodle Passkey App",
    "slug": "moodle-passkey-app",
    "version": "1.0.0",
    "scheme": "myapp",
    "ios": {
      "bundleIdentifier": "com.yourcompany.moodlepasskey"
    },
    "android": {
      "package": "com.yourcompany.moodlepasskey"
    }
  }
}

🚀 Deployment

Development Build

# Create development build
expo build:ios --type development
expo build:android --type development

Production Build

# Create production build
expo build:ios --type production
expo build:android --type production

App Store Deployment

# Submit to App Store
expo upload:ios
expo upload:android

🤝 Contributing

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with proper tests and documentation
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Code Standards

• TypeScript: All code must be properly typed
• ESLint: Follow the configured linting rules
• Prettier: Code must be formatted with Prettier
• Tests: New features must include unit tests
• Documentation: Update documentation for new features

Commit Convention

type(scope): description

feat(auth): add passkey authentication support
fix(webview): resolve deep link parsing issue
docs(readme): update installation instructions

📄 License

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

🆘 Support

Common Issues

1. Deep links not working

   • Verify app scheme configuration
   • Check redirect URI whitelist in Moodle
   • Test with QR code generator

2. Authentication fails

   • Verify Moodle supports WebAuthn
   • Check network connectivity
   • Review console logs for errors

3. WebView not loading

   • Check Moodle URL accessibility
   • Verify CORS settings
   • Test in browser first

Getting Help

• Documentation: Check /docs folder for detailed guides
• Issues: Open an issue on GitHub
• Discussions: Use GitHub Discussions for questions
• Email: Contact the development team

🔮 Roadmap

Version 1.1

• Offline content caching
• Push notifications for course updates
• Dark mode support

Version 1.2

• Multi-language support
• Advanced course filtering
• Grade book integration

Version 2.0

• Native course content rendering
• Real-time collaboration features
• Advanced analytics dashboard

---

Built with ❤️ for seamless mobile learning experiences