How jayanth1802/distributed-job-scheduler works
1. Overall shape
- This is a monorepo for a distributed job scheduler.
- The system is split into four runtime units: Postgres-backed database layer, Express API, polling worker service, and React dashboard.
- There is no separate queue broker; the database is the coordination point for scheduling, claiming, retries, and status history.
2. Database as the core system boundary
- packages/db owns the schema and migration runner (schema.sql, migrate.js, index.js).
- PostgreSQL is the single source of truth for organizations, projects, queues, workers, jobs, retry state, and likely DLQ-related state.
- Both API and worker depend on the shared DB package, so most system behavior crosses the DB boundary rather than service-to-service RPC.
3. API service
- packages/api is an Express server (server.js) with route modules for auth, projects, queues, jobs, workers, retryPolicies, and dashboard.
- It handles request validation, authentication middleware, and CRUD/query endpoints for the scheduler domain.
- The API is also the system’s WebSocket relay, converting database change notifications into live UI updates.
4. Authentication and multi-tenant access
- packages/api/src/routes/auth.js and middleware/auth.js indicate JWT-based auth at the API boundary.
- The dashboard and API are organized around organization/project scoping, with the UI exposing a ProjectPicker.
- This makes “project” the main tenant-level boundary for operational views and job submission.
5. Worker service
- packages/worker is a separate Node.js process that continuously polls for runnable jobs.
- The worker is designed for horizontal scaling: multiple worker processes can run against the same database without double-claiming jobs.
- Its core flow is claim → execute → retry/DLQ, implemented across claim.js, executor.js, retryStrategy.js, scheduler.js, and index.js.
6. Atomic job claiming
- The worker uses PostgreSQL row locking with SELECT ... FOR UPDATE SKIP LOCKED to claim jobs safely under concurrency.
- This is the key distributed-systems mechanism in the repo: the database serializes ownership while allowing many workers to compete.
- The repo’s tests explicitly cover claim exclusivity, so this is a central architectural guarantee.
7. Scheduling and retries
- packages/shared/cron.js is used by both API and worker to parse cron expressions consistently.
- The worker’s scheduler.js materializes cron/recurring work on a periodic tick, controlled by SCHEDULER_TICK_MS.
- retryStrategy.js handles delay/backoff calculations, and the system transitions to a Dead Letter Queue after attempts are exhausted.
8. Task execution boundary
- packages/worker/src/tasks/index.js suggests a task registry or dispatcher that maps job types to executors.
- This is the boundary between generic scheduler mechanics and application-specific work execution.
- In architecture terms, jobs are generic records in Postgres, while task handlers are the code that turns them into actual work.
9. Live operational visibility
- packages/dashboard is a Vite/React 18 app with pages for overview, job explorer, job detail, queues, workers, and login.
- It talks to the API through packages/dashboard/src/lib/api.js and uses native WebSocket support for live updates.
- The UI also uses Recharts for metrics-style visualization, which means the dashboard is not just CRUD; it is an ops console.
10. Real-time update path
- The live-update path is: Postgres LISTEN/NOTIFY → API WebSocket relay → browser WebSocket client.
- This keeps the dashboard reactive without having workers or the UI poll the database directly.
- The API is therefore both a REST control plane and a real-time event bridge.
11. Deployment/runtime topology
- At runtime, the repo expects three long-lived processes: API on :4000, worker(s), and dashboard on :5173.
- The dashboard dev server proxies /api and /ws to the API, but in architecture terms the browser still only depends on the API service.
- The only required external infrastructure is PostgreSQL 14+.
12. Shared code and quality controls
- packages/shared contains cross-cutting logic, currently cron parsing, to prevent drift between services.
- Tests focus on critical system invariants: concurrency/claim safety, cron handling, retry math, job validation, and auth behavior.
- That test scope reinforces the architecture’s main risk areas: distributed coordination, time-based scheduling, and access control.
Main entry points: server.js API server · src/index.js Worker · App.jsx Dashboard · db/index.js DB package
Components 22
Runtime units
Long-lived services and the browser client
- API server · REST API, auth boundary, and WebSocket relay
packages/api/src/server.js - Auth middleware · Request authentication and tenant access enforcement
packages/api/src/middleware/auth.js - Auth routes · Authentication endpoints for the dashboard and API clients
packages/api/src/routes/auth.js - Projects · Organization and project-scoped control and lookup endpoints
packages/api/src/routes/projects.js - Queues · Queue configuration and queue-level job operations
packages/api/src/routes/queues.js - Jobs · Job creation, querying, detail views, and lifecycle endpoints
packages/api/src/routes/jobs.js - Workers API · Worker registry and operational endpoints
packages/api/src/routes/workers.js - Retry APIs · Retry policy and delay configuration endpoints
packages/api/src/routes/retryPolicies.js - Dashboard API · API surface used by the dashboard and WebSocket event relay
packages/api/src/routes/dashboard.js - Worker · Continuously claims, executes, retries, and dead-letters jobs
packages/worker/src/index.js - Claiming · Atomic job acquisition with SKIP LOCKED to avoid double-processing
packages/worker/src/claim.js - Executor · Dispatches claimed jobs to task handlers
packages/worker/src/executor.js - Task registry · Maps job types to application-specific executors
packages/worker/src/tasks/index.js - Retry strategy · Backoff calculations and dead-letter transition logic
packages/worker/src/retryStrategy.js - Scheduler tick · Materializes cron-based work on a periodic poll
packages/worker/src/scheduler.js - Dashboard · Browser UI for overview, jobs, queues, workers, and login
packages/dashboard/src/App.jsx - Project picker · Project-scoped navigation and selection in the dashboard
packages/dashboard/src/components/ProjectPicker.jsx - API client · Dashboard HTTP/WebSocket client for API communication
packages/dashboard/src/lib/api.js - Ops pages · Overview, job explorer, job detail, queues, workers, and login screens
packages/dashboard/src/pages/Overview.jsx
Data plane
PostgreSQL-backed coordination and shared logic
- Postgres · Single source of truth for jobs, workers, queues, orgs, projects, retries, and history
packages/db/schema.sql - DB package · Shared database access, schema, and migration runner
packages/db/index.js - Cron utils · Common cron parsing used by API and worker
packages/shared/cron.js
Connections 22
- DB package → Postgres: migrates+reads · Creates and manages the schema in PostgreSQL
- API server → DB package: queries · Reads and writes scheduler state through the shared DB layer
- Worker → DB package: polls · Claims and updates jobs through the shared DB layer
- API server → Cron utils: parses cron · Uses shared cron logic for request validation and scheduling rules
- Worker → Cron utils: parses cron · Uses the same cron semantics for recurring work
- API server → Auth middleware: guards routes · Applies JWT authentication and access checks
- API server → Auth routes: serves · Exposes login and auth-related endpoints
- API server → Projects: serves · Exposes project and tenant-scoped endpoints
- API server → Queues: serves · Exposes queue management endpoints
- API server → Jobs: serves · Exposes job lifecycle endpoints
- API server → Workers API: serves · Exposes worker operational endpoints
- API server → Retry APIs: serves · Exposes retry policy endpoints
- API server → Dashboard API: serves · Feeds dashboard queries and live updates
- Worker → Claiming: claims · Atomically acquires runnable jobs
- Worker → Executor: executes · Runs claimed jobs through the execution pipeline
- Executor → Task registry: dispatches · Selects the handler for each job type
- Worker → Retry strategy: retries · Computes backoff and DLQ transitions after failures
- Worker → Scheduler tick: ticks · Creates runnable jobs from cron or recurring schedules
- Dashboard → API client: uses · Dashboard talks to the API over HTTP and WebSocket
- API client → API server: calls · Browser client communicates with the API control plane
- Project picker → Dashboard: navigates · Project selection scopes dashboard views
- Ops pages → Dashboard: renders · Operational views make up the main user interface