# h-strangeone/easy_reject architecture

> Architecture diagram of the GitHub repository h-strangeone/easy_reject, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/h-strangeone/easy_reject
- Repository: https://github.com/h-strangeone/easy_reject

## Overview

##### What this project is (type + purpose)
**JobTracker** is a **local-first desktop tool** (single-machine application) that:
- Authenticates to **Gmail via Google OAuth (Desktop App flow)**,
- Reads emails via the **Gmail API (read-only)**,
- Extracts/infers “job application events” (applied / rejected / assessment / interview),
- Stores and organizes results in a **local database**,
- Optionally enriches classification/extraction using an **LLM API** (README mentions Groq + llama-3.1-8b-instant, but it’s pluggable).

The project is small and likely **monolithic** (one Python process) with clear internal modules:
- `app.py` (entrypoint + UI + orchestration)
- `gmail_scanner.py` (Gmail API interaction + email parsing/classification)
- `database.py` (local persistence abstraction)

Build/deploy artifacts:
- `JobTracker.spec`, `build_exe.bat` (packaging into an .exe, likely via PyInstaller)
- `Run JobTracker.bat`, `install.bat` (local execution + dependency install)

##### Core runtime (single process)
- **`app.py`**
Treat as the **Application Layer**: UI, settings, “Scan Gmail Now” action, wiring together scanner + DB, config handling, possibly token/credential selection.
- **`gmail_scanner.py`**
Treat as the **Integration + Domain Logic**: Gmail OAuth/token usage, Gmail API calls, message retrieval, filtering, extraction, optional LLM callouts.
- **`database.py`**
Treat as the **Persistence Layer**: schema, CRUD for companies/applications/events/status history.

- **`requirements.txt`** (runtime deps)
- **`JobTracker.spec` + `build_exe.bat`** (packaging pipeline)
- **`Run JobTracker.bat` + `install.bat`** (execution + install shortcuts)

##### External / user-provided artifacts (implied by README)
- **`credentials.json`** (Google OAuth client secret for Desktop App)
- **OAuth tokens** (often `token.json` or similar; not listed, but typically generated at runtime)
- **Local DB file** (SQLite file likely; name unknown)
- **Local settings/config** (accounts to scan, credential path, optional LLM key)

When drawing, it’s OK (and recommended) to include these “implied” runtime artifacts because they are essential to how the system actually works.

##### What to put

**Actors / external systems:**
- User (local machine)
- Google OAuth Authorization Server (login/consent in browser)
- Gmail API (Google)
- Optional LLM Provider API (Groq / OpenAI / Anthropic etc.)

**System:**
- JobTracker Desktop App (local)

**Key flows:**
- User triggers scan
- OAuth consent happens in browser; app receives/loads tokens
- App reads emails from Gmail API
- App optionally calls LLM API for classification/context extraction
- App writes results to local DB
- App displays results to user

##### JobTracker App (Python process / packaged EXE)
- UI + orchestration (`app.py`)
- Gmail scanning module (`gmail_scanner.py`)
- Database module (`database.py`)
##### Local Storage
- DB (SQLite/file-based)
- OAuth tokens (file)
- Settings/config (file)
- `credentials.json` (user-provided)

**Outside**
##### LLM API (optional)

- App → Google OAuth: “Request user consent / auth code”
- Google OAuth → App: “Token (refresh/access)”
- App → Gmail API: “Fetch message metadata/content”
- App → LLM API (optional): “Classify / extract job status”
- App → Local DB: “Persist application/company/status timeline”
- App → UI: “Render tracking dashboard”

##### UI / Controller (app.py)
- Settings screen (select `credentials.json`, add accounts)
- Scan action (“Scan Gmail Now”)
- Results views (companies/status)
- Error handling + progress
##### Gmail Scanner (gmail_scanner.py)
- Auth/token handling (load/refresh token)
- Gmail query builder (job-related heuristics)
- Message fetcher (list messages, get content)
- Parser/classifier (rules + optional LLM)
- Event normalizer (map to statuses: applied/rejected/interview/etc.)
##### Database Access Layer (database.py)
- Schema (tables: companies, applications, messages/events)
- Upserts/dedup (avoid reprocessing)
- Queries for UI

**Optional subcomponent**
- Provider adapter (Groq now, but “pluggable”)

