Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/eli-keli/soundsteps

Voice-first IVR educational platform with React Native companion app for visually impaired learners
https://github.com/eli-keli/soundsteps

accessibility africastalking education expo express ivr nodejs react-native sqlite typescript voicefirst

Last synced: 4 months ago
JSON representation

Voice-first IVR educational platform with React Native companion app for visually impaired learners

Awesome Lists containing this project

README 

          
# SoundSteps - Project Overview & Quick Start



## What is SoundSteps?



SoundSteps is a hybrid educational platform that combines voice-first IVR (Interactive Voice Response) micro-lessons with a modern React Native companion app. Designed specifically for visually impaired and low-literacy learners, the system provides accessible audio-based education while giving teachers and caregivers powerful management tools.



## 🎯 Key Features



### For Learners (Any Phone)

- **Voice-Based Lessons**: Call in to receive 3-minute structured audio lessons

- **Interactive Quizzes**: Answer questions using phone keypad (DTMF)

- **Progress Tracking**: Automatic score calculation and session history

- **SMS Summaries**: Lesson summaries sent to caregivers in English and Swahili

- **Accessibility First**: Designed for visually impaired and low-literacy users



### For Teachers/Admins (React Native App)

- **Dashboard**: Real-time statistics on active calls, lesson performance, user engagement

- **Lesson Builder**: Create audio lessons with interactive quiz questions

- **Live Monitoring**: Watch ongoing calls and DTMF interactions in real-time

- **User Management**: Handle teacher/admin accounts with secure authentication

- **Analytics**: Track learner progress, quiz scores, and content effectiveness



### System Integration

- **Africa's Talking**: Voice calls, SMS messaging, and airtime rewards

- **Real-time Updates**: Socket.IO for live dashboard updates

- **Modern Architecture**: TypeScript backend, React Native frontend

- **Production Ready**: JWT authentication, secure data handling, comprehensive error management



## 🚀 Quick Start



### Development Setup



1. **Clone and Install**

   ```bash

   cd "SOUND STEPS"

   

   # Backend setup

   cd soundsteps-backend

   npm install

   cp .env.example .env

   # Edit .env with your Africa's Talking credentials

   

   # Frontend setup  

   cd ../soundsteps-app

   npm install

   ```



2. **Start Development Servers**

   ```bash

   # Terminal 1: Backend

   cd soundsteps-backend

   npm run dev

   

   # Terminal 2: Frontend

   cd soundsteps-app

   npx expo start

   ```



3. **Test the System**

   - Backend: http://localhost:3000/health

   - Frontend: Scan QR code with Expo Go app

   - Login: `teacher@soundsteps.com` / `password`



### Production Deployment

See [Deployment Guide](./docs/Deployment-Guide.md) for complete production setup instructions.



## 📁 Project Structure



```

SOUND STEPS/

├── docs/                          # Comprehensive documentation

│   ├── Technical-Architecture.md  # System architecture & database schema

│   ├── API-Reference.md          # Complete API documentation

│   ├── Project-Analysis.md       # Integration analysis & assessment

│   └── Deployment-Guide.md       # Production deployment instructions

│

├── soundsteps-app/               # React Native companion app

│   ├── app/                      # Expo Router screens (login, dashboard, lessons)

│   ├── components/               # Reusable UI components (LessonCard, StatWidget)

│   ├── hooks/                    # Custom hooks (useAuth, useTheme)

│   ├── api/                      # API client with authentication

│   ├── styles/                   # Design system & theme

│   └── types/                    # TypeScript definitions

│

└── soundsteps-backend/           # Node.js TypeScript API

    ├── src/

    │   ├── routes/               # API endpoints & webhooks

    │   │   ├── auth.ts          # JWT authentication

    │   │   ├── lessons.ts       # Lesson CRUD operations

    │   │   ├── sessions.ts      # Call session management

    │   │   └── webhooks/        # Africa's Talking integrations

    │   │       └── voice.ts     # IVR call handling

    │   ├── models/              # Database models

    │   ├── utils/               # Core utilities

    │   │   ├── africasTalking.ts # AT SDK integration

    │   │   ├── auth.ts          # JWT utilities

    │   │   ├── database.ts      # SQLite setup

    │   │   └── lessonFlow.ts    # IVR state machine

    │   └── index.ts             # Server entry point

    ├── dist/                    # Compiled JavaScript

    └── soundsteps.db           # SQLite database

```



