Init

README.md

@@ -0,0 +1,56 @@
+# Luxtools Web Application Scaffold
+
+Luxtools is a minimal-but-complete scaffold for a retro-styled web application built with the Nim programming language. It demonstrates how to deliver an interactive HTMX front end backed by a Nim HTTP server that compiles down to a single distributable binary.
+
+## Why these choices?
+
+- **Nim**: Nim's ahead-of-time compilation and small standard library make it ideal for producing a single self-contained binary. Its async HTTP primitives provide great performance with minimal boilerplate.
+- **HTMX**: HTMX keeps the frontend simple by embracing hypermedia. We can ship almost entirely server-rendered HTML snippets, allowing Nim to stay in control without a bulky SPA build step.
+- **TUI.CSS**: This lightweight CSS framework offers a retro terminal aesthetic with zero JavaScript and a tiny footprint—perfect for a nostalgic interface while remaining easy to customize.
+- **Single binary delivery**: HTML templates are embedded at compile time via `staticRead`, so the server ships with everything it needs. Drop the compiled executable onto any host with the correct architecture and you're ready to run.
+
+## Project layout
+
+```
+luxtools/
+├── bin/                  # Output directory for release binaries
+├── assets/              # Static files served directly by the HTTP handler
+├── src/
+│   └── luxtools.nim      # Main server entrypoint
+├── templates/
+│   └── index.html        # HTMX-powered landing page (compiled into the binary)
+├── tests/
+│   └── test_rendering.nim# Lightweight regression tests for HTML helpers
+├── luxtools.nimble       # Nimble manifest with build/test tasks
+└── README.md             # You're here
+```
+
+## Running the app
+
+```text
+nimble run
+```
+
+This command compiles the server (in debug mode) and starts it at http://127.0.0.1:5000. The console output confirms the address. Open the URL in a browser to see the TUI.CSS interface. The counter widget uses `hx-post` to mutate state on the server, and the clock panel uses `hx-get` with a timed trigger.
+
+## Building the single binary
+
+```text
+nimble build
+```
+
+A release-optimized executable is emitted to `bin/luxtools` (or `bin/luxtools.exe` on Windows). Because the HTML is embedded at compile time, shipping this one file is enough.
+
+## Testing
+
+```text
+nimble test
+```
+
+The test suite checks the generated HTMX markup to catch regressions in the HTML helpers without spinning up the HTTP server.
+
+## Next steps (optional)
+
+- Add persistence by wiring Nim's database libraries or a lightweight KV store.
+- Serve additional HTMX endpoints (e.g., todo lists, metrics dashboards).
+- Extend the styling by composing more TUI.CSS components or creating custom themes.