# quangdungluong/job-finder architecture

> Architecture diagram of the GitHub repository quangdungluong/job-finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/quangdungluong/job-finder
- Repository: https://github.com/quangdungluong/job-finder

## Overview

##### Project type and purpose
- From the file tree and README, this is a full-stack web application called “LinkedIn-Job-Explorer.”
- Frontend: A Next.js/React app under the `frontend/` directory.
- Backend: A Python service (scripts `main.py` and `server.py`) that reads user configs, scrapes or fetches job listings (via modules in `src/`), filters them, and serves them to the frontend.
- Configurations: YAML files in `configs/` for secrets (LinkedIn credentials) and work preferences.
- Orchestration: Docker Compose setup under `docker/docker-compose.yaml`.
- CI/CD and quality tools: GitHub workflows, ESLint, Pre-commit, style-check, tests under `tests/`.

##### File structure
- Top-level directories:
- `frontend/` – stateless UI components, pages, CSS, Next.js config.
- `src/` – Python modules:
– `authenticator.py`: handles LinkedIn authentication
– `job_manager.py` plus `itviec_job_manager.py`, `topcv_job_manager.py` – source-specific scraping/fetching logic
– `job.py`, `models.py`: domain models for jobs, filters
– `config_validator.py`, `clean_blacklist.py`, `regex_utils.py`, `utils.py` – supporting utilities
– `logger.py` – application logging
- `configs/` – sample YAMLs for secrets and preferences
- `docker/` – container definitions and Compose file
- `main.py` – CLI entrypoint to run in interactive mode
- `server.py` – HTTP server exposing REST endpoints to the frontend
- `tests/` – pytest suite for core logic
- `.github/workflows/` – CI for linting and style

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Frontend["Next.js Frontend"]:::frontend
        GlobalStyles["Global Styles & Layout"]:::frontend
        Components["UI Components"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Service"
        direction TB
        CLI["Interactive CLI (main.py)"]:::backend
        API["HTTP Server (server.py)"]:::backend
        Auth["Authenticator Module"]:::backend
        JobMgr["Job Manager Core"]:::backend
        subgraph "Job Manager Plugins"
            direction TB
            Itviec["Itviec Plugin"]:::backend
            TopCV["TopCV Plugin"]:::backend
        end
        Domain["Domain Models"]:::backend
        Validator["Config Validator"]:::backend
        Cleaner["Blacklist Cleaner"]:::backend
        Regex["Regex Utilities"]:::backend
        Utils["General Utilities"]:::backend
        Logger["Logger"]:::backend
    end

    %% Configuration Store
    Config["Configuration Store (YAML)"]:::config

    %% Orchestration
    Docker["Docker Compose"]:::infra

    %% External Services
    subgraph "External Sources"
        direction TB
        LinkedIn["LinkedIn Site"]:::external
        ItviecAPI["Itviec API"]:::external
        TopCVAPI["TopCV API"]:::external
    end

    %% CI/CD & Tests
    subgraph "CI/CD & Testing"
        direction TB
        CI["GitHub Actions"]:::ci
        Precommit["Pre-commit Config"]:::ci
        ESLint["ESLint Config"]:::ci
        Tests["Pytest Suite"]:::ci
    end

    %% Connections
    Frontend -->|HTTP REST| API
    API -->|loads| Config
    API -->|calls Auth| Auth
    Auth -->|uses| Config
    API -->|invokes| Validator
    API -->|invokes| Cleaner
    API -->|invokes| Regex
    API -->|invokes| Utils
    API -->|logs to| Logger
    JobMgr -->|manages| Domain
    API -->|uses| JobMgr
    JobMgr -->|plugin| Itviec
    JobMgr -->|plugin| TopCV
    Itviec -->|HTTP| ItviecAPI
    TopCV -->|HTTP| TopCVAPI
    API -->|reads CLI args| CLI
    Docker -->|orchestrates| Frontend
    Docker -->|orchestrates| API
    Docker -->|mounts| Config
    CI -->|runs| ESLint
    CI -->|runs| Precommit
    CI -->|runs| Tests

    %% Click Events
    click Frontend "https://github.com/quangdungluong/job-finder/tree/master/frontend/"
    click GlobalStyles "https://github.com/quangdungluong/job-finder/blob/master/frontend/app/globals.css"
    click GlobalStyles "https://github.com/quangdungluong/job-finder/blob/master/frontend/app/layout.js"
    click GlobalStyles "https://github.com/quangdungluong/job-finder/blob/master/frontend/app/page.js"
    click Components "https://github.com/quangdungluong/job-finder/blob/master/frontend/components/JobCard.js"
    click Components "https://github.com/quangdungluong/job-finder/blob/master/frontend/components/JobDetails.js"
    click Components "https://github.com/quangdungluong/job-finder/blob/master/frontend/components/JobSourceFilter.js"
    click Components "https://github.com/quangdungluong/job-finder/blob/master/frontend/components/LocationFilter.js"
    click Components "https://github.com/quangdungluong/job-finder/blob/master/frontend/components/ThemeProvider.jsx"
    click Components "https://github.com/quangdungluong/job-finder/blob/master/frontend/components/ThemeToggle.jsx"
    click CLI "https://github.com/quangdungluong/job-finder/blob/master/main.py"
    click API "https://github.com/quangdungluong/job-finder/blob/master/server.py"
    click Auth "https://github.com/quangdungluong/job-finder/blob/master/src/authenticator.py"
    click JobMgr "https://github.com/quangdungluong/job-finder/blob/master/src/job_manager.py"
    click Itviec "https://github.com/quangdungluong/job-finder/blob/master/src/itviec_job_manager.py"
    click TopCV "https://github.com/quangdungluong/job-finder/blob/master/src/topcv_job_manager.py"
    click Domain "https://github.com/quangdungluong/job-finder/blob/master/src/job.py"
    click Domain "https://github.com/quangdungluong/job-finder/blob/master/src/models.py"
    click Validator "https://github.com/quangdungluong/job-finder/blob/master/src/config_validator.py"
    click Cleaner "https://github.com/quangdungluong/job-finder/blob/master/src/clean_blacklist.py"
    click Regex "https://github.com/quangdungluong/job-finder/blob/master/src/regex_utils.py"
    click Utils "https://github.com/quangdungluong/job-finder/blob/master/src/utils.py"
    click Logger "https://github.com/quangdungluong/job-finder/blob/master/src/logger.py"
    click Config "https://github.com/quangdungluong/job-finder/blob/master/configs/secrets.yaml.sample"
    click Config "https://github.com/quangdungluong/job-finder/blob/master/configs/work_preferences.yaml.sample"
    click Docker "https://github.com/quangdungluong/job-finder/blob/master/docker/docker-compose.yaml"
    click Docker "https://github.com/quangdungluong/job-finder/blob/master/docker/.env.template"
    click CI "https://github.com/quangdungluong/job-finder/blob/master/.github/workflows/pr-lint.yaml"
    click CI "https://github.com/quangdungluong/job-finder/blob/master/.github/workflows/style-check.yaml"
    click Precommit "https://github.com/quangdungluong/job-finder/blob/master/.pre-commit-config.yaml"
    click ESLint "https://github.com/quangdungluong/job-finder/blob/master/frontend/eslint.config.mjs"
    click Tests "https://github.com/quangdungluong/job-finder/blob/master/tests/test_job_manager.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#005B96,stroke-width:1px
    classDef backend fill:#E8F4FF,stroke:#004080,stroke-width:1px
    classDef config fill:#E2FFD9,stroke:#008000,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
    classDef infra fill:#FFE8D0,stroke:#D2691E,stroke-width:1px
    classDef ci fill:#FFF3CD,stroke:#856404,stroke-width:1px
```
