The System Book · The Works

How it all works

Everything the UPAGP house does, how each part works, and why it was made that way.

FAMILIES THE BOARD The houserooms, EN and HI The dashboardthe board's room The door appone evening's link The Workerchecks, prices, sends The basethirteen tables your phone keepssettings and drafts door check-ins waitfor signal
Families walk the house; the board runs the year. One small program stands between everyone and the tables.

Two minutes for the bold lines; about fifteen with every card open.

Part 1

The whole thing at once

Think of a family home in Uttar Pradesh with its door open. Guests walk the rooms; the family keeps a register in a drawer; the elders run the household from a small room at the back. The house's pages are the rooms. The base is the register. The dashboard is the room at the back. A small program, the Worker, stands at the door: it checks who is asking, works out prices, sends the post, and makes sure nothing private leaves the drawer.

19rooms: Home and eighteen more, in five wings
13tables in the base
2languages in every room
14walks, run by hand before changes are pushed

The names we use

The house
The website: Home and eighteen rooms in five wings (plus Contact, Privacy and Photo credits), in English and in Hindi.
The aangan
Home's courtyard (the open centre of a house in Uttar Pradesh), drawn for Philadelphia's hour and season, with three doorways.
Come home
The seven short steps that introduce a family to the house, once.
Your family's page
Each family's own room, seen only after signing in.
The directory
Where families who have come home (and member families) find each other, by name, town or district.
The Web of Welcome
A drawing of every family as a point in the year it joined, with an arc from the family that brought it.
Who's coming
The names of the families with a paid booking for a gathering, on its page.
The evening remembered
A gathering's page for the morning after: who came, the photos, families' words.
The door app
A one-evening link for the volunteers at the door: the list, check-ins and walk-ins, even without signal.
The hall screen
A screen for the projector: districts lighting as families come home, a lamp for each family that arrives. Counts only.
The review layer
Notes and "in your own words" cards that appear only for the people walking the house before it opens.
The dashboard
The board's room: families, events, bookings, the door, sponsors, notes, words and email.
The Worker
The small program (a Cloudflare Worker) that answers every page and every form.
The base
The tables (in Airtable) where everything is kept.

What is public, and what is not?

Anyone can seeKept for families and the board
Every room's story, the map of Uttar Pradesh, the gatherings, prices and datesEach family's page, and the directory
The map, as counts (never a count under three); the Web of Welcome, as unnamed points and its totalsNames on the map and the Web of Welcome, for families who have come home and member families
On a gathering's page: the families coming and, afterwards, those who came, unless a family chose to be counted without its name; the album's photos; families' wordsEmail and phone, only where a family chose to show them; birth dates, never shown to anyone

Part 2

The paths

The house is easiest to understand by following people through it. Each path is what happens, step by step, from one person's side.

1What happens when a family comes home?Seven short steps, kept on the phone as they go, sent once at the end.
  1. They give a phone number or email. If the family is already known, a sign-in link goes quietly to its email, and the house says so when they send.
  2. They name everyone in the family, with birth dates (their own is needed).
  3. They tap where in Uttar Pradesh they come from; that district lights on a small map.
  4. They say when they joined, one memory of home, who brought them, and what other families may see.
  5. Everything typed is kept on the phone as they go, so a dropped signal loses nothing; it is sent when the signal returns.
  6. The Worker files the family, checks whether their email is on the association's members list, and tells the board if it might be; the board confirms the match by hand.
  7. A welcome email goes out, and the family is signed in on that phone.

Why: a family should introduce itself once, in its own words, and be known after that.

2How does a family sign in?A link by email, or a phone number and any family member's birth date. No passwords.
  1. By email: the house sends a link that works once, for thirty minutes. The link opens a page with a button, so an email scanner can't use it up.
  2. By phone: any adult's number in the family, then any family member's birth date.
  3. The answer is the same whether or not someone is on file, and repeated tries are slowed down.
  4. On a shared computer, "shared device" signs the family out when the browser closes.
