Job Application Tracker Backend

RESTful API for managing and tracking job applications. This system allows tracking of status evolution of job postings, attaching documents (CV, cover letter, etc.), and maintaining a complete history of each application.

Tech Stack

• Framework: NestJS with Fastify adapter
• Language: TypeScript
• Database: PostgreSQL 18
• ORM: TypeORM
• Authentication: JWT (JSON Web Tokens)
• Validation: class-validator + class-transformer
• API Documentation: Swagger/OpenAPI
• Testing: Jest + Supertest
• Logging: Winston
• Containerization: Docker + Docker Compose
• Storage: MinIO (S3-compatible object storage)

Key Features

Application Management

• Create, read, update, and delete job applications
• Link to job offer
• Summary and notes for each application
• Complete status change history

Status Tracking

• Predefined statuses (Wishlist, Applied, Interview, Offer, Rejected, etc.)
• Automatic recording of every status change
• Chronological history with dates and notes

Document Management

• Secure CV upload (PDF)
• Cover letters and other documents
• Multiple file associations per application
• File type and size validation
• Storage via MinIO

Security

• Robust JWT authentication
• Role-based access control (RBAC)
• Input validation and sanitization
• Rate limiting to prevent abuse
• Protection against SQL injection and XSS

Quality

• Unit, integration, and E2E tests
• Code coverage >80%
• Auto-generated Swagger documentation
• Readable and maintainable code
• Automated linting and formatting

Project Structure

job_project/
├── README.md                          # This file
├── PLANNING.md                        # Detailed development planning
├── CHANGELOG.md                        # Version history and changes
├── .gitignore                         # Git ignore patterns
├── docs/                              # Rules and guidelines
│   ├── 00-architecture.md            # Architecture and patterns
│   ├── 01-database.md                 # Database and schema
│   ├── 02-api-design.md               # RESTful API design
│   ├── 03-security.md                 # Security and best practices
│   ├── 04-testing.md                  # Testing strategy
│   ├── 05-documentation.md            # Documentation and Swagger
│   └── 06-code-style.md               # Code style and conventions
├── docker/                            # Docker configuration
│   ├── data.yml                      # Docker Compose configuration
│   ├── run.sh                       # Startup script for Docker services
│   ├── secrets/                      # Passwords and secrets
│   │   ├── postgres_password.txt
│   │   └── minio_password.txt
│   └── data/                        # Persistent data volumes
│       ├── postgres/
│       └── minio/
└── job-tracker-backend/                # Backend application
    ├── src/                          # Source code
    ├── DATABASE_SETUP.md              # Database setup guide
    ├── package.json                  # Dependencies and scripts
    ├── .env                        # Environment variables (development) - NOT in git
    ├── .env.example                 # Environment variables template
    └── .gitignore                   # Git ignore patterns

Quick Start

Prerequisites

• Node.js >= 18.x
• Docker and Docker Compose
• npm or yarn or pnpm

Installation

1. Clone the project

git clone <repository-url>
cd job_project

2. Install backend dependencies

cd job-tracker-backend
npm install

3. Configure environment variables

Copy the environment variables template to create your local configuration:

cd job-tracker-backend
cp .env.example .env

Edit job-tracker-backend/.env with your specific configuration if needed.

Note: The .env file is excluded from version control via .gitignore to protect sensitive information (passwords, API keys, etc.). It will not be published to Git.

4. Start Docker services

Run the startup script from project root:

cd /Users/macbook/Desktop/job_project
./docker/run.sh

This script will:

• Stop any existing containers
• Start PostgreSQL database (port 5432) - Container: job-tracker-postgres
• Start MinIO storage service (ports 9000, 9001) - Container: job-tracker-minio
• Configure MinIO client
• Create a jobs-tracker bucket

5. Create development database

# Connect to PostgreSQL with new container name
docker exec -it job-tracker-postgres psql -U postgres -c "CREATE DATABASE job_tracker_dev;"

6. Test database connection

cd job-tracker-backend
npm run db:test

7. Run migrations

npm run migration:run

8. Start development server

npm run start:dev

The API will be available at http://localhost:3000 and Swagger documentation at http://localhost:3000/api.

Docker Services

The project includes a complete Docker setup in docker/data.yml with explicit container names:

PostgreSQL:

• Image: postgres:18.2-alpine3.22
• Port: 5432
• User: postgres
• Password: See docker/secrets/postgres_password.txt
• Production DB: job_tracker
• Development DB: job_tracker_dev (must be created)
• Container Name: job-tracker-postgres

MinIO (Object Storage):

• Image: minio/minio
• API Port: 9000
• Console Port: 9001
• User: minio
• Password: See docker/secrets/minio_password.txt
• Container Name: job-tracker-minio
• Access: http://localhost:9001 (MinIO Console)

Documentation

Development Planning

See PLANNING.md for:

• Detailed 8-week planning
• Tasks per phase with deadlines
• Expected deliverables
• Validation criteria
• Quality checklists

Rules and Guidelines

The docs/ folder contains all the rules to guide development:

• Architecture: Models, patterns, modular structure
• Database: Schema, migrations, relationships, indexes
• API Design: RESTful conventions, pagination, validation
• Security: Authentication, authorization, OWASP
• Testing: Strategy, tools, test examples
• Documentation: Swagger, JSDoc, conventions
• Code Style: TypeScript conventions, ESLint, Prettier

These rules are essential for maintaining quality and code consistency, especially during AI-assisted development.

Database Setup

See job-tracker-backend/DATABASE_SETUP.md for:

• Complete Docker setup instructions
• Database creation and management
• Migration commands
• Troubleshooting guide
• MinIO configuration details

