# qaimmehdi/prepza architecture

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

- Interactive diagram: https://gitdiagram.com/qaimmehdi/prepza
- Repository: https://github.com/qaimmehdi/prepza

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“PREPZA”) for AI-powered mock interviews (technical & HR), voice/text interaction, real-time feedback, and performance tracking.
- Frontend: React + TypeScript + Tailwind CSS + Shadcn/ui + Web Speech API.
- Backend: Spring Boot (Java 17) REST API with Spring Security, JWT auth, Spring Data JPA, MySQL.
- AI integration: Google Gemini API for question generation and feedback.

##### File Structure Analysis
- Top‐level build/config: package.json, pom.xml, vite.config.ts, tsconfig.json, tailwind.config.ts.
- Frontend source (src/):
- Pages (src/pages/… .tsx) – React Router views (Index, InterviewPage, Login, Signup, etc.)
- Components (src/components/…): UI building blocks (Navbar, Footer, AuthContext, interview widgets, shadcn/ui primitives).
- Hooks (src/hooks/…): Custom React hooks for mobile detection, interview session logic, toasts.
- lib/utils.ts: shared utilities.
- firebase.ts: Firebase client config (if used).
- Backend source (src/main/java/com/yourcompany/interviewplatform/…):
- config: AuditingConfig, SecurityConfig, WebConfig.
- controller: AuthController, SessionController (REST endpoints).
- service: AuthService, SessionService (business logic, interacts with AIService).
- ai: AIService (calls Google Gemini).
- repository: Spring Data JPA repositories for User, InterviewSession, QuestionAnswer.
- model/dto: domain entities & request/response objects.
- security: JwtTokenProvider.
- Resources: application.properties/yml for DB, JWT, Gemini.
- target/: compiled backend artifacts.
- test-session-api.html, test-speech.html: demo/test pages for API and speech.

##### Key README Insights
- Emphasizes JWT-based auth, transcript & TTS, two interview modes, session persistence, AI prompt engineering.
- Lists major technologies and features, clarifies external dependencies (MySQL, Gemini API).

