{"id":31581296,"url":"https://github.com/eli-keli/soundsteps","last_synced_at":"2026-04-11T09:39:57.853Z","repository":{"id":316492150,"uuid":"1063614802","full_name":"Eli-Keli/soundsteps","owner":"Eli-Keli","description":"Voice-first IVR educational platform with React Native companion app for visually impaired learners","archived":false,"fork":false,"pushed_at":"2025-09-24T22:08:23.000Z","size":752,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T00:10:03.000Z","etag":null,"topics":["accessibility","africastalking","education","expo","express","ivr","nodejs","react-native","sqlite","typescript","voicefirst"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Eli-Keli.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-24T21:54:40.000Z","updated_at":"2025-09-24T22:15:12.000Z","dependencies_parsed_at":"2025-09-25T00:10:18.929Z","dependency_job_id":"e40e87d7-2e50-4532-b755-5ab7b0db8e3e","html_url":"https://github.com/Eli-Keli/soundsteps","commit_stats":null,"previous_names":["eli-keli/soundsteps"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/Eli-Keli/soundsteps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eli-Keli%2Fsoundsteps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eli-Keli%2Fsoundsteps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eli-Keli%2Fsoundsteps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eli-Keli%2Fsoundsteps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Eli-Keli","download_url":"https://codeload.github.com/Eli-Keli/soundsteps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eli-Keli%2Fsoundsteps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526240,"owners_count":26001326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["accessibility","africastalking","education","expo","express","ivr","nodejs","react-native","sqlite","typescript","voicefirst"],"created_at":"2025-10-05T21:55:55.994Z","updated_at":"2025-10-05T21:55:58.327Z","avatar_url":"https://github.com/Eli-Keli.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SoundSteps - Project Overview \u0026 Quick Start\n\n## What is SoundSteps?\n\nSoundSteps 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.\n\n## 🎯 Key Features\n\n### For Learners (Any Phone)\n- **Voice-Based Lessons**: Call in to receive 3-minute structured audio lessons\n- **Interactive Quizzes**: Answer questions using phone keypad (DTMF)\n- **Progress Tracking**: Automatic score calculation and session history\n- **SMS Summaries**: Lesson summaries sent to caregivers in English and Swahili\n- **Accessibility First**: Designed for visually impaired and low-literacy users\n\n### For Teachers/Admins (React Native App)\n- **Dashboard**: Real-time statistics on active calls, lesson performance, user engagement\n- **Lesson Builder**: Create audio lessons with interactive quiz questions\n- **Live Monitoring**: Watch ongoing calls and DTMF interactions in real-time\n- **User Management**: Handle teacher/admin accounts with secure authentication\n- **Analytics**: Track learner progress, quiz scores, and content effectiveness\n\n### System Integration\n- **Africa's Talking**: Voice calls, SMS messaging, and airtime rewards\n- **Real-time Updates**: Socket.IO for live dashboard updates\n- **Modern Architecture**: TypeScript backend, React Native frontend\n- **Production Ready**: JWT authentication, secure data handling, comprehensive error management\n\n## 🚀 Quick Start\n\n### Development Setup\n\n1. **Clone and Install**\n   ```bash\n   cd \"SOUND STEPS\"\n   \n   # Backend setup\n   cd soundsteps-backend\n   npm install\n   cp .env.example .env\n   # Edit .env with your Africa's Talking credentials\n   \n   # Frontend setup  \n   cd ../soundsteps-app\n   npm install\n   ```\n\n2. **Start Development Servers**\n   ```bash\n   # Terminal 1: Backend\n   cd soundsteps-backend\n   npm run dev\n   \n   # Terminal 2: Frontend\n   cd soundsteps-app\n   npx expo start\n   ```\n\n3. **Test the System**\n   - Backend: http://localhost:3000/health\n   - Frontend: Scan QR code with Expo Go app\n   - Login: `teacher@soundsteps.com` / `password`\n\n### Production Deployment\nSee [Deployment Guide](./docs/Deployment-Guide.md) for complete production setup instructions.\n\n## 📁 Project Structure\n\n```\nSOUND STEPS/\n├── docs/                          # Comprehensive documentation\n│   ├── Technical-Architecture.md  # System architecture \u0026 database schema\n│   ├── API-Reference.md          # Complete API documentation\n│   ├── Project-Analysis.md       # Integration analysis \u0026 assessment\n│   └── Deployment-Guide.md       # Production deployment instructions\n│\n├── soundsteps-app/               # React Native companion app\n│   ├── app/                      # Expo Router screens (login, dashboard, lessons)\n│   ├── components/               # Reusable UI components (LessonCard, StatWidget)\n│   ├── hooks/                    # Custom hooks (useAuth, useTheme)\n│   ├── api/                      # API client with authentication\n│   ├── styles/                   # Design system \u0026 theme\n│   └── types/                    # TypeScript definitions\n│\n└── soundsteps-backend/           # Node.js TypeScript API\n    ├── src/\n    │   ├── routes/               # API endpoints \u0026 webhooks\n    │   │   ├── auth.ts          # JWT authentication\n    │   │   ├── lessons.ts       # Lesson CRUD operations\n    │   │   ├── sessions.ts      # Call session management\n    │   │   └── webhooks/        # Africa's Talking integrations\n    │   │       └── voice.ts     # IVR call handling\n    │   ├── models/              # Database models\n    │   ├── utils/               # Core utilities\n    │   │   ├── africasTalking.ts # AT SDK integration\n    │   │   ├── auth.ts          # JWT utilities\n    │   │   ├── database.ts      # SQLite setup\n    │   │   └── lessonFlow.ts    # IVR state machine\n    │   └── index.ts             # Server entry point\n    ├── dist/                    # Compiled JavaScript\n    └── soundsteps.db           # SQLite database\n```\n\n## 🛠 Technology Stack\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| **Backend** | Node.js + Express + TypeScript | API server with type safety |\n| **Database** | SQLite (dev) / PostgreSQL (prod) | Data persistence |\n| **Authentication** | JWT + bcrypt | Secure user management |\n| **Voice/SMS** | Africa's Talking SDK | IVR calls and messaging |\n| **Real-time** | Socket.IO | Live updates and monitoring |\n| **Frontend** | React Native + Expo | Cross-platform mobile app |\n| **Navigation** | Expo Router | File-based routing |\n| **State Management** | TanStack React Query | Server state management |\n| **Forms** | React Hook Form + Yup | Form handling and validation |\n| **Storage** | Expo SecureStore | Secure token storage |\n\n## 📊 System Architecture\n\n```\n┌─────────────────────────────────────────────┐\n│               LEARNER JOURNEY                │\n│                                             │\n│  Phone Call → IVR Lesson → DTMF Quiz       │\n│       ↓                                     │\n│  Session Stored → SMS Summary Sent          │\n└─────────────────────────────────────────────┘\n                        │\n                        ▼\n┌─────────────────────────────────────────────┐\n│            TEACHER/ADMIN JOURNEY            │\n│                                             │\n│  Mobile App → Dashboard → Lesson Builder    │\n│       ↓                                     │\n│  Live Monitoring → Analytics → Management   │\n└─────────────────────────────────────────────┘\n```\n\n## 🔧 Configuration\n\n### Environment Variables\n\n**Backend (.env)**\n```bash\nPORT=3000\nJWT_SECRET=your_secure_jwt_secret\nDATABASE_URL=sqlite:./soundsteps.db\nAT_API_KEY=your_africas_talking_api_key\nAT_USERNAME=your_at_username\n```\n\n**Frontend (.env)**\n```bash\nEXPO_PUBLIC_API_BASE_URL=http://localhost:3000\n```\n\n### Africa's Talking Setup\n1. **Sandbox Account**: Register at https://account.africastalking.com\n2. **API Credentials**: Get your API key and username\n3. **Configure Webhooks**:\n   - Voice Answer URL: `https://yourserver.com/webhooks/voice/voice`\n   - DTMF Callback: `https://yourserver.com/webhooks/voice/dtmf`\n   - SMS Delivery: `https://yourserver.com/webhooks/sms/delivery`\n\n## 🔒 Security Features\n\n- **JWT Authentication**: Secure token-based user sessions\n- **Password Hashing**: bcrypt with salt for password security\n- **Input Validation**: Comprehensive request validation and sanitization\n- **SQL Injection Prevention**: Parameterized queries throughout\n- **CORS Configuration**: Proper cross-origin request handling\n- **Secure Storage**: Expo SecureStore for sensitive mobile data\n- **Error Handling**: No sensitive information leaked in error responses\n\n## 📈 Performance \u0026 Scalability\n\n### Current Capabilities\n- **Database**: SQLite with WAL mode for concurrent access\n- **Caching**: React Query for client-side data caching\n- **Real-time**: Socket.IO for live updates without polling\n- **Optimization**: TypeScript compilation with tree shaking\n\n### Production Scaling\n- **Database**: Migration path to PostgreSQL for higher load\n- **Process Management**: PM2 clustering for multi-core utilization\n- **Load Balancing**: Nginx reverse proxy configuration\n- **CDN**: Audio file delivery optimization\n- **Monitoring**: Application performance monitoring setup\n\n## 🧪 Testing\n\n### Manual Testing\n```bash\n# Test backend API\ncurl http://localhost:3000/health\n\n# Test voice webhook\ncurl -X POST http://localhost:3000/webhooks/voice/voice \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"sessionId=test123\u0026phoneNumber=%2B254712345678\"\n\n# Test authentication\ncurl -X POST http://localhost:3000/auth/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"email\":\"teacher@soundsteps.com\",\"password\":\"password\"}'\n```\n\n### Demo Credentials\n- **Email**: `teacher@soundsteps.com`\n- **Password**: `password`\n\n## 📚 Documentation\n\n| Document | Description |\n|----------|-------------|\n| **[Technical Architecture](./docs/Technical-Architecture.md)** | Complete system architecture, database schema, API endpoints |\n| **[API Reference](./docs/API-Reference.md)** | Comprehensive API documentation with examples |\n| **[Project Analysis](./docs/Project-Analysis.md)** | Integration analysis, quality assessment, recommendations |\n| **[Deployment Guide](./docs/Deployment-Guide.md)** | Production deployment instructions |\n\n## 🎯 Current Status\n\n### ✅ Completed Features\n- **Full IVR Integration**: Complete voice lesson flow with state machine\n- **React Native App**: Professional mobile application with authentication\n- **Real-time Monitoring**: Live call tracking and dashboard updates\n- **Database Integration**: Comprehensive schema with proper relationships\n- **Security Implementation**: JWT authentication and input validation\n- **SMS Integration**: Bilingual lesson summaries to caregivers\n- **TypeScript Migration**: Complete type safety throughout the system\n\n### 🚧 Ready for Implementation\n- **File Upload**: Audio lesson upload functionality (UI components ready)\n- **Push Notifications**: Mobile app notification system (infrastructure ready)\n- **Advanced Analytics**: Detailed learner progress tracking (database supports it)\n- **Multi-language**: Additional language support beyond English/Swahili\n- **Offline Support**: Mobile app offline lesson caching capabilities\n\n### 🎯 Next Phase Recommendations\n1. **Production Deployment**: Deploy to staging/production environment\n2. **User Testing**: Conduct usability testing with target audience\n3. **Performance Optimization**: Load testing and optimization\n4. **Content Creation**: Develop additional lesson content\n5. **Integration Testing**: End-to-end testing with real Africa's Talking calls\n\n## 🤝 Contributing\n\n### Development Workflow\n1. **Fork/Clone** the repository\n2. **Create feature branch**: `git checkout -b feature/your-feature`\n3. **Make changes** with proper TypeScript types\n4. **Test thoroughly** including API endpoints and mobile app\n5. **Submit pull request** with detailed description\n\n### Code Standards\n- **TypeScript**: Full type coverage, no `any` types\n- **ESLint**: Consistent code formatting\n- **Error Handling**: Comprehensive error boundaries\n- **Documentation**: Clear comments and API documentation\n- **Testing**: Unit tests for business logic\n\n## 📞 Support\n\n### Common Issues\n- **Database Connection**: Check SQLite file permissions\n- **Africa's Talking**: Verify API credentials and webhook URLs\n- **React Native**: Ensure Expo CLI is up to date\n- **Authentication**: Check JWT secret configuration\n\n### Getting Help\n1. **Check Documentation**: Comprehensive docs in `/docs` folder\n2. **Review Logs**: Backend logs show detailed error information\n3. **Test API Endpoints**: Use provided cURL examples\n4. **Verify Configuration**: Double-check environment variables\n\n## 🏆 Success Metrics\n\nThe SoundSteps platform successfully demonstrates:\n\n- **Accessibility**: Voice-first design serving visually impaired learners\n- **Modern Architecture**: TypeScript, React Native, and production-ready patterns\n- **Integration Excellence**: Seamless connection between voice, backend, and mobile\n- **Security Focus**: Proper authentication and data protection\n- **Scalability**: Architecture supports growth and additional features\n- **User Experience**: Intuitive interfaces for both learners and administrators\n\n---\n\n**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.**","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feli-keli%2Fsoundsteps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feli-keli%2Fsoundsteps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feli-keli%2Fsoundsteps/lists"}