michel 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3377d5257bd7ad52f252b0c27cd463b93ef3c5f2df0c886b3da63d247849c72
-  data.tar.gz: 45b6662ff6f2bb740db51b2ae964f9b67b6b1b3b46ecb6da73b202cbd8b0f7f1
+  metadata.gz: 729ce5f1ae788f0942ab2e59cd5dc6f1187e881259677a7c7894b32495cf477d
+  data.tar.gz: 7f5daf203587424d2817f51e591f2d1f9a94131f33ffe7e6eecb0fcb73a9cfda
 SHA512:
-  metadata.gz: 55245d9919ed8f65329383cec02dae191c70948e43d11c06628969afbb2b2fcf6775f3309048cdff57547e920cfb7107f311b54436e91b66baaeaef811d381ba
-  data.tar.gz: 95bd0b7e09a5c664ff8ca269f2c1f2d1a99e7f8147c837776b0b7f4b20f8f56ee52f1913321f59ea8cb0e774729a5e75d0fc7324ef4d6b775b0ad3f0c9747f3b
+  metadata.gz: 9e13696e4430a7c9dbd5720486999770d3396f93e06d2873c22a1bfa032de8862fcd63b3357830a5385963bd0e9f6f278145f7125efb91057080ca0680cb6765
+  data.tar.gz: 99fc0c5607d940b4569539b6583402211b202bb616d8d29e89bb1b0881b2553f76ff9737d1a625c1ce6e1a6490198f57fc6f4f9d365171ec082f872dca71cc0c

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.1 - 2026-02-02
+
+Documentation Updates
+
 ## 0.1.0 - 2026-01-28
 
 Initial release

data/README.md

@@ -1,13 +1,79 @@
 # Michel
 
