Real-Time Todo App with Stario

A feature-rich todo application built with Stario, Datastar, and SQLite, featuring real-time collaboration, presence tracking, and JWT authentication.

Features

• Multiple Todo Apps: Create and manage multiple todo lists
• Real-Time Collaboration: See changes instantly with SSE streaming
• Presence Tracking: See who's viewing each todo app
• JWT Authentication: Simple token-based auth (user-managed tokens)
• Visibility Settings:
  • 🔒 Private - Only you can see and edit
  • 🌍 Public - Anyone can view
  • 👥 Shared - Anyone can view (read-only)
• CQRS Architecture: Clean separation of commands and queries
• Turso SQLite: Fast, embedded database with SQLAlchemy

Tech Stack

• Stario: Python async web framework for real-time hypermedia
• Datastar: Reactive UI with SSE streaming and signals
• SQLAlchemy: Database ORM
• JWT: Token-based authentication
• Relay: In-memory pub/sub for real-time updates

Getting Started

Installation

# Install dependencies
uv sync

# The database will be created automatically on first run

Configuration

Edit .env to configure:

TURSO_DATABASE_URL=file:local.db
JWT_SECRET=your-secret-key-here

Running

# Start the development server
uv run stario watch main:bootstrap

# Or run once
uv run stario serve main:bootstrap

Visit http://localhost:8000

Usage

Creating an Account

1. Click "Create Account"
2. Enter a username
3. Important: Save your JWT token securely! You'll need it to log in.

Logging In

1. Paste your JWT token
2. Click "Login"

Creating Todo Apps

1. Click "+ Create New Todo App"
2. Enter name and description
3. Choose visibility (private/public/shared)

Managing Todos

• Add items with the input field
• Click checkboxes to complete/uncomplete
• Click 🗑️ to delete items
• Use Settings to edit app details or visibility

Real-Time Features

• Open the same todo app in multiple browser windows
• See presence indicators showing who's viewing
• Changes appear instantly for all viewers

Project Structure

├── domain/              # Entities and business logic
│   ├── entities.py      # User, TodoApp, TodoItem
│   └── presence.py      # Presence tracking
├── infrastructure/      # External concerns
│   ├── database.py      # SQLAlchemy setup
│   ├── jwt.py           # JWT utilities
│   ├── presence.py      # Presence tracker
│   └── repositories.py  # Data access layer
├── commands/            # CQRS: Write operations
│   ├── schema.py        # Command DTOs
│   ├── create_user.py
│   ├── todo_app_handlers.py
│   └── todo_item_handlers.py
├── queries/             # CQRS: Read operations
│   ├── schema.py        # Query DTOs
│   └── handlers.py      # Query handlers
├── presentation/        # Views and HTTP handlers
│   ├── views.py         # HTML components
│   ├── handlers.py      # HTTP handlers
│   └── signals.py       # Signal schemas
├── static/              # Static assets
│   ├── css/style.css
│   └── js/datastar.js
├── config.py            # Configuration
└── main.py              # Bootstrap

API Endpoints

Authentication

• POST /api/register - Create account and get JWT
• POST /api/login - Login with JWT

Todo Apps

• GET / - List my todo apps
• GET /public - Browse public apps
• GET /apps/:id - View todo app
• POST /api/apps - Create new app
• POST /api/apps/:id/update - Update app
• POST /api/apps/:id/delete - Delete app
• GET /api/apps/:id/subscribe - SSE for real-time updates

Todo Items

• POST /api/apps/:id/items - Add item
• POST /api/todos/:id/toggle - Toggle completion
• POST /api/todos/:id/delete - Delete item

Architecture

CQRS Pattern

Separates read and write operations:

• Commands: Create, update, delete (write to DB)
• Queries: Read-optimized, return DTOs

Real-Time Updates

1. Client connects via SSE to /api/apps/:id/subscribe
2. Server sends initial state as HTML patch
3. On any change, command publishes to Relay
4. All subscribers receive updated state

Presence Tracking

1. On SSE connect, user joins presence tracker
2. Tracker shows who's viewing each app
3. Auto-removes stale connections after 30s

Development

Adding New Features

1. Domain: Add entities to domain/
2. Commands: Create command in commands/, add handler
3. Queries: Create query in queries/, add handler
4. Views: Add UI in presentation/views.py
5. Routes: Wire up in main.py

Database Migrations

Currently using auto-migration. For production, use Alembic.

License

MIT

Notes

• JWT tokens are self-managed by users (like API keys)
• Uses SQLite by default, configurable for Turso
• All data persists in local.db
• Real-time via SSE (no WebSockets needed)
• No frontend framework - pure HTML/Datastar