Add credential-free sample mode with sample data, README, and doc reconciliation
This commit is contained in:
Ian Gulliver
+1
-1
@@ -65,7 +65,7 @@ Original tile art (1254×1254 JPEGs for all nine classrooms and all nine grade t
|
||||
- Pill-shaped search inputs and filter buttons; circular icon buttons for quick actions (message, mail, map, favorite).
|
||||
- List rows with right chevrons; hairline dividers; generous whitespace.
|
||||
- Detail pages break the white page with a full-width deep-teal band for family content.
|
||||
- Inline separators: "▶" chains grade to team to subteam; "·" dots separate contact fragments.
|
||||
- Inline separators: "▶" chains grade to classroom to crew; "·" dots separate contact fragments.
|
||||
|
||||
## Responsive chrome
|
||||
|
||||
|
||||
+21
-26
@@ -1,42 +1,37 @@
|
||||
# Local development
|
||||
|
||||
Toolchain prerequisites: see [setup.md](setup.md).
|
||||
|
||||
## Run
|
||||
|
||||
go run .
|
||||
|
||||
The server listens on http://localhost:8080 (override with `PORT`). Templates, static assets, and sample data are read from disk on every request — edit a file and refresh the browser; no restart needed.
|
||||
http://localhost:8080 (override with `PORT`). With `DIRECTORY_SHEET` unset the server serves the fictional community in `sampledata/`, signs every request in as a sample parent, and geocodes with a deterministic fake — no credentials or configuration. Templates, static assets, and sample data are read from disk on every request; edit a file and refresh.
|
||||
|
||||
## Auth
|
||||
Sample-mode limits: the map section needs a real Maps JavaScript key (`GOOGLE_MAPS_BROWSER_KEY`) to render tiles, and self-service edits and media uploads need real-data mode — there is no writable backend or blob store behind the sample CSVs.
|
||||
|
||||
Everything — pages, static assets, and the API — sits behind Google sign-in restricted to the school's Google Workspace domain. Unauthenticated requests get the login page (API paths get a 401). The OAuth 2.0 Web application client (authorized JavaScript origins must include `http://localhost:8080` for local development) is read from `creds/oauth-client.json` — the JSON downloaded from the Cloud console — or from `GOOGLE_CLIENT_ID` when set; the server refuses to start with neither. After Google sign-in the server issues its own HMAC-signed session cookie; set `SESSION_KEY` to keep sessions valid across restarts and instances (without it each start generates a random key).
|
||||
`sampledata/` mirrors the production Sheets layout: one directory per app, one CSV per table, first row is the schema, served through the same data-source interface the Sheets backend implements. It stays fictional — real community data never goes here.
|
||||
|
||||
To capture authenticated pages with the screenshot tooling, launch the capture browser (`go run ./tools/capturebrowser`), sign in to the local server there once, and use `tools/browse` or `tools/screenshot -remote` — the session cookie lives in the capture profile. Plain `tools/screenshot` runs a fresh headless browser with no session and captures the login page.
|
||||
|
||||
## Maps
|
||||
|
||||
The map section geocodes family addresses server-side via the Google Geocoding API (results cached in memory per address) and renders in the browser with the Maps JavaScript API. Two API keys from a project with those APIs enabled, both required at startup:
|
||||
|
||||
- Server key — Geocoding API; restrict by server IP (or leave unrestricted for dev). Never rendered into pages. Read from `creds/geocoding.key`, or `GOOGLE_MAPS_SERVER_KEY` when set.
|
||||
- Browser key — Maps JavaScript API; rendered into the page, so restrict by HTTP referer (localhost and the serving domain). Read from `creds/maps.key`, or `GOOGLE_MAPS_BROWSER_KEY` when set.
|
||||
|
||||
## Local data
|
||||
|
||||
The server reads local data from `sampledata/`, mirroring the production Sheets layout: one directory per app, one CSV file per table, first row is the schema. It goes through the same data-source interface production backends implement, so app code never knows which backend it is talking to.
|
||||
In sample mode `tools/screenshot` captures pages directly, no session needed (see `docs/screenshots.md`).
|
||||
|
||||
## Real data
|
||||
|
||||
DIRECTORY_SHEET=<spreadsheet id> go run .
|
||||
|
||||
switches the directory app to the Google Sheets source. At startup the directory tables are read from the spreadsheet and normalized into the in-memory data model (see `docs/data.md`); the server refuses to start if that load fails, and the model reloads every five minutes. Requires the service account key at `creds/service-account.json` (the directory is gitignored) with the Sheets API enabled, the spreadsheet shared with the service account as an editor (self-service uploads write media cells and append to the Change Log tab), and the media shared drive shared as content manager (uploads create files and archive old versions). Real data never leaves the process: nothing is written to disk.
|
||||
serves from the production spreadsheet and media drive (see `docs/data.md`) and turns on the full stack. The model loads at startup — the server refuses to start if the load fails — and reloads every five minutes. Real data never leaves the process: nothing is written to disk. Requirements:
|
||||
|
||||
## Layout
|
||||
- **Sign-in** — everything sits behind Google sign-in restricted to the school's Workspace domain (API paths get a 401 instead of the login page). The OAuth web client is read from `creds/oauth-client.json` or `GOOGLE_CLIENT_ID`; its authorized JavaScript origins must include `http://localhost:8080`. The server issues its own HMAC-signed session cookie; set `SESSION_KEY` to keep sessions valid across restarts.
|
||||
- **Service account** — key at `creds/service-account.json` (the directory is gitignored), Sheets API enabled, the spreadsheet shared with it as editor (self-service edits write cells and append to the Change Log tab), the media shared drive shared as content manager (uploads create files and archive old versions).
|
||||
- **Maps** — a server key for the Geocoding API (`creds/geocoding.key` or `GOOGLE_MAPS_SERVER_KEY`; never rendered into pages, restrict by server IP or leave unrestricted for dev) and a browser key for the Maps JavaScript API (`creds/maps.key` or `GOOGLE_MAPS_BROWSER_KEY`; rendered into pages, restrict by HTTP referer). Geocoding results are cached in memory per address.
|
||||
|
||||
- `main.go` — server entry point and app routing
|
||||
- `internal/data` — data source interface and the CSV sample-data implementation
|
||||
- `internal/directory` — directory app handlers
|
||||
- `web/directory` — directory app page templates and static assets
|
||||
- `tools/screenshot` — dev-site page capture, see [screenshots.md](screenshots.md)
|
||||
- `tools/columns` — print the column names of each directory table in the configured source
|
||||
- `tools/splash` — extract the original app's iOS splash screens into `web/static/brand/splash`
|
||||
To capture authenticated real-data pages, launch the capture browser (`go run ./tools/capturebrowser`), sign in to the local server there once, and use `tools/browse` or `tools/screenshot -remote` — the session cookie lives in the capture profile.
|
||||
|
||||
## Setup
|
||||
|
||||
Development happens on macOS. Two Homebrew installs cover everything here and in `docs/screenshots.md`:
|
||||
|
||||
brew install go
|
||||
brew install --cask google-chrome
|
||||
|
||||
- **Go** 1.26 or later — builds and runs the server and all tooling (`go run`, `go vet`).
|
||||
- **Google Chrome** — launched headless by the screenshot tool from its standard install location; never opened by hand.
|
||||
|
||||
No Node, no Docker, and no cloud credentials are needed for local development. Repository layout is in the README.
|
||||
|
||||
+7
-15
@@ -5,11 +5,11 @@ The directory ("Helios Who?") is the community's who's-who: students, parents, a
|
||||
## Entities
|
||||
|
||||
- **Person** — first and last name; role (student, parent, staff); optional pronouns; optional nickname and pronunciation (an audio recording); photo (some people use an illustrated avatar instead); email; role-specific fields:
|
||||
- *Students*: grade, classroom and team assignment (displayed as a chain, e.g. grade ▶ team ▶ subteam), optional free-text "about me" written by or about the kid.
|
||||
- *Students*: grade, classroom, and crew (displayed as a chain, e.g. grade ▶ classroom ▶ crew), optional free-text "about me" written by or about the kid.
|
||||
- *Parents*: their kids (shown as context wherever the parent appears), optional room-parent assignments.
|
||||
- *Staff*: job title, displayed prominently; staff may have no family record.
|
||||
- **Family** — the join between adults and kids: combined surname(s), family photo with a caption identifying everyone in it, an optional family-name pronunciation recording, member list split into adults and kids, address, phone. Lists show the city; the full address powers map actions. Families choose how much address to share (full postal address or just the city).
|
||||
- **Classroom** — name and mascot artwork, the grade band it serves, and its students, staff, and parents. Classrooms nest teams/subteams that student rows reference.
|
||||
- **Classroom** — name and mascot artwork, the grade band it serves, and its students, staff, and parents. Classrooms nest crews that student rows reference.
|
||||
- **Grade** — K through 8, grouped into bands (K, 1st/2nd, 3rd/4th, ...) for browsing.
|
||||
|
||||
## Navigation
|
||||
@@ -22,14 +22,14 @@ Sections:
|
||||
|
||||
Four tabs, each with search and filter:
|
||||
|
||||
- **Everyone** — grid of circular photos. Each card: role label with pronouns (e.g. "PARENT (SHE/HER)"), name, and a context line — kids' names for parents, grade/team chain for students, job title for staff.
|
||||
- **Students** — larger cards, first name prominent over last name, grade/team chain, pronouns badge.
|
||||
- **Everyone** — grid of circular photos. Each card: role label with pronouns (e.g. "PARENT (SHE/HER)"), name, and a context line — kids' names for parents, grade/classroom chain for students, job title for staff.
|
||||
- **Students** — larger cards, first name prominent over last name, grade/classroom chain, pronouns badge.
|
||||
- **Families** — family-photo cards with grade badges, surname combination, and kids' first names.
|
||||
- **Staff** — grouped into sections (admin and office staff, teaching staff, ...), title over name.
|
||||
|
||||
### Person detail
|
||||
|
||||
Breadcrumb back to the list, favorite (heart) toggle, photo, role label with pronouns, name with nickname/pronunciation line, grade/team chain for students, email and address rows with quick actions (message, mail, map). Students add the "about me" paragraph. Below, a contrasting family band: the person's family name, a narrative caption of who's who, kid rows (grade/team, email), adult rows, and a link to the family page.
|
||||
Breadcrumb back to the list, favorite (heart) toggle, photo, role label with pronouns, name with nickname/pronunciation line, grade/classroom chain for students, email and address rows with quick actions (message, mail, map). Students add the "about me" paragraph. Below, a contrasting family band: the person's family name, a narrative caption of who's who, kid rows (grade/team, email), adult rows, and a link to the family page.
|
||||
|
||||
### Family detail
|
||||
|
||||
@@ -37,7 +37,7 @@ Family photo with click-to-expand and its identifying caption, grade badges, fam
|
||||
|
||||
### Classrooms
|
||||
|
||||
Three tabs: browse classrooms by grade band (mascot art, student count, link to detail), the same grouped by classroom, and room parents (parent rows annotated with each of their kids' classroom and grade). Classroom detail shows the mascot, name, and tabbed member lists — students (grouped by team, with parents' names above each student and the about-me blurb inline), staff, and parents — with per-tab counts.
|
||||
Three tabs: browse classrooms by grade band (mascot art, student count, link to detail), the same grouped by classroom, and room parents (parent rows annotated with each of their kids' classroom and grade). Classroom detail shows the mascot, name, and tabbed member lists — students (grouped by crew, with parents' names above each student and the about-me blurb inline), staff, and parents — with per-tab counts.
|
||||
|
||||
### My Family
|
||||
|
||||
@@ -55,14 +55,6 @@ A Google map of family locations: one brand-teal pin per geocoded family address
|
||||
|
||||
A copyable contact table for party planning and outreach: full name, email, role, grade, classroom. Tabs narrow to parents, students, both, or the user's bookmarked people. Filters select grades or classrooms.
|
||||
|
||||
### Data View
|
||||
|
||||
A raw tabular view over the underlying records, for power users.
|
||||
|
||||
### Share & About
|
||||
|
||||
Share the app by SMS or link, an explanation of why photos and facts are collected, a bug-report pointer, and an opt-out form for removing a person's information.
|
||||
|
||||
## Behaviors
|
||||
|
||||
- Everything is cross-linked: parents ↔ kids ↔ families ↔ classrooms; any person reference navigates to that person.
|
||||
@@ -70,4 +62,4 @@ Share the app by SMS or link, an explanation of why photos and facts are collect
|
||||
- Favorites/bookmarks mark people and feed the email list's bookmark tab.
|
||||
- Photos lazy-load; full-size view on click where the photo is the subject (family pages).
|
||||
- All data is community-only, behind sign-in; opt-out removes a person on request.
|
||||
- Self-service media: viewing your own record, your kids', or your family page shows inline edit icons — a camera on the photo for uploads, microphone/file icons under the pronunciation player to record in the browser or upload audio, and a pencil on the About Me text for inline editing. Replaced files move to an `archive` folder in the media drive with a timestamp, the sheet cells are updated, and every change appends to the sheet's `Change Log` tab (timestamp, actor, target, kind, new value, replaced value).
|
||||
- Self-service: viewing your own record, your kids', or your family page shows inline edit affordances — photo upload, pronunciation recording or upload, About Me text, preferred name, phone, address — plus opt-out for yourself or your kids. Media uploads replace the Drive file and archive the previous version; sheet-backed edits write the Overrides tab and append a Change Log row (see `docs/data.md`).
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
# Dev environment setup
|
||||
|
||||
Development happens on macOS. Two Homebrew installs, and everything in `docs/dev.md` and `docs/screenshots.md` works:
|
||||
|
||||
brew install go
|
||||
brew install --cask google-chrome
|
||||
|
||||
- **Go** 1.26 or later — builds and runs the server and all tooling (`go run`, `go vet`).
|
||||
- **Google Chrome** — launched headless by the screenshot tool; never needs to be opened by hand. The tool finds it in its standard install location automatically.
|
||||
|
||||
No Node, no Docker, and no cloud credentials are needed for local development.
|
||||
Reference in New Issue
Block a user