hireme/docs/architecture.md

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.