Technical Documentation

1. Overview

CronFrog is a self-contained job scheduling platform combining a Python backend (FastAPI + APScheduler) with a modern single-page web interface. It allows users to:

• Create scheduled jobs using standard 5-field cron expressions
• Execute shell commands or scripts on the host machine
• Monitor runs in real-time via WebSocket-powered live log streaming
• Manage everything through a REST API or the built-in web dashboard

The entire application runs as a single process — no external message brokers, no Redis, no Celery. Just Python, SQLite, and a browser.

Key Design Decisions

2. Architecture

CronFrog follows a monolithic, single-process architecture. The HTTP server, background scheduler, and job executor all run within the same Python process and share a common asyncio event loop.

How the Three Engines Cooperate

All three share the same event loop, so the scheduler can call execute_job() without thread synchronization, the executor can broadcast logs to WebSocket clients directly, and the API can fire-and-forget a job via asyncio.create_task().

3. Project Structure

cronfrog/
├── run.py                      # Application entry point
├── requirements.txt            # Python dependencies
├── LICENSE                     # MIT License
├── server/                     # Backend Python package
│   ├── __init__.py
│   ├── main.py                 # FastAPI app, lifespan, WebSocket, static mount
│   ├── api.py                  # REST API route definitions
│   ├── database.py             # SQLite data access layer
│   ├── scheduler.py            # APScheduler configuration
│   └── executor.py             # Async subprocess execution + log broadcasting
├── public/                     # Frontend static SPA
│   ├── index.html              # Single-page HTML
│   ├── css/style.css           # Styling
│   ├── js/                     # api.js, app.js, components.js, cron-builder.js, websocket.js
│   └── static/                 # Logo assets
├── data/cronfrog.db            # SQLite database (dev copy)
└── docs/                       # Documentation assets

4. Backend Deep Dive

4.1 Entry Point — run.py

The entry point is deliberately minimal. It ensures the project root is on sys.path, imports the FastAPI app instance from server.main, and starts the Uvicorn ASGI server. Port is configurable via the PORT environment variable (default: 8000).

4.2 Application Bootstrap — server/main.py

Uses FastAPI's lifespan async context manager to:

• Initialize the database — creates tables if they don't exist
• Start APScheduler — begins the background event loop
• Load saved jobs — re-registers all enabled jobs from the database
• Mount static files — serves the public/ directory at /

CORS middleware is configured to allow all origins. The WebSocket endpoint at /api/ws/runs/{run_id} handles live log connections with a late-join buffer replay.

4.3 REST API — server/api.py

All routes are prefixed with /api and handle CRUD operations for jobs, manual triggers, run history, and stats. When a job is created or updated with enabled=True, it's automatically registered with APScheduler. Manual runs use asyncio.create_task() for fire-and-forget execution.

4.4 Database Layer — server/database.py

A thin Data Access Layer (DAL) over SQLite using Python's built-in sqlite3 module. Each function opens a connection, performs the operation, and closes it. The database defaults to ~/.cronfrog/data/cronfrog.db to prevent Uvicorn --reload restart loops.

4.5 Scheduler — server/scheduler.py

Wraps APScheduler's AsyncIOScheduler. Converts standard 5-field cron expressions into trigger objects using CronTrigger.from_crontab(). On startup, all enabled jobs are re-registered (load_jobs_into_scheduler()).

4.6 Executor — server/executor.py

The most complex module. Manages the full lifecycle of job execution:

• Creates a run record in the database
• Merges environment variables and resolves the shell executable
• Spawns an async subprocess via asyncio.create_subprocess_shell()
• Reads stdout/stderr concurrently with asyncio.gather()
• Broadcasts each line to connected WebSocket clients in real-time
• Finalizes the run record with exit code, output, and status

Maintains three in-memory registries: active_processes (for kill support), active_logs (buffer for late-joining clients), and run_websockets (connected viewers).

5. Database Schema

jobs Table

job_runs Table

Relationship: Each job can have many run records (1:N). Runs are ordered by id DESC and limited to 50 per query.

6. API Reference

All endpoints are prefixed with /api. The auto-generated Swagger UI is available at /docs when the server is running.

Jobs CRUD

Job Control

Runs & Stats

Example Response — GET /api/stats

{
    "total_jobs": 5,
    "active_jobs": 3,
    "failed_runs": 1
}

7. WebSocket Protocol

Endpoint: ws://localhost:8000/api/ws/runs/{run_id}

All messages are JSON-encoded strings pushed from the server to the client.

Message Types

Late-Join Buffer

If a client connects after a job has started, the server replays all buffered log lines from active_logs[run_id] before streaming new lines. This ensures no output is ever missed.

8. Frontend Deep Dive

The frontend is a vanilla JavaScript SPA with no build step, no framework, and no npm dependencies. It's served directly as static files by FastAPI.

Module Breakdown

Route Map

Design System

The CSS implements a dark-mode glassmorphism theme using CSS custom properties. Key tokens include emerald green (#10b981) as the primary accent, Inter as the sans-serif font, Fira Code for monospace, and translucent backdrop-filter: blur() panels.

9. Job Execution Flow

Step-by-Step

• Trigger: Manual (POST /api/jobs/{id}/run) or scheduled (APScheduler cron trigger)
• Prepare: Fetch job config, create run record, init log buffer, merge env vars, resolve shell
• Execute: Spawn subprocess, register in active_processes, launch concurrent stream readers
• Stream: Each line appended to buffer and pushed via WebSocket to all connected clients
• Complete: Capture exit code, determine status, write final output to DB, clean up registries, close WebSockets

10. Configuration & Environment

CronFrog is configured entirely through environment variables. No config files needed.

Examples

# Windows (PowerShell)
$env:PORT = 8080
$env:CRONFROG_DB_PATH = "C:\data\cronfrog.db"
python run.py

# Linux / macOS
PORT=8080 CRONFROG_DB_PATH="/data/cronfrog.db" python run.py

11. Dependencies

Additionally uses Python standard library modules: sqlite3, asyncio, json, os, sys, pathlib, datetime, contextlib.