Obsidian → Summaries → Flashcards (Frontend + Backend)

This project processes an Obsidian vault, generates flashcards, and provides a web UI to practice them. Key features include:

• Automatic vault ingestion into a PostgreSQL database.
• Flashcard generation using LLMs (Ollama, OpenAI, or Azure).
• A React frontend for reviewing flashcards.
• Optional semantic search capability using Qdrant for embeddings.

---

Demo

---

Requirements

• Python 3.10+ and uv (https://docs.astral.sh/uv/)
• Node 20+ and pnpm (or npm)
• PostgreSQL (for storing flashcards and metadata)
• Qdrant vector database (for embeddings and semantic search)
• Ollama running locally (recommended), or OpenAI/Azure OpenAI key for LLM operations

Configure

1. Copy the env template and edit configuration:

cp .env.example .env

2. Edit .env to configure:

   • VAULT_DIR: path to your Obsidian vault
   • POSTGRES_*: PostgreSQL connection details (default: localhost:5432)
   • QDRANT_URL: Qdrant connection URL (default: http://localhost:6333)
   • LLM settings (LLM_BACKEND=ollama|openai|azure)

3. Start required services:

# Start PostgreSQL (if not already running)
brew services start postgresql@14  # macOS
# or use your system's PostgreSQL service

# Start Qdrant using Docker
docker run -d -p 6333:6333 -v $(pwd)/qdrant_data:/qdrant/storage qdrant/qdrant

Backend: Setup and Run

Install dependencies first:

cd backend
uv sync

Start the server:

uv run python main.py

The server will:

1. Initialize the PostgreSQL database tables.
2. Automatically ingest your Obsidian vault if the database is empty.
3. Start the FastAPI server at http://localhost:8000.

Frontend: run the flashcards UI

cd frontend
pnpm i    # or: npm i
pnpm dev  # or: npm run dev

Open the shown local URL. The frontend will connect to the backend API to load flashcards.

Flashcards JSON schema

{
  "cards": [
    {
      "question": "string (Markdown supported; code fences allowed)",
      "choices": ["A", "B", "C", "D"],
      "correct_index": 0,
      "hint": "optional"
    }
  ]
}

Questions can include code fences (js ... ). In the UI, hit V (or the Code button) to open the code preview pane and even Open Preview for html/js snippets.

API Reference

The backend provides a REST API with the following endpoints (all under the /api/v1 prefix):

• GET /health: Check server health and card count.
• GET /stats: Get statistics about the vault and database.
• GET /question/random: Get a single random flashcard.
• GET /questions/random?count=N: Get N random flashcards.

You can use these endpoints to build your own clients or integrate with other tools.

Notes

• If no LLM is configured, summarization/flashcards will fall back to a placeholder so the pipeline still runs.
• For best results: set LLM_BACKEND=ollama (local) or openai and a suitable model in .env.
• Make sure both PostgreSQL and Qdrant are running before starting the backend server
• The frontend automatically connects to the backend API for flashcard operations

Happy studying! 🎯