Environment Variables

Environment variables are configured in job-tracker-backend/.env. Here are the main variables:

# Application
NODE_ENV=development
PORT=3000
API_PREFIX=api/v1

# Database
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=password
DB_DATABASE=job_tracker_dev

# Authentication
JWT_SECRET=dev_super_secret_key_minimum_32_characters
JWT_EXPIRATION=15m
JWT_REFRESH_SECRET=dev_refresh_secret_key_minimum_32_characters
JWT_REFRESH_EXPIRATION=7d

# Files
MAX_FILE_SIZE=10485760
ALLOWED_MIME_TYPES=application/pdf,application/msword,application/vnd.openxmlformats-officedocument.wordprocessingml.document,text/plain

# Security
BCRYPT_ROUNDS=12
RATE_LIMIT_TTL=60
RATE_LIMIT_MAX=100
CORS_ORIGINS=http://localhost:3000,http://localhost:4200

# Logging
LOG_LEVEL=debug
LOG_DIR=./logs

# Swagger
SWAGGER_TITLE=Job Application Tracker API
SWAGGER_DESCRIPTION=API for tracking job applications
SWAGGER_VERSION=1.0
SWAGGER_PATH=docs

# MinIO Storage
MINIO_ENDPOINT=localhost
MINIO_PORT=9000
MINIO_ACCESS_KEY=minio
MINIO_SECRET_KEY=password
MINIO_BUCKET_NAME=jobs-tracker
MINIO_USE_SSL=false
MINIO_REGION=us-east-1

Testing

# Run all tests
npm run test

# Tests with coverage
npm run test:cov

# Tests in watch mode
npm run test:watch

# E2E tests
npm run test:e2e

Database Operations

# Generate a migration
npm run migration:generate -- -n MigrationName

# Run pending migrations
npm run migration:run

# Show migration status
npm run migration:show

# Revert last migration
npm run migration:revert

# Test database connection
npm run db:test

API Usage

Main Endpoints

# Authentication
POST /api/v1/auth/register  # Register
POST /api/v1/auth/login      # Login

# Applications
GET    /api/v1/applications              # List applications
POST   /api/v1/applications              # Create application
GET    /api/v1/applications/:id          # Application details
PATCH  /api/v1/applications/:id          # Update
DELETE /api/v1/applications/:id          # Delete

# Files
POST /api/v1/applications/:id/files      # Upload file
GET  /api/v1/applications/:id/files      # List files

# Status
PATCH /api/v1/applications/:id/status   # Change status
GET   /api/v1/applications/:id/history  # Status history

Interactive Documentation

Access Swagger UI: http://localhost:3000/api to explore and test all endpoints.

AI-Assisted Development

This project is designed to be developed with AI assistance. To ensure quality and consistency:

1. Always consult files in docs/ before implementing a new feature
2. Follow the planning in PLANNING.md to meet deadlines and deliverables
3. Respect the code rules defined in each documentation file
4. Maintain consistency with existing code
5. Update CHANGELOG.md when implementing new features
6. Write tests for any new feature
7. Update Swagger documentation

The docs/ files contain concrete examples, patterns to follow, and best practices for every aspect of the project.

Data Models

Application (Job Application)

• Position, Company, Link to offer
• Summary, Notes
• Current status
• Creation and modification dates

StatusHistory (History)

• Previous and new status
• Date and time of change
• Explanatory notes

Document (Attached Files)

• Type: CV, Cover Letter, Other
• Filename, path, size, MIME type
• Upload date

User

• Email, password (hashed)
• First name, last name
• Creation and modification dates

Available Statuses

• Wishlist
• Draft
• Applied
• Phone Screen
• Technical Test
• First Interview
• Second Interview
• Third Interview
• Final Round
• Offer Received
• Accepted
• Rejected by Company
• Withdrawn by Candidate

Document Types

• CV
• Cover Letter
• Other

Security

This project implements robust security measures:

• JWT authentication with access and refresh tokens
• Password hashing with bcrypt (12 rounds)
• Strict validation of all inputs
• SQL injection protection (TypeORM)
• XSS and CSRF protection
• Rate limiting (100 requests/minute)
• Security headers (HSTS, CSP, etc.)
• Validation of types and sizes of uploaded files
• MinIO for secure file storage
• HTTP-only cookies for tokens

Performance

• Pagination on all lists (configurable)
• Optimized database indexes
• Optimized queries to avoid N+1
• Gzip compression enabled
• Caching when necessary
• Fastify adapter for better performance

Development Workflow

Branch Strategy

• main - Production branch
• dev - Development and integration
• staging - Pre-production testing
• feature/* - Feature branches

Code Quality

• ESLint with strict rules
• Prettier for code formatting
• TypeScript strict mode
• Minimum 80% test coverage
• Automated CI/CD checks

Version Management

• RC versions for development: 1.0.0-rc.1, 1.0.0-rc.2
• Final versions for production: 1.0.0, 1.0.1, 1.1.0
• Semantic versioning: MAJOR.MINOR.PATCH
• See CHANGELOG.md for detailed workflow

Contributing

To contribute to this project:

1. Follow the guidelines in docs/ folder
2. Follow the planning in PLANNING.md
3. Write tests for any new feature
4. Update the Swagger documentation
5. Update CHANGELOG.md with your changes
6. Ensure all tests pass
7. Follow the branch flow: feature → dev → staging → main

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For any questions or issues, please open an issue in the repository.

Status Tracking

See CHANGELOG.md for:

• Version history
• New features and changes
• Bug fixes
• Security updates