# Planner — RRULE Recurrence Engine

Started as a course project for Antakya Private University's Advanced Web Programming
module. It kept going after the grade, because I wanted to use it.

The version that got submitted is preserved at the `submission-v1` tag. Everything since
is what happens when a coursework app has to survive contact with daily use.

## Recurrence, done properly

Most task apps grow a `repeats` column with an enum: daily, weekly, monthly. Then someone
wants "the last weekday of every month," or "every other Tuesday," and the enum grows a
sibling column, and then a third, and the query that finds today's tasks becomes
unreadable.

Planner uses **RRULE** — the recurrence grammar from RFC 5545, the same one iCal and every
calendar client already speak — via `simshaun/recurr`. A repeating task stores a rule
string, and the rule expands into real occurrences.

Two consequences worth having. A completed instance generates the next one on completion,
and the scheduler pre-materializes seven days ahead so the upcoming views have something
to show without expanding rules at request time. And because the format is standard, an
export to a real calendar is a formatting problem rather than a translation problem.

## Views are queries, not lists

Today, Inbox and Upcoming are **derived**. There is no `today` table and nothing writes a
task into a view; they're queries over due date and completion state, with live count
badges in the sidebar.

The alternative — materialising a "Today" list — means every write has to remember to
update it, and the day a write forgets, the list is wrong in a way the user notices before
you do. Derived views can be slow, but they cannot be inconsistent.

Every query is policy-scoped per user through Laravel's authorization policies, so
per-user isolation is enforced at the model layer rather than remembered at each call
site.

## Quick-add

Press `c` anywhere, type one line, get a structured record:

```
!high #work finish the ETL writeup tomorrow 5pm
```

The parser pulls out priority (`!high` / `!med` / `!low`), `#category` tags, and date
phrases — `tomorrow`, `next mon`, `5pm`, `jul 4`, `in 3 days` — and shows a live preview
of what it understood before you commit. The preview matters more than the parsing. A
natural-language field that silently guesses wrong is worse than a form.

## What's shipped

Auth via Breeze, full task CRUD, inline complete toggle, bulk actions, snooze, pagination,
search, filters and sort. Per-user categories with colour chips, priorities, subtasks with
drag-to-reorder and a `3/5` progress badge, markdown notes via `league/commonmark`,
drag-to-reorder within a view with SortableJS, and a FullCalendar view where clicking a day
quick-adds and clicking a task edits.

The UI has a collapsible sidebar with state in `localStorage`, dark mode through Bootstrap
5.3's `data-bs-theme` defaulting to system preference, toasts, empty states with a call to
action, and button loading spinners.

## Deployment, and its current state

It used to auto-deploy on every push to `main` — GitHub Actions built an image, pushed it
to GHCR, and Watchtower rolled the container on my home server.

That server was decommissioned in August 2026, so the public instance is gone with it. The
multi-stage Dockerfile still builds a single image with nginx, php-fpm and supervisord on
Alpine, and it still runs locally; there's just nothing hosting it right now.

## Stack

Laravel on PHP 8.3 with SQLite, Blade and Bootstrap 5.3 with vanilla JS, Laravel Breeze for
auth, `simshaun/recurr` for recurrence, `league/commonmark` for markdown, FullCalendar and
SortableJS on the front end.
