# shivoo29/looking-for-reason architecture

> Architecture diagram of the GitHub repository shivoo29/looking-for-reason, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shivoo29/looking-for-reason
- Repository: https://github.com/shivoo29/looking-for-reason

## Overview

##### Project type and purpose
- JobHack is a full-stack, end-to-end AI-powered job application automation platform.
- It consists of a Next.js 14 frontend, a Python FastAPI backend, a Chrome extension, AI/ML services, and various external integrations (DBs, storage, APIs).

##### File structure
- Top level: README and docs (ARCHITECTURE.md, API.md, DEPLOYMENT.md, etc.), docker-compose.yml, scripts.
- backend/: Python microservice built on FastAPI.
- app/api/v1/endpoints: REST endpoints for auth, resumes, applications, analytics, outreach, subscriptions, etc.
- app/services: AI‐centric services (resume parsing, JD parsing, ATS scoring, LaTeX generation, outreach).
- app/models.py, schemas.py, database.py, config.py.
- Dockerfile, requirements.txt.
- frontend/: Next.js application with App Router, TypeScript, Tailwind CSS, Shadcn UI components, Zustand store.
- src/app: pages (dashboard, root).
- src/components/ui: reusable UI primitives (buttons, cards, inputs).
- src/lib: api-client, utils.
- chrome-extension/: Manifest V3 assets (background.js, content.js, popup.html/js, styles).
- scripts/: Helpers for DB setup and dev environment.
- docker-compose.yml: local orchestration of frontend, backend, Postgres, Redis.

##### README for additional insights
- Tech stack calls out: PostgreSQL (Supabase), Redis, AWS S3, Pinecone, OpenAI/Claude, SendGrid/Resend, LinkedIn API, Stripe, Vercel/AWS/Railway, GitHub Actions, BullMQ.
- Core features show multiple layers: frontend UI, API layer, AI/ML pipeline, job board integration via extension, data storage, analytics.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side"
        direction TB
        FE["Next.js App"]:::frontend
        AppRouter["src/app"]:::frontend
        UIPrimitives["src/components/ui"]:::frontend
        APIClient["src/lib/api-client.ts"]:::frontend
        Store["src/store/use-store.ts"]:::frontend
        CE["Chrome Extension"]:::frontend
        Manifest["manifest.json"]:::frontend
        Background["background.js"]:::frontend
        ContentScript["content.js"]:::frontend
        Popup["popup.html/js"]:::frontend
        ContentCSS["content.css"]:::frontend
    end

    %% Server Side
    subgraph "Server Side"
        direction TB
        API["API Gateway / BFF"]:::backend

        subgraph "FastAPI Service"
            direction TB
            MAIN["main.py"]:::backend
            ROUTER["router.py"]:::backend
            ENDPOINTS["Endpoints (auth, resumes, job_descriptions, applications, outreach, analytics, subscription)"]:::backend
            MODELS["models.py & schemas.py"]:::backend
            DB["database.py"]:::backend
            CFG["config.py"]:::backend
        end

        subgraph "AI/ML Services"
            direction TB
            RP["resume_parser.py"]:::backend
            JD["jd_parser.py"]:::backend
            ATS["ats_scorer.py"]:::backend
            LATEX["latex_generator.py"]:::backend
            OUTG["outreach_generator.py"]:::backend
            OPT["ai_optimizer.py"]:::backend
        end

        EVTQ["BullMQ & Workers"]:::backend
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PG[(PostgreSQL)]:::datastore
        RD[(Redis)]:::datastore
        PC[(Pinecone)]:::datastore
        S3[(AWS S3 Storage)]:::datastore
    end

    %% Third-Party Integrations
    subgraph "Third-Party Integrations"
        direction TB
        LI["LinkedIn API"]:::external
        SG["SendGrid / Resend"]:::external
        ST["Stripe"]:::external
    end

    %% CI/CD & Hosting
    subgraph "CI/CD & Hosting"
        direction TB
        GH["GitHub Actions"]:::dev
        VC["Vercel / AWS / Railway"]:::dev
    end

    %% Relationships
    FE -->|uses| API
    AppRouter -->|calls| API
    CE -->|API calls| API
    API -->|routes to| MAIN
    MAIN -->|includes| ROUTER
    ROUTER -->|handles| ENDPOINTS
    ENDPOINTS -->|reads/writes| PG
    ENDPOINTS -->|caches| RD
    ENDPOINTS -->|triggers| RP
    RP -->|uploads| S3
    RP -->|stores| PG
    ENDPOINTS -->|uses| JD
    JD -->|indexes| PC
    ENDPOINTS -->|executes| ATS
    ENDPOINTS -->|executes| LATEX
    LATEX -->|stores PDF| S3
    ENDPOINTS -->|enqueues| OUTG
    OUTG -->|queues| EVTQ
    EVTQ -->|reads| RD
    EVTQ -->|sends| SG
    EVTQ -->|sends| LI
    ENDPOINTS -->|handles webhooks| ST
    MAIN -->|loads| CFG
    DB -->|configured by| CFG

    %% CI/CD relationships
    GH -->|deploys| VC
    VC -->|hosts| FE
    VC -->|hosts| API

    %% Click Events
    click FE "https://github.com/shivoo29/looking-for-reason/tree/main/frontend/"
    click AppRouter "https://github.com/shivoo29/looking-for-reason/tree/main/frontend/src/app/"
    click UIPrimitives "https://github.com/shivoo29/looking-for-reason/tree/main/frontend/src/components/ui/"
    click APIClient "https://github.com/shivoo29/looking-for-reason/blob/main/frontend/src/lib/api-client.ts"
    click Store "https://github.com/shivoo29/looking-for-reason/blob/main/frontend/src/store/use-store.ts"
    click CE "https://github.com/shivoo29/looking-for-reason/tree/main/chrome-extension/"
    click Manifest "https://github.com/shivoo29/looking-for-reason/blob/main/chrome-extension/manifest.json"
    click Background "https://github.com/shivoo29/looking-for-reason/blob/main/chrome-extension/background.js"
    click ContentScript "https://github.com/shivoo29/looking-for-reason/blob/main/chrome-extension/content.js"
    click Popup "https://github.com/shivoo29/looking-for-reason/blob/main/chrome-extension/popup.html"
    click ContentCSS "https://github.com/shivoo29/looking-for-reason/blob/main/chrome-extension/content.css"
    click MAIN "https://github.com/shivoo29/looking-for-reason/blob/main/backend/main.py"
    click ROUTER "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/api/v1/router.py"
    click ENDPOINTS "https://github.com/shivoo29/looking-for-reason/tree/main/backend/app/api/v1/endpoints/"
    click MODELS "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/models.py"
    click DB "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/database.py"
    click CFG "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/config.py"
    click RP "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/services/resume_parser.py"
    click JD "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/services/jd_parser.py"
    click ATS "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/services/ats_scorer.py"
    click LATEX "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/services/latex_generator.py"
    click OUTG "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/services/outreach_generator.py"
    click OPT "https://github.com/shivoo29/looking-for-reason/blob/main/backend/app/services/ai_optimizer.py"
    click DB "https://github.com/shivoo29/looking-for-reason/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#aedff7,stroke:#1e73be;
    classDef backend fill:#c8e6c9,stroke:#388e3c;
    classDef datastore fill:#ffe0b2,stroke:#f57c00,stroke-width:2px;
    classDef external stroke-dasharray:5 5,fill:#ffffff;
    classDef dev fill:#e1bee7,stroke:#8e24aa;
```
