# jeswanthjohn/resume-analyzer-ai architecture

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

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

## Overview

##### Project type and purpose
- This is a minimal full-stack web application showcasing a “serverless resume analysis” service.
- Frontend: static HTML/CSS/JS in /public.
- Backend: a single Vercel serverless function at /api/analyze that invokes OpenAI or a deterministic mock fallback.
- Goal: demonstrate defensive API design, reliability under failure, and production-grade engineering.

##### File structure
Top-level
- .env.example, .gitignore, package.json → environment & build config
- README.md → architecture overview & request lifecycle
Directories
- public/
– app.js, index.html, styles.css → static UI, PDF upload, result rendering
- api/
– analyze.js → single serverless endpoint implementing request handling
- lib/
– constants.js → static config (e.g. rate limits)
– validateInput.js → request validation logic
– rateLimiter.js → abuse protection
– errors.js → error definitions

##### README for additional insights
- Describes a linear “Request Lifecycle” from frontend submission → /api/analyze → validation → rate limit → AI call → fallback decision → unified response → frontend rendering.
- Emphasizes serverless architecture, horizontal scalability, cost-safe design, graceful degradation.

a. Main components
– User’s Browser & Static UI (public/)
– CDN or Static Hosting (Vercel)
– API Gateway / Serverless Invocation (/api/analyze)
– Input Validation module
– Rate Limiter module
– AI Service (OpenAI API)
– Fallback Mock Analysis
– Response Formatter
– Environment & Secrets Store (OPENAI_API_KEY, MOCK_MODE)
b. Relationships & interactions
1. Browser → GET static files from CDN
2. Browser → POST resume text to /api/analyze
3. Serverless function inbound → validateInput → rateLimiter
4. If rate-limited or invalid → error response
5. Else → invoke OpenAI API
6a. On success → normalize AI response
6b. On failure (quota, network, invalid) → invoke mockAnalysis
7. Return unified JSON → Browser → render results
c. Architectural patterns & principles
- Serverless functions for horizontal scalability & cost predictability
- Defensive programming: input validation + rate limiting + try/catch
- Graceful degradation via fallback mock path
- Single-purpose function reduces blast radius
d. Key technologies & frameworks
- Frontend: Vanilla JS, HTML5, CSS3
- Backend: Node.js, Vercel Serverless Functions
- AI: OpenAI Responses API + deterministic mock logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Zone
    subgraph "Frontend" 
        direction TB
        Browser["User Browser"]:::frontend
        CDN["CDN / Static Hosting"]:::frontend
        Browser -->|"GET static assets"| CDN
        CDN -->|"serves index.html"| Index["Index.html"]:::frontend
        CDN -->|"serves app.js"| AppJS["App.js"]:::frontend
        CDN -->|"serves styles.css"| Styles["Styles.css"]:::frontend
        Browser -->|"loads UI and scripts"| Index
        Browser -->|"loads UI and scripts"| AppJS
        Browser -->|"loads UI and scripts"| Styles
        Browser -->|"POST resume text\nPOST /api/analyze"| APIGateway
    end

    %% Backend Zone
    subgraph "Serverless API Function" 
        direction TB
        APIGateway["API Gateway\n/api/analyze"]:::backend
        Validate["Validate Input"]:::backend
        RateLimit["Rate Limiter"]:::backend
        AICaller["AI Service Caller"]:::backend
        FallbackMock["Fallback Mock Analysis"]:::fallback
        Formatter["Response Formatter"]:::backend

        APIGateway -->|"invoke"| Validate
        Validate -->|"valid? yes"| RateLimit
        Validate -->|"invalid"| FormatterError
        RateLimit -->|"within limit? yes"| AICaller
        RateLimit -->|"exceeded"| FormatterError
        AICaller -->|"OpenAI API call"| OpenAI
        AICaller -->|"on failure"| FallbackMock
        OpenAI -->|"response"| Formatter
        FallbackMock -->|"mock result"| Formatter
        Formatter -->|"JSON response"| Browser
        FormatterError["Error Response\n(unified JSON)"]:::backend
        FormatterError -->|"JSON error"| Browser
    end

    %% External Services
    OpenAI["OpenAI API"]:::external

    %% Components outside zones
    Env["Environment & Secrets Store\n(.env.example)"]:::config
    Const["Constants\n(lib/constants.js)"]:::config
    Errors["Error Definitions\n(lib/errors.js)"]:::config
    Package["Project Config\n(package.json)"]:::config
    Docs["Architecture Docs\n(README.md)"]:::config

    %% Config dependencies
    APIGateway -->|"reads"| Env
    APIGateway -->|"imports"| Const
    APIGateway -->|"imports"| Errors
    APIGateway -->|"build config"| Package
    APIGateway -->|"docs reference"| Docs

    %% Click events
    click Index "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/public/index.html"
    click AppJS "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/public/app.js"
    click Styles "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/public/styles.css"
    click CDN "https://github.com/jeswanthjohn/resume-analyzer-ai/tree/main/public/"
    click APIGateway "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/api/analyze.js"
    click Validate "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/lib/validateInput.js"
    click RateLimit "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/lib/rateLimiter.js"
    click Const "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/lib/constants.js"
    click Errors "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/lib/errors.js"
    click Env "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/.env.example"
    click Package "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/package.json"
    click Docs "https://github.com/jeswanthjohn/resume-analyzer-ai/blob/main/README.md"

    %% Styles
    classDef frontend fill:#87CEFA,stroke:#1E90FF,color:#000;
    classDef backend fill:#98FB98,stroke:#2E8B57,color:#000;
    classDef external fill:#FFA500,stroke:#FF8C00,color:#000;
    classDef fallback fill:#D3D3D3,stroke:#A9A9A9,color:#000;
    classDef config fill:#F5F5F5,stroke:#CCCCCC,color:#000;
```
