# sozerong/genuel architecture

> Architecture diagram of the GitHub repository sozerong/genuel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sozerong/genuel
- Repository: https://github.com/sozerong/genuel

## Overview

#### Purpose and Entry Points
This is a browser-based seat-map application with geospatial and solar-position logic, backed by Seoul stop data. The primary client entry point is `public/index.html`, which loads the application code in `public/app.js`. Deployment/platform metadata is defined in `apps-in-toss.config.ts`, while the repository also contains a standalone Node proxy at `server/proxy.mjs`.

#### Client Application Shell
The static frontend is organized as a small JavaScript application rather than a framework project:
- `public/index.html` provides the document shell.
- `public/app.js` coordinates UI state and feature modules.
- `public/style.css` defines the application presentation.
- `public/manifest.json` and `public/sw.js` establish installability/offline-service-worker boundaries.

The public directory is the deployable browser asset boundary; it should not depend directly on server-local files at runtime.

#### Geospatial and Solar Computation
Location and sunlight calculations are separated into domain modules:
- `public/geo.js`
- `public/solar.js`
- `public/app.js`

`geo.js` likely owns coordinate, route, or directional calculations, while `solar.js` computes solar state from location/time. Their results feed the application’s seat-selection or visualization decisions rather than being embedded in UI markup. The corresponding correctness boundary is covered by `test/solar-geo.test.mjs`.

#### Seat Map Presentation
Seat layout and seat-level rendering are isolated from the broader application flow:
- `public/seatmap.js`
- `public/app.js`
- `public/style.css`

`seatmap.js` is the likely boundary between computed travel/sun context and interactive seat-map UI. `app.js` should orchestrate data acquisition, selected trip/location/time state, solar/geo evaluation, and updates to this visual component.

#### Seoul Stop Data Pipeline
The repository ships a generated/static local stop dataset:
- `server/data/seoul-stops.json`
- `server/data/build-seoul-data.py`
- `server/proxy.mjs`

`build-seoul-data.py` is a data-preparation stage that produces or refreshes the Seoul stops artifact. The browser should consume data through static hosting or the proxy/API boundary, not invoke the Python generator. The checked-in JSON allows the application to operate without requiring live stop-data generation.

#### Proxy and External-Service Boundary
Network access is centralized behind proxy implementations:
- `server/proxy.mjs`
- `reference/proxy.mjs`
- `public/app.js`

The Node proxy is the intended server-side integration boundary for any upstream service, insulating browser code from cross-origin, credential, or upstream-response concerns. `reference/proxy.mjs` and `reference/prototype.html` appear to preserve an earlier prototype/reference implementation rather than form the main runtime path.

#### Runtime and Deployment Shape
The system has two material runtimes:
- Browser runtime: static assets under `public/`, including service-worker support.
- Node runtime: `server/proxy.mjs` for proxied network/data access.

Package execution and dependency wiring are defined by `package.json` and `package-lock.json`. Platform-specific application packaging/deployment is represented by `apps-in-toss.config.ts`. Environment-dependent proxy configuration is indicated by `.env.example`, keeping secrets and upstream endpoint configuration outside client assets.