3What happens when someone books a gathering?The price is worked out for each person, shown before anything is paid, and a ticket follows.
  1. Anyone can book; a signed-in family ticks who is coming from its own list.
  2. If the phone or email belongs to a member family, the member price applies by itself, and nothing about that family is shown.
  3. The Worker works out the price on the server: early bird by date or by the first so many tickets, age bands on the day of the gathering, children under each gathering's free age free, places left.
  4. They choose whether their family's name shows on Who's coming.
  5. They pay by card (built, switched on when the house moves), or the booking is kept and the board confirms how to pay.
  6. The ticket is a page at an address no one can guess, with a code for the door, a calendar entry and directions. A copy comes by email once it is paid; the family's name joins Who's coming then too.

A gathering sold elsewhere (this year's Diwali) shows a Buy tickets button to that page instead.

4What happens at the door on the night?A one-evening link on a volunteer's phone; it keeps working without signal.
  1. The board opens the door app from the dashboard and shares its link or code with the volunteers. It stops working the night of the gathering.
  2. The volunteer searches a name or scans a ticket's code. The list is kept on the phone.
  3. A check-in is saved on the phone at once and sent when there is signal. A second check-in for the same family asks first.
  4. Walk-ins are added at the door with how they paid: cash, Zelle, check or no charge.
  5. Each check-in lights a lamp on the hall screen: families here tonight, and how many people.
5What happens the morning after?The gathering's page becomes the evening remembered.
  1. From six hours after the gathering ends, the page leads with "Last time" and how many families came.
  2. The evening's page shows who came (from the door's check-ins), the photos from the evening's Google Photos album, and a code to add more.
  3. A family that booked or came can leave a word, up to three; it shows at once with their family's name.
  4. Their ticket now reads "You were there", with the same box for a word.
  5. On their family's page the ticket joins a row of stubs: every gathering they came to.

Photos are added to Google Photos as before. The house reads the album's public share page; if that ever stops working, the page shows the album's link and code alone.

6What happens when a family brings another family?An invitation link; if the new family says yes, an arc joins them on the Web of Welcome.
  1. On their family's page, a family taps Send your invitation; it opens WhatsApp, Messages or email.
  2. The new family opens it: "The [family name] invites you", then Come home, which greets them with that name.
  3. The question "Did [that family] bring you?" is filled in; they can change it.
  4. If they say yes, and they are new to the house, the two families are linked and the inviters get an email.

A gathering shared from a family's ticket carries the same invitation.

7What happens when a family becomes members?One payment, for the whole family, for life.
  1. The membership room says what it gives: member prices, booking first when the board opens a gathering early, the January meeting, a place on the members list.
  2. A signed-in family confirms and pays; a new family gives a name, email, phone and a birth date first.
  3. Once paid, the family is a member, with the year it joined, and is added to the members list. A welcome follows.
8What happens when the board sets up a gathering?One form holds everything the gathering's page shows.
  1. In the dashboard, Events: when and where, who can book and from when, capacity, prices by band and early bird, the program in English and Hindi, contacts, and the album link afterwards.
  2. "Copy to next year" carries everything but the dates, status and photos.
  3. The overview opens on the next gathering at a glance: days to go, families and people booked against capacity, money in, who still owes, early birds left; on the night, check-ins.
9What happens while the house is walked before it opens?Reviewers leave notes on the spot, and real people's words in their own voice.
  1. A reviewer enters by name and a passcode, or is already in as a board member.
  2. A Note button pins a note to the exact spot on any page: typed, spoken, or a picture.
  3. Where a room needs real people's words (how UPAGP began, each president's years, why families joined), a card asks for them. The reviewer speaks or types, in English or Hindi.
  4. Words show on the page at once, and a voice can be heard with Listen. An Admin can take any of them down.

Why: the house never puts words in a real person's mouth.

