{"id":30362034,"url":"https://github.com/namandhakad712/felearn","last_synced_at":"2026-05-15T21:06:24.423Z","repository":{"id":306370316,"uuid":"1023583867","full_name":"namandhakad712/Felearn","owner":"namandhakad712","description":"Felearn AI","archived":false,"fork":false,"pushed_at":"2025-08-10T14:28:39.000Z","size":7056,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-08-10T14:44:02.990Z","etag":null,"topics":["ai","concepts","education","imagination","kitty","learners","learning","story","storybook","storytelling","vercel-deployment"],"latest_commit_sha":null,"homepage":"https://felearn.is-great.net","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/namandhakad712.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2025-07-21T11:34:04.000Z","updated_at":"2025-08-10T14:25:50.000Z","dependencies_parsed_at":"2025-08-10T14:44:01.388Z","dependency_job_id":null,"html_url":"https://github.com/namandhakad712/Felearn","commit_stats":null,"previous_names":["namandhakad712/felearn"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/namandhakad712/Felearn","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namandhakad712%2FFelearn","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namandhakad712%2FFelearn/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namandhakad712%2FFelearn/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namandhakad712%2FFelearn/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/namandhakad712","download_url":"https://codeload.github.com/namandhakad712/Felearn/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/namandhakad712%2FFelearn/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271189959,"owners_count":24715143,"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-08-19T02:00:09.176Z","response_time":63,"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":["ai","concepts","education","imagination","kitty","learners","learning","story","storybook","storytelling","vercel-deployment"],"created_at":"2025-08-19T17:01:51.414Z","updated_at":"2026-05-15T21:06:24.418Z","avatar_url":"https://github.com/namandhakad712.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐱 Felearn AI - Learn with Cute Cat Stories\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"public/assets/felearn-logo.webp\" alt=\"Felearn AI Logo\" width=\"120\" height=\"120\"\u003e\n  \n  **Transform complex concepts into engaging visual stories featuring adorable cats**\n  \n  [![Vercel](https://img.shields.io/badge/Deployed%20on-Vercel-black?style=for-the-badge\u0026logo=vercel)](https://felearn.vercel.app)\n  [![React](https://img.shields.io/badge/React-18-blue?style=for-the-badge\u0026logo=react)](https://reactjs.org/)\n  [![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?style=for-the-badge\u0026logo=typescript)](https://www.typescriptlang.org/)\n  [![Tailwind CSS](https://img.shields.io/badge/Tailwind-CSS-38B2AC?style=for-the-badge\u0026logo=tailwind-css)](https://tailwindcss.com/)\n  [![Appwrite](https://img.shields.io/badge/Appwrite-18-blue?style=for-the-badge\u0026logo=appwrite)](https://appwrite.io/)\n  [![Gemini AI](https://img.shields.io/badge/Gemini-AI-8E44AD?style=for-the-badge\u0026logo=googlegemini)](https://gemini.google.com/)\n\u003c/div\u003e\n\n## 🌟 Features\n\n### 🎨 **AI-Powered Visual Storytelling**\n- Generate engaging stories with cute cat illustrations using **Google Gemini 2.0 Flash**\n- **Multimodal AI** - Single model generates both text and images together\n- Real-time streaming updates as each slide is generated\n- Interactive story slides with smooth animations\n- Images optimized in WebP format for faster loading and smaller file sizes\n- Contextual captions and coordinated story-image pairs\n\n### 👤 **User Management**\n- Secure authentication with email verification\n- OAuth login (Google, GitHub)\n- Password reset functionality\n- User profile management with settings\n- Admin role support with unlimited privileges\n\n### 📊 **Smart Quota System**\n- **15 stories per day** for regular users\n- **Automatic daily reset** at midnight\n- **Real-time quota tracking** with live updates every 10 seconds\n- **Fair usage policy** - quota only deducted after successful generation\n- **Visual indicators** - Low quota warnings and countdown to reset\n- **Admin unlimited quota** - No restrictions for admin users\n- **Glassmorphism UI** - Beautiful quota display in dashboard header\n\n### 📚 **Story Library**\n- Save and organize your generated stories\n- Pin favorite stories for quick access\n- Advanced search and filter functionality\n- Story management (rename, delete, export)\n- Token usage tracking for each story\n- Automatic story saving after generation\n\n### 📄 **Export \u0026 Sharing**\n- Export stories to PDF format with high-quality images\n- Multiple export options (PDF, images)\n- Responsive design for all devices\n- Share stories with preserved formatting\n\n### 🎨 **Modern UI/UX**\n- Clean, intuitive glassmorphism interface\n- Dark/Light theme support with smooth transitions\n- Fully responsive design (mobile, tablet, desktop)\n- Smooth 60fps animations with Framer Motion and GSAP\n- Interactive elements with hover effects\n- Grainy texture overlays for depth\n- Real-time loading states and progress indicators\n\n## 🚀 Live Demo\n\nVisit [felearn.vercel.app](https://felearn.vercel.app) to try Felearn AI!\n\n## 🤖 AI Models \u0026 Technology\n\n### **Gemini 2.0 Flash - Multimodal AI**\nFelearn AI uses Google's latest **Gemini 2.0 Flash** model for both text and image generation:\n\n- **Single Model Architecture**: One multimodal model handles both story text and image generation\n- **Coordinated Output**: Text and images are generated together for better coherence\n- **Streaming Support**: Real-time updates as each slide is generated\n- **Free Tier**: Uses the free Gemini 2.0 Flash Preview for image generation\n- **Structured Output**: JSON schema support for consistent story formatting\n- **High Performance**: Fast generation with optimized token usage\n\n### **Key Features**\n- ✅ **Multimodal Generation**: Text + Images in one API call\n- ✅ **Real-Time Streaming**: Progressive slide-by-slide updates\n- ✅ **Token Tracking**: Accurate token usage reporting (prompt + response)\n- ✅ **Error Handling**: Automatic retry with exponential backoff\n- ✅ **Fallback Keys**: Multiple API key rotation for reliability\n- ✅ **Beta Access**: \"FREE\" key support for testing\n\n### **Generation Flow**\n```\nUser Prompt → Gemini 2.0 Flash → Multimodal Response\n                                 ├─ Text (Story sentences)\n                                 └─ Images (Cat illustrations)\n                                       ↓\n                              Coordinated Slides\n```\n\n## 🛠️ Tech Stack\n\n### **Frontend**\n- **React 18** - Modern React with hooks and concurrent features\n- **TypeScript** - Type-safe development\n- **Tailwind CSS** - Utility-first CSS framework\n- **Framer Motion** - Smooth animations and transitions\n- **GSAP** - High-performance animations\n- **React Router** - Client-side routing\n- **Vite** - Fast build tool and dev server\n- **Styled Components** - CSS-in-JS styling solution\n\n### **Backend \u0026 Services**\n- **Appwrite** - Backend-as-a-Service\n  - Database (NoSQL) - User and story management\n  - Authentication - Email, OAuth (Google, GitHub)\n  - File Storage - Image and PDF storage\n  - Real-time subscriptions\n- **Google Gemini AI** - Advanced AI models\n  - **Gemini 2.0 Flash** - Multimodal text and image generation\n  - Streaming responses for real-time updates\n  - Structured JSON output support\n- **Vercel** - Deployment and hosting with analytics\n- **PDF Libraries** - Story export functionality (jsPDF, pdf-lib, html2canvas)\n\n### **Development Tools**\n- **ESLint** - Code linting\n- **Prettier** - Code formatting\n- **TypeScript** - Static type checking\n- **PostCSS** - CSS processing\n- **Autoprefixer** - CSS vendor prefixing\n\n## 🏗️ Backend Architecture\n\n```mermaid\ngraph TD\n    A[Frontend - React App] --\u003e B[Appwrite Backend]\n    A --\u003e C[Gemini AI API]\n    \n    B --\u003e B1[(Users Collection)]\n    B --\u003e B2[(Stories Collection)]\n    B --\u003e B3[(Storage - Images)]\n    B --\u003e B4[(Storage - PDFs)]\n    \n    C --\u003e C1[Story Generation]\n    C --\u003e C2[Image Generation]\n    \n    B1 --\u003e D[Authentication Service]\n    B2 --\u003e E[Story Management]\n    B3 --\u003e F[Asset Storage]\n    B4 --\u003e G[Export Service]\n    \n    style A fill:#4CAF50,stroke:#388E3C\n    style B fill:#2196F3,stroke:#0D47A1\n    style C fill:#9C27B0,stroke:#4A148C\n    style B1 fill:#FF9800,stroke:#E65100\n    style B2 fill:#FF9800,stroke:#E65100\n    style B3 fill:#FF9800,stroke:#E65100\n    style B4 fill:#FF9800,stroke:#E65100\n    style C1 fill:#E91E63,stroke:#880E4F\n    style C2 fill:#E91E63,stroke:#880E4F\n```\n\n## 🎯 Usage Guide\n\n### 1. **Getting Started**\n- Sign up with email or use OAuth (Google/GitHub)\n- Verify your email address\n- Complete onboarding by adding your Gemini API key\n\n### 2. **Creating Stories**\n- Enter a concept you want explained (e.g., \"How do neural networks work?\")\n- Watch as AI generates a story with cute cat illustrations\n- Stories are automatically saved to your library\n\n### 3. **Smart Quota System**\n- **Daily Limit**: 15 story generations per day for regular users\n- **Automatic Reset**: Quota resets at midnight (00:00) every day\n- **Fair Usage**: Quota is **only deducted** after successful generation and save\n- **No Penalty**: Failed or interrupted generations don't consume quota\n- **Real-Time Tracking**: \n  - Live quota display in dashboard header\n  - Updates every 10 seconds automatically\n  - Manual refresh by clicking the quota display\n  - Countdown timer showing time until reset\n- **Visual Indicators**:\n  - Green checkmark (\u003e3 stories remaining)\n  - Yellow warning with pulse animation (≤3 stories)\n  - Red blocked icon (0 stories)\n  - Notification dot when quota is low\n- **Admin Privileges**: Unlimited quota for admin users (∞)\n- **Glassmorphism UI**: Beautiful frosted glass effect with grainy texture\n\n### 4. **Managing Stories**\n- View all your stories in the Library\n- Pin important stories\n- Search and filter by title or content\n- Rename, delete, or export stories\n\n### 5. **Exporting Stories**\n- Click the export button on any story\n- Choose PDF format\n- Download your story with high-quality images\n\n## ⚙️ Environment Configuration\n\nThe application requires certain environment variables to function properly. Copy the `.env.example` file to `.env` and configure the following variables:\n\n- `VITE_APPWRITE_ENDPOINT` - Your Appwrite endpoint\n- `VITE_APPWRITE_PROJECT_ID` - Your Appwrite project ID\n- `VITE_GEMINI_FALLBACK_API_KEY_*` - Fallback Gemini API keys for beta access\n\nThe application automatically detects and configures domains for email verification, making deployment to any platform seamless.\n\n## 📁 Project Structure\n\n```\nsrc/\n├── components/        # Reusable UI components\n│   ├── ui/           # UI components (QuotaDisplay, Toast, etc.)\n│   ├── dashboard/    # Dashboard-specific components\n│   ├── story/        # Story generation and display\n│   └── auth/         # Authentication components\n├── contexts/          # React context providers\n│   ├── AuthContext   # User authentication state\n│   └── ThemeContext  # Theme management\n├── hooks/             # Custom React hooks\n│   ├── useQuota      # Quota management hook\n│   ├── useAuth       # Authentication hook\n│   └── useStories    # Story CRUD operations\n├── services/          # API service integrations\n│   ├── gemini.ts     # Gemini AI integration\n│   ├── userService   # User management\n│   ├── storyService  # Story operations\n│   └── database      # Appwrite database\n├── types/             # TypeScript type definitions\n├── App.tsx            # Main application component\n└── main.tsx           # Application entry point\n```\n\n## 🔄 Quota System Architecture\n\n### **Database Schema**\n```typescript\nUser {\n  quota: number;        // Remaining stories (0-15)\n  lastLogin: string;    // ISO timestamp (used for daily reset)\n  isAdmin: boolean;     // Unlimited quota flag\n}\n```\n\n### **Real-Time Sync**\n```\n┌─────────────────────────────────────────┐\n│  useQuota Hook                          │\n│  ├─ Fetch every 10 seconds             │\n│  ├─ Event-based updates                │\n│  ├─ Manual refresh on click            │\n│  └─ Auto-reset at midnight             │\n└─────────────────────────────────────────┘\n           ↓\n┌─────────────────────────────────────────┐\n│  UserService                            │\n│  ├─ getUserQuota() - Read from DB      │\n│  ├─ decrementQuota() - Update DB       │\n│  ├─ resetUserQuota() - Reset to 15     │\n│  └─ needsQuotaReset() - Check date     │\n└─────────────────────────────────────────┘\n           ↓\n┌─────────────────────────────────────────┐\n│  Appwrite Database                      │\n│  └─ Users Collection                    │\n│     └─ quota field (integer, 0-15)     │\n└─────────────────────────────────────────┘\n```\n\n### **Daily Reset Logic**\n```typescript\n// Check if new day\nconst lastLoginDate = user.lastLogin.split('T')[0];\nconst today = new Date().toISOString().split('T')[0];\n\nif (lastLoginDate !== today) {\n  // Reset quota to 15\n  await updateUser({ quota: 15, lastLogin: now });\n}\n```\n\n## 📊 Performance \u0026 Metrics\n\n### **Lighthouse Scores**\n- **Performance**: 95+\n- **Accessibility**: 95+\n- **Best Practices**: 95+\n- **SEO**: 95+\n\n### **Loading Performance**\n- **First Contentful Paint**: \u003c 1.5s\n- **Time to Interactive**: \u003c 3s\n- **Bundle Size**: Optimized with code splitting\n- **Image Loading**: WebP format with lazy loading\n- **Animation Performance**: Smooth 60fps with GPU acceleration\n\n### **Optimization Features**\n- ✅ Code splitting by route and vendor\n- ✅ Tree shaking for minimal bundle size\n- ✅ Image optimization (WebP, lazy loading)\n- ✅ CSS minification and purging\n- ✅ Gzip compression\n- ✅ CDN delivery via Vercel\n- ✅ Service worker caching (PWA ready)\n\n### **Real-Time Features**\n- ✅ Live quota updates (10s interval)\n- ✅ Streaming story generation\n- ✅ Progressive image loading\n- ✅ Instant UI feedback\n- ✅ Optimistic updates\n\n## 🔒 Security\n\n### **Authentication \u0026 Authorization**\n- ✅ Secure authentication with Appwrite\n- ✅ Email verification required\n- ✅ OAuth 2.0 (Google, GitHub)\n- ✅ Password reset with email verification\n- ✅ Session management with JWT tokens\n- ✅ Role-based access control (Admin/User)\n\n### **Data Protection**\n- ✅ API keys encrypted and stored securely\n- ✅ Input validation and sanitization\n- ✅ XSS protection\n- ✅ CSRF protection\n- ✅ SQL injection prevention (NoSQL)\n- ✅ Rate limiting on API calls\n\n### **Infrastructure Security**\n- ✅ HTTPS enforced in production\n- ✅ Secure headers (CSP, HSTS)\n- ✅ Regular security updates\n- ✅ Environment variable protection\n- ✅ Secure cookie handling\n- ✅ CORS configuration\n\n## 🎯 Key Highlights\n\n| Feature | Description | Status |\n|---------|-------------|--------|\n| **AI Model** | Gemini 2.0 Flash (Multimodal) | ✅ Active |\n| **Daily Quota** | 15 stories/day with auto-reset | ✅ Active |\n| **Real-Time Sync** | 10-second quota updates | ✅ Active |\n| **Streaming** | Progressive story generation | ✅ Active |\n| **Token Tracking** | Accurate usage reporting | ✅ Active |\n| **Admin Panel** | Unlimited quota for admins | ✅ Active |\n| **Dark Mode** | Full theme support | ✅ Active |\n| **PDF Export** | High-quality story export | ✅ Active |\n| **OAuth Login** | Google \u0026 GitHub | ✅ Active |\n| **Mobile Support** | Fully responsive | ✅ Active |\n\n## 🆚 Why Felearn AI?\n\n### **Unique Features**\n- 🎨 **Cat-Themed Learning** - Makes complex topics fun and memorable\n- 🤖 **Latest AI** - Uses cutting-edge Gemini 2.0 Flash\n- 📊 **Fair Quota System** - Only charges for successful generations\n- ⚡ **Real-Time Updates** - See your story being created live\n- 🎭 **Beautiful UI** - Glassmorphism design with smooth animations\n- 🔄 **Auto-Save** - Never lose your generated stories\n- 📱 **Mobile-First** - Works perfectly on all devices\n- 🌙 **Dark Mode** - Easy on the eyes, day or night\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n\n## 🛠️ Development Setup\n\n### Prerequisites\n- Node.js \u003e= 18.0.0\n- npm \u003e= 8.0.0\n\n### Installation\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/namandhakad712/Felearn.git\n   ```\n2. Navigate to the project directory:\n   ```bash\n   cd Felearn\n   ```\n3. Install dependencies:\n   ```bash\n   npm install\n   ```\n4. Set up environment variables:\n   - Copy `.env.example` to `.env`\n   - Add your Appwrite and Gemini API keys\n\n### Development\n```bash\nnpm run dev\n```\nVisit `http://localhost:5173` to view the application.\n\n### Building for Production\n```bash\nnpm run build\n```\n\n### Deployment\n```bash\nnpm run deploy\n```\n\n## 🐛 Troubleshooting\n\n### **Quota Not Updating?**\n1. Check browser console for logs: `📊 Quota fetched from database`\n2. Click the quota display to manually refresh\n3. Verify your user has the `quota` field in Appwrite database\n4. Check that `lastLogin` is being updated\n\n### **Story Generation Fails?**\n1. Verify your Gemini API key is valid\n2. Check API key has image generation permissions\n3. Try using \"FREE\" for beta access\n4. Check console for error messages\n5. Ensure you have quota remaining\n\n### **Images Not Loading?**\n1. Check network tab for failed requests\n2. Verify Appwrite storage permissions\n3. Clear browser cache\n4. Try regenerating the story\n\n### **Database Errors?**\n1. Ensure all required fields exist in Appwrite:\n   - `quota` (integer, 0-100000000)\n   - `lastLogin` (string)\n   - `email`, `name`, `geminiKey`, etc.\n2. Check Appwrite collection permissions\n3. Verify API keys in `.env` file\n\n### **Need Help?**\n- 📧 Email: support@felearn.ai\n- 🐛 Issues: [GitHub Issues](https://github.com/namandhakad712/Felearn/issues)\n- 💬 Discussions: [GitHub Discussions](https://github.com/namandhakad712/Felearn/discussions)\n\n## 🌟 Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=namandhakad712/Felearn\u0026type=Date)](https://star-history.com/#namandhakad712/Felearn\u0026Date)\n\n---\n\n## 📈 Roadmap\n\n### **Coming Soon**\n- [ ] Premium tiers with higher quotas (25, 50, 100 stories/day)\n- [ ] Story sharing and collaboration\n- [ ] Custom cat character selection\n- [ ] Voice narration for stories\n- [ ] Multiple language support\n- [ ] Story templates and themes\n- [ ] Community story gallery\n- [ ] Mobile app (iOS \u0026 Android)\n- [ ] API access for developers\n- [ ] Webhook integrations\n\n### **In Progress**\n- [x] Gemini 2.0 Flash integration\n- [x] Real-time quota system\n- [x] Glassmorphism UI redesign\n- [x] Token usage tracking\n- [x] Admin dashboard\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### **Ways to Contribute**\n- 🐛 Report bugs\n- 💡 Suggest features\n- 📝 Improve documentation\n- 🎨 Design improvements\n- 🔧 Code contributions\n- 🌍 Translations\n\n## 📜 Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for a list of changes.\n\n## 🙏 Acknowledgments\n\n- **Google Gemini AI** - For the amazing multimodal AI capabilities\n- **Appwrite** - For the robust backend infrastructure\n- **Vercel** - For seamless deployment and hosting\n- **React Team** - For the incredible framework\n- **Open Source Community** - For all the amazing libraries\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cp\u003eMade with ❤️ and 🐱 by \u003ca href=\"https://github.com/namandhakad712\"\u003eNaman Dhakad\u003c/a\u003e\u003c/p\u003e\n  \n  \u003cp\u003e\n    \u003ca href=\"https://felearn.vercel.app\"\u003e🌐 Website\u003c/a\u003e •\n    \u003ca href=\"https://github.com/namandhakad712/Felearn\"\u003e💻 GitHub\u003c/a\u003e •\n    \u003ca href=\"https://github.com/namandhakad712/Felearn/issues\"\u003e🐛 Issues\u003c/a\u003e •\n    \u003ca href=\"https://github.com/namandhakad712/Felearn/discussions\"\u003e💬 Discussions\u003c/a\u003e\n  \u003c/p\u003e\n  \n  \u003cp\u003e\n    \u003cstrong\u003e⭐ Star this repo if you find it helpful!\u003c/strong\u003e\n  \u003c/p\u003e\n  \n  \u003cp\u003e\n    \u003csub\u003eBuilt with React • TypeScript • Tailwind CSS • Gemini AI • Appwrite\u003c/sub\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamandhakad712%2Ffelearn","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnamandhakad712%2Ffelearn","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnamandhakad712%2Ffelearn/lists"}