calendar/README.md

# Modern CalDAV Web Client

>[!WARNING]
>This project was entirely vibe coded. It's my first attempt vibe coding anything, but I just sat down one day and realized this was something I've wanted to build for many years, but would just take way too long. With AI, I've been able to lay out the majority  of the app in one long weekend. So proceed at your own risk, but I actually think the app is pretty solid.

A full-stack calendar application built with Rust, featuring a modern web interface for CalDAV calendar management.

## Motivation

While there are many excellent self-hosted CalDAV server implementations (Nextcloud, Radicale, Baikal, etc.), the web client ecosystem remains limited. Existing solutions like [AgenDAV](https://github.com/agendav/agendav) often suffer from outdated interfaces, bugs, and poor user experience. This project aims to provide a modern, fast, and reliable web interface for CalDAV servers.

## Features

### Calendar Management
- **Interactive Calendar Views**: Month and week views with intuitive navigation
- **Event Creation & Editing**: Comprehensive event forms with all standard iCalendar properties
- **Drag & Drop**: Move events between dates and times with automatic timezone conversion
- **CalDAV Integration**: Full bidirectional sync with any RFC-compliant CalDAV server

### Recurring Events
- **RFC 5545 Compliance**: Complete RRULE support with proper parsing and generation
- **Flexible Patterns**: Daily, weekly, monthly, and yearly recurrence with custom intervals
- **Advanced Options**: BYDAY rules, COUNT limits, UNTIL dates, and exception handling
- **Series Management**: Edit entire series or "this and future" events with proper UNTIL handling

### Modern Web Experience
- **Fast & Responsive**: Rust WebAssembly frontend for native-like performance  
- **Clean Interface**: Modern, intuitive design built with web standards
- **Real-time Updates**: Seamless synchronization with CalDAV servers
- **Timezone Aware**: Proper local time display with UTC storage

### User Experience
- **Persistent Preferences**: Settings sync across devices and sessions
- **Remember Me**: Optional server/username remembering for convenience
- **Session Management**: Secure session tokens with automatic expiry
- **Cross-Device Sync**: User preferences stored in database, not just browser

## Architecture

### Frontend (Yew WebAssembly)
- **Framework**: Yew for component-based UI development
- **Performance**: Rust WebAssembly for near-native browser performance
- **Models**: RFC 5545-compliant VEvent structures throughout
- **Services**: HTTP client for backend API communication
- **Views**: Responsive month/week calendar views with drag-and-drop

### Backend (Axum)  
- **Framework**: Axum async web framework with CORS support
- **Authentication**: SQLite-backed session management with JWT tokens
- **Database**: SQLite for user preferences and session storage
- **CalDAV Client**: Full CalDAV protocol implementation for server sync
- **API Design**: RESTful endpoints following calendar operation patterns
- **Data Flow**: Proxy between frontend and CalDAV servers with proper authentication

### Key Technical Features
- **RFC 5545 Compliance**: Complete iCalendar standard implementation
- **RRULE Processing**: Advanced recurrence rule parsing and generation
- **Timezone Handling**: Local time in UI, UTC for storage and CalDAV sync
- **Event Series**: Proper handling of recurring event modifications and exceptions
- **Build System**: Trunk for frontend bundling, Cargo workspaces for organization

## Getting Started

### Docker Deployment (Recommended)

The easiest way to run the calendar is using Docker Compose:

1. **Clone the repository**:
   ```bash
   git clone <repository-url>
   cd calendar
   ```

2. **Start the application**:
   ```bash
   docker compose up
   ```

3. **Access the application** at `http://localhost`

The Docker setup includes:
- **Automatic database migrations** on startup
- **Persistent data storage** in `./data/db/` volume
- **Frontend served via Caddy** on port 80
- **Backend API** accessible on port 3000

### Development Setup

#### Prerequisites
- Rust (latest stable version)
- Trunk (`cargo install trunk`)

#### Local Development

1. **Start the backend server** (serves API at http://localhost:3000):
   ```bash
   cargo run --manifest-path=backend/Cargo.toml
   ```

2. **Start the frontend development server** (serves at http://localhost:8080):
   ```bash
   trunk serve
   ```

3. **Access the application** at `http://localhost:8080`

#### Database Setup

For local development, run the database migrations:
```bash
# Install sqlx-cli if not already installed
cargo install sqlx-cli --features sqlite

# Run migrations
sqlx migrate run --database-url "sqlite:calendar.db" --source backend/migrations
```

### Building for Production

```bash
trunk build --release
```

### Development Commands

- `cargo check` - Check frontend compilation
- `cargo check --manifest-path=backend/Cargo.toml` - Check backend compilation  
- `trunk serve` - Start frontend development server with hot reload

## Project Structure

```
calendar/
├── frontend/                    # Yew WebAssembly frontend
│   ├── src/
│   │   ├── app.rs              # Main app component with routing
│   │   ├── components/         # UI components
│   │   │   ├── calendar.rs     # Main calendar container
│   │   │   ├── month_view.rs   # Month calendar view
│   │   │   ├── week_view.rs    # Week calendar view  
│   │   │   ├── create_event_modal.rs # Event creation form
│   │   │   └── ...
│   │   ├── models/
│   │   │   └── ical.rs         # RFC 5545 VEvent structures
│   │   └── services/
│   │       └── calendar_service.rs # HTTP client & RRULE logic
│   ├── index.html              # HTML template
│   └── Trunk.toml              # Frontend build config
├── backend/                     # Axum REST API server
│   └── src/
│       ├── main.rs             # Server entry point
│       ├── handlers/           # API endpoint handlers
│       │   ├── events.rs       # Event CRUD operations
│       │   └── series.rs       # Recurring event operations  
│       ├── auth.rs             # JWT authentication
│       └── calendar.rs         # CalDAV client implementation
└── CLAUDE.md                   # Development instructions
```

## CalDAV Compatibility

This client is designed to work with any RFC-compliant CalDAV server:

- **Baikal** - ✅ Fully tested with complete event and recurrence support
- **Nextcloud** - 🚧 Planned compatibility with calendar app
- **Radicale** - 🚧 Planned lightweight CalDAV server support  
- **Apple Calendar Server** - 🚧 Planned standards-compliant operation
- **Google Calendar** - 🚧 Planned CalDAV API compatibility

*Note: While the client follows RFC standards and should work with any compliant CalDAV server, we have currently only tested extensively with Baikal. Testing with other servers is planned.*