Skip to content

About

Production-ready Intelligent Task Scheduler & Workflow Engine built with Clean Architecture, DAG dependency cycles prevention, BullMQ dynamic buffer auto-rescheduling, and React 19.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

Β 

History

3 Commits

Folders and files

Repository files navigation

Chronos Sync

Intelligent Task Scheduler & Workflow Engine
Production-ready, Clean Architecture Modular Monolith built with TypeScript, Node.js, Express, Prisma ORM, BullMQ, React 19, and Tailwind CSS.

TypeScript React 19 Express.js Prisma ORM BullMQ Tailwind CSS License


πŸ“Œ Executive Summary

Chronos Sync is an enterprise-grade task orchestration platform engineered for developers, technical project leaders, and high-performance teams. Unlike standard todo applications, Chronos Sync models task execution as a Directed Acyclic Graph (DAG) with automated circular dependency prevention, dynamic overrun rescheduling with mandatory cognitive recovery buffers, and context-aware energy mode filtering.

Designed according to Clean Architecture and SOLID principles, the backend is structured as an isolated Modular Monolith with absolute type safety, compile-time Zod schema validation, optimistic locking for offline-first sync, and modular BullMQ worker pipelines.


🌟 Core Features

1. Smart Automation & AI

  • Natural Language Processing (NLP) Quick Capture: High-speed tokenizer converting raw phrases (e.g., "Deploy microservice tomorrow at 4pm for 60m !p0 #deepwork") into structured tasks complete with ISO dates, priority tiers, tags, and duration.
  • Auto-Rescheduling & Dynamic Buffers: When high-priority (P0/P1) tasks run over their allocated timeframe, the BullMQ rescheduling engine recalculates downstream task start times while inserting 5–30 minute cognitive recovery buffers to eliminate burnout and schedule cascading.
  • Predictive Time Estimation & Audit: Logs historical execution metrics and flags tasks with unrealistic allocations using planned vs. actual duration ratios and deviation percentage analytics.

2. Advanced Scheduling Controls

  • Directed Acyclic Graph (DAG) Dependency Engine: Incorporates Kahn’s algorithm and three-color cycle detection (WHITE, GRAY, BLACK) to guarantee prerequisite chains remain non-circular. Tasks are locked in Blocked status until all antecedent dependencies are marked Completed.
  • Flexible Recurring Rule Engine: Extends standard POSIX CRON to evaluate complex real-world cadence rules like "Every 3rd Tuesday" or "Every 10 business days", skipping holidays and weekends.
  • Cross-Calendar Synchronization: Clean abstraction and gateway adapters for two-way synchronization hooks with Google Calendar and Microsoft Outlook APIs.

3. Execution & Focus Tools

  • Context-Based Energy Filtering: Filter workflow pipelines according to available cognitive energy levels:
    • 🧠 Deep Work: 100% uninterrupted focus, zero context switching (architecture, critical algorithms).
    • ⚑ High Focus: Creative engineering, design, and complex problem solving.
    • πŸ”‹ Medium Focus: Routine features, code reviews, PR audits, and technical syncs.
    • 🌿 Low Energy: Lightweight administration, documentation, backlog grooming.
  • Pomodoro Focus Chamber: Built-in 25-minute Pomodoro timer directly coupled with task entities, with active audio chimes, progress rings, and real-time telemetry logging.
  • Precision Time Tracking: Integrated stopwatch recording start/pause/complete events with millisecond precision to feed the predictive estimation audit engine.

4. User Experience & Friction Reduction

  • Multi-View Visual Orchestration:
    • πŸ“‹ Kanban Pipeline: Five-lane state machine (To Do, In Progress, Blocked, In Review, Completed) with optimistic locking indicators and column descriptions.
    • ⏱️ Timeline & Buffers: Gantt-style schedule displaying allocated working time blocks alongside color-coded cognitive buffers.
    • πŸ“… Time-Blocked Day View: Hourly schedule distribution (8:00 AM – 8:00 PM) with overlap warnings.
    • πŸ”— DAG Dependency Studio: Interactive visual node-and-edge graph illustrating predecessor/successor relationships and cycle status.
  • Offline-First Optimistic Locking: Every task entity maintains a monotonically increasing version counter and timestamp. Batch updates performed while offline are reconciled server-side with conflict-detection safety.
  • Omnipresent Quick Capture: Accessible anywhere via ⌘ Cmd + K (or Ctrl + K) for sub-second task creation.

