# Kithkin

Contacts and calendars for smart people.

## Scheduled jobs

Jobs are located in `app/Jobs` and we use Laravel Horizon as an admin frontend. 

### Starting jobs

To start the jobs themselves, run `php artisan schedule:work`. This creates a running process that outputs job runs and other minimal data.

#### Production cron

On production, this should be setup via cron job like this:

```
* * * * * /usr/bin/php /path/to/artisan schedule:run >> /dev/null 2>&1
```

### Monitoring jobs

Horizon is the monitoring app and frontend. Run `php artisan horizon` to start it. This will create a running process that outputs the results of the jobs in a better format than `schedule:work`.

The `/horizon` UI is just a normal route in Kithkin; the `php artisan horizon` process is what actually runs the workers and updates Redis for the dashboard.


### Working with scheduled jobs

To see the list of scheduled jobs and their crons, run `php artisan schedule:list`.


## Application flow notes for my own sanity

### Local calendars

#### Local calendar creation

Creating a local calendar (not available in the UI yet) hits the `Calendar.php` controller. That `store()` method creates entries in the `calendars`, `calendarinstances`, and `calendar_meta` tables using model functions for each of them.

#### Local event creation

When the user creates a new event, it gets added to `calendarobjects` where the raw VEVENT data is stored. We have our own utility tables `event_meta` and `locations` for way more metadata and convenience fields so that we don't need to keep parsing the VEVENT blob.

The controller is `EventController.php` and it uses models `Event.php` (calendarobjects), `EventMeta.php` (event_meta), and Location.php (locations, not yet created).

### Remote calendars

Remote calendars are calendars that a user "subscribes" to via .ics URL. These are also called subscription calendars in the app.

#### Remote calendar creation

The user adds a new remote calendar by entering the url in calendar settings, adding a display name, and picking a color.

When a new remote calendar is added, we create a row in `calendarsubscriptions`, `calendars`, and `calendarinstances`, and a corresponding meta data row in `calendar_meta`. This is so verbose because of the way SabreDAV handles remote subscriptions.

* Normally, all Sabre does is add a row to `calendarsubscriptions`. It doesn't contemplate pulling the events down into the database locally--it assumes you're fetching the .ics file fresh and parsing out events every time the user loads the calendar.

* Since we want to be able to search everything and do more, we need to pull the events down into our database. This requires creating corresponding rows in the local calendar tables. It's a little weird Sabre-wise since we have remote calendars populating their local calendar tables, but Sabre doesn't care that these are in there and it means the user can also share them out again.

The controller is `SubscriptionController.php` and it uses the additional model `Subscription.php`.

#### Remote events

When a user creates an event in a subscription calendar, we need to send that back up to the primary server. We also create the event locally as normal.
