varun-kambali/justhireme

Purpose and Runtime Topology

JustHireMe is a local-first desktop job-intelligence workbench: ingest a candidate profile, discover and filter job leads, rank fit, and generate reviewed application materials. The production application is a Tauri desktop shell hosting a React UI and launching a local Python/FastAPI sidecar; it is not a cloud web app.

Entry points:

• Frontend: src/main.tsx, composed by src/App.tsx

• Desktop shell/sidecar lifecycle: src-tauri/src/main.rs, src-tauri/src/lib.rs

• Backend process/API: backend/main.py, backend/api/app.py

• Agent integration: backend/mcp_server.py

Desktop UI and Backend Boundary

React feature views present dashboard, profile ingestion, lead pipeline, graph visualization, generation/apply work, and settings. API client modules isolate HTTP calls, while WebSocket hooks support backend-pushed activity/state. Tauri owns local process launch, resource packaging, update behavior, and secure bridge details; UI talks to the loopback sidecar rather than directly to storage or external sources.

Paths: src/features/pipeline/PipelineView.tsx, src/api/client.ts, src/shared/hooks/useWS.ts, src-tauri/tauri.conf.json.

API Orchestration and Runtime Services

FastAPI routers form the backend application boundary for profile, ingestion, discovery, leads, ranking/generation, runtime status, settings, automation, diagnostics, and events. Authentication, rate limiting, startup validation, scheduling, and WebSockets are centralized API concerns. Domain services should remain behind these routers rather than accessed from UI code.

Paths: backend/api/app.py, backend/api/routers/discovery.py, backend/api/routers/generation.py, backend/api/scheduler.py, backend/api/websocket.py.

Profile Ingestion and Local Knowledge Model

Profile inputs—documents, GitHub, LinkedIn, and portfolio content—are parsed, normalized, and stored as structured candidate context. This feeds two local representations: a Kuzu profile graph for relationships/evidence and LanceDB embeddings for semantic similarity. These stores are domain infrastructure consumed by ranking and generation, not frontend-owned state.

Paths: backend/profile/service.py, backend/profile/ingestor.py, backend/data/graph/profile.py, backend/data/vector/embeddings.py.

Discovery-to-CRM Pipeline

Discovery service executes source adapters (ATS, feeds, communities, web/custom sources), normalizes raw postings, then applies a deterministic quality gate before persistence. Accepted leads become the local CRM/pipeline; rejected or degraded leads retain explainable reasoning where surfaced. Source adapter implementations are the intended extensibility boundary for new job sources.

Paths: backend/discovery/service.py, backend/discovery/normalizer.py, backend/discovery/quality_gate.py, backend/discovery/sources/ats.py, backend/data/sqlite/leads.py.

Fit Ranking and Feedback Loop

Ranking combines deterministic criteria—role alignment, stack evidence, seniority, logistics, learning curve—with lead quality, graph enrichment, optional vector semantics, feedback learning, and optional LLM evaluation. The scoring engine/evaluator is the central explainability boundary: semantic or LLM signals augment rather than replace the rubric.

Paths: backend/ranking/service.py, backend/ranking/scoring_engine.py, backend/ranking/evaluator.py, backend/ranking/graph_enrichment.py, backend/ranking/feedback_ranker.py.

Generation, External Models, and Experimental Automation

Generation selects profile evidence and produces tailored resumes, letters, outreach drafts, keyword coverage, and PDFs. LLM access is provider-abstracted and supports Anthropic, Gemini, Groq, Ollama, and OpenAI-compatible endpoints; local embeddings can operate without keys. Browser-driven scouting/apply automation is explicitly opt-in experimental functionality, separated from the supported pipeline.

Paths: backend/generation/service.py, backend/generation/generator.py, backend/generation/pdf_renderer.py, backend/llm/client.py, backend/automation/service.py.

Persistence and Delivery Infrastructure

SQLite stores local CRM, settings, events, feedback, and resume templates; Kuzu and LanceDB hold graph/vector data. Heavy dependencies—Chromium, vector runtime, ONNX embedding model—are delivered as a versioned first-run runtime pack rather than fully embedded in installers. Tauri packages the cross-platform desktop application and GitHub Actions handles CI/releases.

Paths: backend/data/sqlite/connection.py, backend/data/graph/connection.py, backend/data/vector/runtime.py, src-tauri/resources/runtime-pack, .github/workflows/release.yml.