Loopi

Your AI-powered skill tree for learning anything

---

Want to learn guitar? Master a new programming language? Finally understand quantum physics? Loopi makes it happen.

Tell Loopi what you want to learn, and it generates a personalized skill tree—breaking down complex topics into bite-sized goals you can actually achieve. Then, using the science-backed FSRS spaced repetition algorithm, Loopi schedules your reviews at the perfect moment to cement knowledge into long-term memory.

No more forgotten tutorials. No more abandoned courses. Just steady, measurable progress toward mastering anything you set your mind to.

Screenshots

Study Session	Goals Dashboard
Progress Statistics	Skill Tree

Features

• AI-Generated Skill Trees: Tell Loopi what you want to learn and watch it create a structured learning path with clear milestones
• Smart Goal Breakdown: Complex topics get decomposed into achievable sub-goals so you always know your next step
• FSRS Spaced Repetition: Science-backed algorithm schedules reviews at optimal intervals for maximum retention
• Interactive Study Sessions: Chat with Claude to deepen understanding, then reinforce with flashcard reviews
• Progress Visualization: Track your mastery across skills with intuitive dashboards and statistics
• Secure & Private: Email verification, encrypted API keys, and comprehensive security logging

Tech Stack

• Framework: Next.js 16.0.10 with React 19 and App Router
• Language: TypeScript 5.7
• Authentication: NextAuth.js 5
• Database: Hybrid architecture
  • PostgreSQL (users, conversations, messages, API keys)
  • LanceDB (flashcards, review logs, vector embeddings)
• AI: Anthropic Claude API, Jina Embeddings API
• Styling: Tailwind CSS 4
• Testing: Vitest, Playwright, React Testing Library

See ARCHITECTURE.md for detailed database design rationale.

Prerequisites

• Node.js 20 or higher
• npm or yarn
• Anthropic API key (get one here)

Getting Started

1. Clone the repository

git clone https://github.com/nicholaspsmith/loopi.git
cd loopi

2. Install dependencies

npm install

3. Configure environment variables

Create a .env.local file in the root directory:

# Authentication
NEXTAUTH_SECRET=your-secret-key-here
NEXTAUTH_URL=http://localhost:3000

# PostgreSQL Database (Supabase or local)
DATABASE_URL=postgresql://user:pass@host:5432/database

# LanceDB (local file-based)
DATABASE_PATH=./data/lancedb

# AI Services
ANTHROPIC_API_KEY=your-anthropic-api-key
JINA_API_KEY=your-jina-api-key

# Email Configuration (SMTP)
SMTP_HOST=smtp.ethereal.email
SMTP_PORT=587
SMTP_USER=your-ethereal-username
SMTP_PASS=your-ethereal-password
SMTP_FROM=noreply@loopi.com
NEXT_PUBLIC_APP_URL=http://localhost:3000

Generate a secure NEXTAUTH_SECRET:

openssl rand -base64 32

Email Setup for Development:

For development, use Ethereal Email - a fake SMTP service that captures emails without sending them:

1. Go to https://ethereal.email and click "Create Ethereal Account"
2. Copy the SMTP credentials to your .env.local
3. Password reset and verification emails will be captured at https://ethereal.email/messages

For production, configure a real SMTP provider (SendGrid, AWS SES, etc.).

Note: Users can optionally add their own Claude API key via the Settings page in the app (encrypted storage).

4. Initialize the database

npm run db:init

5. Start the development server

npm run dev

Open http://localhost:3000 in your browser.

Available Scripts

• npm run dev - Start development server
• npm run build - Build for production
• npm start - Start production server
• npm test - Run unit tests
• npm run test:integration - Run integration tests
• npm run test:e2e - Run end-to-end tests
• npm run db:seed - Seed database with sample data
• npm run lint - Run ESLint
• npm run type-check - Run TypeScript compiler

Project Structure

loopi/
├── app/                    # Next.js App Router
│   ├── (auth)/            # Authentication pages
│   ├── (protected)/       # Protected routes (chat, quiz)
│   └── api/               # API routes
├── components/            # React components
│   ├── auth/             # Authentication components
│   ├── chat/             # Chat interface components
│   ├── quiz/             # Quiz interface components
│   └── nav/              # Navigation components
├── lib/                   # Shared utilities
│   ├── db/               # Database client and queries
│   ├── claude/           # Claude API integration
│   ├── auth/             # NextAuth configuration
│   └── fsrs/             # FSRS scheduling logic
├── types/                 # TypeScript type definitions
└── tests/                 # Test files

## Usage

### Getting Started

1. Create an account and verify your email
2. Add your Anthropic API key in Settings (or use the shared key if available)

### Setting Learning Goals

1. Go to the Goals dashboard
2. Click "New Goal" and describe what you want to learn
3. Loopi generates a skill tree with sub-goals and milestones
4. Start with any goal that interests you

### Study Sessions

1. Select a goal to study
2. Chat with Claude to explore the topic and deepen understanding
3. Loopi automatically generates flashcards from your conversations
4. Review flashcards when they're due—rate each as Again, Hard, Good, or Easy
5. The FSRS algorithm schedules optimal review times for long-term retention

### Tracking Progress

1. View your skill tree to see mastery levels across all goals
2. Check the dashboard for upcoming reviews and study streaks
3. Watch your knowledge compound over time

## Development

### Running Tests

```bash
# Unit tests
npm test

# Integration tests
npm run test:integration

# E2E tests
npm run test:e2e

# All tests with coverage
npm run test:coverage

Code Quality

# Lint code
npm run lint

# Type check
npm run type-check

# Format code
npm run format

Deployment

Loopi uses Docker-based deployment with GitHub Actions CI/CD:

• Production URL: loopi.nicholaspsmith.com
• CI/CD: Automated testing and deployment on merge to main

Quick Start

# Local development with Docker
docker compose up -d

# Production deployment (see full guide)
./scripts/deploy.sh

Documentation

• Deployment Guide - VPS setup and deployment process
• Operations Runbook - Restart, rollback, backup procedures
• GitHub Secrets Setup - Required secrets configuration
• Uptime Monitoring - External monitoring setup

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT License - see LICENSE file for details

Support

For issues or questions, please open an issue on GitHub.