# phanvyvan/resume-ai architecture

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

- Interactive diagram: https://gitdiagram.com/phanvyvan/resume-ai
- Repository: https://github.com/phanvyvan/resume-ai

## Overview

##### Project Type and Purpose
- Full-stack web application for resume analysis, job-description matching, and mock interviews.
- Frontend: React + TypeScript + Vite; Backend: Java Spring Boot; External AI: Google Gemini.
- Users upload CVs or paste text, get AI-driven insights and interview questions.

##### File Structure and Architectural Patterns
- Top level: two separate modules—`frontend/` and `backend/`—deployed independently.
- Frontend follows a component-based structure (pages, UI components, hooks, services).
- Backend uses a classic Spring Boot layered MVC:
- Controllers (`controller/`) expose REST endpoints under `/api/resume/*`.
- Services (`service/`) implement business logic: file parsing, AI calls, question generation.
- Models/DTOs (`model/`, `dto/`) represent domain data and payloads.
- Config (`config/`) holds Web CORS and other settings.

##### Key Components to Illustrate
- Frontend
- UI layer: Pages (`Upload`, `Evaluation`, `MockInterview`, etc.)
- Component library: Shadcn/UI + Tailwind
- API client: `services/geminiApi.ts` → points to `http://localhost:8080/api`
- Backend
- REST API Gateway (Spring MVC)
- DocumentParserService (uses Apache POI/PDFBox)
- GeminiClient (wraps Google Gemini AI calls)
- MockInterviewService (generates Q&A based on CV/JD)
- JobMatchService (computes match score via Gemini)
- External Services
- Google Gemini AI (model: `gemini-2.0-flash`)
- Data Flow
1. User uploads file / submits text → Frontend calls `/api/resume/upload` or `/api/resume/analyze-text`.
2. Backend DocumentParserService extracts text.
3. GeminiClient sends text to Gemini AI.
4. AI responses processed into DTOs (ResumeAnalysisDTO, GradingResultDTO, InterviewQuestionDTO).
5. Frontend displays results or mock interview UI (timer, recording).

##### Relationships & Interactions
[Browser/React App] → [Spring Boot API] → [Gemini AI] → back to API → [React App]
- CORS boundary between frontend (port 5173/8081) and backend (port 8080).

##### Architectural Patterns & Principles
- Layered Architecture on the server (Controller → Service → Model/DTO).
- Component-based, mobile-first design on the client.
- Single-page application (SPA) with client-side routing (React Router).
- Clean separation of concerns: parsing, AI integration, presentation.

##### Essential Elements
- Clear component boundaries (Frontend vs. Backend vs. External).
- Inline notes on key frameworks (React, Spring Boot, Apache POI, PDFBox, Gemini AI).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (React + TypeScript)" 
        direction TB
        BR["Browser/SPA"]:::frontend
        UP["Upload Page"]:::frontend
        EV["Evaluation Page"]:::frontend
        MI["MockInterview Page"]:::frontend
        FU["FileUpload Component"]:::frontend
        IQ["InterviewQuestion Component"]:::frontend
        API["geminiApi.ts (API Client)"]:::frontend
        SR["useSpeechRecognition Hook"]:::frontend
        UI["UI Library (Shadcn/UI + Tailwind)"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend (Spring Boot)" 
        direction TB
        APP["ResumeAiApplication"]:::backend
        WC["WebConfig (CORS)"]:::backend
        RC["ResumeController"]:::backend
        MIC["MockInterviewController"]:::backend
        DP["DocumentParserService<br/>(PDF, DOCX via Apache POI/PDFBox)"]:::backend
        JMS["JobMatchService"]:::backend
        MIS["MockInterviewService"]:::backend
        GC["GeminiClient"]:::backend
        DTO["DTOs<br/>(ResumeAnalysisDTO,<br/>InterviewQuestionDTO,<br/>GradingResultDTO)"]:::backend
        MDL["Models<br/>(InterviewQuestion,<br/>JobMatchResult,<br/>ResumeData)"]:::backend
    end

    %% External AI
    subgraph "External Services"
        direction TB
        GEM["Google Gemini AI<br/>(gemini-2.0-flash)"]:::external
    end

    %% Data Flows
    BR -->|POST /api/resume/upload| RC
    BR -->|POST /api/resume/analyze-text| RC
    BR -->|POST /api/resume/mock-interview| MIC

    RC -->|"parse file/text"| DP
    DP -->|"extracted text"| RC

    RC -->|"job match request"| JMS
    JMS -->|"AI call"| GC

    MIC -->|"generate questions"| MIS
    MIS -->|"AI call"| GC

    GC -->|HTTP/REST| GEM
    GEM -->|response| GC

    GC -->|AI result DTOs| RC
    RC -->|JSON response| BR
    MIS -->|questions DTOs| RC

    %% Click Events - Frontend
    click UP "https://github.com/phanvyvan/resume-ai/blob/master/frontend/src/pages/Upload.tsx"
    click EV "https://github.com/phanvyvan/resume-ai/blob/master/frontend/src/pages/Evaluation.tsx"
    click MI "https://github.com/phanvyvan/resume-ai/blob/master/frontend/src/pages/MockInterview.tsx"
    click FU "https://github.com/phanvyvan/resume-ai/blob/master/frontend/src/components/FileUpload.tsx"
    click IQ "https://github.com/phanvyvan/resume-ai/blob/master/frontend/src/components/InterviewQuestion.tsx"
    click API "https://github.com/phanvyvan/resume-ai/blob/master/frontend/src/services/geminiApi.ts"
    click SR "https://github.com/phanvyvan/resume-ai/blob/master/frontend/src/hooks/useSpeechRecognition.ts"
    click UI "https://github.com/phanvyvan/resume-ai/tree/master/frontend/src/components/ui/"

    %% Click Events - Backend
    click RC "https://github.com/phanvyvan/resume-ai/blob/master/backend/src/main/java/com/resumeai/controller/ResumeController.java"
    click MIC "https://github.com/phanvyvan/resume-ai/blob/master/backend/src/main/java/com/resumeai/controller/MockInterviewController.java"
    click DP "https://github.com/phanvyvan/resume-ai/blob/master/backend/src/main/java/com/resumeai/service/DocumentParserService.java"
    click GC "https://github.com/phanvyvan/resume-ai/blob/master/backend/src/main/java/com/resumeai/service/GeminiClient.java"
    click MIS "https://github.com/phanvyvan/resume-ai/blob/master/backend/src/main/java/com/resumeai/service/MockInterviewService.java"
    click WC "https://github.com/phanvyvan/resume-ai/blob/master/backend/src/main/java/com/resumeai/config/WebConfig.java"
    click DTO "https://github.com/phanvyvan/resume-ai/tree/master/backend/src/main/java/com/resumeai/dto/"
    click MDL "https://github.com/phanvyvan/resume-ai/tree/master/backend/src/main/java/com/resumeai/model/"
    click APP "https://github.com/phanvyvan/resume-ai/blob/master/backend/src/main/java/com/resumeai/ResumeAiApplication.java"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px;
    classDef backend fill:#DFFFD0,stroke:#22863a,stroke-width:1px;
    classDef external fill:#FFE0B2,stroke:#d97706,stroke-width:1px;
```
