# 3fnan/resumeiq architecture

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

- Interactive diagram: https://gitdiagram.com/3fnan/resumeiq
- Repository: https://github.com/3fnan/resumeiq

## Overview

1. **Overall shape**
   - This is a **Next.js 15 App Router** application that acts as a **stateless AI resume-analysis frontend with a single server API backend**.
   - There is no database or long-lived domain state in the repo; user data flows from the browser to an API route, then to external AI/PDF-processing libraries, and back to the UI.

2. **Primary runtime boundary: client UI vs server analysis**
   - The **browser/client side** owns the landing experience, file upload interaction, dashboard rendering, theme/visual state, and user-triggered resets.
   - The **server side** is concentrated in `src/app/api/analyze/route.ts`, which coordinates resume parsing and Gemini-powered analysis.
   - This boundary is the key architectural seam for a diagram: UI components collect input, the API route performs analysis, and results are returned to the dashboard.

3. **App Router entry points**
   - `src/app/page.tsx` is the main composition/root screen for the product experience.
   - `src/app/layout.tsx` provides the shared app shell.
   - `src/app/globals.css` holds global styling and theme/system-wide presentation rules.
   - `src/app/api/analyze/route.ts` is the single backend endpoint and the main integration point for analysis.

4. **Frontend composition**
   - The UI is split into reusable components under `src/components/`.
   - `Hero.tsx` and `Navbar.tsx` form the public-facing top section.
   - `ResumeUpload.tsx` is the user input surface for uploading or submitting a resume.
   - `Dashboard.tsx` is the results area, likely responsible for showing analysis tabs, scores, and generated outputs.
   - `src/components/ui/` contains design-system primitives (`Button`, `Card`, `Progress`, `Tabs`) used across the app.

5. **Request/data flow**
   - The typical flow is: **user uploads a resume in the browser → upload component posts to `/api/analyze` → server parses the document and calls Gemini → structured analysis is returned → dashboard renders the results**.
   - Based on the README, the analysis can cover ATS scoring, missing keywords, interview questions, and cover-letter content.
   - The dashboard then becomes the presentation layer for multiple AI-generated output categories rather than a single result.

6. **Server-side analysis pipeline**
   - `src/utils/pdf.ts` handles **PDF text extraction** using `pdf-parse`.
   - `src/utils/gemini.ts` encapsulates the **Google Gemini API client and prompt logic**.
   - The API route likely combines extracted resume text with any target job description or user context, then sends that to Gemini for structured output.
   - This separation is important: PDF parsing is isolated from AI prompting, and both are isolated from the UI.

7. **External dependency and integration boundary**
   - The only clearly stated external service is **Google Gemini API**, used for scoring and generation.
   - The API key is environment-based (`GEMINI_API_KEY`), so the service dependency is server-only and not exposed to the client.
   - This makes the server route the trust boundary: it receives uploaded content, prepares prompts, calls the model, and returns sanitized/structured output.

8. **Type boundary**
   - `src/types/index.ts` centralizes shared TypeScript shapes for analysis data passed between server and client.
   - This type layer is the contract that keeps the API payloads and dashboard rendering aligned.
   - For an architecture diagram, treat it as the schema boundary between analysis results and UI presentation.

9. **Presentation and interaction model**
   - The UI appears to be a **single-screen product experience** with a guided flow: landing content, upload interaction, then an analysis dashboard with tabs and progress indicators.
   - The `Tabs` and `Progress` primitives suggest the results are organized into multiple sections rather than a single flat report.
   - The README also indicates copy/download/print-oriented output, so the client is designed for both on-screen review and export-friendly presentation.

10. **Testing and quality boundary**
   - `tests/resume-analyzer.spec.js` plus `playwright.config.js` indicate **end-to-end browser testing** with Playwright.
   - These tests likely validate the user journey from upload through dashboard rendering and reset behavior.
   - This is the main automated verification layer for the client/server interaction, not unit-heavy backend logic.

11. **Infrastructure and deployment model**
   - The project is built to deploy on **Vercel or Netlify** with Next.js server routes enabled.
   - The app depends on runtime environment configuration, especially the Gemini API key.
   - Since the backend is an API route inside the Next.js app, deployment must support server-side execution, not just static hosting.

12. **What to draw in an architecture diagram**
   - Draw one browser/client box containing the landing page, upload form, dashboard, and UI primitives.
   - Draw one server box containing the `/api/analyze` route plus PDF parsing and Gemini orchestration utilities.
   - Draw one external service box for Gemini.
   - Show data flowing from user input to server analysis and back to rendered report sections, with no database or persistence layer in between.

