Initial commit

docs/architecture/deployment.md

@@ -0,0 +1,94 @@
+# Deployment
+
+A decision record comparing the two hosting paths under consideration: a plain web host, or packaging
+the server as a StartOS service. **No packaging work is done here** — this exists so the choice can be
+made deliberately, and so the architecture does not accidentally foreclose either option.
+
+Target remains **small self-hosted** scale.
+
+---
+
+## 1. What the server needs, either way
+
+The requirements are modest, which is what makes both paths viable:
+
+| Need | Why |
+| --- | --- |
+| One long-running process | Active games are held in memory ([`overview.md`](overview.md)) |
+| HTTP + WebSocket on one port | Lobby over HTTP, game stream over WebSocket ([`protocol.md`](protocol.md)) |
+| A writable data directory | The append-only event log ([`lobby-and-sessions.md`](lobby-and-sessions.md)) |
+| Static asset serving | The browser client |
+| No outbound network access | The game talks to nobody |
+| No scheduled work | Nothing in the rules is real-time ([`overview.md`](overview.md)) |
+
+No database server, no message broker, no cache, no cron. SQLite or flat files cover persistence.
+That single-process, single-port, one-volume shape is the least demanding thing either platform has
+to host.
+
+---
+
+## 2. Plain web host
+
+**What it takes:** a small VM or container host, a reverse proxy terminating TLS, a process manager,
+and a backup of the data directory.
+
+**Advantages.** Anyone with a link can join, which matters for a game whose discovery mechanism is
+"read a code aloud to your friends." Deployment is unremarkable and every stack has good support for
+it.
+
+**Costs.** You own TLS certificates, updates, backups, and uptime. And a public URL means the server
+is exposed to the open internet, which raises questions the game does not otherwise have — abuse of
+game creation, resource exhaustion from unbounded lobbies, and the need for at least basic rate
+limiting.
+
+---
+
+## 3. StartOS service
+
+**What it takes:** packaging the server as an `.s9pk`. The workspace guide is on disk at
+`start-technologies/projects/start-sdk/docs/src/` — `recipe-basic-service.md` for the overall shape,
+`interfaces.md` for how the UI is exposed, `recipe-health-checks.md` for readiness, and
+`recipe-backups.md` for the data directory. Start with `recipes.md`, which is the intent index.
+
+**Advantages.** Installation, updates, TLS and backups are the platform's job rather than yours. The
+service declares what it exposes; the *user* decides where it is reachable from. For a friends-and-
+family game that fits well — the person running it already controls who gets the address.
+
+**Costs.** Players must reach the host, which is a real constraint for a browser game: everyone needs
+network access to that StartOS box. How they get it is the user's configuration decision, not
+something the application chooses or should claim.
+
+**One thing the architecture must respect.** A packaged service should not assume it is reachable at
+a fixed, publicly-routable URL. Anything that bakes an origin into the client — absolute WebSocket
+URLs, hard-coded hostnames in links, CORS allow-lists pinned to one domain — will break. Serve the
+client from the same origin as the API and use relative URLs throughout. This costs nothing on a
+plain web host and is required on StartOS, so it should simply be the rule.
+
+---
+
+## 4. Recommendation
+
+**Build for both; decide later.** The requirements in §1 are satisfied identically by either path, and
+the only architectural constraint that differs is the same-origin/relative-URL rule in §3 — which is
+good practice regardless.
+
+Concretely, do this from the start:
+
+1. **Single process, single port**, serving both the client and the API.
+2. **Relative URLs everywhere** in the client. No baked-in origin, no hard-coded hostname.
+3. **All state under one configurable data directory**, path supplied by environment variable.
+4. **No assumption of public reachability** anywhere in the code.
+5. **Bind address and port configurable** by environment variable.
+
+That set keeps both doors open at no cost. The decision only needs making when there is something
+worth deploying — and by then it will be an easier call, because you will know whether the people
+playing it are on your network or scattered.
+
+---
+
+## 5. Explicitly not decided here
+
+- The stack. Still open; nothing above depends on it.
+- Whether to publish to a StartOS registry (`publishing.md` in the guide) — irrelevant until the game
+  runs.
+- Domain names, TLS specifics, or backup schedules for the plain-host path.