πŸ›οΈ System Architecture

Chronos Sync enforces a strict decoupled Modular Monolith adhering to Robert C. Martin's Clean Architecture:

chronos-sync/
β”œβ”€β”€ prisma/
β”‚   └── schema.prisma                 # Relational PostgreSQL schema with compound indexes
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ modules/
β”‚   β”‚   β”œβ”€β”€ auth/                     # Supabase & JWT Auth Domain
β”‚   β”‚   β”‚   β”œβ”€β”€ domain/               # Pure Entities & Repository Interfaces
β”‚   β”‚   β”‚   β”œβ”€β”€ application/          # Use Cases (Register, Login, Supabase Verify)
β”‚   β”‚   β”‚   β”œβ”€β”€ infrastructure/       # Prisma Repositories & JWT Adapters
β”‚   β”‚   β”‚   └── presentation/         # Express Controllers & Zod Validators
β”‚   β”‚   β”‚
β”‚   β”‚   β”œβ”€β”€ task/                     # Core Task & DAG Domain
β”‚   β”‚   β”‚   β”œβ”€β”€ domain/               # Task Entity, DAG cycle detector
β”‚   β”‚   β”‚   β”œβ”€β”€ application/          # Create, Update, DAG validation, NLP parser
β”‚   β”‚   β”‚   β”œβ”€β”€ infrastructure/       # PrismaTaskRepository & in-memory stores
β”‚   β”‚   β”‚   └── presentation/         # TaskController & task routes
β”‚   β”‚   β”‚
β”‚   β”‚   └── scheduler/                # BullMQ, Rescheduling & Cron
β”‚   β”‚       β”œβ”€β”€ domain/               # Reschedule Engine & Dynamic Buffer logic
β”‚   β”‚       β”œβ”€β”€ application/          # AutoRescheduleUseCase, RecurringCronUseCase
β”‚   β”‚       β”œβ”€β”€ infrastructure/       # BullMQ queues, workers & Upstash Redis driver
β”‚   β”‚       └── presentation/         # Reschedule and Recurring controllers
β”‚   β”‚
β”‚   β”œβ”€β”€ components/                   # React 19 UI Modules
β”‚   β”‚   β”œβ”€β”€ KanbanView.tsx            # 5-lane Kanban board with DAG locks
β”‚   β”‚   β”œβ”€β”€ TimelineView.tsx          # Gantt schedule & recovery buffers
β”‚   β”‚   β”œβ”€β”€ TimeBlockedView.tsx       # Hourly calendar view
β”‚   β”‚   β”œβ”€β”€ DagStudioView.tsx         # Node-link DAG graph visualizer
β”‚   β”‚   β”œβ”€β”€ FocusPomodoroView.tsx     # Live timer chamber & audio chimes
β”‚   β”‚   β”œβ”€β”€ PredictiveAuditView.tsx   # Planned vs actual duration analytics
β”‚   β”‚   β”œβ”€β”€ QuickCaptureModal.tsx     # Cmd+K NLP task creator
β”‚   β”‚   β”œβ”€β”€ TaskModal.tsx             # Comprehensive task editor & dependency picker
β”‚   β”‚   β”œβ”€β”€ Tooltip.tsx               # Viewport-safe portal tooltips
β”‚   β”‚   └── AuthScreen.tsx            # Login & Supabase JWT verification
β”‚   β”‚
β”‚   β”œβ”€β”€ server/                       # Express Application & Router Bridge
β”‚   β”œβ”€β”€ App.tsx                       # React root application & navigation
β”‚   └── index.css                     # Tailwind CSS v4 styling
β”œβ”€β”€ server.ts                         # Express HTTP Server & Vite middleware bridge
β”œβ”€β”€ vite.config.ts                    # Vite build configuration
└── package.json                      # Project dependencies & scripts