Part 3

The parts

One card for each part of the house. Each opens with its bold line, then what it's like, then how it works.

1What is the courtyard, and the menu?Home drawn for the hour; the house seen from above.

The courtyard follows Philadelphia's season and hour (morning, afternoon, godhuli, the cow-dust hour of dusk, and night), or the hour you choose. A first visit opens with a short scene that ends where we live now, skippable; a calm setting shows still pictures instead. The menu draws the house from above, with five wings, and holds this device's settings: the hour, language, text size and movement.

2What is Our Story?Where we come from, the crossing, and a lamp for every year since 2001.

Keepsakes of Uttar Pradesh are drawn as you reach them; families' memories of home are pinned among them for families who have come home. A line crosses from Uttar Pradesh to the Delaware Valley. Then a lamp for each year, lit as you pass, with the president who took up the lamp, the gatherings held and the families who joined. The presidents have a room of their own: the lamp, hand to hand.

3What is the map of Uttar Pradesh?Eight regions, each lit on the map as you reach it.

Braj, the western Doab, Rohilkhand, Awadh, Kannauj and the central plain, Prayagraj, Bundelkhand and Purvanchal: for each, what is spoken, celebrated, made and tasted, with photographs from Wikimedia Commons, credited under each. Families who have come home also see how many of our families come from there. The Sangam (where the Ganga and the Yamuna meet) and Lucknow have their own rooms.

4What is a gathering's page?Its story, this year's evening, who's coming, and the years before.

Each of the four gatherings wears its own colours. The year is a ring of months. A gathering's page tells what it is, then this year: date and place, the program drawn as a thread of lamps, the price table, the contacts for that evening, and who's coming. Past years sit as a shelf, each opening its evening remembered.

5What is the ticket?A page at an address no one can guess; afterwards, a keepsake.

Before the night: a code for the door, who's coming, what was paid, a calendar entry, directions, and a share button that sends the gathering's page, carrying the family's invitation. After the night, if the family was checked in, it reads "You were there".

6What is your family's page?Everything about your family, in one room only you can open.

