flashcards_backend

A next-generation AI flashcard learning platform.

🌟 What is This Project?

flashcards_backend is more than just another study app. Our mission is to create a free, open-source, next-generation flashcard learning platform—smarter, faster, and more enjoyable thanks to AI.

Why We're Building This Current tools like Anki are powerful, but…

Making flashcards is tedious. The UI is outdated and feels like work. Most apps only support manual, text-based learning. We believe:

Everyone should have access to cutting-edge memory & AI tools. Learning should be effortless, modern, and fun. You should be able to learn from what you love—books, videos, memes, anything. Our Big Ideas

1. Smarter, Effortless Flashcards AI-powered creation. Instantly create rich, context-aware cards from anything—books, web text, videos, audio, screenshots. Automatic extras: Definitions, images, sample sentences, grammar tips, and even audio—all generated by AI. Less typing: Just highlight text or pause a video, and let the AI do the rest.
2. Learn From What You Love Read: Open books (public domain or uploads), highlight text, instantly get study cards. Watch: Watch YouTube/lessons inside the app, highlight phrases, and create cards on the spot. Listen/See: Grab vocabulary or concepts from spoken or visual content with instant card creation. All these feed into your “personal Anki”—but way easier.
3. Beautiful, Modern UI Designed to feel as intuitive and delightful as Instagram, Notion, or Duolingo—not like homework. Works great on web and Android (and more to come).
4. Truly Free and Open All features are free—no limits, no hidden fees. 100% open-source, so anyone can reuse, remix, or self-host. Our dream: Host public web/mobile versions powered by open AI models, but you’ll always own your data and learning journey.
5. Extensible and Social Future: Browser extension so you can add cards while reading or browsing anywhere online. Open to other learning modes—image cards, AI quizzes, chat with an AI teacher, and more. Why It Matters

Instant, personalized flashcards: No more tedious typing—learn while you live. Memorable learning: Context-rich cards help you remember faster—backed by science, supercharged by AI. Accessible for all: We’re democratizing memory, AI, and joy of learning.

🚀 Key Features

• Smarter Flashcards (AI-generated)
• Learn from what you love (books, videos, etc.)
• Beautiful UI/UX
• 100% Free and Open Source
• Community Deck Sharing with AI-powered spam protection
• Import/Export decks in multiple formats (Anki, CSV, JSON, Excel)
• Advanced Search and filtering
• User Authentication with secure JWT tokens

🏗️ Current Status

• ✅ Core flashcard API endpoints
• ✅ User authentication & authorization
• ✅ Database support (SQLite with SQLModel/SQLAlchemy)
• ✅ Import decks (Anki, CSV, JSON, Excel)
• ✅ Export decks (Anki, CSV, JSON, Excel)
• ✅ AI-powered deck generation
• ✅ Community deck sharing with spam protection
• ✅ GitHub Actions CI
• 🚧 More features coming soon!

📦 Requirements

Windows:

py -m venv venv
.\venv\Scripts\Activate.ps1
pip install -r requirements.txt
docker compose up -d

Linux/Mac:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
docker compose up -d

🏃‍♂️ Running the Backend

Windows (Easy way - using helper script):

.\run.ps1          # Runs on port 8000
.\run.ps1 8001     # Runs on port 8001

Windows (Manual way):

.\venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8000
# Or use py launcher:
py -m uvicorn app.main:app --reload --port 8000

Linux/Mac:

uvicorn app.main:app --reload

• API URL: http://127.0.0.1:8000 (or the port you specify)

⚠️ Windows Users: If you see "Python was not found" error, see QUICKSTART.md for solutions!

🛢️ Postgres DB via Docker

⚠️ IMPORTANT: Make sure Docker Desktop is running before starting the database!

# Start Docker Desktop first (if not already running)

# Then start the database container
docker compose up -d

# Check if it's running
docker ps

# View database logs
docker compose logs db

# Stop the database container
docker compose down

# Stop and delete ALL data
docker compose down -v

Troubleshooting:

• If you see "docker daemon is not running", start Docker Desktop
• Database runs on port 5555 (mapped from container port 5432)
• Connection string: postgresql+asyncpg://flashcards_user:supersecret@localhost:5555/flashcards

🤝 Contributing

See CONTRIBUTING.md.

📝 License

MIT - see file.

👀 More Info

• Quick Start Guide - Troubleshooting Python command issues on Windows
• Security Policy
• Code of Conduct
• Architecture Documentation
• Shared Deck Feature Guide
• AI Models Documentation
• Export Feature Guide