Darwined Core Schedules

Build Status Dependency Status

Description

This is a web service for generating schedules. It exposes a REST interface (with all the CRUD actions) using JSON as its message format.

It's built using Sinatra and ActiveRecord and uses RSpec for its tests.

Schedule Definition

Let's define what a schedule is and how we try to model it in a easy way. First's, suppose a certain university (or any other institution) has the next schedule for theis classes

# Monday Tuesday Wednesday Thursday Friday Saturday Sunday
08:30 AB
09:15 AB
10:00
10:15
11:00 C
11:45
12:00
13:00
13:45
14:30
14:45
15:30
16:15
16:30
17:15
18:00

So, we have classes A, B and C. Class A spans from 8:30 to 10:00 in the morning. So does B, and class C spans from 11:00 to 11:45.

Block Definition

A block is a unit of time between two hours. In our example, C spans a single block, while A spans two.

Block Notation

We could go by referencing a block by its start time and its end time, but that could be very verbose, time consuming and error-prone. So, we define a simple notation for them:

1.1 represents the first block of monday
1.2 represents the second block of monday
7.3 represents the third block of sunday
*.1 represents the first blocks of each day
1.* represents all the blocks of monday

So, class C occurs in 1.5, while A does in 1.1 and 1.2.

Then, how could we define a schedule and its blocks easily without having to define each block for each day? Enter separators.

Separator Definition

A separator is an horizontal division through a schedule, from day A to day B, at a given time.

Two separators are needed to define a block.

For example

  1. Separator A from monday to sunday at 10:00
  2. Separator B from monday to sunday at 11:00

This way, the schedule automatically generates *.1 blocks, i.e, each day now has a block (named 1.1 for monday), that spans from 10:00 to 11:00.

So, for the previous schedule, we would need 17 separators to define all the blocks.

Moreover, if we were to have some weird schedule, where each day is differente from each other, we could have separators that range from day X to day X.

Grid Definition

The resulting schedule is stored in a grid. Each time we add or remove a separator, the schedule recalculates the blocks defined and generates a grid that has all the blocks and the times they span over. In our previous example, the grid would look like this:

{ "grid": [
    [ { "code": "1.1", "start": "10:00", "end", "11:00" } ], // Blocks for monday
    [ { "code": "2.1", "start": "10:00", "end", "11:00" } ], // Blocks for tuesday
    [ { "code": "3.1", "start": "10:00", "end", "11:00" } ],
    [ { "code": "4.1", "start": "10:00", "end", "11:00" } ],
    [ { "code": "5.1", "start": "10:00", "end", "11:00" } ],
    [ { "code": "6.1", "start": "10:00", "end", "11:00" } ],
    [ { "code": "7.1", "start": "10:00", "end", "11:00" } ] 
  ]
}

Thus, let's dive into the web service attributes.

A schedule has a name, many separators, and a calculater, read-only, grid with all its blocks.

  • name of the schedule, like "Master Schedule".
  • separators, an array of separators, each separator has the following attributes:
    • time a Time object.
    • start the start day of the separator.
    • end the end day of the separator.
  • grid an array of blocks, based on the separators defined.

A JSON representation of a schedule should be:

{
  "schedule": {
    "id": 1,
    "name": "Master Schedule",
    "grid": [
        [
          {
            "start": "10:00:00",
            "end": "11:00:00",
            "code": "1.1"
          }
        ],
        [
          {
            "start": "10:00:00",
            "end": "11:00:00",
            "code": "2.1"
          }
        ],
        [
          {
            "start": "10:00:00",
            "end": "11:00:00",
            "code": "3.1"
          }
        ],
        [
          {
            "start": "10:00:00",
            "end": "11:00:00",
            "code": "4.1"
          }
        ],
        [
          {
            "start": "10:00:00",
            "end": "11:00:00",
            "code": "5.1"
          }
        ],
        [
          {
            "start": "10:00:00",
            "end": "11:00:00",
            "code": "6.1"
          }
        ],
        [
          {
            "start": "10:00:00",
            "end": "11:00:00",
            "code": "7.1"
          }
        ]
    ],
    "separators": [
        {
          "separator": {
            "id": 1,
            "initial_day": 1,
            "final_day": 7,
            "time": "10:00:00"
          }
        },
        {
          "separator": {
            "id": 2,
            "initial_day": 1,
            "final_day": 7,
            "time": "11:00:00"
          }
        }
    ]
  }
}

As said, grid is a read-only property, so, to modify it, we need to edit the separators.

This way, we don't need to store a block entity, but rather refer it by a notation that is understood by all.

About