Candidate Creation + Resume Upload + Resume Parsing

Upload resume to object storage, optionally parse fields for the form, then create the candidate record.

Sequence

sequenceDiagram
  autonumber
  participant Web as Web client
  participant API as Hono API
  participant Files as files.service
  participant Resume as resume.service
  participant LLM as platform/llm
  participant S3 as S3
  participant Cand as candidate.service
  participant Mongo as MongoDB

  Web->>API: POST /v1/files/resume-upload-url
  API->>Files: requestResumeUploadUrl
  Files-->>Web: presigned PUT url + resumeKey
  Web->>S3: PUT resume bytes

  Web->>API: POST /v1/files/resume-parse
  API->>Files: parseUploadedResume
  Files->>S3: getResumeObject
  Files->>Resume: extractResumeText
  Files->>Resume: parseResumeFields
  Resume->>LLM: extractStructured
  Files-->>Web: suggested fields (no DB)

  Web->>API: POST /v1/candidates
  API->>Cand: createCandidate
  Cand->>S3: moveResume to permanent key
  Cand->>Resume: extractResumeText (persist text)
  Cand->>Mongo: insert Candidate
  Cand-->>Web: 201 candidate (no resume.text)

Steps

1. Client requests a presigned URL and uploads the resume directly to storage.
2. Optional parse step extracts text and suggests form fields without writing to the database.
3. Create candidate checks org-unique email and moves the resume to a permanent key.
4. Resume text is stored for scheduling; API responses omit raw resume text.