# Listopia

[![Ruby on Rails](https://img.shields.io/badge/Rails-8.0+-d82c20?style=flat-square&logo=rails)](https://rubyonrails.org)
[![Ruby](https://img.shields.io/badge/Ruby-3.4.7-d91c1c?style=flat-square&logo=ruby)](https://www.ruby-lang.org)
[![Tests](https://github.com/spaquet/listopia/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/spaquet/listopia/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/License-AGPL%20v3-blue?style=flat-square)](LICENSE)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15+-336791?style=flat-square&logo=postgresql)](https://www.postgresql.org)
[![Hotwire](https://img.shields.io/badge/Hotwire-Turbo%20%26%20Stimulus-5F3DC4?style=flat-square&logo=turbo)](https://hotwired.dev)

![Listopia Screenshot](https://raw.githubusercontent.com/spaquet/listopia/main/images/screenshot.png)

**Listopia** is a modern, collaborative list management application built with Ruby on Rails 8. It showcases cutting-edge Rails development practices, offering real-time collaboration, passwordless authentication, and a responsive, user-friendly interface powered by Tailwind CSS.

## Core Mission

Listopia aims to provide a powerful yet intuitive platform for organizing tasks, projects, and collaborative workflows, while serving as a reference for modern Rails 8 development. Whether you're managing personal to-do lists or collaborating with a team, Listopia delivers a seamless experience with live updates and smart features.

## Key Features

- **Real-Time Collaboration**: Instant updates for shared lists using Hotwire Turbo Streams.
- **Passwordless Authentication**: Secure magic link sign-in alongside traditional methods.
- **Smart Lists**: Organize tasks, notes, links, files, and reminders with drag-and-drop reordering.
- **Responsive Design**: Mobile-first interface built with Tailwind CSS for accessibility and performance.
- **Progress Tracking**: Visualize completion percentages and track collaborator activity.
- **Secure Sharing**: Granular permissions and public sharing options with unique URLs.
- **AI-Powered Chat**: Control Listopia with natural language commands. See [AI_DISCLAIMER.md](AI_DISCLAIMER.md) for important information on limitations and risks.

## Documentation

Listopia has comprehensive documentation organized by task and audience. Get started with the right guide for your needs:

- **Architecture Overview** → [CLAUDE.md](CLAUDE.md) - Master development reference with stack overview, architecture patterns, and standards
- **Chat System** → [docs/README.md](docs/README.md) - Complete chat documentation (flow, request types, model selection, features)
- **Building Chat Features** → [docs/CHAT_FEATURES.md](docs/CHAT_FEATURES.md) - Implementation guide for adding commands, tools, and message templates
- **Search & RAG** → [docs/RAG_SEMANTIC_SEARCH.md](docs/RAG_SEMANTIC_SEARCH.md) - Complete guide to embeddings, vector search, and RAG integration

**For Developers:**
- New team members? → Start with [docs/README.md](docs/README.md) for documentation index
- Want to understand chat? → Follow [docs/CHAT_FLOW.md](docs/CHAT_FLOW.md) then [docs/CHAT_REQUEST_TYPES.md](docs/CHAT_REQUEST_TYPES.md)
- Implementing chat features? → Follow [docs/CHAT_FEATURES.md](docs/CHAT_FEATURES.md)
- Need architecture details? → See [CLAUDE.md](CLAUDE.md)

**For AI Agents & Claude Code:**
[docs/README.md](docs/README.md) provides the complete documentation structure and optimal entry points for any task.

## Getting Started

To set up and run Listopia locally, follow the instructions in [INSTALL.md](INSTALL.md).

## Contributing

We welcome contributions to Listopia! Please review our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) to ensure a positive community environment.

## License

Listopia is licensed under the [GNU Affero General Public License v3.0](LICENSE). This ensures that any modified versions used in a SaaS context must make their source code available. See the [LICENSE](LICENSE) file for details.

## Security

Security features including authentication, authorization, prompt injection detection, and content moderation are documented in [docs/AUTHENTICATION.md](docs/AUTHENTICATION.md) and [docs/CHAT_FEATURES.md](docs/CHAT_FEATURES.md#authorization--security).

## Why Listopia?

Listopia is both a practical tool and a showcase of Rails 8's capabilities, including Solid Queue, Zeitwerk autoloading, and modern authentication patterns. Whether you're a developer exploring Rails or a user seeking a robust list management solution, Listopia offers a blend of innovation and utility.

Join us in building the future of collaborative task management!