# umeshchandra-rao/scanlance architecture

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

- Interactive diagram: https://gitdiagram.com/umeshchandra-rao/scanlance
- Repository: https://github.com/umeshchandra-rao/scanlance

## Overview

##### Project Type & Purpose
- Full-stack AI-driven resume analysis web app.
- Frontend built with Next.js 14 App Router, React, Tailwind CSS, Framer Motion, shadcn/ui.
- Backend serverless API routes (Next.js) orchestrate file extraction, AI calls (Google Gemini), rate-limiting (Redis), and feedback submission.

##### High-Level Components
a. Frontend UI Layer
- App Router (app/layout.tsx, app/page.tsx, app/analyzer/page.tsx)
- Analyzer feature (app/analyzer/…): pages, layouts, animations, constants, utils
- Shared components (components/… & components/ui/…): hero, navbar, footer, file uploader, interactive result views
- Custom hooks (app/analyzer/hooks, hooks/…): useAnalysis, useFileHandling, useStepNavigation, useToast, useMobile
b. Backend API Layer
- API routes (app/api/analyze/route.ts, app/api/send-feedback/route.ts)
- Server actions (app/actions.ts) for form handling
c. Business Logic & Services
- lib/: analyze-resume.ts, gemini-client.ts, pdf-extractor.ts, docx-extractor.ts, text-extractor-utils.ts
- Domain-specific NER modules: skill-taxonomy.ts, domain-specific-ner.ts, education-analyzer.ts, improved-resume-section-detector.ts
- Rate limiter (lib/rate-limiter.ts) with optional Redis
- Validation & error handling (validation-schemas.ts, error-handler.ts, env-validation.ts)
d. External Services
- Google Gemini API for AI analysis
- Redis (optional) for rate limiting
- Resend API (optional) for feedback emails
e. Configuration & Assets
- next.config.mjs, tailwind.config.ts, tsconfig.json, .env(.example)
- Public/static assets (public/) and global styles (styles/globals.css)

##### Component Relationships & Data Flows
- User interacts with Frontend UI → uploads resume + enters job description
- Frontend invokes client-side hooks (useFileHandling, useAnalysis) → submits POST /api/analyze
- Next.js API route (/api/analyze)
→ validates input (Zod schemas)
→ invokes lib.analyzeResume:
- runs extractors (PDF, DOCX, TXT)
- runs NER and domain analyzers
- constructs AI prompts (prompt-templates.ts)
→ calls Google Gemini client → receives AI response
→ applies scoring & recommendations → returns JSON
- Frontend receives JSON → ResultsDisplay component renders interactive breakdown
- Feedback loop: user submits feedback → POST /api/send-feedback → optional Resend email dispatch

