heliosian/docs/dev.md

Local development

Toolchain prerequisites: see 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.

Auth

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).

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.

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.

Layout

• 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
• 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