Main entry points: [`src/components/Dashboard.tsx`](https://github.com/3fnan/resumeiq/blob/main/src/components/Dashboard.tsx) (Dashboard), [`src/app/page.tsx`](https://github.com/3fnan/resumeiq/blob/main/src/app/page.tsx) (Home page), [`src/components/ResumeUpload.tsx`](https://github.com/3fnan/resumeiq/blob/main/src/components/ResumeUpload.tsx) (Resume upload), [`src/app/api/analyze/route.ts`](https://github.com/3fnan/resumeiq/blob/main/src/app/api/analyze/route.ts) (Analyze API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_app_page["Home page<br/>app entry<br/>[page.tsx]"]
  node_app_layout["App shell<br/>layout shell<br/>[layout.tsx]"]
  node_global_css["Global styles<br/>style layer<br/>[globals.css]"]
  node_navbar["Navbar<br/>ui section<br/>[Navbar.tsx]"]
  node_hero["Hero<br/>ui section<br/>[Hero.tsx]"]
  node_upload["Resume upload<br/>client input<br/>[ResumeUpload.tsx]"]
  node_dashboard["Dashboard<br/>results view<br/>[Dashboard.tsx]"]
  node_ui_button["Button<br/>ui primitive<br/>[Button.tsx]"]
  node_ui_card["Card<br/>ui primitive<br/>[Card.tsx]"]
  node_ui_progress["Progress<br/>ui primitive<br/>[Progress.tsx]"]
  node_ui_tabs["Tabs<br/>ui primitive<br/>[Tabs.tsx]"]
end

subgraph group_server["Server Analysis"]
  node_api_analyze["Analyze API<br/>server route<br/>[route.ts]"]
  node_pdf_utils["PDF parser<br/>text extraction<br/>[pdf.ts]"]
  node_gemini_utils["Gemini client<br/>prompt orchestration<br/>[gemini.ts]"]
end

subgraph group_shared["Shared Contracts"]
  node_analysis_types["Analysis types<br/>shared schema<br/>[index.ts]"]
end

subgraph group_external["External Service"]
  node_gemini_api{{"Gemini API<br/>external model"}}
end

subgraph group_testing["Testing"]
  node_playwright_spec["E2E spec<br/>browser test"]
end

node_app_layout -->|"wraps"| node_app_page
node_app_layout -->|"loads"| node_global_css
node_app_page -->|"composes"| node_navbar
node_app_page -->|"composes"| node_hero
node_app_page -->|"composes"| node_upload
node_app_page -->|"composes"| node_dashboard
node_navbar -->|"uses"| node_ui_button
node_hero -->|"uses"| node_ui_card
node_upload -->|"uses"| node_ui_button
node_upload -->|"uses"| node_ui_card
node_dashboard -->|"uses"| node_ui_tabs
node_dashboard -->|"uses"| node_ui_progress
node_dashboard -->|"uses"| node_ui_card
node_upload -->|"submits"| node_api_analyze
node_api_analyze -->|"parses"| node_pdf_utils
node_api_analyze -->|"orchestrates"| node_gemini_utils
node_gemini_utils -->|"calls"| node_gemini_api
node_api_analyze -->|"returns"| node_analysis_types
node_dashboard -->|"renders"| node_analysis_types
node_playwright_spec -.->|"drives"| node_upload
node_playwright_spec -.->|"asserts"| node_dashboard
node_playwright_spec -.->|"covers"| node_api_analyze

click node_app_page "https://github.com/3fnan/resumeiq/blob/main/src/app/page.tsx"
click node_app_layout "https://github.com/3fnan/resumeiq/blob/main/src/app/layout.tsx"
click node_global_css "https://github.com/3fnan/resumeiq/blob/main/src/app/globals.css"
click node_navbar "https://github.com/3fnan/resumeiq/blob/main/src/components/Navbar.tsx"
click node_hero "https://github.com/3fnan/resumeiq/blob/main/src/components/Hero.tsx"
click node_upload "https://github.com/3fnan/resumeiq/blob/main/src/components/ResumeUpload.tsx"
click node_dashboard "https://github.com/3fnan/resumeiq/blob/main/src/components/Dashboard.tsx"
click node_ui_button "https://github.com/3fnan/resumeiq/blob/main/src/components/ui/Button.tsx"
click node_ui_card "https://github.com/3fnan/resumeiq/blob/main/src/components/ui/Card.tsx"
click node_ui_progress "https://github.com/3fnan/resumeiq/blob/main/src/components/ui/Progress.tsx"
click node_ui_tabs "https://github.com/3fnan/resumeiq/blob/main/src/components/ui/Tabs.tsx"
click node_api_analyze "https://github.com/3fnan/resumeiq/blob/main/src/app/api/analyze/route.ts"
click node_pdf_utils "https://github.com/3fnan/resumeiq/blob/main/src/utils/pdf.ts"
click node_gemini_utils "https://github.com/3fnan/resumeiq/blob/main/src/utils/gemini.ts"
click node_analysis_types "https://github.com/3fnan/resumeiq/blob/main/src/types/index.ts"
click node_playwright_spec "https://github.com/3fnan/resumeiq/blob/main/tests/resume-analyzer.spec.js"

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_app_page,node_app_layout,node_global_css,node_navbar,node_hero,node_upload,node_dashboard,node_ui_button,node_ui_card,node_ui_progress,node_ui_tabs toneBlue
class node_api_analyze,node_pdf_utils,node_gemini_utils toneAmber
class node_analysis_types toneMint
class node_gemini_api toneRose
class node_playwright_spec toneIndigo
```

## Components

### Client UI

Browser-side experience for landing, upload, and results rendering

- [Home page](https://github.com/3fnan/resumeiq/blob/main/src/app/page.tsx): app entry · Main App Router screen composing the product experience · `src/app/page.tsx`
- [App shell](https://github.com/3fnan/resumeiq/blob/main/src/app/layout.tsx): layout shell · Shared document and application wrapper · `src/app/layout.tsx`
- [Global styles](https://github.com/3fnan/resumeiq/blob/main/src/app/globals.css): style layer · App-wide CSS and theme rules · `src/app/globals.css`
- [Navbar](https://github.com/3fnan/resumeiq/blob/main/src/components/Navbar.tsx): ui section · Top-level navigation and branding · `src/components/Navbar.tsx`
- [Hero](https://github.com/3fnan/resumeiq/blob/main/src/components/Hero.tsx): ui section · Landing-page introduction and value proposition · `src/components/Hero.tsx`
- [Resume upload](https://github.com/3fnan/resumeiq/blob/main/src/components/ResumeUpload.tsx): client input · Resume submission and reset interaction surface · `src/components/ResumeUpload.tsx`
- [Dashboard](https://github.com/3fnan/resumeiq/blob/main/src/components/Dashboard.tsx): results view · Tabbed analysis output and report presentation · `src/components/Dashboard.tsx`
- [Button](https://github.com/3fnan/resumeiq/blob/main/src/components/ui/Button.tsx): ui primitive · Shared action control used across the interface · `src/components/ui/Button.tsx`
- [Card](https://github.com/3fnan/resumeiq/blob/main/src/components/ui/Card.tsx): ui primitive · Shared content container for page sections · `src/components/ui/Card.tsx`
- [Progress](https://github.com/3fnan/resumeiq/blob/main/src/components/ui/Progress.tsx): ui primitive · Score and completion visualization · `src/components/ui/Progress.tsx`
- [Tabs](https://github.com/3fnan/resumeiq/blob/main/src/components/ui/Tabs.tsx): ui primitive · Section switching for multi-part analysis results · `src/components/ui/Tabs.tsx`

### Server Analysis

Next.js API route and analysis utilities

- [Analyze API](https://github.com/3fnan/resumeiq/blob/main/src/app/api/analyze/route.ts): server route · Single server endpoint that orchestrates resume analysis · `src/app/api/analyze/route.ts`
- [PDF parser](https://github.com/3fnan/resumeiq/blob/main/src/utils/pdf.ts): text extraction · Extracts resume text from uploaded PDF files · `src/utils/pdf.ts`
- [Gemini client](https://github.com/3fnan/resumeiq/blob/main/src/utils/gemini.ts): prompt orchestration · Builds prompts and calls the Google Gemini API · `src/utils/gemini.ts`

### Shared Contracts

Types used across client and server

- [Analysis types](https://github.com/3fnan/resumeiq/blob/main/src/types/index.ts): shared schema · Cross-layer TypeScript contract for analysis payloads · `src/types/index.ts`

### External Service

Third-party model API used for analysis

- **Gemini API**: external model · External AI service used for scoring and generation

### Testing

End-to-end browser verification

- [E2E spec](https://github.com/3fnan/resumeiq/blob/main/tests/resume-analyzer.spec.js): browser test · End-to-end resume analysis journey checks · `tests/resume-analyzer.spec.js`

## Connections

- App shell → Home page: wraps · Provides the shared application shell for the main screen
- App shell → Global styles: loads · Applies global styling to the app
- Home page → Navbar: composes · Renders the navigation header
- Home page → Hero: composes · Renders the landing introduction
- Home page → Resume upload: composes · Renders the resume submission flow
- Home page → Dashboard: composes · Renders the analysis results area
- Navbar → Button: uses · Shares common action styling
- Hero → Card: uses · Wraps promotional content in reusable layout blocks
- Resume upload → Button: uses · Uses action controls for upload and reset
- Resume upload → Card: uses · Frames the upload surface
- Dashboard → Tabs: uses · Organizes multiple analysis outputs into sections
- Dashboard → Progress: uses · Displays scoring and completion indicators
- Dashboard → Card: uses · Presents report content in structured blocks
- Resume upload → Analyze API: submits · Sends the uploaded resume for analysis
- Analyze API → PDF parser: parses · Extracts text from the resume document
- Analyze API → Gemini client: orchestrates · Builds analysis prompts and requests model output
- Gemini client → Gemini API: calls · Invokes the external Gemini service
- Analyze API → Analysis types: returns · Shapes the response contract consumed by the UI
- Dashboard → Analysis types: renders · Consumes the shared analysis schema
- E2E spec → Resume upload: drives · Exercises upload and reset flows
- E2E spec → Dashboard: asserts · Verifies results rendering after analysis
- E2E spec → Analyze API: covers · Validates the browser-to-server analysis path
