forQ — Distributed Job Scheduler

Author: ASHWIN R (https://github.com/ashwin-r11)
Stack: Node.js, Express, TypeScript, MongoDB, Redis, React, Vite, Socket.io, Vitest

Production-inspired distributed job scheduling platform: authenticate users, manage projects and queues, enqueue five job types, claim work atomically across scaled workers, retry with backoff, land failures in a DLQ, and operate everything from a live React dashboard.

---

Mark-Mapped Documentation

Rubric (marks)	Primary evidence
System Architecture (20)	docs/architecture.md · UML: component, deployment, claim, job state
Database Design (20)	docs/er-diagram.md · UML: 19-er.png, 02-class.png
Backend Engineering (20)	docs/backend.md
Reliability & Concurrency (15)	docs/backend.md · docs/architecture.md · docs/testing.md
Frontend & UX (10)	docs/frontend.md
API Design (5)	docs/api.md
Documentation (5)	This README + docs suite
Testing (5)	docs/testing.md · server/tests/
Design decisions (deliverable)	docs/design-decisions.md
Evaluator index	docs/DISTRIBUTED_JOB_SCHEDULER_REPORT.md
PlantUML UML figures	docs/uml/README.md — rendered PNG gallery (19 figures)

---

UML Diagrams

Assignment figures (PlantUML exports). Full gallery: docs/uml/README.md (all 19 diagrams).

---

Features

• 5 job types: immediate, delayed, scheduled, recurring (cron), batch
• Atomic claiming: Redis pre-lock + MongoDB findOneAndUpdate
• Retries: fixed / linear / exponential + jitter → DLQ
• Workers: heartbeats, graceful SIGTERM drain, independent stale recovery on API
• Queues: priority, concurrency, pause/resume, rate limits, stats
• Auth: JWT access + refresh; tenant isolation middleware
• Dashboard: Socket.io live updates + 3s polling fallback, Recharts
• Bonus-aligned: rate limiting, distributed locks, WebSocket live updates, RBAC role field

---

Tech Stack

Layer	Technology
Backend	Node.js + Express + TypeScript
Database	MongoDB (Mongoose)
Cache / locks	Redis (ioredis)
Auth	JWT (access + refresh)
Worker	Separate Node process, same codebase
Cron	croner
Frontend	React + TypeScript + Vite
Charts	Recharts
Validation	Zod
Testing	Vitest + Supertest
Containers	Docker Compose

---

Quick Start

Prerequisites

• Node.js 18+
• Docker (recommended) or local MongoDB + Redis

Option 1: Docker Compose (recommended)

docker-compose up --build

Service	URL / port
Dashboard	http://localhost:3000
API	http://localhost:5000
Health	http://localhost:5000/api/health
MongoDB	27017
Redis	6379

Scale workers:

docker-compose up --scale worker=5

Option 2: Local development

# Databases
docker run -d -p 27017:27017 -e MONGO_INITDB_ROOT_USERNAME=admin -e MONGO_INITDB_ROOT_PASSWORD=password123 mongo:7
docker run -d -p 6379:6379 redis:7-alpine

# API
cd server && npm install && cp .env.example .env && npm run dev

# Worker
cd server && npm run dev:worker

# Frontend
cd client && npm install && npm run dev

• Dashboard (Vite): http://localhost:5173
• API: http://localhost:5000

---

Testing

cd server
npm test

See docs/testing.md.

---

Project Structure

├── docker-compose.yml
├── server/          # API + worker (forq-server)
├── client/          # React dashboard (forq-client)
└── docs/            # Rubric-mapped documentation
    ├── architecture.md
    ├── er-diagram.md
    ├── backend.md
    ├── frontend.md
    ├── api.md
    ├── design-decisions.md
    ├── testing.md
    ├── DISTRIBUTED_JOB_SCHEDULER_REPORT.md
    └── uml/         # PlantUML UML diagrams (paste into plantuml.com)

---

Job Lifecycle

Queued → Scheduled → Claimed → Running → Completed
                         ↓         ↓
                      Failed → (retry) → Queued
                         ↓
                   Dead Letter Queue

---

License

MIT
Author: ASHWIN R — https://github.com/ashwin-r11