# adrianhajdin/ai-resume-analyzer architecture

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

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

## Overview

1. **Overall shape**
   - This is a **client-side React application** built with **React Router v7**, **Vite**, **TypeScript**, and **Tailwind CSS**.
   - There is **no custom backend** in the repo; the app relies on **Puter.js / Puter.com** for auth, storage, and AI-powered operations.

2. **Primary architectural boundary: browser app vs external Puter services**
   - The core boundary is between the **UI/routes in the browser** and the **Puter SDK** accessed from `app/lib/puter.ts`.
   - Puter is used to offload authentication, file persistence, and AI evaluation, which keeps the app mostly stateless on its own.

3. **Routing and application shell**
   - `app/root.tsx` provides the app shell/layout, while `app/routes.ts` and `react-router.config.ts` define the route structure.
   - The route modules in `app/routes/` are the top-level functional slices of the product:
     - `home.tsx` landing page
     - `auth.tsx` sign-in/auth flow
     - `upload.tsx` resume upload flow
     - `resume.tsx` resume detail / analysis view
     - `wipe.tsx` data reset / cleanup action

4. **User journey / main data flow**
   - A user enters through **Home**, authenticates via **Auth**, uploads a resume through **Upload**, then views analysis in **Resume**.
   - The resulting data appears to be stored/retrieved through Puter and then rendered back into the UI as a scored resume analysis.
   - `wipe.tsx` likely exists as a maintenance or account-reset path to remove stored user data.

5. **Resume ingestion pipeline**
   - `app/components/FileUploader.tsx` is the entry point for user resume files.
   - `app/lib/pdf2img.ts` suggests a document-processing step that converts PDF resumes into images, likely for preview or downstream AI/OCR processing.
   - This means the upload flow is not just storage; it includes **document normalization** before analysis/rendering.

6. **AI analysis and score presentation**
   - The analysis output is presented through a dedicated set of components:
     - `ATS.tsx` for ATS-style evaluation
     - `ScoreBadge.tsx`, `ScoreCircle.tsx`, `ScoreGauge.tsx` for score visualization
     - `Summary.tsx` and `Details.tsx` for textual feedback
     - `Accordion.tsx` for collapsible breakdowns
   - These components indicate the app breaks AI output into **structured sub-results** rather than rendering a single blob of text.

7. **Resume list and reusable UI**
   - `ResumeCard.tsx` likely represents each stored resume in a list or dashboard view.
   - `Navbar.tsx` provides shared navigation across routes.
   - The component layer is intentionally reusable and presentational, with route modules orchestrating data and interactions.

8. **Shared libraries and utilities**
   - `app/lib/puter.ts` is the main abstraction layer around Puter APIs, keeping vendor-specific calls out of routes/components.
   - `app/lib/utils.ts` contains shared helper logic, likely for formatting, class composition, or small UI/data transformations.
   - This separation is the clearest internal boundary in the codebase: **UI components** vs **integration/utilities**.

9. **Typed domain and SDK extensions**
   - `types/index.d.ts` and `types/puter.d.ts` indicate custom TypeScript definitions for app data and Puter SDK behavior.
   - That suggests the app models a typed resume-analysis domain and also extends or patches third-party typings where needed.

10. **Constants and content**
   - `constants/index.ts` centralizes static values used across the app, likely labels, route metadata, or analysis-related presets.
   - This keeps route/components from hardcoding repeated business/UI text.

11. **Styling and assets**
   - `app/app.css` plus Tailwind utility classes drive the visual system.
   - `public/` contains icons, images, and readme assets; these are static presentation assets rather than app logic.
   - The architecture is UI-heavy, but still modularized by feature and component responsibility.

12. **Build/runtime context**
   - `vite.config.ts`, `tsconfig.json`, `package.json`, and `Dockerfile` show the app is meant to run as a modern SPA in local dev and containerized deployment.
   - The runtime model is browser-first; no server process is present in the repository itself.

13. **What to show in an architecture diagram**
   - The key diagram should include:
     - **Browser UI**
     - **Route modules**
     - **Reusable components**
     - **Shared libs (`puter`, `pdf2img`, utils)**
     - **Puter external services** for auth/storage/AI
     - **Static assets/constants/types** as supporting layers
   - The main arrows are:
     - user → routes/UI
     - routes/components → `puter.ts`
     - upload flow → `pdf2img.ts` → analysis/storage
     - analysis results → score/summary/detail components

