docs: initial scaffold design for Spine

2026-06-20 15:19:57 -04:00
commit 7612e20669
1 changed files with 145 additions and 0 deletions
@@ -0,0 +1,145 @@
+# Spine — initial scaffold
+
+A minimal working Emacs web server that serves templated HTML. This is the
+first concrete slice of [spine-spec.md](../spine-spec.md), resolving the open
+"glue language + web framework" decision: Emacs owns the HTTP socket and serves
+the UI directly.
+
+## Architecture decision
+
+**Emacs end-to-end.** No external web process, no `emacsclient` IPC for reads.
+The app is a single Emacs instance running `simple-httpd`. This keeps the build
+simple (one language, two packages) and is adequate for Spine's complexity level.
+
+## Packages
+
+| Package | Version | Source | Purpose |
+|---------|---------|--------|---------|
+| `simple-httpd` | MELPA latest | MELPA | HTTP server, `defservlet` routing |
+| `mustache` | MELPA latest | MELPA | Mustache template rendering |
+| `ht` | — | transitive via `mustache` | Hash table for template context |
+
+## Project structure
+
+```
+spine/
+├── spine.el              # entry point: bootstrap, server start, handlers
+├── templates/
+│   └── hello.mustache    # smoke-test template
+├── spine-spec.md         # design brief (existing)
+├── spine-mockup-a-agenda.html
+├── spine-mockup-b-journal.html
+└── README.md
+```
+
+- `spine.el` is the sole Elisp file for now. Split later when a seam earns it.
+- Templates live in `templates/` as `.mustache` files.
+- Mockups stay as reference artifacts; they are not served.
+
+## Package bootstrap
+
+`spine.el` uses `package.el` (built-in). On first run it installs missing
+packages from MELPA; subsequent starts skip the install step.
+
+```
+(require 'package)
+(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
+(package-initialize)
+(dolist (pkg '(simple-httpd mustache))
+  (unless (package-installed-p pkg)
+    (package-refresh-contents)
+    (package-install pkg)))
+```
+
+`package-refresh-contents` runs only when a package is missing — not on every
+start.
+
+## Server startup
+
+```
+(defvar spine-port 8080
+  "Port for the Spine HTTP server.")
+
+(defvar spine-template-dir
+  (expand-file-name "templates/" (file-name-directory load-file-name))
+  "Directory containing .mustache templates.")
+
+(setq httpd-port spine-port)
+(httpd-start)
+(message "Spine listening on http://localhost:%d" spine-port)
+```
+
+- Port defaults to 8080, overridable by setting `spine-port` before loading.
+- `spine-template-dir` resolves relative to `spine.el`'s directory so the app
+  works regardless of `default-directory`.
+
+## Template rendering
+
+A single helper wraps Mustache rendering:
+
+```
+(defun spine-render (name context)
+  "Render templates/NAME.mustache with CONTEXT (an ht hash table).
+Returns the rendered string."
+  (mustache-render
+   (with-temp-buffer
+     (insert-file-contents
+      (expand-file-name name spine-template-dir))
+     (buffer-string))
+   context))
+```
+
+- Reads the template file from disk on every request. No caching — correct and
+  simple; add caching if profiling shows a need.
+- `context` is an `ht` hash table whose keys map to `{{key}}` placeholders.
+
+## Hello World handler
+
+```
+(defservlet hello text/html ()
+  (insert (spine-render "hello.mustache"
+            (ht ("title"   "Spine")
+                ("message" "Hello from Emacs.")))))
+```
+
+`templates/hello.mustache`:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{title}}</title>
+</head>
+<body>
+  <h1>{{message}}</h1>
+</body>
+</html>
+```
+
+- Accessible at `http://localhost:8080/hello`.
+- The root `/` is unbound and will show `simple-httpd`'s default directory
+  listing — acceptable for a smoke test.
+
+## Invocation
+
+```bash
+emacs --quick --load spine.el
+```
+
+`--quick` (aliases: `-Q`) skips init files for a clean, repeatable start.
+
+## Acceptance
+
+- [ ] `emacs --quick --load spine.el` starts without errors.
+- [ ] Browsing `http://localhost:8080/hello` shows "Hello from Emacs."
+- [ ] Templates load relative to `spine.el`'s directory, not `default-directory`.
+- [ ] Second invocation skips package install (packages already present).
+
+## Out of scope
+
+- Book data, Org file integration, any handler beyond `/hello`.
+- Static file serving (CSS, JS, icons).
+- Emacs daemon mode, process management, systemd units.
+- Tests — the scaffold is small enough to smoke-test manually.