docs: initialize project documentation, AI guidelines, and logging standards

2026-08-15 00:31:20 -07:00
parent 150e3dfbd5
commit 3d0156a7d8
5 changed files with 230 additions and 0 deletions
@@ -0,0 +1,38 @@
+# UI Guidelines
+
+Hireme uses a modern, server-rendered UI stack that eliminates the need for heavy JavaScript frameworks (React, Vue, etc.) while maintaining a highly reactive, single-page application (SPA) feel.
+
+## Stack
+
+- **HTML / Go Templates:** Server-side rendering using `html/template`.
+- **HTMX (`hx-*`):** Used for all dynamic interactions, form submissions, and UI updates.
+- **Tailwind CSS:** Utility-first CSS framework for styling via CDN.
+
+## Architecture & Patterns
+
+### 1. Template Strings vs Files
+
+Templates are declared as `const` strings in `.go` files (e.g., `template_layout.go`, `template_jobs.go`) and collected in a `TemplateRegistry` in `templates.go`. This keeps the final build as a single executable without requiring external static asset folders.
+
+### 2. HTMX Updates
+
+Instead of returning JSON and re-rendering via JS, API endpoints return rendered HTML fragments.
+
+- **Example:** Clicking `+ Save` on a job POSTs to `/applications`. The handler updates the DB and returns the `template_jobs` HTML fragment, which HTMX swaps directly into the `#jobs-container` DOM element.
+
+### 3. Layout & Navigation (Tab Persistence)
+
+- The main UI uses a tabbed layout (Jobs, Apply, Targets).
+- Switching tabs is handled via lightweight Vanilla JS (`switchTab(id)`) which toggles `.hidden` classes.
+- Tab states are synced to the URL `#hash` so reloading the page preserves the active tab.
+
+### 4. Client-Side Filtering & Sorting
+
+- To prevent unnecessary server load for display formatting, table sorting and filtering (e.g., searching by keyword, or filtering by "Qualified") is done purely client-side using Vanilla JS.
+- Data attributes (`data-sort-val`, `data-qual`, `data-app`) are embedded in the `<tr>` elements during server-render to aid the JS filter logic.
+
+### 5. Design Aesthetics
+
+- **Dark Mode Default:** The UI uses Tailwind's `dark:` classes implicitly by having `class="dark"` on the root `<html>` tag.
+- **Micro-interactions:** Use hover states (`hover:bg-slate-800`), transitions (`transition-colors`), and subtle borders to create a premium feel.
+- **Indicators:** Use badges and color-coded text (Emerald for success/qualified, Rose for rejected/not qualified, Indigo for actions).