Static HTML Prototype / file:// Compatibility
Superseded by ADR-009 — all research documents are pure HTML with CDN dependencies; no server, no build step.
Context
The research and prototype documents (catalog UI, advertiser profiles, proposal) are being created during the pre-backend phase of the project. The backend (Lambda, DynamoDB, Stripe MPP) does not exist yet. Prototypes need to be iterated on quickly and shared without setup friction.
The prototype must be viewable by anyone who receives a copy of the files —
no npm install, no running server, no environment variables.
Decision
All files under docs/research/ and docs/adr/ are pure HTML
with CSS and JavaScript loaded from CDN. No bundler, no build step, no local server
is required to open them.
Every file must open correctly from file:// in Chrome, Firefox, or Safari.
JSON data is embedded in <script type="application/json"> tags and
read via document.getElementById(...).textContent to work around the
browser restriction that blocks fetch() across file:// origins.
Consequences
Positive
- Zero setup: double-click the file to open it
- Portable: zip the
docs/folder and share it with anyone - No Node.js, Python, or any runtime dependency for viewing
- Fast iteration: edit HTML, save, reload — no build step between changes
- Works offline once CDN resources are cached by the browser
Negative
fetch()to local JSON files blocked underfile://; JSON must be embedded inline- No ES module
import; all JS must be in<script src>or inline - No hot-reload; manual browser refresh on every change
- CDN dependency: offline use requires prior cache; unavailable CDN blocks render
- This approach does not scale to the production Hugo site; it is explicitly prototype-only
Alternatives Considered
| Option | Why not chosen |
|---|---|
| Vite dev server | Requires npm install and a running process; violates the zero-setup sharing goal |
| Hugo (static site generator) | Hugo is the production plan; using it for prototypes adds template complexity before content is stable |
Python http.server | Removes the "just open the file" experience; requires Python and an extra terminal pane |
| CodeSandbox / StackBlitz embed | Adds a third-party dependency for viewing; offline use breaks; no local editing |