## 🛠 Technology Stack



| Component | Technology | Purpose |

|-----------|------------|---------|

| **Backend** | Node.js + Express + TypeScript | API server with type safety |

| **Database** | SQLite (dev) / PostgreSQL (prod) | Data persistence |

| **Authentication** | JWT + bcrypt | Secure user management |

| **Voice/SMS** | Africa's Talking SDK | IVR calls and messaging |

| **Real-time** | Socket.IO | Live updates and monitoring |

| **Frontend** | React Native + Expo | Cross-platform mobile app |

| **Navigation** | Expo Router | File-based routing |

| **State Management** | TanStack React Query | Server state management |

| **Forms** | React Hook Form + Yup | Form handling and validation |

| **Storage** | Expo SecureStore | Secure token storage |



## 📊 System Architecture



```

┌─────────────────────────────────────────────┐

│               LEARNER JOURNEY                │

│                                             │

│  Phone Call → IVR Lesson → DTMF Quiz       │

│       ↓                                     │

│  Session Stored → SMS Summary Sent          │

└─────────────────────────────────────────────┘

                        │

                        ▼

┌─────────────────────────────────────────────┐

│            TEACHER/ADMIN JOURNEY            │

│                                             │

│  Mobile App → Dashboard → Lesson Builder    │

│       ↓                                     │

│  Live Monitoring → Analytics → Management   │

└─────────────────────────────────────────────┘

```



## 🔧 Configuration



### Environment Variables



**Backend (.env)**

```bash

PORT=3000

JWT_SECRET=your_secure_jwt_secret

DATABASE_URL=sqlite:./soundsteps.db

AT_API_KEY=your_africas_talking_api_key

AT_USERNAME=your_at_username

```



**Frontend (.env)**

```bash

EXPO_PUBLIC_API_BASE_URL=http://localhost:3000

```



### Africa's Talking Setup

1. **Sandbox Account**: Register at https://account.africastalking.com

2. **API Credentials**: Get your API key and username

3. **Configure Webhooks**:

   - Voice Answer URL: `https://yourserver.com/webhooks/voice/voice`

   - DTMF Callback: `https://yourserver.com/webhooks/voice/dtmf`

   - SMS Delivery: `https://yourserver.com/webhooks/sms/delivery`



## 🔒 Security Features



- **JWT Authentication**: Secure token-based user sessions

- **Password Hashing**: bcrypt with salt for password security

- **Input Validation**: Comprehensive request validation and sanitization

- **SQL Injection Prevention**: Parameterized queries throughout

- **CORS Configuration**: Proper cross-origin request handling

- **Secure Storage**: Expo SecureStore for sensitive mobile data

- **Error Handling**: No sensitive information leaked in error responses



## 📈 Performance & Scalability



### Current Capabilities

- **Database**: SQLite with WAL mode for concurrent access

- **Caching**: React Query for client-side data caching

- **Real-time**: Socket.IO for live updates without polling

- **Optimization**: TypeScript compilation with tree shaking



### Production Scaling

- **Database**: Migration path to PostgreSQL for higher load

- **Process Management**: PM2 clustering for multi-core utilization

- **Load Balancing**: Nginx reverse proxy configuration

- **CDN**: Audio file delivery optimization

- **Monitoring**: Application performance monitoring setup



## 🧪 Testing



### Manual Testing

