Chronos - Distributed Job Scheduler System

A reliable and scalable distributed job scheduling system built with TypeScript, Node.js, React, PostgreSQL, and Redis. Chronos supports one-time jobs, recurring jobs (cron), automatic retries, and comprehensive monitoring.

🏗️ Architecture

Tech Stack

Backend:

• Node.js + TypeScript
• Express.js (RESTful API)
• PostgreSQL (Job storage)
• Redis + BullMQ (Distributed job queue)
• JWT (Authentication)
• Winston (Logging)

Frontend:

• React + TypeScript
• Vite
• React Query (Data fetching)
• Tailwind CSS
• React Router

Infrastructure:

• Docker & Docker Compose
• Multi-container architecture (API, Worker, DB, Redis)

Overview & Design of the System

┌─────────────┐
│   Client    │
│  (Browser)  │
└──────┬──────┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│  API Server │────▶│  PostgreSQL │
│  (Express)  │     │   (Jobs)    │
└──────┬──────┘     └─────────────┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│    Redis    │◀────│   Workers   │
│   (Queue)   │     │  (BullMQ)   │
└─────────────┘     └─────────────┘

📦 Installation

Prerequisites

• Node.js (version 20 or higher) - Download here
• npm or yarn (comes with Node.js)
• Docker and Docker Compose - Download here
• Git (for cloning the repository)

🚀 How to Run Project Locally

Step 1: Clone the Repository

git clone <your-repo-url>
cd chronos

Step 2: Set Up Environment Variables

Create a .env file in the root directory of the project after referring .env.example:

Step 3: Start Infrastructure Services (PostgreSQL & Redis)

Chronos requires PostgreSQL and Redis to be running. The easiest way is to use Docker Compose:

# Start PostgreSQL and Redis containers
docker-compose up -d postgres redis

This command will:

• Start PostgreSQL on port 5432
• Start Redis on port 6379
• Automatically create the database schema using db/init.sql

Verify services are running:

docker ps

Step 4: Install Backend Dependencies

Install all required Node.js packages for the backend:

# Make sure you're in the project root directory
npm install

Step 5: Build the Backend

npm run build

Step 6: Start the Backend API Server

npm run dev

The API server will start on http://localhost:3000.

Step 7: Start the Worker Process

The worker process handles job execution.

# Make sure you're in the project root directory
npm run dev:worker

Step 8: Install Frontend Dependencies

cd frontend
npm install

Step 9: Start the Frontend Development Server

npm run dev

The frontend will start on http://localhost:5173 (Vite's default port).

Step 10: Access the Application

Open your web browser and navigate to:

• Frontend UI: http://localhost:5173
• Backend API: http://localhost:3000
• API Health Check: http://localhost:3000/health