Complex Pico Structures: Guard Tours


We've recently been working on a large project that we architected using picos, CloudOS, and the Personal Cloud Application Architecture. I'm pleased with how this turned out and the lessons that we learned.

Mall Security

We have recently been working on a project for a client that implements a guard tour patrol system. From Wikipedia:

A guard tour patrol system is a system for logging the rounds of employees in a variety of situations such as security guards patrolling property, technicians monitoring climate-controlled environments, and correctional officers checking prisoner living areas. It helps ensure that the employee makes his or her appointed rounds at the correct intervals and can offer a record for legal or insurance reasons.
From Guard tour patrol system - Wikipedia, the free encyclopedia
Referenced Fri Jan 17 2014 15:46:17 GMT-0700 (MST)

You could imagine implementing such a system in a variety of ways, but I saw it as an opportunity to experiment with picos, CloudOS, and the Personal Cloud Application Architectures, extending our techniques and learning important lessons. If you squint a little, you can see that this system and SquareTag are quite similar. In fact, the personal cloud and pico infrastructure are identical.


The fundamental use case of a guard tour system is a guard going from place to place, checking-in at each location to record the state of each location and reporting any anomalies. At its simplest, a tour is an ordered list of locations. The system also has to know about guards, managers, and reports.

We modeled these by creating a prototype pico for each of these objects. At present, KRL has no facility for formally managing prototypes, so we simply write initialization functions that we run in a pico after it's created depending on which type of pico we want to create. There is an Institution pico that is the "root" object of an entire guard tour. Creating prototypes allows us to easily create a new guard tour system using an initialization ruleset.

The other type of pico that might not be apparently obvious is an index pico for tours, locations, and reports. The index pico is necessary to map identifiers for each picos to an event channel identifier (ECI) as well as providing various query capabilities. The tour, location, and report identifiers are URLs and are, consequently, globally unique. Institution picos and the various index picos are all singletons, meaning that in any given Guard Tour set up, there is only one of each.

When a guard tour has been initialized, locations have been entered, and tours created, it might look like this:

guard tour pico relationships

Guards and managers have a "Guard Tour ruleset" installed in their personal cloud. In every other respect, these are just ordinary personal clouds like the ones we create for SquareTag. This is a critical idea: guards and managers don't get an account in the guard tour system. In fact the Guard Tour system has no notion of accounts. Instead, guards and managers have their own personal cloud that they might be using for other things—like running Fuse. This might be a personal cloud they use exclusively for work or they might mingle other components of their life in it—just like people do with laptops and other personal computing devices.

Each guard or manager has a subscription to the Institution pico representing the guard tour. The Guard Tour ruleset manages this subscription and knows what to do with it. The Guard Tour app provides an event-query API for use by the unhosted Guard Tour Web application that provides guards and managers with a user interface for interacting with tours.

The following diagram, from my blog post on the event-query API, shows the overall structure of the application except that a guard tour isn't a single pico, like the one shown here, but rather a constellation of picos like the one shown above. Conceptually, however, it looks just like this since the API provided by the ruleset installed in the guard or manager's personal cloud provides a proxy for the rest of the system. The Web application doesn't know that the other picos exist.

event-query model

The Web application is a pretty straightforward jQuery Mobile application. We built a JavaScript library on top of the CloudOS.js library that provides a Guard Tour-specific interface for the Web application to interface with the event-auery API presented by the Guard Tour ruleset. As for the code, the KRL that runs in the various picos represents about 25% of the overall code base. There's more than twice as much JavaScript (55%) as KRL.

Walking a Tour

When a guard, call him "Frank," starts a tour, he goes to the Web application and authorizes it to access his personal cloud (shown in purple in the first diagram). As stated, the Guard Tour ruleset provides the event-query API that the Web application needs to function. The Guard Tour API presented by the guard's personal cloud acts as an interface for the API presented by the Institution pico. Of course, the Guard Tour API need not be identical to that provided by the Institution pico. The ruleset for a guard, for example, only exposes the funciontality a guard needs; whereas the ruleset for a manager includes facilities for creating new locations and tours, updating them, and so on.

The Institution pico has subscriptions to the tour, location, and report index picos. When Frank does a search for tours that he's been assigned, the Web app asks the API presented by his personal cloud to find locations using specific criteria, which in turn asks the institution for those tours, which further pushes the request to the Tour Index pico. That pico handles the query and returns the list of appropriate tours to show Frank.

When Frank clicks on a tour to start walking it, the process is repeated, only this time, the Tour index pico is used to decode the tour identifier to the ECI for the selected Tour pico (LUFX in the diagram). Queries to that pico return the list of locations, which include ECIs to specific Location picos. As Frank manipulates the user interface, his personal cloud uses temporary channels (shown in green in the diagram) to the tour he's walking, various location picos, and a report pico created just for this interaction. When Frank's done, the report pico is completed and his personal cloud forgets all the temporary channels.

Lessons Learned

That may sound complicated, but it's surprisingly quick and effective. We could have just stored a tour's locations as data inside the tour pico. For that matter, we could store tours as data inside the Institution pico. By representing each as a separate pico, we maximize our flexibility and allow for reuse. For example, a location can be in more than one tour. More importantly, I imagine the day when each room in a building might be represented by an online avatar. One function of that room avatar would be to provide data for a guard tour. But it might also know about the room's structure, features, emergency access capabilities, maintenance, and so on.

Similarly, we could of just created accounts in the Institution pico and had it offer a OAuth-protected API directory, but I believe strongly in the idea of personal clouds and saw this as a way to experiment with how they can be used in conjunction with unhosted Web applications and a complex pico constellation to provide specific functionality. For example, Frank the guard might want his personal cloud to record the fact that he walked particular tours on particular days.

Overall, we've learned a lot from this project and I'm grateful we got the chance to do it. Here are a few of the things we've learned:

  • Building complex pico structures with many members that are also fast and responsive
  • Using personal clouds as the basis for interacting with complicated, pico-based applications
  • Techniques for testing
  • Using index picos and temporary channels

Many of these techniques will be useful to us as build the Fuse API and application. That's next on our plate. Eventually I hope to redo SquareTag in this style, making it an application that could be used by people with personal clouds that are hosted on other systems so long as they were based on CloudOS. There is much to recommend picos, event-query APIs, personal clouds, and unhosted Web apps as a programming style: it's readily distributable and protects personal data. I'm excited by the progress we've made.

Please leave comments using the sidebar.

Last modified: Wed Jan 27 18:30:41 2021.