automated-job-tracker

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #golang #deep-learning #macos #nodejs #awesome #cli #ios #mcp #openai

automated-job-tracker

(★ 11)

Help you track your job applications automatically by fetching and processing emails from your Gmail account.

automated-job-tracker 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Automated Job Tracker

Do you apply to hundreds of jobs then often forget to track their statuses since there are too much? Yeah, same here. So I created an app that can automatically read you email and update the job application status to Google sheet. This saved me so much time and I hope it would do the same for you.

![Demo](https://raw.githubusercontent.com/ngavu2004/automated-job-tracker/main/public/demo.gif)

## Features

- Fetch unread recruiter emails from Gmail
- Extract job application data (job title, company name, application status) from emails
- Store and manage job application data in a PostgreSQL database
- View and edit job application data through a REST API
- Clear email records from the database
- Integrate with Google Sheets for job data storage
- OpenAI API integration for advanced processing

## Usage

Here is a step by step tutorial on how to use the app.
1. Login with your Google account
    - If you see the screen this app is not secured, I haven't done verifying it with Google yet (sorry it takes 4 - 6 weeks). I would try to complete this ASAP.

2. Connect the desired Google sheet.
    - Create a Google sheet to track your job. Put the link to the sheet in the Google sheet tab and hit "Connect".

3. (First time user only) If you are first time user, the app will ask you to put a time from which you want it to read the email.

4. Hit fetch job.
    - After the first time user set up, the next time you hit "Fetch Job", it would automatically handles emails based on your last time using the app.

5. Open the Google sheet and you will see the jobs automatically added.

## Deployment

For detailed deployment instructions including:
- Local development setup
- Production deployment (Heroku, Render, Docker, VPS)
- Environment configuration
- Running the API and Celery worker
- Monitoring and troubleshooting

**Please see [DEPLOYMENT.md](DEPLOYMENT.md)** for the complete guide.

## Architecture

This application is built using Django REST Framework with Celery for asynchronous task processing. It integrates with Gmail API to fetch emails, OpenAI API to extract job application data, and Google Sheets API to store the data.

### Technology Stack

- **Backend**: Django 5.1.6, Django REST Framework 3.15.2
- **Authentication**: JWT (djangorestframework-simplejwt), Google OAuth 2.0
- **Task Queue**: Celery 5.5.2 with RabbitMQ
- **Database**: PostgreSQL (production), SQLite (mock mode)
- **External APIs**: Gmail API, Google Sheets API, OpenAI API (GPT-4o-mini)
- **Deployment**: Gunicorn, WhiteNoise for static files

## File Structure

```
automated-job-tracker/
├── jobtracker_backend_api/          # Main Django project directory
│   ├── service_provider/            # Main Django app
│   │   ├── migrations/              # Database migrations
│   │   ├── tests/                   # Test files
│   │   │   ├── test_email_services.py
│   │   │   └── test_env.py
│   │   ├── __init__.py
│   │   ├── admin.py                 # Django admin configuration
│   │   ├── apps.py                  # App configuration
│   │   ├── auth.py                  # Custom JWT authentication from cookies
│   │   ├── authenticate.py          # Google API service initialization
│   │   ├── email_services.py        # Gmail API integration and email processing
│   │   ├── googlesheet_services.py  # Google Sheets API integration
│   │   ├── models.py                # Database models (User, JobApplied, FetchLog, GoogleSheet)
│   │   ├── parsers.py               # OpenAI/Ollama extractors for email parsing
│   │   ├── serializers.py           # DRF serializers
│   │   ├── tasks.py                 # Celery tasks
│   │   └── views.py                 # API endpoints
│   ├── __init__.py
│   ├── asgi.py                      # ASGI configuration
│   ├── celery.py                    # Celery configuration
│   ├── settings.py                  # Django settings (production)
│   ├── test_settings.py             # Django settings (testing)
│   ├── urls.py                      # URL routing
│   └── wsgi.py                      # WSGI configuration
├── notebooks/                       # Jupyter notebooks (if any)
├── public/                          # Public assets
│   └── demo.gif
├── staticfiles/                     # Collected static files
├── docker-compose.mock.yml          # Docker compose for mock/testing
├── manage.py                        # Django management script
├── Makefile                         # Make commands
├── Procfile                         # Heroku/deployment configuration
├── pyproject.toml                   # Python project configuration
├── requirements.txt                 # Python dependencies
├── CODE_OF_CONDUCT.md              # Code of conduct
├── CONTRIBUTING.md                  # Contribution guidelines
├── LICENSE                          # MIT License
└── README.md                        # This file
```

### Key Components

#### Models (`models.py`)
- **User**: Custom user model with Google OAuth tokens and sheet ID
- **JobApplied**: Stores job application data (title, company, status, sender email)
- **FetchLog**: Tracks when emails were last fetched for each user
- **GoogleSheet**: Stores Google Sheet IDs (currently not actively used)

#### Services
- **email_services.py**: Handles Gmail API integration, email fetching, parsing, and classification
- **googlesheet_services.py**: Manages Google Sheets operations (reading, writing job data)
- **authenticate.py**: Initializes and manages Google API service clients
- **parsers.py**: Uses OpenAI API to extract structured job data from email content

#### Tasks (`tasks.py`)
- **fetch_emails_task**: Celery task that asynchronously processes emails in the background

## API Endpoints

### Authentication Endpoints

#### `GET /auth/google/login/`
Initiates Google OAuth 2.0 login flow.

**Query Parameters:**
- `redirect_uri` (optional): Frontend URL to redirect after authentication

**Response:** Redirects to Google OAuth consent screen

---

#### `GET /auth/google/callback/`
Handles Google OAuth callback and creates/updates user session.

**Query Parameters:**
- `code`: Authorization code from Google
- `state`: State parameter containing redirect URI

**Response:** Sets JWT access token in HTTP-only cookie and redirects to frontend

---

### User Endpoints

Base URL: `/users/`

#### `GET /users/`
Get current authenticated user information.