# rithb898/fitforjob-ai-application-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/rithb898/fitforjob-ai-application-assistant
- Repository: https://github.com/rithb898/fitforjob-ai-application-assistant

## Overview

##### Project type and purpose
- This is a full-stack web application (“FitForJob”) built with Next.js 15 (App Router) that helps job seekers generate AI-driven, personalized application materials (cover letters, LinkedIn messages, interview prep, etc.) by uploading a resume and entering job details.
- It combines a React-based front-end, serverless API routes, third-party services (Clerk, Groq AI, PostHog), PDF processing, and MongoDB persistence.

##### File structure
Top-level directories:
- app/ – Next.js App Router pages and API routes
– app/page.tsx, app/layout.tsx: Root layout and home page
– app/(auth)/…: Sign-in, sign-up via Clerk
– app/api/parse-resume, generate, regenerate: Serverless endpoints
– app/api/webhooks/clerk: Clerk authentication webhook
– app/create, history, response/[id]: UI pages for resume upload, history view, single response view
- components/ – Reusable UI components (forms, navbar, response section)
- lib/ – Business-logic modules: database setup (lib/db.ts), models, API actions, AI prompt builder (lib/prompt.ts), PostHog wrapper, storage utilities
- hooks/ – Custom React hooks for state, form submission, resume management
- public/ – Static assets
- middleware.ts – Next.js middleware, e.g., auth checks
- next.config.ts, tsconfig.json, eslint.config.mjs, postcss.config.mjs – Configuration

##### README insights
- Tech stack summary: Next.js + Turbopack, Tailwind CSS + Shadcn UI, React Hook Form + Zod, MongoDB, Clerk, PDF-parse, Groq AI (LLama 3.x), PostHog.
- Workflow overview: upload resume → /api/parse-resume → structure text → /api/generate → present responses → save/regenerate → persist in MongoDB & localStorage.

- Client (Browser/Mobile): React UI pages, form inputs, file upload, UI state hooks, Tailwind styles
- Frontend Layer: Next.js Server-Side Rendering (SSR) / Client-Side React components
- API Layer (Next.js serverless functions):
– /api/parse-resume
– /api/generate
– /api/regenerate
– /api/webhooks/clerk
- Business Logic (lib/actions, lib/prompt, hooks)
- Persistence: MongoDB cluster (user, resume, response collections), LocalStorage (for unauthenticated or caching)
- External Services:
– Clerk (Auth + webhooks)
– pdf-parse (resume text extraction)
– Groq AI SDK (LLama model inference)
– PostHog (analytics events)
- CDN / Vercel (Deployment platform)

1. Client → Next.js pages/components (UI rendering, form submission)
2. Client → /api/parse-resume (upload PDF) → pdf-parse → structured text → returns JSON
3. Client → /api/generate or regenerate → Groq AI → generated responses → returns JSON
4. API Layer → lib/db.ts → MongoDB (CRUD operations)
5. API Layer → lib/posthog → PostHog
6. Client + server → Clerk (authentication flows, webhooks)
7. Client → LocalStorage (cache resume, temporary responses)

c. Architectural patterns/design principles:
- Full-stack monorepo using Next.js App Router (co-located front/back)
- Serverless API functions for microservices-style endpoints
- Layered separation: UI, API, business logic, persistence, external services
- Unidirectional data flow in React + local/global state via hooks & stores (Zustand or custom lib/store)
- Validation at form layer (Zod) and at API boundary

– Next.js 15 (App Router, turbopack)
– React + Tailwind CSS + Shadcn UI
– React Hook Form + Zod
– pdf-parse, Groq AI SDK (LLama 3.x)
– MongoDB, Mongoose (models)
– Clerk (Auth)
– PostHog (Analytics)

##### Elements
- Labels: Component names (e.g., “ResumeUploader.tsx”, “/api/generate”)
- Blue rectangles for UI components
- Green rounded for API functions
- Purple clouds for external services