Main entry points: [`public/app.js`](https://github.com/sozerong/genuel/blob/main/public/app.js) (App coordinator), [`public/index.html`](https://github.com/sozerong/genuel/blob/main/public/index.html) (Document shell), [`public/geo.js`](https://github.com/sozerong/genuel/blob/main/public/geo.js) (Geospatial logic), [`public/solar.js`](https://github.com/sozerong/genuel/blob/main/public/solar.js) (Solar logic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser runtime"]
  node_html["Document shell<br/>HTML entry<br/>[index.html]"]
  node_app["App coordinator<br/>browser module<br/>[app.js]"]
  node_styles["Presentation<br/>CSS<br/>[style.css]"]
  node_seatmap["Seat map<br/>UI module<br/>[seatmap.js]"]
  node_manifest["App manifest<br/>PWA metadata<br/>[manifest.json]"]
  node_service_worker["Service worker<br/>offline runtime<br/>[sw.js]"]
end

subgraph group_domain["Travel computation"]
  node_geo["Geospatial logic<br/>domain module<br/>[geo.js]"]
  node_solar["Solar logic<br/>domain module<br/>[solar.js]"]
  node_tests["Solar/geo tests<br/>correctness tests<br/>[solar-geo.test.mjs]"]
end

subgraph group_data["Stop data pipeline"]
  node_stop_builder["Stop data builder<br/>Python generator"]
  node_stops[("Seoul stops<br/>static dataset<br/>[seoul-stops.json]")]
end

subgraph group_server["Node integration"]
  node_proxy{{"Upstream proxy<br/>Node service<br/>[proxy.mjs]"}}
  node_env["Proxy environment<br/>environment contract<br/>[.env.example]"]
end

node_reference_proxy["Reference proxy<br/>prototype reference<br/>[proxy.mjs]"]
node_reference_ui["Reference prototype<br/>prototype reference<br/>[prototype.html]"]
node_package["Package execution<br/>Node package<br/>[package.json]"]
node_lockfile["Locked dependencies<br/>lockfile<br/>[package-lock.json]"]
node_deployment["Platform packaging<br/>deployment config"]

node_html -->|"loads"| node_app
node_html -->|"loads"| node_styles
node_html -->|"declares"| node_manifest
node_manifest -.->|"installability/offline"| node_service_worker
node_app -->|"evaluates route/location"| node_geo
node_app -->|"evaluates sun state"| node_solar
node_geo -->|"travel context"| node_seatmap
node_solar -->|"sun context"| node_seatmap
node_app -->|"updates"| node_seatmap
node_app -->|"consumes local stop data"| node_stops
node_app -->|"requests network data"| node_proxy
node_stop_builder -->|"generates"| node_stops
node_env -.->|"configures"| node_proxy
node_package -->|"locks dependencies"| node_lockfile
node_package -->|"runs"| node_proxy
node_deployment -.->|"packages static app"| node_html
node_tests -.->|"verifies"| node_geo
node_tests -.->|"verifies"| node_solar
node_reference_ui -.->|"prototype path"| node_reference_proxy

click node_html "https://github.com/sozerong/genuel/blob/main/public/index.html"
click node_app "https://github.com/sozerong/genuel/blob/main/public/app.js"
click node_styles "https://github.com/sozerong/genuel/blob/main/public/style.css"
click node_seatmap "https://github.com/sozerong/genuel/blob/main/public/seatmap.js"
click node_manifest "https://github.com/sozerong/genuel/blob/main/public/manifest.json"
click node_service_worker "https://github.com/sozerong/genuel/blob/main/public/sw.js"
click node_geo "https://github.com/sozerong/genuel/blob/main/public/geo.js"
click node_solar "https://github.com/sozerong/genuel/blob/main/public/solar.js"
click node_stop_builder "https://github.com/sozerong/genuel/blob/main/server/data/build-seoul-data.py"
click node_stops "https://github.com/sozerong/genuel/blob/main/server/data/seoul-stops.json"
click node_proxy "https://github.com/sozerong/genuel/blob/main/server/proxy.mjs"
click node_env "https://github.com/sozerong/genuel/blob/main/.env.example"
click node_reference_proxy "https://github.com/sozerong/genuel/blob/main/reference/proxy.mjs"
click node_reference_ui "https://github.com/sozerong/genuel/blob/main/reference/prototype.html"
click node_package "https://github.com/sozerong/genuel/blob/main/package.json"
click node_lockfile "https://github.com/sozerong/genuel/blob/main/package-lock.json"
click node_deployment "https://github.com/sozerong/genuel/blob/main/apps-in-toss.config.ts"
click node_tests "https://github.com/sozerong/genuel/blob/main/test/solar-geo.test.mjs"

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_html,node_app,node_styles,node_seatmap,node_manifest,node_service_worker toneBlue
class node_geo,node_solar,node_tests toneAmber
class node_stop_builder,node_stops toneMint
class node_proxy,node_env toneRose
class node_reference_proxy,node_reference_ui,node_package,node_lockfile,node_deployment toneNeutral
```

## Components

### Browser runtime

Deployable static application assets.

- [Document shell](https://github.com/sozerong/genuel/blob/main/public/index.html): HTML entry · `public/index.html`
- [App coordinator](https://github.com/sozerong/genuel/blob/main/public/app.js): browser module · Orchestrates state, data, calculations, and UI updates. · `public/app.js`
- [Presentation](https://github.com/sozerong/genuel/blob/main/public/style.css): CSS · `public/style.css`
- [Seat map](https://github.com/sozerong/genuel/blob/main/public/seatmap.js): UI module · Renders and updates interactive seats. · `public/seatmap.js`
- [App manifest](https://github.com/sozerong/genuel/blob/main/public/manifest.json): PWA metadata · `public/manifest.json`
- [Service worker](https://github.com/sozerong/genuel/blob/main/public/sw.js): offline runtime · Provides the offline boundary. · `public/sw.js`

### Travel computation

Location and sunlight evaluation.

- [Geospatial logic](https://github.com/sozerong/genuel/blob/main/public/geo.js): domain module · `public/geo.js`
- [Solar logic](https://github.com/sozerong/genuel/blob/main/public/solar.js): domain module · `public/solar.js`
- [Solar/geo tests](https://github.com/sozerong/genuel/blob/main/test/solar-geo.test.mjs): correctness tests · Covers the travel computation boundary. · `test/solar-geo.test.mjs`

### Stop data pipeline

Generated Seoul stop dataset.

- [Stop data builder](https://github.com/sozerong/genuel/blob/main/server/data/build-seoul-data.py): Python generator · Refreshes the checked-in Seoul stop artifact. · `server/data/build-seoul-data.py`
- [Seoul stops](https://github.com/sozerong/genuel/blob/main/server/data/seoul-stops.json): static dataset · Generated local stop data. · `server/data/seoul-stops.json`

### Node integration

Server-side upstream access boundary.

- [Upstream proxy](https://github.com/sozerong/genuel/blob/main/server/proxy.mjs): Node service · Centralizes browser-facing upstream access. · `server/proxy.mjs`
- [Proxy environment](https://github.com/sozerong/genuel/blob/main/.env.example): environment contract · Keeps upstream settings and secrets outside client assets. · `.env.example`

### Other components

- [Reference proxy](https://github.com/sozerong/genuel/blob/main/reference/proxy.mjs): prototype reference · Preserved earlier implementation, outside the main runtime. · `reference/proxy.mjs`
- [Reference prototype](https://github.com/sozerong/genuel/blob/main/reference/prototype.html): prototype reference · Preserved earlier UI prototype. · `reference/prototype.html`
- [Package execution](https://github.com/sozerong/genuel/blob/main/package.json): Node package · Defines dependency and execution wiring. · `package.json`
- [Locked dependencies](https://github.com/sozerong/genuel/blob/main/package-lock.json): lockfile · `package-lock.json`
- [Platform packaging](https://github.com/sozerong/genuel/blob/main/apps-in-toss.config.ts): deployment config · Platform-specific application packaging metadata. · `apps-in-toss.config.ts`

## Connections

- Document shell → App coordinator: loads
- Document shell → Presentation: loads
- Document shell → App manifest: declares
- App manifest → Service worker: installability/offline
- App coordinator → Geospatial logic: evaluates route/location
- App coordinator → Solar logic: evaluates sun state
- Geospatial logic → Seat map: travel context
- Solar logic → Seat map: sun context
- App coordinator → Seat map: updates
- App coordinator → Seoul stops: consumes local stop data
- App coordinator → Upstream proxy: requests network data
- Stop data builder → Seoul stops: generates
- Proxy environment → Upstream proxy: configures
- Package execution → Locked dependencies: locks dependencies
- Package execution → Upstream proxy: runs
- Platform packaging → Document shell: packages static app
- Solar/geo tests → Geospatial logic: verifies
- Solar/geo tests → Solar logic: verifies
- Reference prototype → Reference proxy: prototype path