```bash

# Test backend API

curl http://localhost:3000/health



# Test voice webhook

curl -X POST http://localhost:3000/webhooks/voice/voice \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -d "sessionId=test123&phoneNumber=%2B254712345678"



# Test authentication

curl -X POST http://localhost:3000/auth/login \

  -H "Content-Type: application/json" \

  -d '{"email":"teacher@soundsteps.com","password":"password"}'

```



### Demo Credentials

- **Email**: `teacher@soundsteps.com`

- **Password**: `password`



## 📚 Documentation



| Document | Description |

|----------|-------------|

| **[Technical Architecture](./docs/Technical-Architecture.md)** | Complete system architecture, database schema, API endpoints |

| **[API Reference](./docs/API-Reference.md)** | Comprehensive API documentation with examples |

| **[Project Analysis](./docs/Project-Analysis.md)** | Integration analysis, quality assessment, recommendations |

| **[Deployment Guide](./docs/Deployment-Guide.md)** | Production deployment instructions |



## 🎯 Current Status



### ✅ Completed Features

- **Full IVR Integration**: Complete voice lesson flow with state machine

- **React Native App**: Professional mobile application with authentication

- **Real-time Monitoring**: Live call tracking and dashboard updates

- **Database Integration**: Comprehensive schema with proper relationships

- **Security Implementation**: JWT authentication and input validation

- **SMS Integration**: Bilingual lesson summaries to caregivers

- **TypeScript Migration**: Complete type safety throughout the system



### 🚧 Ready for Implementation

- **File Upload**: Audio lesson upload functionality (UI components ready)

- **Push Notifications**: Mobile app notification system (infrastructure ready)

- **Advanced Analytics**: Detailed learner progress tracking (database supports it)

- **Multi-language**: Additional language support beyond English/Swahili

- **Offline Support**: Mobile app offline lesson caching capabilities



### 🎯 Next Phase Recommendations

1. **Production Deployment**: Deploy to staging/production environment

2. **User Testing**: Conduct usability testing with target audience

3. **Performance Optimization**: Load testing and optimization

4. **Content Creation**: Develop additional lesson content

5. **Integration Testing**: End-to-end testing with real Africa's Talking calls



## 🤝 Contributing



### Development Workflow

1. **Fork/Clone** the repository

2. **Create feature branch**: `git checkout -b feature/your-feature`

3. **Make changes** with proper TypeScript types

4. **Test thoroughly** including API endpoints and mobile app

5. **Submit pull request** with detailed description



### Code Standards

- **TypeScript**: Full type coverage, no `any` types

- **ESLint**: Consistent code formatting

- **Error Handling**: Comprehensive error boundaries

- **Documentation**: Clear comments and API documentation

- **Testing**: Unit tests for business logic



## 📞 Support



### Common Issues

- **Database Connection**: Check SQLite file permissions

- **Africa's Talking**: Verify API credentials and webhook URLs

- **React Native**: Ensure Expo CLI is up to date

- **Authentication**: Check JWT secret configuration



### Getting Help

1. **Check Documentation**: Comprehensive docs in `/docs` folder

2. **Review Logs**: Backend logs show detailed error information

3. **Test API Endpoints**: Use provided cURL examples

4. **Verify Configuration**: Double-check environment variables



## 🏆 Success Metrics



The SoundSteps platform successfully demonstrates:



- **Accessibility**: Voice-first design serving visually impaired learners

- **Modern Architecture**: TypeScript, React Native, and production-ready patterns

- **Integration Excellence**: Seamless connection between voice, backend, and mobile

- **Security Focus**: Proper authentication and data protection

- **Scalability**: Architecture supports growth and additional features

- **User Experience**: Intuitive interfaces for both learners and administrators



---



**SoundSteps represents a successful integration of accessible educational technology with modern development practices, creating a platform that serves underrepresented learners while providing educators with powerful management tools.**