Architecture

                 +----------------------------+
  Browser ---->  |     hashtasker-server      |  <---- LDAP / AD (optional)
  (web UI)       |  Gin web UI + JSON API     |
                 |  SQLite (hashtasker.db)    |
                 |  uploads/  wordlists/ rules|
                 +-------------+--------------+
                               ^  HTTP (poll)
            +------------------+------------------+
            |                  |                  |
     +------+------+    +------+------+    +------+------+
     |  worker-01  |    |  worker-02  |    |  worker-N   |
     |  hashcat    |    |  hashcat    |    |  hashcat    |
     +-------------+    +-------------+    +-------------+
            \                  |                  /
             +------ shared NFS wordlists (nfs mode only)

Components

Server (hashtasker-server)

• Serves the web UI (templates and static assets are embedded in the binary)
• Exposes an authenticated management API for the UI and an unauthenticated worker API
• Stores everything in SQLite (hashtasker.db in its working directory). MySQL is used only if SQLite cannot be opened.
• Runs background tasks: worker offline detection, NFS health checks, 45-day job purge, orphaned file cleanup, and (NFS mode) the wordlist line-count warmer

Worker (hashtasker-worker)

• A single stdlib-only Go binary that wraps hashcat
• Polls the server for assignments, runs hashcat, streams progress and cracked hashes back
• Tracks its own hashcat processes and retries when hashcat reports the system is overloaded

Job Lifecycle

1. A user submits a job. The server records it and looks up every online worker.
2. The job's wordlist keyspace is divided into one chunk per online worker.
   • Push mode: the wordlist is physically split into chunk files in upload_path.
   • NFS mode: the wordlist's line count is looked up (cached) and each worker gets a --skip/--limit range.
3. Each worker picks up its assignment on its next check-in (GET /api/worker/assignments).
4. The worker writes the hashes to temp_path, fetches its chunk if needed, and launches hashcat with the job's hash mode and rulesets.
5. While running, the worker posts progress (speed, percentage, ETA) and each cracked hash as it is found.
6. When hashcat exits, the worker reports the chunk as completed or failed (with a reason).
7. When every chunk is final, the job becomes completed (or failed), a webhook fires if configured, and temporary files are cleaned up on both sides.

Job and Chunk States

State	Meaning
queued	Created, waiting for workers to start (or NFS mode still preparing chunks)
running	At least one worker is actively cracking
overloaded	A worker could not start hashcat because the host is saturated; it will retry automatically
completed	All chunks finished
failed	A chunk failed, or job preparation failed (see the status message)
cancelled	Cancelled by a user

Overload Handling

Workers do not pre-limit how many jobs they take. They start hashcat and, if hashcat exits with code 252 (device/system overloaded), the job is queued locally and shown as "queued" in the UI. The worker retries once its running hashcat process count drops.

Worker Online/Offline

A worker is marked offline if it has not checked in for 60 seconds. Only online workers receive chunks when a job is created, so bring workers up before submitting large jobs.