freehire AGENTS.md

AGENTS.md

Guidance for AI agents working in this repository.

Working principles

• No overengineering, and no MVP shortcuts. Hold the middle path: don't build infrastructure before there's a concrete need (note the seam for later instead), and don't ship quick-and-dirty or "for now" hacks. Build each feature correctly and idiomatically — neither gold-plated nor a placeholder.
• MVP stage — keep the architecture fluid. The current structure is not load-bearing legacy. When a new feature doesn't fit cleanly, prefer reshaping the affected part over bolting on an awkward special case.
• Surgical changes. Clean up what your change orphaned; leave pre-existing dead code alone. Prefer a library's intended API over a clever shim.
• English only. All code, comments, identifiers, docs, and commits.

What this is

freehire (freehire.me) is an open-source IT job aggregator. Many source parsers feed a pipeline that normalizes jobs into one schema, deduplicates them, and enriches them with AI; served over an HTTP API with rich filters, consumed by a SvelteKit app under web/.

Stack: Go + Fiber v2, PostgreSQL, sqlc, Meilisearch, Docker Compose, langchaingo.

Layout

internal/<block>/<pkg>/ — every package sits in exactly one of eleven blocks, and the blocks form eight layers. A block may import only blocks strictly below it; two blocks sharing a layer may not see each other in either direction. The substantial packages carry their own AGENTS.md (see the table below), and each block carries one saying what it is and what it may reach for.

8. api           handlers, middleware, realtime, OG images
7. engage        notifications, digests, onboarding, referrals
   ingest        source adapters, crawl pipeline, link import, manual intake
6. application   tracking, stages, the event ledger, mail and calendar
   search        Meili topology, the drain, saved searches, intent
5. job           the posting: identity, facets, wire shape, dedup, ghost signal
4. candidate     CV, structured extraction, experience bank, PII, matching
3. ai            enrichment, embeddings, assistant, speech, plan limits
   identity      accounts, auth, profile
2. dict          the facet dictionaries and normalisation under them
1. platform      db, worker plumbing, outbox, cache, HTTP and LLM transport