How justinliu47/1050-light-website works
1. What this repo is
- This is a static, browser-driven dashboard for light-pollution field data.
- The system has no traditional backend database; instead, the GitHub repository itself is the data store for session metadata and per-session readings.
2. Main user-facing surfaces
- Homepage.html is the map overview showing one marker per recording session.
- SessionDetail.html is the drill-down view for a single session, with timeline and spectral breakdown.
- SubmitReading.html is the data ingestion/upload page for new sensor CSVs.
- Aboutuspage.html is the documentation/reference page for hardware, firmware, and file format.
3. Core data model
- sessions.json is the index: it contains summary metadata for every session, including ID, file path, date/time range, aggregate clear-channel stats, row count, and coordinates.
- readings/session_XXX.json contains the full time-series data for one session, used only when a user opens that session’s detail page.
- This split keeps the homepage lightweight: it loads only summaries, not full reading histories.
4. Data acquisition boundary
- The sensor device is external to the web app: an ESP32 + AS7341 spectral sensor + DS1302 RTC + SD card produces CSV files on-device.
- The website does not talk to the hardware directly; it consumes the CSV output after the field session is complete.
5. Upload and commit flow
- On SubmitReading.html, the CSV is parsed in the browser and previewed before save.
- The page then commits the session into the repo via the GitHub Contents API, updating both:
- a new readings/session_XXX.json file
- the central sessions.json index
- This means “publishing” a session is effectively a Git commit through the browser.
6. Map and session discovery flow
- The homepage fetches only sessions.json and places a marker for each session on a Leaflet/OpenStreetMap map.
- Marker color is derived from each session’s average Clear-channel value, normalized against the set of all sessions.
- Clicking a marker routes the user to the corresponding session detail page.
7. Session detail flow
- SessionDetail.html loads one session’s JSON file based on the query parameter, e.g. ?session=session_001.
- It renders:
- session summary stats
- a 2-second-per-segment timeline
- an interactive spectral bar chart for a selected reading
- The timeline uses the session’s own min/max Clear values for visual scaling, while the chart shows all 10 spectral channels plus NIR/Clear/Lux-derived context per reading.
8. AI analysis subsystem
- When a new session is uploaded, the summary is sent to a Netlify serverless function at netlify/functions/analyse.js.
- That function calls the Anthropic API to generate a plain-English assessment of the light pollution characteristics.
- The browser never calls Anthropic directly; the AI capability is isolated behind the serverless boundary.
9. Runtime and deployment shape
- The frontend is plain HTML/CSS/JavaScript, no framework.
- The app is deployed on Netlify, which also hosts the serverless AI function.
- The repo’s JSON files are both the source of truth and the published content, so the deployment model is static site + function + GitHub-backed content.
10. Security and secrets boundary
- GitHub write access is handled locally through config.js, which is gitignored and contains a personal access token.
- The Anthropic key is stored only in Netlify environment variables.
- So there are two separate secret zones: local GitHub upload credentials and deployed AI credentials.
11. Key architectural dependency chain
- Field hardware produces CSV → browser upload page parses CSV → GitHub repo is updated with session JSON and index entry → homepage reads sessions.json → detail page reads the selected session file → optional AI analysis is generated through Netlify.
- The repo therefore acts as both content store and publish target, with Netlify providing the only server-side execution.
12. Repo-specific note
- The README refers to index.html, but the file tree shows Homepage.html; architecturally, that file is the main landing page for the map view in this repository.
Main entry points: SubmitReading.html Upload page · SessionDetail.html Session detail · Homepage.html Homepage · sessions.json Session index
Components 14
Browser app
Static HTML/JS pages users interact with in the browser.
- Homepage · Main landing page showing one marker per recording session on the map.
Homepage.html - Session detail · Drill-down page for a single session with summary, timeline, and spectral chart.
SessionDetail.html - Upload page · Browser upload flow that parses CSV, previews readings, and publishes a session.
SubmitReading.html - About page · Documentation for hardware, firmware, and the file format.
Aboutuspage.html
Content store
GitHub-hosted JSON content that serves as both source of truth and published site data.
- Session index · Central index of all sessions with metadata used by the homepage and publishing flow.
sessions.json - Session data · Representative per-session readings and detailed spectral history loaded by the detail page.
readings/session_001.json - Session files · Collection of per-session JSON payloads that store the full readings for each recording.
Serverless AI
Netlify-hosted analysis boundary for optional session interpretation.
- Analysis fn · Netlify serverless boundary that receives session summaries and invokes AI analysis.
External systems
Hardware and third-party services outside the web app.
- GitHub API · Repository write path used by the upload page to commit new session content.
- Anthropic API · External model API used to generate plain-English light-pollution assessments.
- Sensor device · ESP32, AS7341, DS1302 RTC, and SD card that produce CSV files in the field.
- CSV output · On-device CSV produced after a field session and later imported by the browser.
Secrets
Credential boundaries split between local upload access and deployed function secrets.
- Git token · GitHub personal access token kept outside the repo in a gitignored local config.
- AI key · Anthropic credential stored in Netlify environment variables.
Connections 16
- Sensor device → CSV output: records · The field device exports a CSV after collecting sensor readings.
- CSV output → Upload page: imports · The upload page parses and previews the CSV in the browser.
- Upload page → GitHub API: commits · Publishing uses the GitHub Contents API to write repo content.
- Git token → GitHub API: authenticates · Local token authorizes repository writes from the browser upload flow.
- GitHub API → Session index: updates · A new session appends to the central index.
- GitHub API → Session files: writes · Publishing also creates the per-session JSON payload.
- Session index → Homepage: feeds map · Homepage loads only the summary index to render session markers.
- Session index → Session detail: selects session · The detail page resolves the requested session from the index/reference flow.
- Session files → Session detail: loads detail · Session detail fetches the selected session JSON file.
- Session detail → Session data: reads · The detailed view renders timeline and spectral chart data from the session file.
- Upload page → Analysis fn: requests analysis · After upload, the browser sends summary data to the serverless analysis boundary.
- Analysis fn → Anthropic API: calls · The function forwards the summary to Anthropic for narrative assessment.
- AI key → Analysis fn: secrets · Netlify environment variables supply the AI credential.
- Homepage → Session detail: opens · Clicking a map marker routes to the session detail page.
- Homepage → About page: references · The site includes a documentation surface for the hardware and file format.
- Upload page → About page: documents · The upload flow is supported by the reference page for expected inputs and hardware context.