How adrianhajdin/ai-resume-analyzer works
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: puter.ts Puter SDK · routes.ts Routes config · resume.tsx Resume · home.tsx Home
Components 23
Browser app
Client-side React UI, routes, and feature components running in the browser.
- User · Person using the resume analysis app.
- App shell · Top-level React Router layout and app shell.
app/root.tsx - Routes config · Route registration and router wiring.
app/routes.ts - Home · Landing page and entry point into the product.
app/routes/home.tsx - Auth · Sign-in and authentication flow.
app/routes/auth.tsx - Upload · Resume upload and submission flow.
app/routes/upload.tsx - Resume · Resume detail and analysis view.
app/routes/resume.tsx - Wipe · Data reset and cleanup action.
app/routes/wipe.tsx - Navbar · Shared navigation across routes.
app/components/Navbar.tsx - File uploader · Entry component for selecting and submitting resume files.
app/components/FileUploader.tsx - Resume card · Reusable resume summary card for lists or dashboards.
app/components/ResumeCard.tsx - ATS view · ATS-style evaluation display for resume analysis.
app/components/ATS.tsx - Score UI · Score presentation components for badges, circles, and gauges.
- Feedback UI · Summary, details, and accordion components for structured feedback.
Shared code
Cross-cutting libraries, types, constants, and styling used across the app.
- Puter SDK · App-specific wrapper around Puter authentication, storage, and AI APIs.
app/lib/puter.ts - PDF to image · Converts uploaded resume PDFs into images for downstream processing.
app/lib/pdf2img.ts - Utils · Shared helper functions used across the UI and integration code.
app/lib/utils.ts - Constants · Centralized static values and shared copy/presets.
constants/index.ts - Types · Custom TypeScript domain and Puter type definitions.
types/index.d.ts - Puter types · Type augmentation for the Puter SDK.
types/puter.d.ts - Static assets · Icons, images, and readme assets served from public/.
public - App styles · 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 auth, storage, and AI services provided by Puter.
Connections 27
- 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.