-Find available time slots quickly with a materialized view.
+A generator for creating a materialized-view-backed model for querying available time slots. Inspired by and tailored for health care applications that need self-scheduling capability for users. Named for the worst scheduling assistant on tv, [Michel Gerard of Gilmore Girls.](https://gilmoregirls.fandom.com/wiki/Michel_Gerard)
+
+
+## The problem
+When scheduling things like doctor's appointments, hair cuts, or conference room bookings, answering "Is Dr. Doolittle available at this time?" is fairly straightforward. You can query whether there are existing appointments overlapping the time you're looking at, which is fairly quick to do with a well-indexed database.
+
+Answering the same question for multiple doctors, stylists, or conference rooms - "Who is available at this time" - is slightly more complex, but still manageable with standard database query methods.
+
+When building an app that allows self-scheduling, the question you really want to ask it "what resources are available at what times during this time period?"  This is a more complicated query. Finding available time slots using Ruby is painfully slow. Postgres has some powerful capabilities that can help us, though.
+
+## The solution
+
+Michel helps create a materialized database view for answering this question, using the power of [Scenic](https://github.com/scenic-views/scenic) and [Postgres](https://www.postgresql.org/). Postgres has powerful tools for querying time ranges and finding overlaps.  You tell Michel the class name of your resource (doctor, stylist, conference room, etc), the class name of your booking (appointment, reservation, etc) and the class name of your availability model and Michel creates a materialized view-backed model called `AvailableTimeSlot`.
+
+These available time slots have start times every 15 minutes for 30 minute durations during times the resource is not already booked. The view currently calculates time slots for the next six months. In the future, this range will be configurable.
+
+For example, a doctor who works 9am-12pm Eastern on Mondays would have the following available 30-minute time slots for the first full week of 2026:
+
+* Monday, Jan 5, 2026, 9:00am EST
+* Monday, Jan 5, 2026, 9:15am EST
+* Monday, Jan 5, 2026, 9:30am EST
+* Monday, Jan 5, 2026, 9:45am EST
+* Monday, Jan 5, 2026, 10:00am EST
+* Monday, Jan 5, 2026, 10:15am EST
+* Monday, Jan 5, 2026, 10:30am EST
+* Monday, Jan 5, 2026, 10:45am EST
+* Monday, Jan 5, 2026, 11:00am EST
+* Monday, Jan 5, 2026, 11:15am EST
+* Monday, Jan 5, 2026, 11:30am EST
+
+If they then scheduled a 30-minute appointment on Jan 5, 2026 starting at 9:45, the refreshed availability would be:
+* Monday, Jan 5, 2026, 9:00am EST
+* Monday, Jan 5, 2026, 9:15am EST
+* Monday, Jan 5, 2026, 10:15am EST
+* Monday, Jan 5, 2026, 10:30am EST
+* Monday, Jan 5, 2026, 10:45am EST
+* Monday, Jan 5, 2026, 11:00am EST
+* Monday, Jan 5, 2026, 11:15am EST
+* Monday, Jan 5, 2026, 11:30am EST
+
+An appointment that ends at 10:15 and an appointment that begins at 10:15 are considered to be consecutive, not overlapping.
+
+More details on what an availability record looks like are in the Configure section.
+
+## Limitations
+
+The materialized view is stored in the database and it is not a trivial size. Michel favors increasing database storage over database or application processing. If limiting database size is a higher priority than finding available time slots quickly, this is not the right tool for you. In our experience, it's cheaper and easier to scale up a database than to lose users waiting for time slots to load.
+
+Currently, only the class names and the attributes stored on availabilities are customizable.  Start times are every 15 minutes and the total range of time slots is 6 months from the current date. More configuration options will be available in the future.
+
+The materialized view must be refreshed every time a booking or availability is created, modified, or deleted. For most applications that involve self-scheduling, a user queries the availability much more often than a booking is created or a schedule is changed, so it is much more efficient to materialize the view and refresh it regularly than to have a non-materialized view that is queried on every search.
+
+All bookings are considered to be blocking. In order to make a time slot available, the booking must be destroyed. In the future, we intend to add a way to configure status values that are non-blocking for things like cancelled appointments where you'd like to keep the record but want the resource to be available.
+
+Available time slots each have a 30-minute duration. This will be configurable in the future. Bookings can be any duration.
+
+Availabilities are for only one resource type right now. A doctor who works at two different clinics, for example, will not have a way to distinguish between availabilities at different clinics. In the future, we will add support for a second resource type, so a query for available time slots can be scoped to a second resource, like a clinic location. The current view allows for this scoping only by joining to the availability table and scoping that to the second resource, which is less efficient.
+
+## Integration with an EHR
+
+Michel was inspired while working on a health care app that integrated with an existing EHR. The EHR was able to provide appointment times and provider schedules, but not available time slots. Michel's materialized view helped us calculate those and ensure that providers weren't double-booked via both our application and staff booking directly in the EHR. In order to make sure the two systems stay in sync, it is necessary to:
+
+* Update the application database with booking creations/changes/deletions from the EHR as they are made. Many EHRs use webhooks for this sort of synchronization.
+* Update the EHR with booking creations/changes/deletions from the application as they are made. This is usually accomplished with an api endpoint provided by the EHR.
+* Update the application database with availability creations/changes/deletions from the EHR as they are made. This is usually also a webhook.
+* Refresh the materialized view when any of the above updates are made.
+* Treat the EHR as the source of truth for both bookings and availabilities. Be careful about allowing modifications of resource availability from both the EHR and the application, as this can be tricky to keep in sync.
 
 ## Usage
 
 ### Install Michel
   In order to run the migrations, you must also install Scenic. Add to your gemfile:
 
-  ```
+  ``` ruby
   gem "michel"
   gem "scenic"
   ```
@@ -15,7 +81,28 @@ Find available time slots quickly with a materialized view.
   Run `bundle install`, then  `rails generate michel:install`
 
 ### Configure
-  Configure the class names in `config/initializers/michel.rb`
+  Configure the class names in `config/initializers/michel.rb`. The default initializer is copied to your app when you run `rake michel:install` and looks like this:
+
+  ``` ruby
+  # config/initializers/michel.rb
+
+  Michel.setup do |config|
+    config.resource_class_name = "Resource"
+    config.booking_class_name = "Booking"
+    config.availability_class_name = "Availability"
+  end
+```
+Replace the default class names with the class names from your app, if they differ, for example:
+
+  ``` ruby
+  # config/initializers/michel.rb
+
+  Michel.setup do |config|
+    config.resource_class_name = "ConferenceRoom"
+    config.booking_class_name = "Reservation"
+    config.availability_class_name = "RoomSchedule"
+  end
+```
 
   Michel expects three classes to exist in the application:
   * Resource Class
@@ -51,7 +138,8 @@ Find available time slots quickly with a materialized view.
 
   Once the generator is finished, run `rails db:migrate` to run the generated migrations.
 
-### Start Scheduling.
+### Start querying for Available Time Slots
+  The `AvailableTimeSlot` class stores the generated time slots that don't overlap with existing bookings.
   To find available time slots, search for matching `AvailableTimeSlots`. Each slot has a `start_time` and an `end_time` and belongs to an `availability` and a `resource`.
 
   To refresh the materialized view, run `AvailableTimeSlot.refresh`. The view should be refreshed when a booking is created, updated, or deleted, or when availability changes.

data/SECURITY.md

@@ -1,2 +1,20 @@
 <!-- START /templates/security.md -->
+# Security Policy
+
+## Supported Versions
+
+Only the the latest version of this project is supported at a given time. If
+you find a security issue with an older version, please try updating to the
+latest version first.
+
+If for some reason you can't update to the latest version, please let us know
+your reasons so that we can have a better understanding of your situation.
+
+## Reporting a Vulnerability
+
+For security inquiries or vulnerability reports, visit
+<https://thoughtbot.com/security>.
+
+If you have any suggestions to improve this policy, visit <https://thoughtbot.com/security>.
+
 <!-- END /templates/security.md -->

data/lib/michel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Michel
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: michel
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Sally Hall
 - Aji Slater
 bindir: exe
 cert_chain: []
-date: 2026-01-28 00:00:00.000000000 Z
+date: 2026-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord