PlaceCal has the following data structures:
Partners: individual organisations, campaigns, groups, institutions, venues, etc. The coordinator (ideally a paid role) initially can write up descriptions of each group from public information sources, and then send the group a login to edit it. Partners can either be at an address (community centres, theatres, places of worship etc), have a service area (support lines, outreach services), or both.
Calendars: individual event sources such as iCal feeds, APIs, etc. A calendar comes with a set of rules for how to import events. Are they all at the same location? Should each address be looked up and matched to a venue PlaceCal already knows about? Are they online? Calendars can have events for multiple partners, one partner can have multiple calendars, etc.
Neighbourhoods: UK political wards, districts, regions, counties etc (”communities of place”). This is the primary way people understand where things are and where they live (not “1.2km”, for example). It’s also how institutions run services on the ground so it matches up to existing political boundaries. PlaceCal sorts everything into neighbourhoods and allows listings based on various scales.
Events: single event listings — just a note you can’t directly make these in PlaceCal! Events get assigned to a partner and sorted by neighbourhood using one of a number of heuristics.
Tags: interest or feature-based tagging. Unlike other sites we maintain control over who can apply certain tags to partners. For example, only GI can tag things as “The Trans Dimenson”. However “free wifi” etc we trust people to list themselves.
Users: people who log in and add data. We work on a whitelist-only system: you need an invite from a local coordinator to add information. This is to keep the Nazis out. Less dramatically, it’s to make sure that the info is made based on a real life trust network and not any old reply guy. User permissions can be root (global), or based on neighbourhoods, partners, or tags (the details of this are fiddly). Note that most users don’t ever really have to log in, they just need to update their calendar.
Articles: news articles. These can be posted by users about partners, tags, or neighbourhoods. These are currently done inside PlaceCal but we want to expand so people can post by email, RSS, WhatsApp, etc.
Sites: individual frontends like hulme.placecal.org, trans-dimension.placecal.org. These are configured to show partners within a certain neighbourhood and (optionally) with certain tags. They have their own colour scheme, logo, cover photo, etc, and are personalisable by the groups.
TODO: incorporate anything below that’s missing from the above (old version below, new version above)
Database structures
===================
This page covers the high level relationships as described by the database schema. These schema were mainly derived from following the core actions in the PlaceCal application and discerning how the data is gathered before being sent to the user.
Sites
~~~~~
Sites represent the entry point for users to see what is going on in their local area. It is derived from the url domain so `hulme.placecal.org` has the site of `hulme`.
.. figure:: /assets/developers/db-sites.png
:alt: Image of Site relationship
Sites have a primary neighbourhood indicated by a field on one of the SiteNeighbourhood records. I don't think there is any logic stopping more than one site_neighbourhood from being flagged at a time.
Neighbourhoods are recursively self-referential: this is how areas can contain areas like regions having many post-codes.
The hierarchy of the unit field in the Neighbourhood model is: country->region->county->district->ward.
Users
~~~~~
Users come in two varieties: `root` and `citizen` where root is an application wide administrator of PlaceCal itself and citizen users exist to administer a given partner or site.
.. figure:: /assets/developers/db-users.png
:alt: User data structures
Not sure if Tags is used? (See Tags section below)
Events
~~~~~~
Events are the core resource that has the most utility for the end-users: people who are looking for things to do near them.
.. figure:: /assets/developers/db-events-overview.png
:alt: Event data Diagram
via path
--------
Events as described by the `/events` action.
.. figure:: /assets/developers/db-event-via-site.png
:alt: Event via Site
This is one of the primary paths that events are returned to the user. It is tied to Site, which in turn is derived from the domain (see above).
Partners
~~~~~~~~
Partners are the entities that actually host the event. So a coding challenge (the event) will be hosted on a college campus (the partner).
.. figure:: /assets/developers/db-partner.png
:alt: Partner relationship structure
(More description of partner)
via path
--------
End users can also access Partners via the action `/partners`. Has the same pattern as Event above.
.. figure:: /assets/developers/db-partner-via-site.png
:alt: Partner via Site
Calendars
~~~~~~~~~
Calendars are created by Partner admins to import events in bulk from an online calendar service.
.. figure:: /assets/developers/db-calendar.png
:alt: Calendar data structures
Collections
~~~~~~~~~~~
(TBD)
Tags
~~~~
*(currently non-functional)*
Tags allow Site admins (coordinators) to associate a Partner with a set of properties.