From 3d0156a7d8592d0e4c9f24274ce472cc06251267 Mon Sep 17 00:00:00 2001 From: haopengzhan Date: Sat, 15 Aug 2026 00:23:24 -0700 Subject: [PATCH] docs: initialize project documentation, AI guidelines, and logging standards --- .vibe/ai-guideline.md | 32 ++++++++++++++++++++ .vibe/skills/logging.md | 51 +++++++++++++++++++++++++++++++ README.md | 66 +++++++++++++++++++++++++++++++++++++++++ docs/architecture.md | 43 +++++++++++++++++++++++++++ docs/ui-guidelines.md | 38 ++++++++++++++++++++++++ 5 files changed, 230 insertions(+) create mode 100644 .vibe/ai-guideline.md create mode 100644 .vibe/skills/logging.md create mode 100644 README.md create mode 100644 docs/architecture.md create mode 100644 docs/ui-guidelines.md diff --git a/.vibe/ai-guideline.md b/.vibe/ai-guideline.md new file mode 100644 index 0000000..f14e77e --- /dev/null +++ b/.vibe/ai-guideline.md @@ -0,0 +1,32 @@ +# AI Development Guidelines for Hireme + +These guidelines provide context to AI assistants working on the `hireme` repository. Adhere to these principles to maintain the project's architecture and design philosophy. + +## 1. Single Binary & Zero Dependencies + +- **Goal:** The application must compile into a single Go binary. +- **Rule:** Do NOT introduce external dependencies that require separate build steps, node_modules, or static asset folders unless explicitly authorized. +- **Rule:** Use Go 1.22+ standard library features wherever possible (e.g., `net/http` `ServeMux`). + +## 2. UI Philosophy (HTMX + Tailwind) + +- **Rule:** Do NOT introduce React, Vue, or any heavy JS frameworks. +- **Rule:** All dynamic interactions must be handled via HTMX (`hx-get`, `hx-post`, `hx-target`). Endpoints should return HTML fragments, not JSON, for UI updates. +- **Rule:** CSS is handled via Tailwind CSS utility classes. Maintain the dark mode aesthetic using `bg-slate-*`, `text-slate-*`, and vibrant accents (`indigo`, `emerald`, `rose`). +- **Rule:** UI templates are stored as constant strings in Go files (`internal/ui/template_*.go`) and registered in `templates.go`. Do not create external `.html` files. + +## 3. Database Integrity + +- **Rule:** Use `go-sqlite3` and ensure `PRAGMA journal_mode=WAL;` is maintained. The application heavily relies on WAL mode to allow concurrent reads (from the UI) and writes (from background workers). +- **Rule:** Avoid long-running transactions that could lock the database. + +## 4. Structured Logging + +- **Rule:** Use `zap` structured logging exclusively. Do NOT use the standard library `log.Printf`. +- **Rule:** Use the `w` methods (`Infow`, `Debugw`, `Errorw`) to pass key-value pairs. + - **Correct:** `logger.Log.Infow("User created", "component", "API", "user_id", id)` + - **Incorrect:** `logger.Log.Infof("[API] User created: %d", id)` + +## 5. Background Workers + +- **Rule:** Long-running tasks (Crawling, LLM Analysis) must be executed asynchronously via the `internal/worker` pool. Do not block HTTP request handlers. Enqueue tasks in the SQLite `tasks` table instead. diff --git a/.vibe/skills/logging.md b/.vibe/skills/logging.md new file mode 100644 index 0000000..45100c8 --- /dev/null +++ b/.vibe/skills/logging.md @@ -0,0 +1,51 @@ +--- +name: Structured Logging with Zap +description: How to correctly use the zap structured logging library in this repository instead of standard log or string formatting. +--- + +# Structured Logging with Zap + +When adding logs to the `hireme` repository, **always** use the global `logger.Log` (which is a `zap.SugaredLogger`). + +Do **NOT** use `log.Printf` or `fmt.Printf`. +Do **NOT** use `logger.Log.Infof` to format strings with variables if those variables should be structured data. + +## Proper Usage (The `w` methods) + +Use the `w` variants of the log methods (`Infow`, `Debugw`, `Errorw`, `Warnw`). These methods take a message string as the first argument, followed by variadic key-value pairs. + +### Example: API Endpoints + +Always include a `"component", "API"` field. + +```go +// GOOD +logger.Log.Infow("Triggered endpoint", "component", "API", "endpoint", "/applications", "status", "success") + +// BAD - String interpolation hides the data from JSON parsers +logger.Log.Infof("[API] Triggered /applications with status %s", "success") +``` + +### Example: Background Workers + +Include the worker ID and task ID. + +```go +// GOOD +logger.Log.Errorw("Task processing failed", "component", "Worker", "worker_id", id, "task_id", task.ID, "error", err) +``` + +### Example: Database Operations + +```go +// GOOD +logger.Log.Debugw("Running query", "component", "DB", "query", "SELECT * FROM jobs") +``` + +## Summary of `w` Methods + +- `logger.Log.Debugw(msg string, keysAndValues ...interface{})` +- `logger.Log.Infow(msg string, keysAndValues ...interface{})` +- `logger.Log.Warnw(msg string, keysAndValues ...interface{})` +- `logger.Log.Errorw(msg string, keysAndValues ...interface{})` +- `logger.Log.Fatalw(msg string, keysAndValues ...interface{})` // Note: calls os.Exit(1) diff --git a/README.md b/README.md new file mode 100644 index 0000000..4706f98 --- /dev/null +++ b/README.md @@ -0,0 +1,66 @@ +# Hireme (GJCC) + +**Hireme (Google Job Command Center)** is a high-performance, single-binary job application and tracking command center written in Go. + +It completely automates the job search workflow by crawling job boards, analyzing job descriptions against your profile using Large Language Models (LLMs), and presenting a sleek, HTMX-powered UI to review, save, and track your applications. + +## Key Features + +- **Automated Crawling:** Background worker pools discover and fetch job listings from targets (e.g., Google Jobs). +- **LLM Job Analysis:** Integrates with LLMs (Mock, Gemini, Claude) to score jobs based on your qualifications, identify missing skills, and provide resume tailoring suggestions. +- **Smart Filtering:** Multi-stage filtering pipeline (Hard Keywords + Scoring Weights) configured via YAML to automatically reject unqualified jobs before expensive LLM calls. +- **Sleek UI:** A responsive, dark-mode dashboard built with Go Templates, HTMX, and Tailwind CSS. +- **Pipeline Management:** An interactive Apply Table to move jobs through your pipeline (Saved ▶ Applied ▶ Interview ▶ Offer). +- **Single Binary & SQLite:** Everything is packaged into a single Go binary using a local SQLite database (WAL mode enabled) for zero-dependency deployment. + +## Quick Start + +### Prerequisites + +- Go 1.26+ +- `make` + +### Installation + +1. **Clone the repository:** + + ```bash + git clone https://github.com/hireme/hireme.git + cd hireme + ``` + +2. **Configure Data & Filters:** + Copy the example configurations and adjust them: + - `data/config/targets.yaml`: Setup crawler targets. + - `data/config/filters.yaml`: Setup hard keywords and scoring weights. + +3. **Set Environment Variables:** + + ```bash + export LOG_LEVEL=debug + export GEMINI_API_KEY="your_api_key" # If using Gemini LLM + ``` + +4. **Build and Run:** + + ```bash + make clean + make run + ``` + +5. **Access the UI:** + Open your browser and navigate to [http://localhost:8080](http://localhost:8080). + +## Commands + +- `make build`: Builds the `hireme` binary into `build/`. +- `make run`: Builds and runs the binary. +- `make clean`: Removes the build binary and test databases. + +## Contributing + +Contributions are welcome! Please review the documentation in the `docs/` folder to understand the architecture and UI guidelines before submitting pull requests. + +## License + +MIT License. diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..6951c45 --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,43 @@ +# System Architecture + +Hireme is designed as a single-binary, local-first web application. It combines a high-performance backend, an embedded database, background job processing, and a lightweight frontend into a cohesive, easy-to-deploy system. + +## Components + +### 1. Database Layer (`internal/db`) + +- **Technology:** SQLite3 via `github.com/mattn/go-sqlite3`. +- **Mode:** WAL (Write-Ahead Logging) mode is enabled (`PRAGMA journal_mode=WAL;`) to support high concurrency between the HTTP server reads and background worker writes without "database is locked" errors. +- **Pattern:** Centralized query methods attached to a `DB` struct (`queries.go`). + +### 2. Worker Pool & Task Queue (`internal/worker`, `internal/db/tasks.go`) + +- **Technology:** Custom goroutine worker pool pulling from a `tasks` SQLite table. +- **Tasks:** + - `DISCOVER`: Initiates crawling on a target (e.g., Google Jobs search URL). + - `FETCH`: Fetches raw HTML for a specific job posting. + - `PROCESS`: Parses raw HTML, applies rule-based filtering (keywords, scoring), and enqueues for analysis if qualified. + - `ANALYZE`: Sends the parsed job to an LLM for final qualification scoring and tailoring tips. +- **Concurrency:** Managed via context cancellation and `atomic.Bool` flags for safe pausing and resuming. + +### 3. Filters & Rules (`internal/filter`, `data/config/filters.yaml`) + +- A pipeline pattern is used to quickly reject jobs before doing expensive LLM API calls. +- **Hard Keywords:** Immediate rejection if a keyword (e.g., "Clearance", "Staff") is found. +- **Scoring Weights:** Basic substring counting for required technologies (e.g., "Go", "Python"). If the raw score falls below a threshold, the job is rejected. + +### 4. Crawlers (`pkg/crawler`) + +- Currently implements Google Jobs (`pkg/crawler/google`). +- **Mechanism:** Parses embedded JSON (`AF_initDataCallback`) in the raw HTML response rather than fragile DOM traversal. This ensures stability against UI changes. + +### 5. UI Layer (`internal/ui`) + +- **Technology:** Standard Go HTTP server (`net/http`), Go Templates (`html/template`), HTMX, and Tailwind CSS. +- **Philosophy:** Server-Side Rendered (SSR) HTML fragments returned directly to HTMX for seamless, single-page application (SPA) like updates without heavy JS payloads. +- **Templates:** Statically compiled strings in `.go` files (`template_layout.go`, `template_jobs.go`) rather than external `.html` files to keep the binary fully self-contained. + +### 6. Logging (`internal/logger`) + +- **Technology:** `go.uber.org/zap` (Sugared Logger). +- **Pattern:** Structured logging using `w` methods (`Infow`, `Errorw`, `Debugw`) to allow for strongly-typed key-value pairs (`"component", "API"`) instead of string formatting. diff --git a/docs/ui-guidelines.md b/docs/ui-guidelines.md new file mode 100644 index 0000000..c720d0c --- /dev/null +++ b/docs/ui-guidelines.md @@ -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 `` 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 `` 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).