Listle

A mobile-first grocery list application with AI-powered categorization and real-time multi-user sharing for self-hosted deployment.

Features

• Multiple Lists: Create and manage unlimited shopping lists
• AI-Powered Sorting: Automatically categorizes items with Claude AI (Produce, Dairy, Meat, Bakery, etc.)
• Visual Progress Bars: Track completion percentage for each category
• Share Lists: Generate passphrase-protected URLs to share lists with family
• Real-Time Sync: Collaborative editing with 2-second polling sync
• Mobile-First Design: Touch-optimized interface with custom modals
• Self-Hosted: Deploy on your own infrastructure with Docker

Quick Start

Option 1: Docker (Recommended)

docker-compose up -d

Visit http://localhost:3000

Option 2: Manual Setup

Prerequisites:

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

Installation:

npm install
node server.js

Visit http://localhost:3000

For full deployment instructions, see DOCKER.md.

How to Use

Personal Lists

1. Add Items: Type items and press Enter
2. Check Off Items: Tap items to mark as done
3. Sort with AI: Click "Magic Sort" to categorize (requires API key)
4. Create Lists: Use the dropdown to create and switch between lists

Sharing Lists

1. Click the share icon (network dots)
2. Enter a custom passphrase or use auto-generated one
3. Copy and share the URL with family members
4. Both users can edit and sync in real-time

AI Categorization

The app uses Claude AI to intelligently categorize your grocery items into sections like:

• 🥬 Produce (Fruits & Vegetables)
• 🥛 Dairy & Eggs
• 🥩 Meat & Seafood
• 🍞 Bakery
• 🥫 Pantry & Dry Goods
• 🧊 Frozen Foods
• 🥤 Beverages
• 🍪 Snacks
• 🧴 Personal Care
• 🧹 Household

Repository Structure

listle/
├── index.html              # Main HTML application
├── app.js                  # Frontend logic
├── styles.css              # Responsive styles
├── server.js               # Backend server
├── db.js                   # Database initialization
├── crypto.js               # Encryption utilities
├── package.json            # Node.js configuration
├── Dockerfile              # Docker image definition
├── docker-compose.yml      # Docker deployment config
├── .gitignore              # Git ignore patterns
├── README.md               # This file
├── PRD.md                  # Product requirements document
├── DOCKER.md               # Deployment instructions
└── .sdlc/                  # Development documentation (44 files)
    ├── testing/            # Test reports and scripts
    ├── implementation/     # Feature implementation docs
    ├── approval/           # PO approval documents
    └── security/           # Security audit reports

Technical Stack

Frontend:

• Vanilla JavaScript (no frameworks)
• Mobile-first CSS with custom modals
• localStorage for personal lists

Backend:

• Node.js 20 on Alpine Linux
• SQLite database for shared lists
• Anthropic Claude API (Haiku model)

Security:

• Passphrase-based sharing (no login required)
• AES-256-GCM API key encryption
• PBKDF2 key derivation (100k iterations)
• Rate limiting (10 sorts/hour per list)

Privacy & Security

• Local lists: Stored in browser localStorage, never leave your device
• Shared lists: Stored in SQLite database on your server
• API keys: Encrypted server-side, never exposed to clients
• No tracking: Self-hosted, no analytics or telemetry

Documentation

• PRD.md - Complete product requirements and architecture
• DOCKER.md - Docker deployment guide with reverse proxy examples
• .sdlc/ - Development documentation and test reports

Development

Local development:

npm install
node server.js

Run tests:

node .sdlc/testing/scripts/comprehensive-test.js

Docker build:

docker-compose build
docker-compose up

Contributing

This is a personal project designed for homelab deployment. Feel free to fork and adapt for your own use.

License

Free to use and modify for personal projects.

---

Built with Claude AI | Product Requirements | Deployment Guide