# squidchemistry/interviewcoach architecture

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

- Interactive diagram: https://gitdiagram.com/squidchemistry/interviewcoach
- Repository: https://github.com/squidchemistry/interviewcoach

## Overview

AI Interview Coach is a full-stack practice platform: candidates authenticate, configure their profile and resume, select a question or round, conduct a streamed mock interview, and receive evidence-backed evaluation and progress guidance. The backend’s interview service coordinates sessions and code submissions; the state-machine engine, evaluation, streaming, AI, and code execution are distinct domain stages. The README documents additional product branches, including question discovery, spaced-repetition revision, billing, sharing, and administration. Some backend implementations were not sampled, so their internal call links are omitted or marked unverified.

Main entry points: [`backend/src/main/java/com/aicoach/interview/service/InterviewService.java`](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/InterviewService.java) (Session orchestration), [`backend/src/main/java/com/aicoach/interview/service/evaluation/EvaluationService.java`](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/evaluation/EvaluationService.java) (Rubric evaluation), [`frontend/src/features/interviews/room/useSessionRoom.ts`](https://github.com/squidchemistry/interviewcoach/blob/main/frontend/src/features/interviews/room/useSessionRoom.ts) (Interview room), [`backend/src/main/java/com/aicoach/question/service/QuestionService.java`](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/question/service/QuestionService.java) (Question bank)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and accounts"]
  node_auth["Authentication<br/>[AuthService.java]"]
  node_users["User and profile<br/>[UserService.java]"]
end

subgraph group_practice["Interview practice"]
  node_interview_ui["Interview room<br/>[useSessionRoom.ts]"]
  node_interview_service["Session orchestration"]
  node_engine["Session state engine"]
  node_rounds["Round and question planning<br/>[RoundFactory.java]"]
  node_session_store[("Interview session data")]
  node_stream["Live event stream"]
  node_executor["Code execution<br/>[CodeRunner.java]"]
end

subgraph group_content["Preparation content"]
  node_resume["Resume parsing<br/>[ResumeService.java]"]
  node_question_bank[("Question bank")]
  node_admin["Content administration"]
end

subgraph group_insights["Evaluation and progress"]
  node_evaluation["Rubric evaluation"]
  node_report["Interview reports"]
  node_progress["Progress and revision"]
end

subgraph group_platform["Platform services"]
  node_web["Web application<br/>[App.tsx]"]
  node_ai["AI providers and prompts<br/>[AiGateway.java]"]
  node_billing["Subscriptions and billing"]
  node_payments["Razorpay or mock payments"]
  node_audit[("Administrative audit<br/>[AuditService.java]")]
  node_database[("PostgreSQL and pgvector")]
end

node_candidate(("Candidate"))
node_judge0["Judge0 sandbox"]

node_candidate -->|"uses"| node_web
node_web -.->|"authenticates"| node_auth
node_auth -->|"creates users"| node_users
node_candidate -.->|"starts practice"| node_interview_ui
node_interview_ui -.->|"sends answers"| node_interview_service
node_interview_service -.->|"dispatches commands"| node_engine
node_interview_service -.->|"reads and writes"| node_session_store
node_interview_service -.->|"plans rounds"| node_rounds
node_interview_service -->|"runs submissions"| node_executor
node_executor -.->|"executes code"| node_judge0
node_interview_service -->|"publishes events"| node_stream
node_interview_ui -.->|"replays events"| node_stream
node_interview_service -.->|"evaluates session"| node_evaluation
node_evaluation -->|"requests assessment"| node_ai
node_resume -->|"extracts profile"| node_ai
node_candidate -.->|"uploads resume"| node_resume
node_candidate -.->|"browses questions"| node_question_bank
node_interview_service -.->|"selects questions"| node_question_bank
node_evaluation -.->|"provides feedback"| node_report
node_candidate -.->|"reviews progress"| node_progress
node_candidate -.->|"manages plan"| node_billing
node_billing -->|"charges subscription"| node_payments
node_admin -.->|"records changes"| node_audit
node_evaluation -.->|"stores evaluations"| node_database
node_question_bank -.->|"stores and searches"| node_database

click node_web "https://github.com/squidchemistry/interviewcoach/blob/main/frontend/src/app/App.tsx"
click node_auth "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/auth/service/AuthService.java"
click node_users "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/user/service/UserService.java"
click node_interview_ui "https://github.com/squidchemistry/interviewcoach/blob/main/frontend/src/features/interviews/room/useSessionRoom.ts"
click node_interview_service "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/InterviewService.java"
click node_engine "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/engine/InterviewEngine.java"
click node_rounds "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/round/RoundFactory.java"
click node_session_store "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/repository/SessionRepository.java"
click node_stream "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/stream/SessionStreamService.java"
click node_ai "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/ai/service/AiGateway.java"
click node_executor "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/execution/service/CodeRunner.java"
click node_resume "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/resume/service/ResumeService.java"
click node_question_bank "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/question/service/QuestionService.java"
click node_evaluation "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/evaluation/EvaluationService.java"
click node_report "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/web/PublicReportController.java"
click node_progress "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/progress/service/ProgressService.java"
click node_billing "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/billing/service/BillingService.java"
click node_payments "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/billing/service/PaymentProvider.java"
click node_admin "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/question/service/QuestionAdminService.java"
click node_audit "https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/audit/service/AuditService.java"

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_auth,node_users toneBlue
class node_interview_ui,node_interview_service,node_engine,node_rounds,node_session_store,node_stream,node_executor toneAmber
class node_resume,node_question_bank,node_admin toneMint
class node_evaluation,node_report,node_progress toneRose
class node_web,node_ai,node_billing,node_payments,node_audit,node_database,node_candidate,node_judge0 toneIndigo
```

## Components

### Identity and accounts

- [Authentication](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/auth/service/AuthService.java): `backend/src/main/java/com/aicoach/auth/service/AuthService.java`
- [User and profile](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/user/service/UserService.java): `backend/src/main/java/com/aicoach/user/service/UserService.java`

### Interview practice

- [Interview room](https://github.com/squidchemistry/interviewcoach/blob/main/frontend/src/features/interviews/room/useSessionRoom.ts): `frontend/src/features/interviews/room/useSessionRoom.ts`
- [Session orchestration](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/InterviewService.java): `backend/src/main/java/com/aicoach/interview/service/InterviewService.java`
- [Session state engine](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/engine/InterviewEngine.java): `backend/src/main/java/com/aicoach/interview/service/engine/InterviewEngine.java`
- [Round and question planning](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/round/RoundFactory.java): `backend/src/main/java/com/aicoach/interview/service/round/RoundFactory.java`
- [Interview session data](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/repository/SessionRepository.java): `backend/src/main/java/com/aicoach/interview/repository/SessionRepository.java`
- [Live event stream](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/stream/SessionStreamService.java): `backend/src/main/java/com/aicoach/interview/service/stream/SessionStreamService.java`
- [Code execution](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/execution/service/CodeRunner.java): `backend/src/main/java/com/aicoach/execution/service/CodeRunner.java`

### Preparation content

- [Resume parsing](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/resume/service/ResumeService.java): `backend/src/main/java/com/aicoach/resume/service/ResumeService.java`
- [Question bank](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/question/service/QuestionService.java): `backend/src/main/java/com/aicoach/question/service/QuestionService.java`
- [Content administration](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/question/service/QuestionAdminService.java): `backend/src/main/java/com/aicoach/question/service/QuestionAdminService.java`

### Evaluation and progress

- [Rubric evaluation](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/service/evaluation/EvaluationService.java): `backend/src/main/java/com/aicoach/interview/service/evaluation/EvaluationService.java`
- [Interview reports](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/interview/web/PublicReportController.java): `backend/src/main/java/com/aicoach/interview/web/PublicReportController.java`
- [Progress and revision](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/progress/service/ProgressService.java): `backend/src/main/java/com/aicoach/progress/service/ProgressService.java`

### Platform services

- [Web application](https://github.com/squidchemistry/interviewcoach/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [AI providers and prompts](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/ai/service/AiGateway.java): `backend/src/main/java/com/aicoach/ai/service/AiGateway.java`
- [Subscriptions and billing](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/billing/service/BillingService.java): `backend/src/main/java/com/aicoach/billing/service/BillingService.java`
- [Razorpay or mock payments](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/billing/service/PaymentProvider.java): `backend/src/main/java/com/aicoach/billing/service/PaymentProvider.java`
- [Administrative audit](https://github.com/squidchemistry/interviewcoach/blob/main/backend/src/main/java/com/aicoach/audit/service/AuditService.java): `backend/src/main/java/com/aicoach/audit/service/AuditService.java`
- **PostgreSQL and pgvector**

### Other components

- **Candidate**
- **Judge0 sandbox**

## Connections

- Candidate → Web application: uses
- Web application → Authentication: authenticates
- Authentication → User and profile: creates users (evidence: `backend/src/main/java/com/aicoach/auth/service/AuthService.java`)
- Candidate → Interview room: starts practice
- Interview room → Session orchestration: sends answers
- Session orchestration → Session state engine: dispatches commands (evidence: `backend/src/main/java/com/aicoach/interview/service/InterviewService.java`)
- Session orchestration → Interview session data: reads and writes (evidence: `backend/src/main/java/com/aicoach/interview/service/InterviewService.java`)
- Session orchestration → Round and question planning: plans rounds
- Session orchestration → Code execution: runs submissions (evidence: `backend/src/main/java/com/aicoach/interview/service/InterviewService.java`)
- Code execution → Judge0 sandbox: executes code
- Session orchestration → Live event stream: publishes events (evidence: `backend/src/main/java/com/aicoach/interview/service/InterviewService.java`)
- Interview room → Live event stream: replays events
- Session orchestration → Rubric evaluation: evaluates session
- Rubric evaluation → AI providers and prompts: requests assessment (evidence: `backend/src/main/java/com/aicoach/interview/service/evaluation/EvaluationService.java`)
- Resume parsing → AI providers and prompts: extracts profile (evidence: `backend/src/main/java/com/aicoach/resume/service/ResumeService.java`)
- Candidate → Resume parsing: uploads resume
- Candidate → Question bank: browses questions
- Session orchestration → Question bank: selects questions (evidence: `backend/src/main/java/com/aicoach/interview/service/InterviewService.java`)
- Rubric evaluation → Interview reports: provides feedback
- Candidate → Progress and revision: reviews progress
- Candidate → Subscriptions and billing: manages plan
- Subscriptions and billing → Razorpay or mock payments: charges subscription (evidence: `backend/src/main/java/com/aicoach/billing/service/BillingService.java`)
- Content administration → Administrative audit: records changes (evidence: `backend/src/main/java/com/aicoach/question/service/QuestionAdminService.java`)
- Rubric evaluation → PostgreSQL and pgvector: stores evaluations
- Question bank → PostgreSQL and pgvector: stores and searches