{"id":39862642,"url":"https://github.com/markmdev/lingput","last_synced_at":"2026-01-18T14:02:28.082Z","repository":{"id":284414021,"uuid":"954815050","full_name":"markmdev/lingput","owner":"markmdev","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-10T15:41:48.000Z","size":28978,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-10T19:45:10.227Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://lingput.dev/","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/markmdev.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-03-25T16:53:18.000Z","updated_at":"2025-09-10T15:41:52.000Z","dependencies_parsed_at":"2025-03-25T19:35:12.128Z","dependency_job_id":"0bb71854-9ad9-45cd-bf3f-9361f155faef","html_url":"https://github.com/markmdev/lingput","commit_stats":null,"previous_names":["morgan-mdev/compinput","mark-mdev/compinput","mark-mdev/lingput","markmdev/lingput"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/markmdev/lingput","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Flingput","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Flingput/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Flingput/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Flingput/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markmdev","download_url":"https://codeload.github.com/markmdev/lingput/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markmdev%2Flingput/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28537485,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T13:04:05.990Z","status":"ssl_error","status_checked_at":"2026-01-18T13:01:44.092Z","response_time":98,"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-01-18T14:02:24.310Z","updated_at":"2026-01-18T14:02:28.076Z","avatar_url":"https://github.com/markmdev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lingput - Production-Grade AI Language Learning Platform\n\n[![Tests](https://github.com/markmdev/lingput/actions/workflows/pr-tests.yml/badge.svg)](https://github.com/markmdev/lingput/actions/workflows/pr-tests.yml)\n[![Deploy](https://github.com/markmdev/lingput/actions/workflows/deploy.yml/badge.svg)](https://github.com/markmdev/lingput/actions/workflows/deploy.yml)\n\n**🚀 Live Demo:** https://lingput.dev/ | **📚 API Docs:** https://docs.lingput.dev/\n\n\u003cimg src=\"docs/logo_min.jpeg\" alt=\"Lingput logo\" width=\"320\" /\u003e\n\n## The Challenge\n\nTraditional language learning apps rely on flashcards and repetitive drills. **Lingput solves the real problem**: providing learners with **comprehensible input** - personalized stories at exactly their vocabulary level, complete with audio and smart word tracking.\n\n## Impact \u0026 Performance\n\n- **85% faster page load** (600ms → 85ms) by implementing Redis caching to eliminate multiple redundant database queries\n- **Zero-downtime deployments** with 80% reduction in deployment time (25min → 5min)\n- **Non-blocking user experience** replacing 30-second blocking API requests with async job queues and real-time progress updates\n- **Production-ready architecture** handling concurrent AI processing and real-time progress updates\n\n\u003cp align=\"center\" id=\"video-demo\"\u003e\n  \u003cimg src=\"docs/lingput-demo.gif\" width=\"960\" height=\"540\"/\u003e\n\u003c/p\u003e\n\n---\n\n## Technical Architecture Highlights\n\n### 🏗️ Scalable Backend Design\n\n- **Clean Architecture**: Multi-layered Express.js backend (Controller/Service/Repository) with dependency injection for maintainability and testability\n- **Async Job Processing**: BullMQ + Redis job queue system offloads heavy AI tasks, enabling responsive API and real-time progress tracking\n- **Intelligent Caching**: Redis-powered caching strategy dramatically reduces database load and API latency\n- **Secure Authentication**: HTTP-only cookies with access/refresh token flow, protecting against XSS attacks\n\n### ⚡ Performance Engineering\n\n- **Database Optimization**: PostgreSQL with Prisma ORM, optimized queries and connection pooling\n- **Caching Strategy**: Multi-layer caching (Redis) for frequently accessed stories and vocabulary data\n- **Background Processing**: Complex AI workflows (story generation, translation, audio synthesis) handled asynchronously\n- **Resource Management**: Docker containerization with optimized resource allocation\n\n### 🔄 Production DevOps\n\n- **CI/CD Pipeline**: Automated testing, linting, and deployment with GitHub Actions\n- **Containerized Deployment**: Docker Compose orchestration with NGINX reverse proxy\n- **Monitoring \u0026 Reliability**: Comprehensive error handling and job queue monitoring\n\n---\n\n## System Architecture\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/architecture.png\" alt=\"Architecture diagram\" width=\"650\"/\u003e\n\u003c/p\u003e\n\n### Story Generation Pipeline\n\n```\nUser Request → Job Queue → Background Worker Pipeline:\n├── Vocabulary Analysis (PostgreSQL)\n├── AI Story Generation (OpenAI)\n├── Chunk Translation (OpenAI)\n├── Lemmatization \u0026 Translation\n├── Audio Synthesis (TTS + FFmpeg)\n├── Asset Upload (Supabase)\n└── Database Persistence\n```\n\n**Frontend receives real-time progress updates throughout the entire pipeline.**\n\n---\n\n## Tech Stack\n\n**Backend \u0026 Infrastructure**\n\n- **API**: Express.js with TypeScript\n- **Database**: PostgreSQL + Prisma ORM\n- **Caching \u0026 Jobs**: Redis + BullMQ\n- **Authentication**: JWT with HTTP-only cookies\n- **DevOps**: Docker, NGINX, GitHub Actions\n\n**Frontend \u0026 User Experience**\n\n- **Framework**: Next.js (App Router) + TypeScript\n- **Styling**: Tailwind CSS\n- **State Management**: Custom React hooks for job lifecycle management\n- **Real-time Updates**: Polling-based progress tracking\n\n**External Services**\n\n- **AI**: OpenAI GPT for story generation and translation\n- **Storage**: Supabase for audio file management\n- **Deployment**: DigitalOcean + CapRover\n\n---\n\n## Key Features\n\n### For Language Learners\n\n- **Personalized Content**: AI generates stories tailored to individual vocabulary levels\n- **Comprehensive Learning**: Story text, translations, audio, and vocabulary tracking\n- **Progress Tracking**: Smart word learning system with spaced repetition principles\n- **Seamless UX**: Non-blocking interface with real-time generation progress\n\n### For Developers\n\n- **Production-Ready**: Built with scalability, maintainability, and reliability in mind\n- **Modern Architecture**: Clean separation of concerns with dependency injection\n- **Comprehensive Testing**: Unit and integration tests with CI/CD pipeline\n- **Developer Experience**: Fast local development setup with Docker Compose\n\n---\n\n## Getting Started\n\n### Prerequisites\n\n- Docker and Docker Compose\n- OpenAI API key\n- Supabase project (for audio storage)\n\n### Quick Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/markmdev/lingput\ncd lingput\n\n# Configure environment\ncp apps/backend/.env.example apps/backend/.env\ncp apps/frontend/.env.example apps/frontend/.env\n# Edit .env files with your API keys\n\n# Start all services\ndocker compose -f docker-compose-dev.yml up -d\n```\n\n**Access the app:** http://localhost:3050\n\n\u003e **Note:** Account creation takes 2 seconds with no email verification required for easy testing.\n\n### Environment Configuration\n\n**Backend (`apps/backend/.env`):**\n\n```env\nOPENAI_API_KEY=sk-...\nJWT_SECRET=your-secure-jwt-secret\nSUPABASE_URL=https://YOUR_PROJECT_ID.supabase.co\nSUPABASE_SERVICE_API_KEY=eyJ......\n```\n\n**Frontend (`apps/frontend/.env`):**\n\n```env\nNEXT_PUBLIC_AUDIO_BUCKET_URL=https://YOUR_PROJECT_ID.supabase.co/storage/v1/object/public/YOUR_BUCKET/\n```\n\n---\n\n## Development Workflow\n\n### Branch Protection \u0026 CI/CD\n\n- **Protected `main` branch**: All changes via Pull Requests\n- **Automated Testing**: ESLint + unit/integration tests on every PR\n- **Continuous Deployment**: Automatic deployment to production on merge\n- **Zero-Downtime Deployments**: Rolling updates with health checks\n\n### Code Quality Standards\n\n- **TypeScript Strict Mode**: Type safety throughout the application\n- **Clean Architecture**: Testable, maintainable code structure\n- **Comprehensive Testing**: Unit tests for business logic, integration tests for API endpoints\n- **Code Reviews**: All changes reviewed before merge\n\n---\n\n## Roadmap\n\n**Phase 1: Core Learning Experience** ✅\n\n- [x] Vocabulary assessment and personalized story generation\n- [x] Audio synthesis with synchronized translations\n- [x] Smart vocabulary tracking and progress monitoring\n\n**Phase 2: Enhanced Features** 🚧\n\n- [ ] Anki import/export functionality\n- [ ] Advanced word information (definitions, grammar, examples)\n- [ ] Detailed learning analytics and progress visualization\n- [ ] Offline audio download capability\n\n**Phase 3: Gamification \u0026 Social** 📋\n\n- [ ] Achievement system and learning streaks\n- [ ] Leaderboards and social learning features\n- [ ] Multi-language support expansion\n- [ ] Advanced TTS voice options\n\n---\n\n## Performance Benchmarks\n\n| Metric                | Before Optimization | After Optimization | Improvement      |\n| --------------------- | ------------------- | ------------------ | ---------------- |\n| Story Fetch API       | 600ms               | 85ms               | **85% faster**   |\n| Database Queries      | N/A                 | Cached             | **Reduced load** |\n| Deployment Time       | 25 minutes          | 5 minutes          | **80% faster**   |\n| Dev Environment Setup | 2 minutes           | 20 seconds         | **83% faster**   |\n\n---\n\n## Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork the repository** and create a feature branch\n2. **Follow the existing code style**: TypeScript strict mode, meaningful variable names\n3. **Write tests** for new functionality\n4. **Run the test suite**: `npm run test` before submitting\n5. **Create a Pull Request** with a clear description\n\n**Code Style Guidelines:**\n\n- Use early returns and avoid deep nesting\n- Prefer composition over inheritance\n- Write self-documenting code with clear function names\n- Include JSDoc comments for complex business logic\n\n---\n\n## License\n\nLicensed under the [ISC License](./LICENSE).\n\n---\n\n## Connect\n\nBuilt by **Mark** - Backend-focused Full-stack Developer  \n🌐 **Portfolio:** https://markmdev.com/  \n💼 **LinkedIn:** [Connect with me](https://www.linkedin.com/in/markmdev/)  \n📧 **Contact:** Open to backend and full-stack opportunities!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmdev%2Flingput","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkmdev%2Flingput","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkmdev%2Flingput/lists"}