##### Architectural Patterns & Principles
- Next.js App Router for file-based routing & nested layouts
- Serverless API endpoints co-located with pages
- Separation of concerns: UI components vs. domain/business logic (lib/) vs. data-flow hooks
- Domain-driven modules in lib/ for extraction, analysis, validation
- Progressive enhancement: optional Redis integration with graceful fallback
- Strict typing & schema validation (TypeScript + Zod)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client/UI Layer
    subgraph "Client/UI Layer"
        direction TB
        AR["App Router\n(app/layout.tsx)"]:::ui
        LP["Landing Page\n(app/page.tsx)"]:::ui
        subgraph "Analyzer Flow"
            direction TB
            AFL["Analyzer Layout\n(app/analyzer/layout.tsx)"]:::ui
            AFP["Analyzer Page\n(app/analyzer/page.tsx)"]:::ui
            subgraph "Analyzer Components"
                direction TB
                AP["AnalysisProgress"]:::ui
                AE["AnalyzerErrorFallback"]:::ui
                JD["JobDetailsForm"]:::ui
                RD["ResultsDisplay"]:::ui
                RU["ResumeUploader"]:::ui
                SP["StepProgress"]:::ui
            end
            subgraph "Analyzer Hooks"
                direction TB
                AH1["useAnalysis"]:::ui
                AH2["useFileHandling"]:::ui
                AH3["useScrollHandling"]:::ui
                AH4["useStepNavigation"]:::ui
            end
            subgraph "Animations/Constants/Utils"
                direction TB
                AN["animations.ts"]:::ui
                CO["constants.ts"]:::ui
                UT["utils.ts"]:::ui
            end
        end
        subgraph "Shared UI Components"
            direction TB
            SU1["file-uploader.tsx"]:::ui
            SU2["resume-analysis-result.tsx"]:::ui
            SU3["hero-section.tsx"]:::ui
            SU4["navbar.tsx"]:::ui
            SU5["footer.tsx"]:::ui
            SU6["faq-section.tsx"]:::ui
            SU7["features-section.tsx"]:::ui
            SU8["how-it-works.tsx"]:::ui
            SU9["testimonials-section.tsx"]:::ui
            SU10["error-boundary.tsx"]:::ui
            SU11["theme-provider.tsx"]:::ui
        end
        subgraph "Shared UI Primitives"
            direction TB
            PRI["components/ui/ (shadcn/ui)"]:::ui
        end
        subgraph "Global Hooks"
            direction TB
            GH1["use-mobile.tsx"]:::ui
            GH2["use-toast.ts"]:::ui
        end
    end

    %% Server/API Layer
    subgraph "Server/API Layer"
        direction TB
        API1["POST /api/analyze\n(app/api/analyze/route.ts)"]:::api
        API2["POST /api/send-feedback\n(app/api/send-feedback/route.ts)"]:::api
        SA["Server Actions\n(app/actions.ts)"]:::api
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        ORC["Resume Orchestration\n(lib/analyze-resume.ts)"]:::logic
        GC["Gemini Client\n(lib/gemini-client.ts)"]:::logic
        subgraph "Extractors"
            direction TB
            EX1["PDF Extractor\n(lib/pdf-extractor.ts)"]:::logic
            EX2["DOCX Extractor\n(lib/docx-extractor.ts)"]:::logic
            EX3["Text Utils\n(lib/text-extractor-utils.ts)"]:::logic
        end
        PT["Prompt Templates\n(lib/prompt-templates.ts)"]:::logic
        subgraph "Domain Analyzers"
            direction TB
            DA1["Skill Taxonomy\n(lib/skill-taxonomy.ts)"]:::logic
            DA2["Domain NER\n(lib/domain-specific-ner.ts)"]:::logic
            DA3["Education Analyzer\n(lib/education-analyzer.ts)"]:::logic
            DA4["Section Detector\n(lib/improved-resume-section-detector.ts)"]:::logic
        end
        RL["Rate Limiter\n(lib/rate-limiter.ts)"]:::logic
        subgraph "Validation & Error Handling"
            direction TB
            VS["Schemas\n(lib/validation-schemas.ts)"]:::logic
            EH["Error Handler\n(lib/error-handler.ts)"]:::logic
            EV["Env Validation\n(lib/env-validation.ts)"]:::logic
        end
    end

    %% External Services Layer
    subgraph "External Services"
        direction TB
        EG["Google Gemini API"]:::external
        RDServ["Redis (optional)"]:::external
        RE["Resend Email API"]:::external
    end

    %% Data Flows
    AR -->|uses| LP
    LP -->|navigates to| AFL
    RU -->|triggers| AH2
    JD -->|triggers| AH1
    AFP -->|calls POST /api/analyze| API1
    RD -->|displays response| RD
    RD -->|feedback flow| API2
    API1 -->|validates via| VS
    API1 -->|orchestrates| ORC
    ORC -->|extracts via| EX1
    ORC -->|extracts via| EX2
    ORC -->|extracts via| EX3
    ORC -->|analyzes via| DA1
    ORC -->|analyzes via| DA2
    ORC -->|analyzes via| DA3
    ORC -->|analyzes via| DA4
    ORC -->|uses prompts| PT
    ORC -->|calls| GC
    GC -->|REST to Gemini| EG
    API1 -->|rate limit| RL
    RL -->|optional| RDServ
    API2 -->|sends email via| RE
    SA -->|handles forms| API1
    SA -->|handles forms| API2

    %% Click Events
    click AR "https://github.com/umeshchandra-rao/scanlance/blob/main/app/layout.tsx"
    click LP "https://github.com/umeshchandra-rao/scanlance/blob/main/app/page.tsx"
    click AFL "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/layout.tsx"
    click AFP "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/page.tsx"
    click AN "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/animations.ts"
    click CO "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/constants.ts"
    click UT "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/utils.ts"
    click AP "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/components/AnalysisProgress.tsx"
    click AE "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/components/AnalyzerErrorFallback.tsx"
    click JD "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/components/JobDetailsForm.tsx"
    click RD "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/components/ResultsDisplay.tsx"
    click RU "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/components/ResumeUploader.tsx"
    click SP "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/components/StepProgress.tsx"
    click AH1 "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/hooks/useAnalysis.ts"
    click AH2 "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/hooks/useFileHandling.ts"
    click AH3 "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/hooks/useScrollHandling.ts"
    click AH4 "https://github.com/umeshchandra-rao/scanlance/blob/main/app/analyzer/hooks/useStepNavigation.ts"
    click SU1 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/file-uploader.tsx"
    click SU2 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/resume-analysis-result.tsx"
    click SU3 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/hero-section.tsx"
    click SU4 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/navbar.tsx"
    click SU5 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/footer.tsx"
    click SU6 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/faq-section.tsx"
    click SU7 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/features-section.tsx"
    click SU8 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/how-it-works.tsx"
    click SU9 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/testimonials-section.tsx"
    click SU10 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/error-boundary.tsx"
    click SU11 "https://github.com/umeshchandra-rao/scanlance/blob/main/components/theme-provider.tsx"
    click PRI "https://github.com/umeshchandra-rao/scanlance/tree/main/components/ui/"
    click GH1 "https://github.com/umeshchandra-rao/scanlance/blob/main/hooks/use-mobile.tsx"
    click GH2 "https://github.com/umeshchandra-rao/scanlance/blob/main/hooks/use-toast.ts"
    click API1 "https://github.com/umeshchandra-rao/scanlance/blob/main/app/api/analyze/route.ts"
    click API2 "https://github.com/umeshchandra-rao/scanlance/blob/main/app/api/send-feedback/route.ts"
    click SA "https://github.com/umeshchandra-rao/scanlance/blob/main/app/actions.ts"
    click ORC "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/analyze-resume.ts"
    click GC "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/gemini-client.ts"
    click EX1 "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/pdf-extractor.ts"
    click EX2 "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/docx-extractor.ts"
    click EX3 "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/text-extractor-utils.ts"
    click PT "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/prompt-templates.ts"
    click DA1 "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/skill-taxonomy.ts"
    click DA2 "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/domain-specific-ner.ts"
    click DA3 "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/education-analyzer.ts"
    click DA4 "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/improved-resume-section-detector.ts"
    click RL "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/rate-limiter.ts"
    click VS "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/validation-schemas.ts"
    click EH "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/error-handler.ts"
    click EV "https://github.com/umeshchandra-rao/scanlance/blob/main/lib/env-validation.ts"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0B69A3,color:#000
    classDef api fill:#DFFFE0,stroke:#3C8D0D,color:#000
    classDef logic fill:#FFF4C1,stroke:#B58A00,color:#000
    classDef external fill:#FFE6C2,stroke:#A34D00,color:#000rror
```
