Langsplain ✨

Understand any word, in any context.

Langsplain is an AI-powered language learning application designed to provide deep, contextual, and multi-faceted explanations for any word or phrase. Moving beyond simple dictionary definitions, it leverages a generative AI to act as a personal language tutor, helping users understand not just what a word means, but how to use it effectively.

Features

• 🧠 AI-Powered Explanations: Get rich, structured explanations covering simple definitions, analogies, contextual breakdowns, conversation examples, and comparisons with similar words.
• 🗣️ Conversational Study Mode: An innovative, interactive study mode where users respond to conversation prompts and receive real-time, AI-powered feedback and corrections.
• 🗓️ Spaced Repetition System (SRS): An intelligent flashcard system (based on the SM-2 algorithm) that schedules reviews at optimal intervals to strengthen long-term memory.
• 📚 Personal Deck Management: Full CRUD functionality for users to create, manage, and organize their saved words into focused study decks.
• ⚡ Fast & Efficient UI: A modern frontend built with performance in mind, featuring autocomplete search, pagination, skeleton loaders, and debouncing for a smooth user experience.
• 🔊 Text-to-Speech: Integrated with Google Cloud TTS for accurate pronunciation of words and phrases.
• 👤 User Authentication & Profiles: Secure, session-based authentication, with user profiles to track stats and manage settings.

Tech Stack

This project is a full-stack monorepo managed with pnpm and Turborepo.

Category	Technology
Backend	Bun (Runtime), Hono (Web Framework), Drizzle ORM (TypeScript ORM), PostgreSQL (Database), Redis (Session & Job Queue), BullMQ (Background Jobs), Mailjet (Transactional Emails), Google Cloud TTS
Frontend	React (UI Library), Vite (Build Tool), TanStack Router (Type-Safe Routing), TanStack Query (Data Fetching/State Management), Tailwind CSS v4 (Styling), Shadcn (Components)
DevOps	Docker & Podman (Containerization), Traefik (Reverse Proxy), Quadlet & systemd (Deployment)

Project Structure

This is a Turborepo-powered monorepo.

• apps/api: The Hono backend server.
• apps/web: The React (Vite) frontend application.
• packages/eslint-config: Shared ESLint configuration.
• packages/typescript-config: Shared tsconfig.json files.

Getting Started (Local Development)

Follow these steps to get the full development environment running locally.

Prerequisites

• Node.js (v20+)
• pnpm (v9+)
• Docker and Docker Compose

1. Clone the Repository

git clone https://git.leedude.xyz/malino/langsplain.git
cd langsplain

2. Install Dependencies

Install all dependencies for all workspaces using pnpm.

pnpm install

3. Set Up Environment Variables

Create a .env file in the root of the project by copying the example.

cp .env.example .env

Now, open the .env file and fill in your credentials:

# .env.example

# =====================
# App
# =====================
PORT=3000
LOG_LEVEL=debug   # options: debug, info, warn, error

# =====================
# Better Auth
# =====================
BETTER_AUTH_SECRET=your-secret-key-here
BETTER_AUTH_URL=https://your-domain.com/auth
TRUSTED_ORIGINS=["https://your-frontend.com"]

# =====================
# Database (Postgres)
# =====================
POSTGRES_USER=your_db_user
POSTGRES_PASSWORD=your_db_password
POSTGRES_DB=your_database_name
POSTGRES_PORT=5432
DATABASE_URL=postgresql://your_db_user:your_db_password@localhost:5432/your_database_name

# =====================
# Redis
# =====================
REDIS_HOST=localhost
REDIS_PORT=6379

# =====================
# Gemini (Google AI API)
# =====================
GEMINI_API_KEYS=["your-gemini-api-key"]

# =====================
# Email (Mailjet)
# =====================
MJ_APIKEY_PUBLIC=your-mailjet-public-key
MJ_APIKEY_PRIVATE=your-mailjet-private-key
MJ_SENDER_EMAIL=your-email@example.com

4. Start Infrastructure Services

This command will start the PostgreSQL database and Redis server in the background using Docker.

docker compose up -d

4. Start Infrastructure Services

This command uses Turborepo to run the dev script for all applications (api, web, worker) in parallel.

pnpm dev