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,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.