##### If needed, OAuth happens
- Browser opens to Google OAuth
- User consents
- App stores **token** locally
##### For each email
- Parse subject/sender/body
- Classify status (rules and/or **LLM API call**)
- Store/update records in local DB
##### UI queries DB and renders updated tracking view

- **Local-first / privacy-preserving**: no email content is sent anywhere except:
- Gmail API (obviously), and
- **Layered monolith**:
- Presentation (UI) → Domain/Integration (scanner) → Persistence (DB)
- **External integration via OAuth2 + REST APIs**:
- Gmail API access is gated by OAuth tokens
- **Optional “provider adapter” pattern** for LLM:

##### Technologies/frameworks to label (only what’s materially architectural)
- **Python 3.9+**
- **Google OAuth 2.0 (Desktop App)** + **Gmail API**
- **Local DB (likely SQLite)** via `database.py`
- **Optional LLM API (Groq / llama-3.1-8b-instant)** as an external service
- **PyInstaller packaging** (in a separate “Build/Distribution” lane): `JobTracker.spec`, `build_exe.bat`

##### Build/Packaging Pipeline
`requirements.txt` → install.bat/pip; `JobTracker.spec` + `build_exe.bat` → EXE; `Run JobTracker.bat` → launches EXE/python.

##### Suggested component list (don’t omit)
- JobTracker UI/Orchestrator (`app.py`)
- Gmail Scanner (`gmail_scanner.py`)
- Database Layer (`database.py`)
- Local DB file
- credentials.json
- OAuth token store
- Google OAuth endpoint
- Gmail API endpoint
- LLM Provider API endpoint
- Build pipeline (PyInstaller spec + batch scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Pane 1: Runtime (Context + Containers)
%% =========================
subgraph "Runtime Architecture (Local-first Desktop App)"
direction TB

    User["User"]:::actor

    subgraph "User Machine"
    direction TB

        AppProc["JobTracker Desktop App\n(Python process / Packaged EXE)"]:::container

        subgraph "Internal Modules (Layered Monolith)"
        direction TB
            UI["UI / Controller\n(app.py)"]:::module
            Scanner["Gmail Scanner\n(gmail_scanner.py)"]:::module
            LLMClient["LLM Client (Optional)\n(provider adapter)"]:::optional
            DBLayer["Database Access Layer\n(database.py)"]:::module
        end

        subgraph "Local Storage (Files)"
        direction TB
            Creds["Google OAuth Client Secrets\n(credentials.json)"]:::file
            TokenStore["OAuth Token Store\n(access/refresh tokens)"]:::file
            Settings["Local Settings / Config"]:::file
            LocalDB[("Local Database\n(SQLite file)")]:::db
        end

        AppProc -->|"hosts"| UI
        AppProc -->|"hosts"| Scanner
        AppProc -->|"hosts"| DBLayer
        Scanner -->|"uses (optional)"| LLMClient

        UI -->|"read/write settings"| Settings
        UI -->|"selects"| Creds

        Scanner -->|"loads client secrets"| Creds
        Scanner -->|"reads/writes tokens"| TokenStore
        UI -->|"renders from queries"| DBLayer
        Scanner -->|"persist events"| DBLayer
        DBLayer -->|"CRUD"| LocalDB
    end

    subgraph "Internet Services"
    direction TB
        GoogleOAuth["Google OAuth 2.0\n(Desktop App Flow)"]:::external
        GmailAPI["Gmail API\n(read-only)"]:::external
        LLMAPI["LLM Provider API\n(Groq / others)"]:::externalOptional
    end

    User -->|"clicks Scan Gmail Now"| UI

    %% OAuth + Gmail flows
    Scanner -->|"request consent / auth code"| GoogleOAuth
    GoogleOAuth -->|"issue tokens"| TokenStore
    Scanner -->|"fetch message metadata/content"| GmailAPI

    %% Optional LLM enrichment (privacy caveat)
    LLMClient -.->|"classify / extract\n(optional,user-configured)"| LLMAPI

    %% UI feedback loop
    DBLayer -->|"query results"| UI
    UI -->|"display dashboard"| User
end

%% =========================
%% Pane 2: Primary Scan Flow (dynamic view)
%% =========================
subgraph "Primary Scan Flow (Annotated Data Flow)"
direction TB
    Step1["1) User triggers scan in UI"]:::step
    Step2["2) Load credentials + settings"]:::step
    Step3["3) OAuth if needed\n(store/refresh token)"]:::step
    Step4["4) Query Gmail API for relevant emails"]:::step
    Step5["5) Parse + classify\n(rules and/or optional LLM)"]:::step
    Step6["6) Upsert into local DB\n(company/application/status timeline)"]:::step
    Step7["7) UI refreshes from DB"]:::step

    Step1 --> Step2 --> Step3 --> Step4 --> Step5 --> Step6 --> Step7

    Step1 -->|"maps to"| UI
    Step2 -->|"uses"| Creds
    Step3 -->|"writes"| TokenStore
    Step4 -->|"calls"| GmailAPI
    Step5 -.->|"optional call"| LLMAPI
    Step6 -->|"via"| DBLayer
    Step6 -->|"writes"| LocalDB
    Step7 -->|"via"| DBLayer
end

%% =========================
%% Pane 3: Build / Packaging Pipeline
%% =========================
subgraph "Build / Distribution (Non-runtime)"
direction TB
    Req["requirements.txt\n(Python runtime deps)"]:::build
    Install["install.bat\n(setup environment/deps)"]:::build
    Spec["JobTracker.spec\n(PyInstaller config)"]:::build
    BuildExe["build_exe.bat\n(package into EXE)"]:::build
    Exe["Packaged JobTracker EXE"]:::artifact
    Run["Run JobTracker.bat\n(launch app)"]:::build
    Docs["readme.md\n(usage, OAuth/LLM notes)"]:::doc

    Req -->|"pip installs"| Install
    Spec -->|"PyInstaller uses"| BuildExe
    BuildExe -->|"produces"| Exe
    Exe -->|"started by"| Run

    Docs -->|"guides setup"| Install
    Docs -->|"explains packaging"| BuildExe
end

%% Cross-pane ties (kept minimal)
Run -->|"launches"| AppProc
Install -->|"installs deps for"| AppProc

%% =========================
%% Click Events (from component mapping)
%% =========================
click UI "https://github.com/h-strangeone/easy_reject/blob/master/app.py"
click Scanner "https://github.com/h-strangeone/easy_reject/blob/master/gmail_scanner.py"
click DBLayer "https://github.com/h-strangeone/easy_reject/blob/master/database.py"
click Req "https://github.com/h-strangeone/easy_reject/blob/master/requirements.txt"
click Spec "https://github.com/h-strangeone/easy_reject/blob/master/JobTracker.spec"
click BuildExe "https://github.com/h-strangeone/easy_reject/blob/master/build_exe.bat"
click Run "https://github.com/h-strangeone/easy_reject/blob/master/Run JobTracker.bat"
click Install "https://github.com/h-strangeone/easy_reject/blob/master/install.bat"
click Docs "https://github.com/h-strangeone/easy_reject/blob/master/readme.md"

%% =========================
%% Styles
%% =========================
classDef actor fill:#0b1320,stroke:#7dd3fc,stroke-width:2px,color:#e5e7eb
classDef container fill:#111827,stroke:#a78bfa,stroke-width:2px,color:#e5e7eb
classDef module fill:#1f2937,stroke:#34d399,stroke-width:2px,color:#e5e7eb
classDef optional fill:#1f2937,stroke:#fbbf24,stroke-width:2px,color:#e5e7eb,stroke-dasharray:6 4
classDef external fill:#0f172a,stroke:#60a5fa,stroke-width:2px,color:#e5e7eb
classDef externalOptional fill:#0f172a,stroke:#f59e0b,stroke-width:2px,color:#e5e7eb,stroke-dasharray:6 4
classDef db fill:#0b1320,stroke:#22c55e,stroke-width:2px,color:#e5e7eb
classDef file fill:#0b1320,stroke:#93c5fd,stroke-width:2px,color:#e5e7eb
classDef build fill:#1f2937,stroke:#fb7185,stroke-width:2px,color:#e5e7eb
classDef artifact fill:#111827,stroke:#f472b6,stroke-width:2px,color:#e5e7eb
classDef doc fill:#111827,stroke:#c4b5fd,stroke-width:2px,color:#e5e7eb
classDef step fill:#111827,stroke:#e5e7eb,stroke-width:1.5px,color:#e5e7eb
```