Architectural Principles:

  1. Dependency Rule: Inner domain layers contain zero imports from outer layers (no database, no HTTP frameworks).
  2. Repository Pattern: All database interactions pass through explicit TypeScript interfaces (ITaskRepository, IUserRepository), allowing mock testing and persistence swapping.
  3. Directed Acyclic Graph Validation: Circular dependencies ($A \rightarrow B \rightarrow C \rightarrow A$) are intercepted at the application layer before reaching persistence.
  4. Resilient Background Processing: BullMQ queues isolate CPU-intensive operations (schedule cascade recalculations, recurring task expansions) from the HTTP event loop.

πŸ› οΈ Technology Stack

Layer Technology Purpose
Frontend Framework React 19 Concurrent rendering, hooks, responsive state management
Styling & Design Tailwind CSS v4 Modern CSS design tokens, dark-mode slate theme
Icons & Animation Lucide React, Motion Scalable vector icons and layout transitions
Backend Framework Express.js 4 RESTful API routing and JSON middleware
Language & Typing TypeScript 5 Strict static type safety across client and server
Validation Zod Runtime request payload validation
Database ORM Prisma ORM Relational modeling, migrations, and PostgreSQL client
Database PostgreSQL ACID transactions and relational foreign key constraints
Queue & Cache BullMQ, Redis / Upstash Background workers, delay scheduling, and cron queues
Tooling & Bundler Vite 8, tsx Instant HMR development and fast TypeScript execution

πŸš€ Getting Started

Prerequisites

  • Node.js: v20.x or higher
  • npm: v10.x or higher
  • (Optional) Redis and PostgreSQL instance or Docker (fallback in-memory store is enabled by default for standalone testing).

Installation

  1. Clone the repository:

    git clone https://github.com/YOUR_USERNAME/chronos-sync.git
    cd chronos-sync
  2. Install dependencies:

    npm install
  3. Configure Environment Variables: Create a .env file from the example:

    cp .env.example .env

    (Ensure PORT=3000 is configured).

  4. Start Development Server:

    npm run dev

    The application will be live at http://localhost:3000.

  5. Build for Production:

    npm run build
    npm run start

πŸ“‘ REST API Reference

Method Endpoint Description
GET /api/tasks Fetch all user tasks
POST /api/tasks Create a new task with DAG dependency validation
PUT /api/tasks/:id Update task details or change execution status
DELETE /api/tasks/:id Remove a task and cascade orphan dependencies
POST /api/tasks/quick-capture 2-second low-latency NLP parser endpoint
GET /api/tasks/views/multi Returns structured projections for Kanban, Timeline, Day-Block, and DAG views
POST /api/tasks/offline-batch-sync Optimistic locking reconciliation for offline updates
POST /api/reschedule/auto Trigger BullMQ dynamic buffer recalculation for overruns
POST /api/focus/session Record a completed Pomodoro session and update task duration
GET /api/audit/predictive Retrieve planned vs. actual duration estimation variance
POST /api/auth/login Authenticate user session
POST /api/auth/supabase-verify Validate Supabase JWT bearer token

πŸ™ Recommended GitHub Repository Settings

To present this repository cleanly on GitHub, use the following configurations:

1. Repository "About" Description

Production-ready Intelligent Task Scheduler & Workflow Engine built with Clean Architecture, DAG dependency cycles prevention, BullMQ dynamic buffer auto-rescheduling, and React 19.

2. Website URL

Set the website field to your deployment link or preview URL.

3. Repository Topics (Tags)

Add these topics in the GitHub repo header to maximize discoverability:

task-scheduler, dag-workflow, clean-architecture, kanban, gantt-chart, bullmq, prisma-orm, expressjs, react19, typescript, tailwindcss, pomodoro-timer, time-blocking, modular-monolith

4. Branch Protection Rules (main)

  • Go to Settings β†’ Branches β†’ Add branch protection rule:
    • Branch name pattern: main
    • Check: Require a pull request before merging
    • Check: Require status checks to pass before merging (build, lint)
    • Check: Do not allow bypassing the above settings

5. Recommended GitHub Actions Workflow

Create .github/workflows/ci.yml:

name: CI Build & Typecheck

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run build

πŸ“„ License

This project is licensed under the Apache-2.0 License. See the LICENSE file for details.

About

Production-ready Intelligent Task Scheduler & Workflow Engine built with Clean Architecture, DAG dependency cycles prevention, BullMQ dynamic buffer auto-rescheduling, and React 19.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Contributors

Languages