Core concepts
AudienceKit’s data model is small. Every object below is defined in api/app/models.
Audience
Section titled “Audience”An audience is a tenant: a community with a name and a unique subdomain (lowercase letters, digits and hyphens). Everything an app shows belongs to an audience: its locales, venues, people and events. An audience also stores a theme, which decides how its apps and admin console look (see Theme an audience).
Users join audiences through AudienceUser records.
Audience domain
Section titled “Audience domain”An audience can own one or more domains, such as hotmess.social. The API uses them to find the audience for a request: a host matches an audience when it equals one of its domains or is admin. plus one of them. That is how admin.hotmess.social serves the Hot Mess admin console. See Connect a domain.
Locale
Section titled “Locale”A locale is a city or metro area inside an audience, such as Seattle. It has a label, a name, a list of cityNames, an optional timezoneZuluDelta, and a geographic envelope that the API computes from the points of its visible venues.
A venue is a place that holds events: a bar, club or community space. It belongs to a locale and an audience, and it can have a location (a point plus Google Places data) and a legacy Facebook page. Venues have an order, can be hidden, and have a distanceTolerance used when the API decides whether a user is at the venue.
Venues maintained by the researcher worker also carry an external_key, a confidence between 0 and 1, provenance and last_verified_at.
Person
Section titled “Person”A person is a promoter, performer or organization. People belong to an audience (or are global) and link to a page that holds their name and photos. Events list the people involved.
An event happens at a venue, with a name, startAt and endAt. Events can be featured, can have ticket types, and can be RSVPed to through POST /v1/events/:id/rsvp. Most lists return only future events: those that start or end after now.
User, device and session
Section titled “User, device and session”A user signs in with Facebook from a device. Each sign-in creates a session on that device and returns a JWT for it. Users can be administrators (isAdmin), which gives them access to cross-audience administration. See Authentication.
Application
Section titled “Application”An application is an API key that belongs to one audience. Server-side apps use it to call that audience’s endpoints without a user.
Service token
Section titled “Service token”A service token is a long-lived secret for a machine, such as the researcher worker. It belongs to one audience, carries scopes, and is exchanged for short-lived JWTs. See Automate with service tokens.