pievr/README.md

# pievr

Telegram bot for technical interview preparation using flashcards and smart prioritized spaced repetition.

## Overview

**pievr** is a personal Telegram bot designed to streamline technical interview preparation. Instead of standard rigid calendar intervals (like traditional spaced repetition apps), it uses a dynamic priority queue system based on recent performance and time elapsed.

## Core Concepts & Architecture

### 1. Dynamic Priority System
- **No Calendar Dates:** Spaced repetition doesn't rely on strict dates.
- **Priority Calculation:** Priorities are calculated dynamically in Go code based on:
  - Time elapsed since the question was last asked (older unseen/unasked questions rise in priority).
  - Success streak (`streak`): successful answers decrease priority, while mistakes increase it sharply.
- **New Questions Mix:** Unseen questions (`times_asked = 0`) have no priority and are smoothly mixed into study sessions in a configurable proportion alongside prioritized review questions.

### 2. Flexible Tagging
- Questions support multiple tags (many-to-many relationship) to allow granular topic filtering and cross-cutting selections (e.g., combining `go` and `concurrency`).

### 3. LLM Integration (Gemini API)
- **Configurable BaseURL:** Configurable via environment or config file to support proxies or custom endpoints.
- **Background Generation:** Background workers passively generate questions in bulk (e.g., in JSON batches) to maintain a target buffer of questions.
- **Self-Validation:** When questions are generated, the LLM validates them by answering its own questions before they enter the active pool.
- **Bot Interaction:** The bot can operate as an AI assistant with tool-use capabilities to query the database, manage tags, and fetch questions.

### 4. Database Schema (SQLite)
Stored locally in `storage/` (excluded via `.gitignore`):
- **`questions`**: Stores core content (`type`, `question_text`, `payload` as JSON, `active`, `last_asked_at`, `streak`, `times_asked`, `times_correct`, `created_at`).
- **`tags`**: Tag definitions (`name`).
- **`question_tags`**: Many-to-many mapping between questions and tags.

## Project Structure
- `cmd/` — Application entrypoints
- `internal/` — Private application code (domain, services, storage, bot handlers)
- `prompts/` — Prompt templates embedded via `go:embed`
- `storage/` — SQLite database files and schemas
- `docs/` — Documentation and architectural notes

## Development Workflow
1. Sync with `master` before starting any new feature branch.
2. Implement features or fixes in dedicated feature branches (`feature/...` or `fix/...`).
3. Rebase against `master` before pushing.
4. Open a Pull Request for review and merge.