Sophia — technical system overview

Standalone AI interviews: Position → Candidate → Interview → scored Report, paid with prepaid credits. Shared packages also support CleverHire. Executive overview · Backend architecture

flowchart LR
  subgraph Users
    Recruiter[Recruiter / Admin]
    Candidate[Candidate]
  end

  subgraph Sophia["Sophia (this repo)"]
    Web[Web SPA<br/>Cloudflare Pages]
    API[HTTP API<br/>Hono on Fargate]
    Fn[Lambda workers<br/>SQS consumers]
  end

  subgraph Data
    Mongo[(MongoDB)]
    S3[(S3 resumes)]
    Q1[Interview completed queue]
    Q2[Report generate queue]
  end

  subgraph External
    Firebase[Firebase Auth]
    Stripe[Stripe]
    Daily[Daily.co]
    OpenAI[OpenAI]
    Bot[Interview bot service]
  end

  Recruiter --> Web
  Candidate --> Web
  Web --> API
  API --> Firebase
  API --> Mongo
  API --> S3
  API --> Stripe
  API --> Daily
  API --> Q1
  API --> Bot
  Bot --> API
  Candidate --> Daily
  Q1 --> Fn
  Fn --> Mongo
  Fn --> Q2
  Q2 --> Fn
  Fn --> OpenAI
  Fn --> S3

Major systems

• Web app (apps/web) — Recruiter UI and candidate join; React + Vite on Cloudflare Pages.
• API (apps/api) — Hono on Fargate: auth, hiring, billing, bot control, presigned files.
• MongoDB / S3 — Tenant-scoped data; private resumes via presigned PUT.
• Async workers (apps/functions) — SQS Lambdas for settlement and report generation.
• Interview bot — External live AI; API is the control plane.
• Integrations — Firebase auth, Stripe checkout/webhooks, Daily.co rooms, OpenAI (+ optional Gemini for parsing).

Typical end-to-end flow

1. Recruiter signs up or in; API validates Firebase token and persists user/org in MongoDB.
2. Create positions and candidates; optional resume upload to S3 and field parsing.
3. Schedule interview — invitation, join link, credit reserve.
4. Candidate opens join link, password, consent; receives Daily room and bot session.
5. Bot drives lifecycle via internal auth; completion message goes to SQS.
6. Lambda settles credits, enqueues report generation; second Lambda writes report; recruiter reads via API.

Backlog items (email, sweepers, proctoring UI, ops console) are tracked in Remaining work.

Request IDs run browser → API → SQS; /health is ok or degraded when MongoDB is down.