# ranxi2001/offerpilot architecture

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

- Interactive diagram: https://gitdiagram.com/ranxi2001/offerpilot
- Repository: https://github.com/ranxi2001/offerpilot

## Overview

OfferPilot is an AI interview-preparation product: users provide a resume and job description, receive matching or resume feedback, then practice interviews with evidence-based assessment and reports. The primary deployed flow is the Next.js interface and BFF calling the Go API, whose typed interview agents use an LLM, knowledge retrieval, and persistent interview state; speech services support recorded answers and spoken questions. The README documents additional capability branches beyond the sampled source. Those branches are represented at their documented subsystem paths; unsampled internal call details are not inferred.

Main entry points: [`backend/internal/httpapi/server.go`](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/httpapi/server.go) (HTTP API), [`backend/internal/interview/service.go`](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/interview/service.go) (Interview Service), [`web/src/app/api`](https://github.com/ranxi2001/offerpilot/tree/main/web/src/app/api) (Web BFF), [`backend/internal/harness/runtime.go`](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/harness/runtime.go) (Agent Harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Experience"]
  node_webui["Preparation UI<br/>[page.tsx]"]
  node_webapi["Web BFF"]
  node_webcomponents["Interview and Reports"]
end

subgraph group_api["Go API"]
  node_goapi["HTTP API<br/>[server.go]"]
end

subgraph group_interview["Interview Domain"]
  node_interviewservice["Interview Service<br/>[service.go]"]
  node_harness["Agent Harness<br/>[runtime.go]"]
  node_interviewstate[("Interview State")]
  node_knowledge["Knowledge Retrieval"]
  node_evals["Offline Evaluation<br/>[runner.go]"]
end

subgraph group_analysis["Material Analysis"]
  node_profile["Typed Profile<br/>[extractor.go]"]
  node_jobmatch["JD Matching<br/>[agent.go]"]
  node_resume["Resume Diagnosis<br/>[agent.go]"]
  node_crawler["JD Crawler<br/>[agent.go]"]
end

subgraph group_integrations["AI and Speech"]
  node_llm["LLM Gateway<br/>[client.go]"]
  node_speech["MiMo Speech<br/>[mimo.go]"]
end

node_candidate(("Candidate"))
node_llmprovider{{"LLM Provider"}}
node_mimo{{"MiMo Service"}}

node_candidate -->|"provides materials"| node_webui
node_webui -->|"submits requests"| node_webapi
node_webapi -->|"forwards requests"| node_goapi
node_goapi -->|"dispatches interview"| node_interviewservice
node_interviewservice -->|"runs agents"| node_harness
node_interviewservice -->|"retrieves evidence"| node_knowledge
node_interviewservice -->|"persists state"| node_interviewstate
node_harness -->|"requests generation"| node_llm
node_llm -->|"sends model requests"| node_llmprovider
node_goapi -->|"dispatches matching"| node_jobmatch
node_goapi -->|"dispatches diagnosis"| node_resume
node_goapi -->|"dispatches crawling"| node_crawler
node_goapi -->|"dispatches transcription and speech"| node_speech
node_speech -->|"sends audio requests"| node_mimo
node_goapi -->|"extracts typed evidence"| node_profile
node_goapi -->|"returns results"| node_webapi
node_webapi -->|"supplies results"| node_webcomponents
node_webcomponents -->|"shows feedback"| node_candidate
node_evals -.->|"evaluates behavior"| node_harness

click node_webui "https://github.com/ranxi2001/offerpilot/blob/main/web/src/app/page.tsx"
click node_webapi "https://github.com/ranxi2001/offerpilot/tree/main/web/src/app/api"
click node_goapi "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/httpapi/server.go"
click node_interviewservice "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/interview/service.go"
click node_harness "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/harness/runtime.go"
click node_interviewstate "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/interview/sqlite_persistence.go"
click node_profile "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/profile/extractor.go"
click node_jobmatch "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/jobmatch/agent.go"
click node_resume "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/resumediagnosis/agent.go"
click node_crawler "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/webcrawler/agent.go"
click node_knowledge "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/knowledge/interview_retriever.go"
click node_llm "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/llm/client.go"
click node_speech "https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/speech/mimo.go"
click node_webcomponents "https://github.com/ranxi2001/offerpilot/tree/main/web/src/components"
click node_evals "https://github.com/ranxi2001/offerpilot/blob/main/backend/evals/runner.go"

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_webui,node_webapi,node_webcomponents toneBlue
class node_goapi toneAmber
class node_interviewservice,node_harness,node_interviewstate,node_knowledge,node_evals toneMint
class node_profile,node_jobmatch,node_resume,node_crawler toneRose
class node_llm,node_speech,node_candidate,node_llmprovider,node_mimo toneIndigo
```

## Components

### Web Experience

- [Preparation UI](https://github.com/ranxi2001/offerpilot/blob/main/web/src/app/page.tsx): `web/src/app/page.tsx`
- [Web BFF](https://github.com/ranxi2001/offerpilot/tree/main/web/src/app/api): `web/src/app/api`
- [Interview and Reports](https://github.com/ranxi2001/offerpilot/tree/main/web/src/components): `web/src/components`

### Go API

- [HTTP API](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/httpapi/server.go): `backend/internal/httpapi/server.go`

### Interview Domain

- [Interview Service](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/interview/service.go): `backend/internal/interview/service.go`
- [Agent Harness](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/harness/runtime.go): `backend/internal/harness/runtime.go`
- [Interview State](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/interview/sqlite_persistence.go): `backend/internal/interview/sqlite_persistence.go`
- [Knowledge Retrieval](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/knowledge/interview_retriever.go): `backend/internal/knowledge/interview_retriever.go`
- [Offline Evaluation](https://github.com/ranxi2001/offerpilot/blob/main/backend/evals/runner.go): `backend/evals/runner.go`

### Material Analysis

- [Typed Profile](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/profile/extractor.go): `backend/internal/profile/extractor.go`
- [JD Matching](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/jobmatch/agent.go): `backend/internal/jobmatch/agent.go`
- [Resume Diagnosis](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/resumediagnosis/agent.go): `backend/internal/resumediagnosis/agent.go`
- [JD Crawler](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/webcrawler/agent.go): `backend/internal/webcrawler/agent.go`

### AI and Speech

- [LLM Gateway](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/llm/client.go): `backend/internal/llm/client.go`
- [MiMo Speech](https://github.com/ranxi2001/offerpilot/blob/main/backend/internal/speech/mimo.go): `backend/internal/speech/mimo.go`

### Other components

- **Candidate**
- **LLM Provider**
- **MiMo Service**

## Connections

- Candidate → Preparation UI: provides materials
- Preparation UI → Web BFF: submits requests
- Web BFF → HTTP API: forwards requests
- HTTP API → Interview Service: dispatches interview
- Interview Service → Agent Harness: runs agents
- Interview Service → Knowledge Retrieval: retrieves evidence
- Interview Service → Interview State: persists state
- Agent Harness → LLM Gateway: requests generation
- LLM Gateway → LLM Provider: sends model requests
- HTTP API → JD Matching: dispatches matching
- HTTP API → Resume Diagnosis: dispatches diagnosis
- HTTP API → JD Crawler: dispatches crawling
- HTTP API → MiMo Speech: dispatches transcription and speech
- MiMo Speech → MiMo Service: sends audio requests
- HTTP API → Typed Profile: extracts typed evidence
- HTTP API → Web BFF: returns results
- Web BFF → Interview and Reports: supplies results
- Interview and Reports → Candidate: shows feedback
- Offline Evaluation → Agent Harness: evaluates behavior