# varun-kambali/justhireme architecture

> Architecture diagram of the GitHub repository varun-kambali/justhireme, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/varun-kambali/justhireme
- Repository: https://github.com/varun-kambali/justhireme

## Overview

#### 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`.

Main entry points: [`backend/api/routers/discovery.py`](https://github.com/varun-kambali/justhireme/blob/main/backend/api/routers/discovery.py) (Domain routers), [`backend/ranking/scoring_engine.py`](https://github.com/varun-kambali/justhireme/blob/main/backend/ranking/scoring_engine.py) (Explainable scoring engine), [`backend/generation/service.py`](https://github.com/varun-kambali/justhireme/blob/main/backend/generation/service.py) (Material generation), [`backend/api/app.py`](https://github.com/varun-kambali/justhireme/blob/main/backend/api/app.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop application"]
  node_react_ui["React feature UI<br/>frontend<br/>[PipelineView.tsx]"]
  node_api_client["API client and WS hooks<br/>frontend boundary<br/>[client.ts]"]
  node_tauri_shell["Tauri shell<br/>desktop runtime<br/>[main.rs]"]
end

subgraph group_backend["Local backend"]
  node_fastapi_app["FastAPI application<br/>API boundary<br/>[app.py]"]
  node_api_routers["Domain routers<br/>API routes<br/>[discovery.py]"]
  node_scheduler_events["Scheduler and WebSockets<br/>runtime coordination<br/>[scheduler.py]"]
  node_profile_ingestion["Profile ingestion<br/>domain service<br/>[ingestor.py]"]
  node_discovery_service["Discovery service<br/>domain service<br/>[service.py]"]
  node_quality_gate["Normalization and quality gate<br/>pipeline stage<br/>[quality_gate.py]"]
  node_ranking_service["Fit ranking<br/>domain service<br/>[service.py]"]
  node_scoring_engine["Explainable scoring engine<br/>ranking core<br/>[scoring_engine.py]"]
  node_generation_service["Material generation<br/>domain service<br/>[service.py]"]
  node_llm_client["LLM provider client<br/>provider abstraction<br/>[client.py]"]
  node_automation_service["Experimental automation<br/>opt-in service<br/>[service.py]"]
end

subgraph group_data["Local data"]
  node_sqlite[("SQLite CRM and settings<br/>local database<br/>[connection.py]")]
  node_profile_graph[("Kuzu profile graph<br/>graph store<br/>[profile.py]")]
  node_vector_store[("LanceDB embeddings<br/>vector store<br/>[embeddings.py]")]
end

subgraph group_delivery["Packaging and release"]
  node_runtime_pack["First-run runtime pack<br/>dependency bundle"]
  node_release_pipeline["Release workflow<br/>CI/release<br/>[release.yml]"]
end

node_react_ui -->|"uses"| node_api_client
node_api_client -->|"loopback HTTP / WebSocket"| node_fastapi_app
node_tauri_shell -->|"launches sidecar"| node_fastapi_app
node_tauri_shell -->|"installs and uses"| node_runtime_pack
node_fastapi_app -->|"routes requests"| node_api_routers
node_fastapi_app -->|"coordinates"| node_scheduler_events
node_scheduler_events -->|"pushes events"| node_api_client
node_api_routers -->|"profile operations"| node_profile_ingestion
node_api_routers -->|"discovery operations"| node_discovery_service
node_api_routers -->|"ranking operations"| node_ranking_service
node_api_routers -->|"generation operations"| node_generation_service
node_api_routers -.->|"opt-in operations"| node_automation_service
node_profile_ingestion -->|"stores evidence"| node_profile_graph
node_profile_ingestion -->|"creates embeddings"| node_vector_store
node_discovery_service -->|"raw postings"| node_quality_gate
node_quality_gate -->|"persists CRM leads and reasons"| node_sqlite
node_ranking_service -->|"evaluates fit"| node_scoring_engine
node_scoring_engine -->|"uses leads and feedback"| node_sqlite
node_scoring_engine -->|"uses graph enrichment"| node_profile_graph
node_scoring_engine -.->|"uses semantic signals"| node_vector_store
node_ranking_service -.->|"optional evaluation"| node_llm_client
node_generation_service -->|"selects evidence"| node_profile_graph
node_generation_service -->|"uses templates and stores outputs"| node_sqlite
node_generation_service -->|"generates drafts"| node_llm_client
node_release_pipeline -->|"packages releases"| node_tauri_shell
node_release_pipeline -->|"versions runtime dependencies"| node_runtime_pack

click node_react_ui "https://github.com/varun-kambali/justhireme/blob/main/src/features/pipeline/PipelineView.tsx"
click node_api_client "https://github.com/varun-kambali/justhireme/blob/main/src/api/client.ts"
click node_tauri_shell "https://github.com/varun-kambali/justhireme/blob/main/src-tauri/src/main.rs"
click node_fastapi_app "https://github.com/varun-kambali/justhireme/blob/main/backend/api/app.py"
click node_api_routers "https://github.com/varun-kambali/justhireme/blob/main/backend/api/routers/discovery.py"
click node_scheduler_events "https://github.com/varun-kambali/justhireme/blob/main/backend/api/scheduler.py"
click node_profile_ingestion "https://github.com/varun-kambali/justhireme/blob/main/backend/profile/ingestor.py"
click node_discovery_service "https://github.com/varun-kambali/justhireme/blob/main/backend/discovery/service.py"
click node_quality_gate "https://github.com/varun-kambali/justhireme/blob/main/backend/discovery/quality_gate.py"
click node_ranking_service "https://github.com/varun-kambali/justhireme/blob/main/backend/ranking/service.py"
click node_scoring_engine "https://github.com/varun-kambali/justhireme/blob/main/backend/ranking/scoring_engine.py"
click node_generation_service "https://github.com/varun-kambali/justhireme/blob/main/backend/generation/service.py"
click node_llm_client "https://github.com/varun-kambali/justhireme/blob/main/backend/llm/client.py"
click node_automation_service "https://github.com/varun-kambali/justhireme/blob/main/backend/automation/service.py"
click node_sqlite "https://github.com/varun-kambali/justhireme/blob/main/backend/data/sqlite/connection.py"
click node_profile_graph "https://github.com/varun-kambali/justhireme/blob/main/backend/data/graph/profile.py"
click node_vector_store "https://github.com/varun-kambali/justhireme/blob/main/backend/data/vector/embeddings.py"
click node_runtime_pack "https://github.com/varun-kambali/justhireme/tree/main/src-tauri/resources/runtime-pack"
click node_release_pipeline "https://github.com/varun-kambali/justhireme/blob/main/.github/workflows/release.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_react_ui,node_api_client,node_tauri_shell toneBlue
class node_fastapi_app,node_api_routers,node_scheduler_events,node_profile_ingestion,node_discovery_service,node_quality_gate,node_ranking_service,node_scoring_engine,node_generation_service,node_llm_client,node_automation_service toneAmber
class node_sqlite,node_profile_graph,node_vector_store toneMint
class node_runtime_pack,node_release_pipeline toneRose
```

## Components

### Desktop application

- [React feature UI](https://github.com/varun-kambali/justhireme/blob/main/src/features/pipeline/PipelineView.tsx): frontend · Dashboard, profile, pipeline, graph, generation, and settings views. · `src/features/pipeline/PipelineView.tsx`
- [API client and WS hooks](https://github.com/varun-kambali/justhireme/blob/main/src/api/client.ts): frontend boundary · Connects the UI to the loopback API and backend events. · `src/api/client.ts`
- [Tauri shell](https://github.com/varun-kambali/justhireme/blob/main/src-tauri/src/main.rs): desktop runtime · Owns sidecar lifecycle and secure desktop integration. · `src-tauri/src/main.rs`

### Local backend

- [FastAPI application](https://github.com/varun-kambali/justhireme/blob/main/backend/api/app.py): API boundary · Centralizes routers, auth, limits, validation, scheduling, and WebSockets. · `backend/api/app.py`
- [Domain routers](https://github.com/varun-kambali/justhireme/blob/main/backend/api/routers/discovery.py): API routes · Profile, discovery, leads, ranking, generation, settings, automation, diagnostics, and events. · `backend/api/routers/discovery.py`
- [Scheduler and WebSockets](https://github.com/varun-kambali/justhireme/blob/main/backend/api/scheduler.py): runtime coordination · Schedules backend work and pushes activity/state to clients. · `backend/api/scheduler.py`
- [Profile ingestion](https://github.com/varun-kambali/justhireme/blob/main/backend/profile/ingestor.py): domain service · Parses and normalizes documents, GitHub, LinkedIn, and portfolio inputs. · `backend/profile/ingestor.py`
- [Discovery service](https://github.com/varun-kambali/justhireme/blob/main/backend/discovery/service.py): domain service · Runs extensible job-source adapters. · `backend/discovery/service.py`
- [Normalization and quality gate](https://github.com/varun-kambali/justhireme/blob/main/backend/discovery/quality_gate.py): pipeline stage · Normalizes postings and records deterministic acceptance or rejection reasoning. · `backend/discovery/quality_gate.py`
- [Fit ranking](https://github.com/varun-kambali/justhireme/blob/main/backend/ranking/service.py): domain service · Combines rubric, quality, enrichment, semantics, feedback, and optional LLM signals. · `backend/ranking/service.py`
- [Explainable scoring engine](https://github.com/varun-kambali/justhireme/blob/main/backend/ranking/scoring_engine.py): ranking core · Keeps deterministic criteria central while augmenting them with optional signals. · `backend/ranking/scoring_engine.py`
- [Material generation](https://github.com/varun-kambali/justhireme/blob/main/backend/generation/service.py): domain service · Selects evidence and creates tailored application materials. · `backend/generation/service.py`
- [LLM provider client](https://github.com/varun-kambali/justhireme/blob/main/backend/llm/client.py): provider abstraction · Abstracts hosted and local-compatible model endpoints. · `backend/llm/client.py`
- [Experimental automation](https://github.com/varun-kambali/justhireme/blob/main/backend/automation/service.py): opt-in service · Browser-driven scouting and apply workflows are isolated from the supported pipeline. · `backend/automation/service.py`

### Local data

- [SQLite CRM and settings](https://github.com/varun-kambali/justhireme/blob/main/backend/data/sqlite/connection.py): local database · Stores leads, settings, events, feedback, and resume templates. · `backend/data/sqlite/connection.py`
- [Kuzu profile graph](https://github.com/varun-kambali/justhireme/blob/main/backend/data/graph/profile.py): graph store · Stores candidate relationships and supporting evidence. · `backend/data/graph/profile.py`
- [LanceDB embeddings](https://github.com/varun-kambali/justhireme/blob/main/backend/data/vector/embeddings.py): vector store · Provides local semantic similarity. · `backend/data/vector/embeddings.py`

### Packaging and release

- [First-run runtime pack](https://github.com/varun-kambali/justhireme/tree/main/src-tauri/resources/runtime-pack): dependency bundle · Delivers Chromium, vector runtime, and ONNX embedding model. · `src-tauri/resources/runtime-pack`
- [Release workflow](https://github.com/varun-kambali/justhireme/blob/main/.github/workflows/release.yml): CI/release · Builds and publishes cross-platform desktop releases. · `.github/workflows/release.yml`

## Connections

- React feature UI → API client and WS hooks: uses
- API client and WS hooks → FastAPI application: loopback HTTP / WebSocket
- Tauri shell → FastAPI application: launches sidecar
- Tauri shell → First-run runtime pack: installs and uses
- FastAPI application → Domain routers: routes requests
- FastAPI application → Scheduler and WebSockets: coordinates
- Scheduler and WebSockets → API client and WS hooks: pushes events
- Domain routers → Profile ingestion: profile operations
- Domain routers → Discovery service: discovery operations
- Domain routers → Fit ranking: ranking operations
- Domain routers → Material generation: generation operations
- Domain routers → Experimental automation: opt-in operations
- Profile ingestion → Kuzu profile graph: stores evidence
- Profile ingestion → LanceDB embeddings: creates embeddings
- Discovery service → Normalization and quality gate: raw postings
- Normalization and quality gate → SQLite CRM and settings: persists CRM leads and reasons
- Fit ranking → Explainable scoring engine: evaluates fit
- Explainable scoring engine → SQLite CRM and settings: uses leads and feedback
- Explainable scoring engine → Kuzu profile graph: uses graph enrichment
- Explainable scoring engine → LanceDB embeddings: uses semantic signals
- Fit ranking → LLM provider client: optional evaluation
- Material generation → Kuzu profile graph: selects evidence
- Material generation → SQLite CRM and settings: uses templates and stores outputs
- Material generation → LLM provider client: generates drafts
- Release workflow → Tauri shell: packages releases
- Release workflow → First-run runtime pack: versions runtime dependencies