# justinliu47/1050-light-website architecture

> Architecture diagram of the GitHub repository justinliu47/1050-light-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/justinliu47/1050-light-website
- Repository: https://github.com/justinliu47/1050-light-website

## Overview

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`](https://github.com/justinliu47/1050-light-website/blob/main/SubmitReading.html) (Upload page), [`SessionDetail.html`](https://github.com/justinliu47/1050-light-website/blob/main/SessionDetail.html) (Session detail), [`Homepage.html`](https://github.com/justinliu47/1050-light-website/blob/main/Homepage.html) (Homepage), [`sessions.json`](https://github.com/justinliu47/1050-light-website/blob/main/sessions.json) (Session index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Browser app"]
  node_n1["Homepage<br/>map view<br/>[Homepage.html]"]
  node_n2["Session detail<br/>detail view<br/>[SessionDetail.html]"]
  node_n3["Upload page<br/>ingest UI<br/>[SubmitReading.html]"]
  node_n4["About page<br/>reference page<br/>[Aboutuspage.html]"]
end

subgraph group_g2["Content store"]
  node_n5["Session index<br/>summary JSON<br/>[sessions.json]"]
  node_n6["Session data<br/>time-series JSON<br/>[session_001.json]"]
  node_n7[("Session files<br/>session archive")]
end

subgraph group_g3["Serverless AI"]
  node_n9["Analysis fn<br/>serverless lambda"]
end

subgraph group_g4["External systems"]
  node_n8{{"GitHub API<br/>contents API"}}
  node_n10{{"Anthropic API<br/>llm service"}}
  node_n11["Sensor device<br/>field hardware"]
  node_n12["CSV output<br/>device export"]
end

subgraph group_g5["Secrets"]
  node_n13["Git token<br/>local secret"]
  node_n14["AI key<br/>env secret"]
end

node_n11 -->|"records"| node_n12
node_n12 -->|"imports"| node_n3
node_n3 -->|"commits"| node_n8
node_n13 -->|"authenticates"| node_n8
node_n8 -->|"updates"| node_n5
node_n8 -->|"writes"| node_n7
node_n5 -->|"feeds map"| node_n1
node_n5 -->|"selects session"| node_n2
node_n7 -->|"loads detail"| node_n2
node_n2 -->|"reads"| node_n6
node_n3 -->|"requests analysis"| node_n9
node_n9 -->|"calls"| node_n10
node_n14 -->|"secrets"| node_n9
node_n1 -->|"opens"| node_n2
node_n1 -->|"references"| node_n4
node_n3 -.->|"documents"| node_n4

click node_n1 "https://github.com/justinliu47/1050-light-website/blob/main/Homepage.html"
click node_n2 "https://github.com/justinliu47/1050-light-website/blob/main/SessionDetail.html"
click node_n3 "https://github.com/justinliu47/1050-light-website/blob/main/SubmitReading.html"
click node_n4 "https://github.com/justinliu47/1050-light-website/blob/main/Aboutuspage.html"
click node_n5 "https://github.com/justinliu47/1050-light-website/blob/main/sessions.json"
click node_n6 "https://github.com/justinliu47/1050-light-website/blob/main/readings/session_001.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n1,node_n2,node_n3,node_n4 toneBlue
class node_n5,node_n6,node_n7 toneAmber
class node_n9 toneMint
class node_n8,node_n10,node_n11,node_n12 toneRose
class node_n13,node_n14 toneIndigo
```

## Components

### Browser app

Static HTML/JS pages users interact with in the browser.

- [Homepage](https://github.com/justinliu47/1050-light-website/blob/main/Homepage.html): map view · Main landing page showing one marker per recording session on the map. · `Homepage.html`
- [Session detail](https://github.com/justinliu47/1050-light-website/blob/main/SessionDetail.html): detail view · Drill-down page for a single session with summary, timeline, and spectral chart. · `SessionDetail.html`
- [Upload page](https://github.com/justinliu47/1050-light-website/blob/main/SubmitReading.html): ingest UI · Browser upload flow that parses CSV, previews readings, and publishes a session. · `SubmitReading.html`
- [About page](https://github.com/justinliu47/1050-light-website/blob/main/Aboutuspage.html): reference 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](https://github.com/justinliu47/1050-light-website/blob/main/sessions.json): summary JSON · Central index of all sessions with metadata used by the homepage and publishing flow. · `sessions.json`
- [Session data](https://github.com/justinliu47/1050-light-website/blob/main/readings/session_001.json): time-series JSON · Representative per-session readings and detailed spectral history loaded by the detail page. · `readings/session_001.json`
- **Session files**: session archive · 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**: serverless lambda · Netlify serverless boundary that receives session summaries and invokes AI analysis.

### External systems

Hardware and third-party services outside the web app.

- **GitHub API**: contents API · Repository write path used by the upload page to commit new session content.
- **Anthropic API**: llm service · External model API used to generate plain-English light-pollution assessments.
- **Sensor device**: field hardware · ESP32, AS7341, DS1302 RTC, and SD card that produce CSV files in the field.
- **CSV output**: device export · 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**: local secret · GitHub personal access token kept outside the repo in a gitignored local config.
- **AI key**: env secret · Anthropic credential stored in Netlify environment variables.

## Connections

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