a. Main Components
- Frontend SPA (React)
– UI Layer: Pages & Components
– State Management: AuthContext, custom hooks
– Voice Engine: Web Speech API (Speech-to-Text, Text-to-Speech)
- Backend REST API (Spring Boot)
– AuthController (login/signup, JWT issuance)
– SessionController (start/end session, answer submission)
– AIService (calls Gemini API)
– Services & Repositories
- Database (MySQL via Spring Data JPA)
- External Services
– Google Gemini API (AI question/feedback)
– (Optional) Firebase (if used for analytics/auth)
b. Relationships & Data Flows
1. User interacts with React UI (voice/text).
2. UI calls AuthController endpoints → JWT token.
3. UI stores JWT, invokes SessionController with JWT in Authorization header.
4. SessionController → SessionService → AIService calls Gemini API → returns questions/feedback.
5. SessionService persists InterviewSession and QuestionAnswer via repositories.
6. UI displays AI responses & real-time feedback; persists session progress.
c. Architectural Patterns
- Layered architecture for backend (Controller → Service → Repository).
- Component-based UI architecture in frontend.
- Context & custom hooks for state management.
- JWT stateless authentication.
- API integration with external AI service.
d. Technology Highlights
- React + TypeScript + Tailwind + Shadcn/ui
- Web Speech API for voice
- Spring Boot + Security + Data JPA + JWT
- MySQL persistence
- Google Gemini API for NLP tasks

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Frontend
  subgraph "Frontend SPA" 
    direction TB
    subgraph "UI Layer (Pages & Components)"
      direction TB
      Index["Index.tsx"]:::frontend
      InterviewPage["InterviewPage.tsx"]:::frontend
      Login["Login.tsx"]:::frontend
      Signup["Signup.tsx"]:::frontend
      LoginSuccess["LoginSuccess.tsx"]:::frontend
      NotFound["NotFound.tsx"]:::frontend
      Contact["Contact.tsx"]:::frontend
      Navbar["Navbar.tsx"]:::frontend
      Footer["Footer.tsx"]:::frontend
      AuthContext["AuthContext.tsx"]:::frontend
    end
    subgraph "UI Primitives (shadcn/ui)"
      UIPrimitives["src/components/ui/"]:::frontend
    end
    subgraph "Custom Hooks"
      UseInterview["useInterview.ts"]:::frontend
      UseMobile["use-mobile.tsx"]:::frontend
      UseToast["use-toast.ts"]:::frontend
    end
    Utils["utils.ts"]:::frontend
    Firebase["firebase.ts"]:::frontend
    EntryFE["main.tsx"]:::frontend
  end

  %% Backend
  subgraph "Backend (Spring Boot)" 
    direction TB
    EntryBE["InterviewPlatformApplication.java"]:::backend
    subgraph "Configuration & Security"
      AuditingConfig["AuditingConfig.java"]:::backend
      SecurityConfig["SecurityConfig.java"]:::backend
      WebConfig["WebConfig.java"]:::backend
      JwtProvider["JwtTokenProvider.java"]:::backend
      AppProps["application.properties/yml"]:::backend
    end
    subgraph "Controllers"
      AuthController["AuthController.java"]:::backend
      SessionController["SessionController.java"]:::backend
    end
    subgraph "Services"
      AuthService["AuthService.java"]:::backend
      SessionService["SessionService.java"]:::backend
      AIService["AIService.java"]:::backend
    end
    subgraph "Repositories"
      UserRepo["UserRepository.java"]:::backend
      InterviewSessionRepo["InterviewSessionRepository.java"]:::backend
      QuestionAnswerRepo["QuestionAnswerRepository.java"]:::backend
    end
    subgraph "Models & DTOs"
      UserModel["User.java"]:::backend
      SessionModel["InterviewSession.java"]:::backend
      QAmodel["QuestionAnswer.java"]:::backend
      DTOs["dto/"]:::backend
    end
  end

  %% External Services
  DB["MySQL"]:::external
  Gemini["Google Gemini API"]:::external
  FirebaseExt["Firebase"]:::external

  %% Data Flows
  EntryFE -->|"renders"| Index
  Index -->|"router"| InterviewPage
  InterviewPage -->|"uses"| ChatInterview
  InterviewPage -->|"uses"| FeedbackDisplay
  InterviewPage -->|"uses"| InterviewInterface
  InterviewPage -->|"uses"| InterviewSummary
  InterviewPage -->|"uses"| TopicSelection
  Index -->|"navigates"| Login
  Login -->|"navigates"| Signup
  Signup -->|"on success"| LoginSuccess
  EntryFE -->|"imports"| AuthContext
  EntryFE -->|"imports"| UIPrimitives
  EntryFE -->|"imports"| UseInterview
  EntryFE -->|"imports"| UseMobile
  EntryFE -->|"imports"| UseToast
  EntryFE -->|"imports"| Utils
  EntryFE -->|"imports"| Firebase

  %% API calls
  Index -->|"/api/auth/login"| AuthController
  Login -->|"/api/auth/signup"| AuthController
  InterviewPage -->|"/api/session/*"| SessionController
  AuthController -->|calls| AuthService
  AuthService -->|uses| JwtProvider
  SessionController -->|calls| SessionService
  SessionService -->|calls| AIService
  SessionService -->|persists via JPA| InterviewSessionRepo
  SessionService -->|persists via JPA| QuestionAnswerRepo
  AuthService -->|persists via JPA| UserRepo

  %% DB & External
  UserRepo -->|CRUD| DB
  InterviewSessionRepo -->|CRUD| DB
  QuestionAnswerRepo -->|CRUD| DB
  AIService -->|HTTPS/API Key| Gemini
  Firebase -->|analytics/auth| FirebaseExt

  %% Click Events
  click Index "https://github.com/qaimmehdi/prepza/blob/main/src/pages/Index.tsx"
  click InterviewPage "https://github.com/qaimmehdi/prepza/blob/main/src/pages/InterviewPage.tsx"
  click Login "https://github.com/qaimmehdi/prepza/blob/main/src/pages/Login.tsx"
  click Signup "https://github.com/qaimmehdi/prepza/blob/main/src/pages/Signup.tsx"
  click LoginSuccess "https://github.com/qaimmehdi/prepza/blob/main/src/pages/LoginSuccess.tsx"
  click NotFound "https://github.com/qaimmehdi/prepza/blob/main/src/pages/NotFound.tsx"
  click Contact "https://github.com/qaimmehdi/prepza/blob/main/src/pages/Contact.tsx"
  click Navbar "https://github.com/qaimmehdi/prepza/blob/main/src/components/Navbar.tsx"
  click Footer "https://github.com/qaimmehdi/prepza/blob/main/src/components/Footer.tsx"
  click AuthContext "https://github.com/qaimmehdi/prepza/blob/main/src/components/AuthContext.tsx"
  click UIPrimitives "https://github.com/qaimmehdi/prepza/tree/main/src/components/ui/"
  click UseInterview "https://github.com/qaimmehdi/prepza/blob/main/src/hooks/useInterview.ts"
  click UseMobile "https://github.com/qaimmehdi/prepza/blob/main/src/hooks/use-mobile.tsx"
  click UseToast "https://github.com/qaimmehdi/prepza/blob/main/src/hooks/use-toast.ts"
  click Utils "https://github.com/qaimmehdi/prepza/blob/main/src/lib/utils.ts"
  click Firebase "https://github.com/qaimmehdi/prepza/blob/main/src/firebase.ts"
  click EntryFE "https://github.com/qaimmehdi/prepza/blob/main/src/main.tsx"
  click EntryBE "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/InterviewPlatformApplication.java"
  click AuditingConfig "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/config/AuditingConfig.java"
  click SecurityConfig "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/config/SecurityConfig.java"
  click WebConfig "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/config/WebConfig.java"
  click JwtProvider "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/security/JwtTokenProvider.java"
  click AppProps "https://github.com/qaimmehdi/prepza/blob/main/src/main/resources/application.properties"
  click AuthController "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/controller/AuthController.java"
  click SessionController "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/controller/SessionController.java"
  click AuthService "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/service/AuthService.java"
  click SessionService "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/service/SessionService.java"
  click AIService "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/ai/AIService.java"
  click UserRepo "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/repository/UserRepository.java"
  click InterviewSessionRepo "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/repository/InterviewSessionRepository.java"
  click QuestionAnswerRepo "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/repository/QuestionAnswerRepository.java"
  click UserModel "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/model/User.java"
  click SessionModel "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/model/InterviewSession.java"
  click QAmodel "https://github.com/qaimmehdi/prepza/blob/main/src/main/java/com/yourcompany/interviewplatform/model/QuestionAnswer.java"
  click DTOs "https://github.com/qaimmehdi/prepza/tree/main/src/main/java/com/yourcompany/interviewplatform/dto/"
  
  %% Styles
  classDef frontend fill:#D6E8FF,stroke:#333,stroke-width:1px
  classDef backend fill:#DFF4D6,stroke:#333,stroke-width:1px
  classDef external fill:#FFE5B4,stroke:#333,stroke-width:1px
```