A family photo, a thread drawn from your district in Uttar Pradesh to where you live now, everyone in the family, your year with UPAGP as a ring, every gathering you came to as stubs, a memory of home, who brought you, an invitation to bring another family, how others find you (email, phone, your name on Who's coming), your details and your language.

7What are the directory, the map of families and the Web of Welcome?Families who have come home find each other; others see counts.

The directory searches by name, town or district; it has no list to browse. The map of families shows how many live in each town and come from each district; families who have come home can open a district to see who is there, with their memories. The Web of Welcome draws every family at the year it joined, with arcs from the family that brought it; it plays the years, and stands upright on a phone.

8What is the dashboard?The board's room, behind its own sign-in.

Overview, Families, Match (possible members-list matches, confirmed by hand), Events, Bookings, Door, Sponsors, Pages, Notes, Own words, Narration (recordings for the Listen buttons), Emails, a daily check, exports, and printable table cards and paper forms. A board member marked as an Admin is let in with their own sign-in; a passcode is the other way in. Match lists families who may be on the old members list, for the board to confirm.

9What email does the house send?Only the letters a family would expect, each one logged.

A sign-in link, a welcome, a ticket, a note when the board finds a family on the members list, a sponsor's thank-you, "they've come home" to a family that brought another, birthday greetings, and each morning a note to the board. In English, in one letter design. Until real email is switched on, they are kept in a test inbox for the board.

10What runs by itself each day?A morning check, birthday greetings, and a note to the board.

At eight each morning in Philadelphia (seven in winter) the house checks that its tables and front page answer and that no email failed the day before, notes whether email and card payments are switched on, sends the day's birthday greetings, and writes the board a short note.

11What does a shared link look like?Each room draws its own preview picture.

When a link to any room is shared on WhatsApp or by message, the preview shows the room's title and line in its own colours, with the lamp in its doorway, in English or Hindi. An invitation's preview carries the inviting family's name: "The [family name] invites you to UPAGP".

Part 4

The promises

What the house keeps to, whatever else changes.

  1. No home address, anywhere. A town and a state, never a street.
  2. No one's date of birth is ever shown. It sets ticket prices by age, is one way to sign in, and brings a birthday greeting.
  3. Children belong with their families. Their names appear with their family's, like everyone's.
  4. Contact details only by choice. Email and phone show to other families only if the family chooses, and the choice takes effect at once.
  5. A family can be counted without its name on any gathering's page, from its booking or its own page.
  6. Prices are worked out by the house and shown before anything is paid. Card details go to the payment company and never reach the house.
  7. Real people's words are their own. Nothing is written for them; spelling may be fixed, never what they said.
  8. No advertising and no tracking. Settings stay on the device.
  9. Nothing is thrown away by accident. A record that is finished with is marked and kept. A family that asks to be removed is deleted, with its people; its payments stay in the accounts without its name.

What runs by itself, and what is done by hand?

By itselfBy hand
Prices, early birds, places left, member pricesSetting up each gathering, and copying it to next year
Tickets, welcomes and every other emailConfirming a family's place on the members list
The morning check and birthday greetingsConfirming a sponsor before their name joins the wall
Who's coming, who came, the hall screenAdding the album link after a gathering; taking words down if needed

How was it checked?

Fourteen walks, run by hand before changes are pushed, go through the house as a script: signing in, coming home, joining, booking, the members' side, giving, own words, the evening, bringing a family, the dashboard, the door, the board, review notes and the shell of every room. Every room is walked at phone and computer width for keyboard use, sideways scroll and page errors. An independent reviewer, given the code and not the conclusions, read the latest work against it, and its findings were fixed; another read these three pages against the code before they went up.

What's ahead?

  1. The walk with the people who will run it, with their notes left on the pages.
  2. Photographs of past gatherings, from the association's albums.
  3. Card payments and real email switched on, and the move to upagp.com.
  4. Booking in the house from the January meeting on.
For buildersThe program, the tables and the settings behind each card above.
  • The program. One Cloudflare Worker serves every page and form; static files (styles, scripts, photographs) come from its assets. Pages are written in plain JavaScript on the server, English at / and Hindi at /hi/. A push to the main branch deploys.
  • The base. Thirteen Airtable tables: Families, People, Events, Bookings, Sponsors, Presidents, Years, Settings, Members List, Narration, Own Words, Email Log and Notes. The Worker reads and writes them through the Airtable API with a key held as a Worker secret.
  • Sessions. Signed tokens, each with its own lifetime: in a cookie for a family (and its person), the board and a reviewer; in the address for a ticket, a door and an invitation. A sign-in link carries a fingerprint of the last sign-in, so it works once.
  • Payments. Stripe Checkout (the card company's own payment page), with a webhook (a message Stripe sends back when a payment lands) that marks a booking paid and sends the ticket. Until a key is set, bookings are kept and the board confirms payment.
  • Email. One sender: Resend once a sender address and its key are set, otherwise the test inbox. Every email is written to the Email Log.
  • The door app. A service worker (a small script the browser keeps) keeps the page on the phone; the list and the check-ins waiting to be sent are kept in the page's own storage, and the check-ins go when there is signal, each once. The list stays on the phone after the evening.
  • Share pictures. /og.png?p=<path> renders the room as a visitor would see it, reads its card line, and draws a 1200×630 picture (resvg; Hindi shaped with HarfBuzz). Kept a day in Cloudflare's cache.
  • The daily check. A scheduled trigger at 12:00 UTC (8am in Philadelphia in summer, 7am in winter).
  • The checks. Fourteen Playwright walks (scripts that drive a real browser) against a strict offline copy of the base that refuses any unknown table or field, run by hand before a push, at 390 and 1440 pixels wide.