# msuryakumar4550/hirecraft-ai architecture

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

- Interactive diagram: https://gitdiagram.com/msuryakumar4550/hirecraft-ai
- Repository: https://github.com/msuryakumar4550/hirecraft-ai

## Overview

HireCraft AI is a career-preparation and placement-readiness platform. The candidate enters through the React application, uses resume/ATS analysis and practice or interview features, and receives evaluation, memory, and readiness feedback. The documented system assigns orchestration to Spring Boot, with specialized Python services and external execution/AI integrations. Source evidence is sampled unevenly, so undocumented backend-to-service connections are shown as unverified rather than asserted.

Main entry points: [`backend/src/main/java/com/hirecraft/backend/BackendApplication.java`](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/BackendApplication.java) (Core orchestrator), [`backend/src/main/java/com/hirecraft/backend/coding/Judge0AsyncExecutionService.java`](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/coding/Judge0AsyncExecutionService.java) (Coding arena), [`backend/src/main/java/com/hirecraft/backend/service/ResumeService.java`](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/ResumeService.java) (Resume analysis), [`frontend/src/App.tsx`](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/frontend/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Candidate experience"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_api["API client<br/>[apiClient.ts]"]
end

subgraph group_core["Spring Boot core"]
  node_backend["Core orchestrator"]
  node_submission[("Submission records")]
  node_memory["Candidate memory"]
  node_readiness["Readiness &amp; reports"]
end

subgraph group_prep["Preparation domains"]
  node_resume["Resume analysis<br/>[ResumeService.java]"]
  node_aptitude["Aptitude practice<br/>[main.py]"]
  node_questionbank["Question engine"]
  node_coding["Coding arena"]
  node_wrapper["Code wrappers"]
  node_interviews["Mock interviews"]
end

subgraph group_ai["AI services"]
  node_ats["ATS scoring<br/>[main.py]"]
  node_parser["Resume parsing<br/>[main.py]"]
  node_evaluation["Interview evaluation<br/>[app.py]"]
end

subgraph group_runtime["Runtime integrations"]
  node_judge["Judge0 engine"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_gemini["Gemini AI"]
  node_livekit["LiveKit"]
end

node_candidate(("Candidate"))

node_candidate -->|"uses"| node_webapp
node_webapp -.->|"requests data"| node_api
node_api -.->|"calls REST"| node_backend
node_backend -.->|"routes requests"| node_resume
node_resume -.->|"parses documents"| node_parser
node_resume -.->|"scores resume"| node_ats
node_backend -.->|"requests questions"| node_aptitude
node_backend -->|"serves questions"| node_questionbank
node_questionbank -->|"checks history"| node_submission
node_backend -.->|"handles submissions"| node_coding
node_coding -->|"wraps code"| node_wrapper
node_coding -.->|"executes tests"| node_judge
node_coding -->|"updates status"| node_submission
node_backend -.->|"manages sessions"| node_interviews
node_backend -.->|"submits answers"| node_evaluation
node_backend -.->|"tracks mastery"| node_memory
node_backend -.->|"builds readiness"| node_readiness
node_backend -.->|"stores data"| node_postgres
node_backend -.->|"caches state"| node_redis
node_backend -.->|"orchestrates AI"| node_gemini
node_backend -.->|"streams voice"| node_livekit

click node_webapp "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/frontend/src/services/apiClient.ts"
click node_backend "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/BackendApplication.java"
click node_resume "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/ResumeService.java"
click node_ats "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/hirecraft_ats_scorer/main.py"
click node_parser "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/resume-parser-service/main.py"
click node_aptitude "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/aptitude-service/main.py"
click node_questionbank "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/QuestionEngineService.java"
click node_coding "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/coding/Judge0AsyncExecutionService.java"
click node_wrapper "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/coding/SolutionWrapperService.java"
click node_submission "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/entity/CodingSubmission.java"
click node_interviews "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/VirtualInterviewService.java"
click node_evaluation "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/interview_evaluator_service/app.py"
click node_memory "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/AiMemoryService.java"
click node_readiness "https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/ReadinessService.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_webapp,node_api toneBlue
class node_backend,node_submission,node_memory,node_readiness toneAmber
class node_resume,node_aptitude,node_questionbank,node_coding,node_wrapper,node_interviews toneMint
class node_ats,node_parser,node_evaluation toneRose
class node_judge,node_postgres,node_redis,node_gemini,node_livekit,node_candidate toneIndigo
```

## Components

### Candidate experience

- [Web application](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [API client](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`

### Spring Boot core

- [Core orchestrator](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/BackendApplication.java): `backend/src/main/java/com/hirecraft/backend/BackendApplication.java`
- [Submission records](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/entity/CodingSubmission.java): `backend/src/main/java/com/hirecraft/backend/entity/CodingSubmission.java`
- [Candidate memory](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/AiMemoryService.java): `backend/src/main/java/com/hirecraft/backend/service/AiMemoryService.java`
- [Readiness & reports](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/ReadinessService.java): `backend/src/main/java/com/hirecraft/backend/service/ReadinessService.java`

### Preparation domains

- [Resume analysis](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/ResumeService.java): `backend/src/main/java/com/hirecraft/backend/service/ResumeService.java`
- [Aptitude practice](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/aptitude-service/main.py): `aptitude-service/main.py`
- [Question engine](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/QuestionEngineService.java): `backend/src/main/java/com/hirecraft/backend/service/QuestionEngineService.java`
- [Coding arena](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/coding/Judge0AsyncExecutionService.java): `backend/src/main/java/com/hirecraft/backend/coding/Judge0AsyncExecutionService.java`
- [Code wrappers](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/coding/SolutionWrapperService.java): `backend/src/main/java/com/hirecraft/backend/coding/SolutionWrapperService.java`
- [Mock interviews](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/backend/src/main/java/com/hirecraft/backend/service/VirtualInterviewService.java): `backend/src/main/java/com/hirecraft/backend/service/VirtualInterviewService.java`

### AI services

- [ATS scoring](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/hirecraft_ats_scorer/main.py): `hirecraft_ats_scorer/main.py`
- [Resume parsing](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/resume-parser-service/main.py): `resume-parser-service/main.py`
- [Interview evaluation](https://github.com/msuryakumar4550/hirecraft-ai/blob/main/interview_evaluator_service/app.py): `interview_evaluator_service/app.py`

### Runtime integrations

- **Judge0 engine**
- **PostgreSQL**
- **Redis**
- **Gemini AI**
- **LiveKit**

### Other components

- **Candidate**

## Connections

- Candidate → Web application: uses (evidence: `README.md`)
- Web application → API client: requests data
- API client → Core orchestrator: calls REST (evidence: `README.md`)
- Core orchestrator → Resume analysis: routes requests (evidence: `README.md`)
- Resume analysis → Resume parsing: parses documents (evidence: `README.md`)
- Resume analysis → ATS scoring: scores resume (evidence: `README.md`)
- Core orchestrator → Aptitude practice: requests questions (evidence: `README.md`)
- Core orchestrator → Question engine: serves questions (evidence: `backend/src/main/java/com/hirecraft/backend/service/QuestionEngineService.java`)
- Question engine → Submission records: checks history (evidence: `backend/src/main/java/com/hirecraft/backend/service/QuestionEngineService.java`)
- Core orchestrator → Coding arena: handles submissions
- Coding arena → Code wrappers: wraps code (evidence: `backend/src/main/java/com/hirecraft/backend/coding/Judge0AsyncExecutionService.java`)
- Coding arena → Judge0 engine: executes tests (evidence: `README.md`)
- Coding arena → Submission records: updates status (evidence: `backend/src/main/java/com/hirecraft/backend/coding/Judge0AsyncExecutionService.java`)
- Core orchestrator → Mock interviews: manages sessions
- Core orchestrator → Interview evaluation: submits answers (evidence: `README.md`)
- Core orchestrator → Candidate memory: tracks mastery (evidence: `README.md`)
- Core orchestrator → Readiness & reports: builds readiness (evidence: `README.md`)
- Core orchestrator → PostgreSQL: stores data (evidence: `README.md`)
- Core orchestrator → Redis: caches state (evidence: `README.md`)
- Core orchestrator → Gemini AI: orchestrates AI (evidence: `README.md`)
- Core orchestrator → LiveKit: streams voice (evidence: `README.md`)