##### Detail
- API route as its own node.
- Internal libraries (lib/actions, lib/prompt) as sub-components.
- Don’t omit middleware.ts (e.g., auth guard).
- Both client storage (LocalStorage) and server storage (MongoDB).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Layout["Root Layout\n(app/layout.tsx)"]:::frontend
        Home["Home Page\n(app/page.tsx)"]:::frontend
        AuthSignIn["Sign-In Page\n(app/(auth)/sign-in/[[...sign-in]]/page.tsx)"]:::frontend
        AuthSignUp["Sign-Up Page\n(app/(auth)/sign-up/[[...sign-up]]/page.tsx)"]:::frontend
        CreatePage["Resume Upload Page\n(app/create/page.tsx)"]:::frontend
        ResumeUploader["ResumeUploader.tsx"]:::frontend
        JobForm["JobForm.tsx"]:::frontend
        HistoryPage["History View Page\n(app/history/page.tsx)"]:::frontend
        ResponsePage["Single Response Page\n(app/response/[id]/page.tsx)"]:::frontend
        ResponseSection["ResponseSection.tsx"]:::frontend
        Navbar["Navbar.tsx"]:::frontend
        PostHogProvider["PostHogProvider.tsx"]:::frontend
        LocalStorage["LocalStorage\n(lib/storage.ts)"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        ParseResume["/api/parse-resume"]:::api
        Generate["/api/generate"]:::api
        Regenerate["/api/regenerate"]:::api
        ClerkWebhook["/api/webhooks/clerk"]:::api
        Middleware["middleware.ts"]:::api
    end

    %% Business Logic
    subgraph "Business Logic"
        direction TB
        ResumeAction["resume.action.ts"]:::logic
        ResponseAction["response.action.ts"]:::logic
        UserAction["user.action.ts"]:::logic
        PromptBuilder["prompt.ts"]:::logic
        DBConn["db.ts"]:::logic
        UserModel["user.model.ts"]:::logic
        ResumeModel["resume.model.ts"]:::logic
        ResponseModel["response.model.ts"]:::logic
        ContentStore["content-store.ts"]:::logic
        HistoryStore["history-store.ts"]:::logic
        ResumeStore["resume-store.ts"]:::logic
        HookAppState["useAppState.ts"]:::logic
        HookJobSubmit["useJobFormSubmit.ts"]:::logic
        HookResumeMgr["useResumeManager.ts"]:::logic
    end

    %% Persistence
    subgraph "Persistence"
        direction TB
        MongoDB["MongoDB Cluster"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Clerk["Clerk Auth"]:::service
        PDFParse["pdf-parse"]:::service
        GroqAI["Groq AI SDK"]:::service
        PostHog["PostHog"]:::service
        Vercel["Vercel/CDN"]:::service
    end

    %% Connections
    Layout -->|wraps| Navbar
    Layout -->|renders| Home
    Layout -->|renders| AuthSignIn
    Layout -->|renders| AuthSignUp
    Layout -->|renders| CreatePage
    Layout -->|renders| HistoryPage
    Layout -->|renders| ResponsePage

    Home -->|navigates to| CreatePage
    Navbar -->|links to| Home
    Navbar -->|links to| CreatePage
    Navbar -->|links to| HistoryPage

    CreatePage --> ResumeUploader
    CreatePage --> JobForm
    JobForm -->|submit PDF & job details| ParseResume
    ResumeUploader -->|upload PDF| ParseResume

    ParseResume -->|calls| PDFParse
    ParseResume -->|returns structured text| JobForm

    JobForm -->|submit for generation| Generate
    Generate -->|calls| PromptBuilder
    PromptBuilder -->|build prompt| GroqAI
    GroqAI -->|response| Generate
    Generate -->|returns JSON| ResponseSection

    ResponseSection -->|save/regenerate| Regenerate
    Regenerate -->|calls PromptBuilder| PromptBuilder
    Regenerate -->|returns JSON| ResponseSection

    Generate -->|log event| PostHog
    Regenerate -->|log event| PostHog

    ParseResume -->|log event| PostHog

    Generate -->|store| ResponseAction
    Regenerate -->|store| ResponseAction
    ParseResume -->|store| ResumeAction

    ResponseAction -->|CRUD| MongoDB
    ResumeAction -->|CRUD| MongoDB
    UserAction -->|CRUD| MongoDB
    DBConn -->|connects| MongoDB

    Generate -->|auth check| Middleware
    ParseResume -->|auth check| Middleware
    Regenerate -->|auth check| Middleware

    AuthSignIn -->|Clerk SDK| Clerk
    AuthSignUp -->|Clerk SDK| Clerk
    Clerk -->|webhook event| ClerkWebhook
    ClerkWebhook --> UserAction

    Home -->|init state| HookAppState
    CreatePage -->|uses| HookJobSubmit
    CreatePage -->|uses| HookResumeMgr

    CreatePage -->|cache| LocalStorage
    ResponseSection -->|cache| LocalStorage

    PostHogProvider -->|wraps| Layout

    %% Click events
    click Layout "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/layout.tsx"
    click Home "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/page.tsx"
    click AuthSignIn "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/(auth)/sign-in/[[...sign-in]]/page.tsx"
    click AuthSignUp "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/(auth)/sign-up/[[...sign-up]]/page.tsx"
    click CreatePage "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/create/page.tsx"
    click ResumeUploader "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/components/ResumeUploader.tsx"
    click JobForm "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/components/JobForm.tsx"
    click HistoryPage "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/history/page.tsx"
    click ResponsePage "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/response/[id]/page.tsx"
    click ResponseSection "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/components/ResponseSection.tsx"
    click Navbar "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/components/Navbar.tsx"
    click PostHogProvider "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/components/PostHogProvider.tsx"
    click ParseResume "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/api/parse-resume/route.ts"
    click Generate "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/api/generate/route.ts"
    click Regenerate "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/api/regenerate/route.ts"
    click ClerkWebhook "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/app/api/webhooks/clerk/route.ts"
    click ResumeAction "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/actions/resume.action.ts"
    click ResponseAction "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/actions/response.action.ts"
    click UserAction "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/actions/user.action.ts"
    click PromptBuilder "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/prompt.ts"
    click DBConn "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/db.ts"
    click UserModel "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/models/user.model.ts"
    click ResumeModel "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/models/resume.model.ts"
    click ResponseModel "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/models/response.model.ts"
    click LocalStorage "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/storage.ts"
    click ContentStore "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/store/content-store.ts"
    click HistoryStore "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/store/history-store.ts"
    click ResumeStore "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/lib/store/resume-store.ts"
    click HookAppState "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/hooks/useAppState.ts"
    click HookJobSubmit "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/hooks/useJobFormSubmit.ts"
    click HookResumeMgr "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/hooks/useResumeManager.ts"
    click Middleware "https://github.com/rithb898/fitforjob-ai-application-assistant/blob/main/middleware.ts"

    %% Styles
    classDef frontend fill:#CFE2FF,stroke:#0366d6,stroke-width:1px;
    classDef api fill:#D1E7DD,stroke:#0f5132,stroke-width:1px;
    classDef logic fill:#FFF3CD,stroke:#664d03,stroke-width:1px;
    classDef db fill:#F8D7DA,stroke:#842029,stroke-width:1px;
    classDef service fill:#E2E3E5,stroke:#41464b,stroke-width:1px;
```
