{"id":48596178,"url":"https://github.com/emminix/electrosage","last_synced_at":"2026-04-08T21:02:04.751Z","repository":{"id":304314603,"uuid":"1018338208","full_name":"EmminiX/ElectroSage","owner":"EmminiX","description":"🔌 ElectroSage Academy - Master Electrical Engineering with AI-powered Socratic tutoring, 14 interactive visualizations, and professional circuit tools. Comprehensive educational platform with accessibility features, progress tracking, and external learning resources.","archived":false,"fork":false,"pushed_at":"2026-04-05T21:44:22.000Z","size":171228,"stargazers_count":0,"open_issues_count":23,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-05T23:25:38.493Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://electro-sage-gamma.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EmminiX.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-07-12T04:02:07.000Z","updated_at":"2026-04-05T21:43:29.000Z","dependencies_parsed_at":"2025-07-12T10:36:41.109Z","dependency_job_id":null,"html_url":"https://github.com/EmminiX/ElectroSage","commit_stats":null,"previous_names":["emminix/electrosage"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/EmminiX/ElectroSage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmminiX%2FElectroSage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmminiX%2FElectroSage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmminiX%2FElectroSage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmminiX%2FElectroSage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EmminiX","download_url":"https://codeload.github.com/EmminiX/ElectroSage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EmminiX%2FElectroSage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31573788,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-08T21:01:15.752Z","updated_at":"2026-04-08T21:02:04.721Z","avatar_url":"https://github.com/EmminiX.png","language":"TypeScript","readme":"# ElectroSage Academy\n\nA comprehensive electrical education platform featuring AI-powered Socratic tutoring, 14 interactive visualizations, educational podcasts, voice-to-text learning, and professional circuit building tools. Master electrical engineering from fundamentals to advanced concepts.\n\n**🚀 Live Demo**: [Visit ElectroSage Academy](https://github.com/EmminiX/ElectroSage)\n\n![ElectroSage Academy Interface](./public/electrosage-screenshot.jpg)\n\n*ElectroSage Academy's comprehensive learning interface featuring AI-powered Socratic tutoring, interactive content navigation, and real-time progress tracking.*\n\n## Features\n\n### 🎓 Comprehensive Electrical Education\n- **8 Progressive Sections**: From atomic structure to advanced electronic components\n- **Professional Curriculum**: Structured learning path with mastery tracking\n- **Interactive Content**: Rich educational content with embedded visualizations\n- **Real-world Applications**: Practical knowledge for electrical engineering\n\n### 🤖 AI-Powered Socratic Tutoring\n- **ElectroSage AI**: Advanced AI tutor using Socratic questioning method\n- **Personalized Learning**: Context-aware responses tailored to your progress\n- **Guided Discovery**: Never gives direct answers - helps you discover solutions\n- **Conversation History**: Maintains context across learning sessions\n- **Voice-to-Text**: Powered by OpenAI Whisper for natural speech input\n\n### 🔧 14 Interactive Visualizations\n- **Circuit Builder**: Professional circuit construction with component library\n- **Atomic Structure**: Interactive atomic models showing conductivity properties\n- **AC Waveform Analysis**: Real-time frequency analysis and RMS calculations\n- **Series/Parallel Circuits**: Current division and voltage drop demonstrations\n- **Transformer Operation**: Interactive transformer voltage transformation\n- **Capacitor/Inductor Effects**: Charging curves and magnetic field visualization\n- **Safety Demonstrations**: Interactive electrical safety scenarios\n- **Resistance Effects**: Heat generation and material property visualization\n\n### 🎧 Educational Podcasts\n- **8 Section-Based Episodes**: Professional podcast series covering each course section\n- **Expert Insights**: In-depth discussions and real-world applications\n- **iPhone Dynamic Island Player**: Minimalist audio player with track controls\n- **Integrated Learning**: Podcasts complement visualizations and written content\n\n### 🎤 Voice-to-Text Learning\n- **OpenAI Whisper Integration**: High-accuracy speech-to-text transcription\n- **Natural Voice Input**: Speak questions directly to the AI tutor\n- **HTTPS Security**: Secure microphone access with permission management\n- **Real-time Processing**: Live audio level feedback and instant transcription\n\n### ♿ Accessibility Features\n- **Keyboard Navigation**: Full keyboard support for all interactions\n- **High Contrast Mode**: Enhanced visibility for users with visual impairments\n- **Reduced Motion**: Respects user preferences for motion sensitivity\n- **Focus Management**: Clear focus indicators and logical tab order\n- **Screen Reader Support**: ARIA labels and semantic HTML\n- **Voice Input**: Speech-to-text for hands-free interaction\n\n## Getting Started\n\n### Prerequisites\n- Node.js 18+ \n- npm or yarn\n- OpenAI API key\n\n### Installation\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/EmminiX/ElectroSage.git\n   cd ElectroSage\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Set up environment variables**\n   ```bash\n   cp .env.example .env.local\n   ```\n   \n   Edit `.env.local` and add your OpenAI API key:\n   ```\n   OPENAI_API_KEY=your_openai_api_key_here\n   ```\n\n4. **Run the development server**\n   ```bash\n   npm run dev\n   ```\n\n5. **Open your browser**\n   Navigate to [http://localhost:4100](http://localhost:4100)\n\n## Deployment\n\n### 🐳 Docker Deployment (Recommended)\n\nThe easiest way to deploy ElectroSage Academy is using Docker Compose:\n\n1. **Prerequisites**\n   - Docker and Docker Compose installed\n   - OpenAI API key\n\n2. **Environment Setup**\n   ```bash\n   # Copy the environment template\n   cp .env.example .env.local\n   \n   # Edit .env.local with your OpenAI API key\n   nano .env.local\n   ```\n\n3. **Deploy with Docker Compose**\n   ```bash\n   # Build and start the application\n   docker compose build\n   docker compose up -d\n   \n   # View logs (optional)\n   docker compose logs -f\n   ```\n\n4. **Access the Application**\n   - Open your browser to [http://localhost:4100](http://localhost:4100)\n   - The application will be running in production mode with optimized performance\n\n5. **Management Commands**\n   ```bash\n   # Stop the application\n   docker compose down\n   \n   # Rebuild after code changes\n   docker compose build --no-cache\n   docker compose up -d\n   \n   # View application status\n   docker compose ps\n   ```\n\n### Traditional Production Build\n```bash\nnpm run build\nnpm start\n```\n\n### Environment Variables for Production\n- `OPENAI_API_KEY`: Your OpenAI API key (**required**)\n- `OPENAI_MODEL`: AI model to use (default: gpt-4)\n- `OPENAI_MAX_TOKENS`: Maximum tokens per response (default: 1000)\n- `OPENAI_TEMPERATURE`: AI response creativity (default: 0.7)\n- `NEXT_PUBLIC_APP_NAME`: Application name\n- `NEXT_PUBLIC_APP_VERSION`: Application version\n- `NODE_ENV`: Set to \"production\" for optimized builds\n- `PORT`: Application port (default: 4100)\n\n### Deployment Platforms\nThis app can be deployed on:\n- **Docker Compose** (recommended - see above)\n- **Vercel** (excellent for Next.js)\n- **Netlify**\n- **AWS Amplify**\n- **Digital Ocean App Platform**\n- **Heroku**\n- **Any VPS with Docker support**\n\n## Usage Guide\n\n### Navigation\n- Use the sidebar to navigate between sections\n- Progress is automatically tracked\n- Settings panel (⚙️) for accessibility options\n\n### ElectroSage AI Tutor\n- Click the chat icon to open the AI tutor\n- Experience Socratic method teaching - no direct answers!\n- Get guided discovery through electrical concepts\n- Ask questions about any section for personalized help\n- Use voice input by clicking the microphone button (requires HTTPS or localhost)\n- Speak naturally - Whisper AI converts speech to text\n\n### Interactive Visualizations\n- 14 advanced visualizations available across all sections\n- Circuit Builder: Professional drag-and-drop circuit construction\n- Atomic Structure: Explore elements and their conductivity properties\n- AC Waveform: Real-time frequency analysis and oscilloscope simulation\n- Transformer Demo: Interactive voltage transformation visualization\n- Safety Scenarios: Interactive electrical safety training\n\n### Educational Podcasts\n- 8 professional podcast episodes, one for each course section\n- Access via the iPhone Dynamic Island-style player in the top navigation\n- Auto-minimize functionality with smooth playback transitions\n- Full track controls with next/previous and episode selection dropdown\n\n### Accessibility\n- Press `Ctrl/Cmd + A` to open accessibility panel\n- Use Tab/Shift+Tab for keyboard navigation\n- Enable high contrast or reduced motion as needed\n- Voice input available for hands-free interaction\n- Full screen reader support with ARIA labels\n\n## Technical Architecture\n\n### Frontend Stack\n- **Next.js 15**: React framework with App Router for optimal performance\n- **TypeScript**: Type-safe development with full IntelliSense support\n- **Tailwind CSS**: Utility-first CSS framework for responsive design\n- **React Context**: Global state management for learning progress and accessibility\n- **Framer Motion**: Smooth animations and transitions\n\n### Interactive Visualizations\n- **D3.js**: Advanced data visualization library for educational charts\n- **Three.js**: 3D graphics engine for atomic structure visualization\n- **Canvas API**: Professional circuit builder with drag-and-drop interface\n- **Web Audio API**: Real-time audio processing for AC waveform analysis\n\n### Backend \u0026 AI\n- **Next.js API Routes**: Server-side functionality and API endpoints\n- **OpenAI GPT-4**: Advanced AI tutoring with Socratic method implementation\n- **OpenAI Whisper**: High-accuracy speech-to-text transcription\n- **Markdown Processing**: Rich content rendering with mathematical expression support\n- **Remark/Rehype**: Extensible markdown processing pipeline\n\n### DevOps \u0026 Deployment\n- **Docker**: Containerized deployment with multi-stage builds\n- **Docker Compose**: Orchestration for easy local and production deployment\n- **ESLint \u0026 TypeScript**: Code quality and type checking\n- **Next.js Optimization**: Automatic code splitting and performance optimization\n\n### Key Components\n- `ContentContext`: Manages learning content and navigation\n- `ProgressContext`: Tracks user progress and achievements\n- `AccessibilityContext`: Handles accessibility preferences\n- `PodcastContext`: Manages podcast player state and episodes\n- `TourContext`: Handles interactive onboarding tour system\n- `ChatInterface`: AI tutor integration with voice input\n- `SpeechRecorder`: Voice-to-text component using OpenAI Whisper\n- `PodcastPlayer`: iPhone Dynamic Island-style audio player\n- `VisualizationContainer`: Interactive learning tools\n\n## Development\n\n### Project Structure\n```\nsrc/\n├── app/                 # Next.js App Router pages\n├── components/          # React components\n├── contexts/           # React Context providers\n├── data/              # Static data and types\n├── hooks/             # Custom React hooks\n├── lib/               # Utility functions\n└── styles/            # Global styles\n```\n\n### Scripts\n- `npm run dev`: Start development server\n- `npm run build`: Create production build\n- `npm run start`: Start production server\n- `npm run lint`: Run ESLint\n\n### Performance Features\n- **Next.js 15 Optimizations**: Automatic code splitting and tree shaking\n- **Image Optimization**: Responsive images with WebP format\n- **Static Generation**: Pre-rendered pages for faster loading\n- **Edge Runtime**: Optimized API routes with global deployment\n- **Progressive Web App**: Offline support and mobile app-like experience\n\n## Troubleshooting\n\n### Common Issues\n\n**1. OpenAI API Key Issues**\n```bash\n# Verify your API key is set correctly\necho $OPENAI_API_KEY\n\n# Check if the key has the correct permissions\n# Ensure your OpenAI account has sufficient credits\n```\n\n**2. Docker Build Fails**\n```bash\n# Clear Docker cache and rebuild\ndocker system prune -f\ndocker compose build --no-cache\n```\n\n**3. Port Already in Use**\n```bash\n# Change the port in docker-compose.yml or .env.local\n# Default port is 4100, you can use any available port\n```\n\n**4. Voice Input Not Working**\n- Ensure you're using HTTPS or localhost\n- Check browser microphone permissions\n- Verify Web Audio API support in your browser\n\n**5. Visualizations Not Loading**\n- Clear browser cache and cookies\n- Ensure JavaScript is enabled\n- Check browser console for any errors\n\n### Browser Compatibility\n- **Chrome**: Fully supported (recommended)\n- **Firefox**: Fully supported\n- **Safari**: Fully supported\n- **Edge**: Fully supported\n- **Mobile**: Responsive design works on all mobile browsers\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## Educational Content\n\n### Learning Sections\n1. **Introduction to Electrical Engineering** - Foundational concepts and career overview\n2. **Atomic Structure and Electrical Fundamentals** - How matter enables electrical flow\n3. **Understanding the Atom** - Detailed atomic behavior and electrical properties\n4. **Electron Shells and Valence Electrons** - Electronic structure and conductivity\n5. **Electrical Charge and Charge Interaction** - Fundamental forces and field theory\n6. **Coulomb's Law and Charge Quantification** - Mathematical foundations of electrostatics\n7. **Basic Electrical Units and Properties** - Standard units and measurement principles\n8. **Circuit Fundamentals** - Practical circuit analysis and component behavior\n\n### Assessment \u0026 Progress\n- **Interactive Quizzes**: Knowledge verification for each section\n- **Progress Tracking**: Visual progress indicators and completion statistics\n- **Mastery-Based Learning**: Must demonstrate understanding before advancing\n- **Socratic AI Feedback**: Personalized guidance without giving direct answers\n\n## Contributing\n\nWe welcome contributions to ElectroSage Academy! Here's how you can help:\n\n### Development Setup\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests if applicable\n5. Ensure all tests pass (`npm run lint`)\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n### Areas for Contribution\n- **Educational Content**: Additional sections, improved explanations\n- **Visualizations**: New interactive demonstrations and simulations\n- **Accessibility**: Enhanced screen reader support and keyboard navigation\n- **Internationalization**: Multi-language support\n- **Performance**: Optimization and speed improvements\n- **Testing**: Unit tests and integration tests\n\n## License\n\nThis project is licensed under the ISC License. See the LICENSE file for details.\n\n## Acknowledgments\n\n- **OpenAI**: For providing the GPT-4 and Whisper APIs that power our AI tutoring\n- **Next.js Team**: For the excellent React framework and development experience\n- **Educational Community**: For feedback and suggestions that improve the learning experience\n\n## Support\n\n- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/EmminiX/ElectroSage/issues)\n- **Discussions**: Join community discussions in [GitHub Discussions](https://github.com/EmminiX/ElectroSage/discussions)\n- **Documentation**: Find additional help in our [Wiki](https://github.com/EmminiX/ElectroSage/wiki)\n\n---\n\n**Made with ❤️ for electrical engineering education**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femminix%2Felectrosage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femminix%2Felectrosage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femminix%2Felectrosage/lists"}