Main entry points: [`app/lib/puter.ts`](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/lib/puter.ts) (Puter SDK), [`app/routes.ts`](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes.ts) (Routes config), [`app/routes/resume.tsx`](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/resume.tsx) (Resume), [`app/routes/home.tsx`](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/home.tsx) (Home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser app"]
  node_user(("User<br/>actor"))
  node_root["App shell<br/>react-root<br/>[root.tsx]"]
  node_routes_config["Routes config<br/>router-config<br/>[routes.ts]"]
  node_home_route["Home<br/>route<br/>[home.tsx]"]
  node_auth_route["Auth<br/>route<br/>[auth.tsx]"]
  node_upload_route["Upload<br/>route<br/>[upload.tsx]"]
  node_resume_route["Resume<br/>route<br/>[resume.tsx]"]
  node_wipe_route["Wipe<br/>route<br/>[wipe.tsx]"]
  node_navbar["Navbar<br/>ui-nav<br/>[Navbar.tsx]"]
  node_file_uploader["File uploader<br/>upload-ui<br/>[FileUploader.tsx]"]
  node_resume_card["Resume card<br/>list-card<br/>[ResumeCard.tsx]"]
  node_ats["ATS view<br/>analysis-ui<br/>[ATS.tsx]"]
  node_score_ui["Score UI<br/>score-visuals"]
  node_feedback_ui["Feedback UI<br/>analysis-details"]
end

subgraph group_shared["Shared code"]
  node_puter_lib["Puter SDK<br/>integration<br/>[puter.ts]"]
  node_pdf2img["PDF to image<br/>document-processing<br/>[pdf2img.ts]"]
  node_utils["Utils<br/>helpers<br/>[utils.ts]"]
  node_constants["Constants<br/>[index.ts]"]
  node_types["Types<br/>type-defs<br/>[index.d.ts]"]
  node_puter_types["Puter types<br/>sdk-types<br/>[puter.d.ts]"]
  node_assets["Static assets<br/>static-assets"]
  node_styles["App styles<br/>styling<br/>[app.css]"]
end

subgraph group_external["External services"]
  node_puter_service[("Puter services<br/>external-platform")]
end

node_user -->|"enters"| node_home_route
node_home_route -->|"sign in"| node_auth_route
node_auth_route -->|"auth"| node_puter_lib
node_upload_route -->|"uses"| node_file_uploader
node_file_uploader -->|"normalizes"| node_pdf2img
node_pdf2img -->|"prepares input"| node_puter_lib
node_resume_route -->|"renders"| node_ats
node_resume_route -->|"shows scores"| node_score_ui
node_resume_route -->|"shows feedback"| node_feedback_ui
node_resume_route -->|"lists"| node_resume_card
node_wipe_route -->|"cleans data"| node_puter_lib
node_root -->|"wires"| node_routes_config
node_routes_config -->|"maps"| node_home_route
node_routes_config -->|"maps"| node_auth_route
node_routes_config -->|"maps"| node_upload_route
node_routes_config -->|"maps"| node_resume_route
node_routes_config -->|"maps"| node_wipe_route
node_root -->|"shares shell"| node_navbar
node_root -->|"styles"| node_styles
node_navbar -->|"reads"| node_constants
node_puter_lib -->|"connects to"| node_puter_service
node_puter_lib -->|"typed by"| node_types
node_puter_lib -->|"extends"| node_puter_types
node_upload_route -->|"stores"| node_puter_lib
node_resume_route -->|"loads"| node_puter_lib
node_wipe_route -->|"removes"| node_puter_lib
node_home_route -->|"uses"| node_assets

click node_root "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/root.tsx"
click node_routes_config "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes.ts"
click node_home_route "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/home.tsx"
click node_auth_route "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/auth.tsx"
click node_upload_route "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/upload.tsx"
click node_resume_route "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/resume.tsx"
click node_wipe_route "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/wipe.tsx"
click node_navbar "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/components/Navbar.tsx"
click node_file_uploader "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/components/FileUploader.tsx"
click node_resume_card "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/components/ResumeCard.tsx"
click node_ats "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/components/ATS.tsx"
click node_puter_lib "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/lib/puter.ts"
click node_pdf2img "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/lib/pdf2img.ts"
click node_utils "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/lib/utils.ts"
click node_constants "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/constants/index.ts"
click node_types "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/types/index.d.ts"
click node_puter_types "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/types/puter.d.ts"
click node_assets "https://github.com/adrianhajdin/ai-resume-analyzer/tree/main/public"
click node_styles "https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/app.css"

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_user,node_root,node_routes_config,node_home_route,node_auth_route,node_upload_route,node_resume_route,node_wipe_route,node_navbar,node_file_uploader,node_resume_card,node_ats,node_score_ui,node_feedback_ui toneBlue
class node_puter_lib,node_pdf2img,node_utils,node_constants,node_types,node_puter_types,node_assets,node_styles toneAmber
class node_puter_service toneMint
```

## Components

### Browser app

Client-side React UI, routes, and feature components running in the browser.

- **User**: actor · Person using the resume analysis app.
- [App shell](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/root.tsx): react-root · Top-level React Router layout and app shell. · `app/root.tsx`
- [Routes config](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes.ts): router-config · Route registration and router wiring. · `app/routes.ts`
- [Home](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/home.tsx): route · Landing page and entry point into the product. · `app/routes/home.tsx`
- [Auth](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/auth.tsx): route · Sign-in and authentication flow. · `app/routes/auth.tsx`
- [Upload](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/upload.tsx): route · Resume upload and submission flow. · `app/routes/upload.tsx`
- [Resume](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/resume.tsx): route · Resume detail and analysis view. · `app/routes/resume.tsx`
- [Wipe](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/routes/wipe.tsx): route · Data reset and cleanup action. · `app/routes/wipe.tsx`
- [Navbar](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/components/Navbar.tsx): ui-nav · Shared navigation across routes. · `app/components/Navbar.tsx`
- [File uploader](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/components/FileUploader.tsx): upload-ui · Entry component for selecting and submitting resume files. · `app/components/FileUploader.tsx`
- [Resume card](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/components/ResumeCard.tsx): list-card · Reusable resume summary card for lists or dashboards. · `app/components/ResumeCard.tsx`
- [ATS view](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/components/ATS.tsx): analysis-ui · ATS-style evaluation display for resume analysis. · `app/components/ATS.tsx`
- **Score UI**: score-visuals · Score presentation components for badges, circles, and gauges.
- **Feedback UI**: analysis-details · Summary, details, and accordion components for structured feedback.

### Shared code

Cross-cutting libraries, types, constants, and styling used across the app.

- [Puter SDK](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/lib/puter.ts): integration · App-specific wrapper around Puter authentication, storage, and AI APIs. · `app/lib/puter.ts`
- [PDF to image](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/lib/pdf2img.ts): document-processing · Converts uploaded resume PDFs into images for downstream processing. · `app/lib/pdf2img.ts`
- [Utils](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/lib/utils.ts): helpers · Shared helper functions used across the UI and integration code. · `app/lib/utils.ts`
- [Constants](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/constants/index.ts): app-constants · Centralized static values and shared copy/presets. · `constants/index.ts`
- [Types](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/types/index.d.ts): type-defs · Custom TypeScript domain and Puter type definitions. · `types/index.d.ts`
- [Puter types](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/types/puter.d.ts): sdk-types · Type augmentation for the Puter SDK. · `types/puter.d.ts`
- [Static assets](https://github.com/adrianhajdin/ai-resume-analyzer/tree/main/public): static-assets · Icons, images, and readme assets served from public/. · `public`
- [App styles](https://github.com/adrianhajdin/ai-resume-analyzer/blob/main/app/app.css): styling · Global app CSS and Tailwind-driven presentation layer. · `app/app.css`

### External services

Third-party Puter services used for auth, storage, and AI operations.

- **Puter services**: external-platform · External auth, storage, and AI services provided by Puter.

## Connections

- User → Home: enters · The user starts at the landing page.
- Home → Auth: sign in · Home leads into authentication.
- Auth → Puter SDK: auth · Auth flow delegates to the Puter integration.
- Upload → File uploader: uses · Upload route renders the file picker/upload entry point.
- File uploader → PDF to image: normalizes · Uploaded PDFs are converted into images for processing.
- PDF to image → Puter SDK: prepares input · Document processing feeds the integration layer for persistence or AI work.
- Resume → ATS view: renders · Resume detail view surfaces structured analysis UI.
- Resume → Score UI: shows scores · Analysis page uses score visualizations.
- Resume → Feedback UI: shows feedback · Analysis page uses summary and detailed feedback components.
- Resume → Resume card: lists · Resume data can be summarized in reusable cards.
- Wipe → Puter SDK: cleans data · Reset action goes through the Puter integration.
- App shell → Routes config: wires · The app shell is driven by the router configuration.
- Routes config → Home: maps · Route table includes the home page.
- Routes config → Auth: maps · Route table includes the auth page.
- Routes config → Upload: maps · Route table includes the upload page.
- Routes config → Resume: maps · Route table includes the resume page.
- Routes config → Wipe: maps · Route table includes the wipe action.
- App shell → Navbar: shares shell · Shared navigation appears in the app shell.
- App shell → App styles: styles · Global styling is applied through the root app shell.
- Navbar → Constants: reads · Navigation and labels are likely driven by shared constants.
- Puter SDK → Puter services: connects to · Integration layer talks to external Puter APIs.
- Puter SDK → Types: typed by · Integration uses app domain types.
- Puter SDK → Puter types: extends · Integration relies on custom Puter type definitions.
- Upload → Puter SDK: stores · Upload flow persists resume data through Puter.
- Resume → Puter SDK: loads · Resume analysis view reads stored data through Puter.
- Wipe → Puter SDK: removes · Cleanup flow removes stored user data via Puter.
- Home → Static assets: uses · Landing page can draw from static images and icons.
