dm / commit
docs: explain single-file architecture decision and Vite+TS upgrade path
README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 863befc..fa03744 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,12 @@ Requires Node.js. No build step — the entire app is a single `public/index.htm | Analytics | `metadata.user_id` in each API request carries `p_<playerId>:g_<gameId>` for Anthropic Console | | Deployment | GitLab Pages — push to `main`, CI deploys `public/` automatically | +### Why a single file? + +`public/index.html` is currently ~3,500 lines of vanilla JS — no build step, no bundler, no TypeScript. This is intentional. The constraint keeps the CI pipeline trivial (push `public/` → GitLab Pages deploys it) and makes the project easy to fork and self-host without a Node.js toolchain beyond the dev server. + +The tradeoffs are real — no type safety, no module splitting, global state everywhere — but acceptable for a project of this size and pace. If the file grows significantly or type errors become a recurring problem, the natural upgrade path is **Vite + TypeScript**: split `index.html` into modules, add a `vite.config.ts`, update the CI `script:` step to run `vite build`, and point GitLab Pages at `dist/` instead of `public/`. That migration is well-understood and can be done incrementally. + ## Reporting issues Use the **🐛 Report** button in the top bar — it collects debug info automatically. Or open an issue directly at [gitlab.com/PavelSafronov/dm/-/issues](https://gitlab.com/PavelSafronov/dm/-/issues).