Vocabularium

Vocabularium is an intelligent language learning application that helps users build and maintain their vocabulary through spaced repetition. It uses advanced AI for translations and sophisticated scheduling algorithms to optimize learning retention.

🌐 Live Demo: vocabularium.binaj.dev

Features

• 📚 Create and manage vocabulary decks
• 🤖 AI-powered translations and conjugations
• 📊 Smart review scheduling using FSRS algorithm
• 🌍 Support for multiple languages (English, French, German, Spanish)
• 🔄 Spaced repetition learning system
• 📱 Responsive web design

Tech Stack

Core

• Framework: SolidStart - Server-side rendering with SolidJS
• Database: SQLite - Embedded database
• ORM: Drizzle - TypeScript ORM
• Styling: TailwindCSS - Utility-first CSS

Key Dependencies

• Auth: Argon2 for password hashing
• AI Integration: OpenAI API for translations
• Scheduling: ts-fsrs - Free Spaced Repetition Scheduler

Infrastructure

• Containerization: Docker
• Deployment: Self-hosted with Docker Compose
• Development: Bun as runtime and package manager

Spaced Repetition System

Vocabularium uses the Free Spaced Repetition Scheduler (FSRS) algorithm, an advanced implementation that improves upon traditional systems like SM-2. The system:

• Adapts to individual learning patterns
• Optimizes review intervals based on performance
• Uses difficulty factors to personalize scheduling
• Implements fuzzy scheduling for natural review patterns

Learn more about FSRS at the algorithm documentation.

Local Development

Prerequisites

• Bun (>= 1.0.0)
• Docker and Docker Compose (optional)

Setup

1. Clone the repository:

git clone https://github.com/yourusername/vocabularium.git
cd vocabularium

2. Install dependencies:

bun install

3. Create environment file:

cp .env.example .env

4. Update .env with your settings:

DATABASE_URL=file:/data/db.sqlite
SESSION_SECRET="your-secret-here"
OPENAI_KEY="your-openai-key"

5. Create data directory and set permissions:

sudo mkdir -p /var/lib/vocabularium/data
sudo chown -R `whoami` /var/lib/vocabularium

6. Initialize database:

bun migrate
bun run src/database/seed.ts

Running the Application

Development Mode

bun dev

Production Build

bun run build
bun start

Docker Deployment

Build and run with Docker Compose:

docker compose up --build

The application will be available at http://localhost:4269.

Project Structure

vocabularium/
├── src/
│   ├── ai/           # AI integration for translations
│   ├── api/          # Server-side API routes
│   ├── components/   # Reusable UI components
│   ├── database/     # Database schema and migrations
│   ├── routes/       # Application routes
│   └── utils/        # Utility functions
├── public/           # Static assets
└── docker/          # Docker configuration

Contributing

I welcome contributions! Please feel free to submit a Pull Request.

TODO

Like every project, this is a never ending product. Check the TODO file to learn more about the roadmap.

License

This project is licensed under the Apache License - see the LICENSE file for details.