Road Hawk Version 0.0.2

STWL · Susquehanna Timberwolf Lines LLC
Product: Road Hawk · Brand: Road Hammer

Status

Road Hawk is back in current development.

This repository is the active Road Hammer / STWL development lane for fleet and driver operations. The MVP includes a modular Python backend (CLI + FastAPI), SQLite persistence, and a Next.js web dashboard.

Classification: ACTIVE-BUILD
Safe to run: Yes — CLI + web dashboard with SQLite persistence
Next action: Coyote voice integration and cloud sync (document intake lane active in Round 2)

License status

No public license is currently selected for this repository.

The prior MIT license marker is being retired as part of the current-development refresh. Do not treat this repository as open source unless a future license file or release note explicitly says otherwise.

Deployment modes

Road Hawk is designed to run multi-platform (Windows, Linux, macOS) in three configurations:

Mode	What runs where	Use case
Standalone local	CLI or API + SQLite + web UI on one machine	Driver laptop, shop PC, Lucy/Windows dev
Standalone server	API + SQLite on a host (`0.0.0.0`); clients connect over LAN/WAN	Fleet server, garage NUC, VPS
Client (remote API)	Web dashboard (or future API-aware clients) pointed at your server	Tablet/phone/laptop hitting a central Road Hawk server

Standalone server (accept remote clients):

export ROAD_HAWK_API_HOST=0.0.0.0
export ROAD_HAWK_CORS_ORIGINS=http://localhost:3000,http://192.168.1.10:3000
pip install -e .
road-hawk-api

Client dashboard (hook to remote server of your choice):

# web/.env.local
NEXT_PUBLIC_API_URL=http://your-server:8000

Copy .env.example and web/.env.example for all options. Override data location with ROAD_HAWK_DATA_DIR for portable/per-device storage.

Platform notes

npm scripts default to cross-platform next commands (npm run dev).
Windows helpers: npm run dev:win uses bin\run-with-node.cmd when Node is not on PATH.
Unix helpers: npm run dev:unix or scripts/start-api.sh / scripts/start-web.sh.
scripts/*.ps1 are Windows-first convenience wrappers; shell scripts are the portable path.

Quick Start (CLI)

pip install -e .
road-hawk

Or without installing:

python -m road_hawk

Web UI

Terminal 1 — API server:

pip install -e .
road-hawk-api

Terminal 2 — web dashboard:

.\scripts\setup-local.ps1   # first time only
.\scripts\start-web.ps1

Or manually:

cd web
npm install
npm run dev

If node is not recognized, run once from repo root:

.\scripts\repair-node-path.ps1

Open http://localhost:3000 (API at http://127.0.0.1:8000)

Data is stored in data/road_hawk.db. Legacy code is preserved in archive/ (including archive/legacy-0.0.2/).

STWL brand assets

Canonical brand files live on D: at D:\STWL\STWL\SCREENSHOTS\. The web UI uses the STWL square logo synced into web/public/brand/.

.\scripts\sync-brand-assets.ps1

Document intake (Coyote Round 2)

Drivers can upload paperwork through the Documents page in the web dashboard or via the API. Road Hawk extracts embedded text first and only falls back to local OCR for images/scans/image-only PDFs.

pip install -e ".[dev]"
road-hawk-api
# web dashboard → Documents

Optional local OCR (Tesseract + image-only PDF page rendering):

pip install -e ".[ocr]"
# Windows: winget install UB-Mannheim.TesseractOCR

If OCR is not installed, uploads still work — the record is stored, the original file is preserved, and the document is marked needs_review for manual entry.

API endpoints:

Method	Path	Purpose
POST	`/api/documents/upload`	Upload file + metadata, run extraction
GET	`/api/documents`	List document records
GET	`/api/documents/{id}`	Metadata, raw text, parsed fields
POST	`/api/documents/{id}/verify`	Driver confirms/corrects fields
POST	`/api/documents/{id}/reject`	Reject or flag needs review
POST	`/api/documents/{id}/reprocess`	Rerun extraction/parser
POST	`/api/export/documents`	CSV export (includes verification status)

Original files: data/uploads/{document_id}/
Parsed fields remain unverified until the driver reviews them.

Updating Road Hawk

Road Hawk has two update flows: pull updates on a machine that already runs the app, and push updates when Road Hammer ships new code to GitHub.

Bump the package version

Edit version in pyproject.toml, then sync web metadata:

python scripts/sync-version.py

Pull updates (driver laptop, shop PC, fleet server)

Gets the latest code from GitHub, reinstalls Python + web deps, and runs smoke tests.

Windows:

.\scripts\update-package.ps1

Linux / macOS:

chmod +x scripts/update-package.sh
./scripts/update-package.sh

Useful flags:

Flag	Effect
`-SkipPull` / `--skip-pull`	Reinstall only; do not `git pull`
`-SkipTests` / `--skip-tests`	Skip pytest after update
`-IncludeOcr` / `--include-ocr`	Also install optional OCR extras
`-ProductionWeb` / `--production-web`	`npm ci` + production web build

After updating, restart the API and web processes if they are already running.

Push updates (maintainer / Road Hammer dev)

Syncs version metadata, runs tests, builds the web dashboard, commits, and pushes to Road-Hawk (triggers CI).

Windows:

.\scripts\push-update.ps1 -Message "Describe the update here"

Linux / macOS:

chmod +x scripts/push-update.sh
./scripts/push-update.sh "Describe the update here"

Optional flags: -SkipTests, -SkipWebBuild, -DryRun (PowerShell) or --skip-tests, --skip-web-build, --dry-run (shell).

Override branch with -Branch other-branch or ROAD_HAWK_GIT_BRANCH=other-branch.

Windows note: push-update.ps1 and update-package.ps1 create a C:\rh-web junction to the repo web/ folder so npm ci uses a short path and avoids ENOTEMPTY errors on long D: drive paths. If local web build still fails, use -SkipWebBuild — GitHub Actions builds the dashboard on push.

GET /api/health returns version and git_revision so clients can confirm what build is running.

Tests

pip install -e ".[dev]"
pytest

Smoke tests live in tests/test_*.py and are auto-discovered by pytest (including tests/test_documents.py).

CI on push to Road-Hawk:

test — pytest -q
web-build — npm ci + npm run build in web/

Project Structure

src/road_hawk/   → Python package (CLI, API, services, document intake, database, config)
web/             → Next.js dashboard (includes /documents intake page)
scripts/         → Start/setup, update-package, push-update (.ps1 + .sh)
tests/           → pytest suite (test_services, test_api, test_documents)
archive/         → Legacy prototypes and prior monolithic sources
data/            → SQLite database (gitignored)
.env.example     → Standalone/server/client environment template

Contact

Susquehanna Timberwolf Lines, LLC / That Dam BBS!, Inc.
Montrose, PA — USA · UTC-04:00

"Old School Truckin' Values. Building new School Tools."

Hours: 11am to 8pm Eastern, Monday to Friday. Closed weekends and federal holidays.

Website: www.thatdambbs.com
Email: office@thatdambbs.com
Phone: 570-442-0273
GitHub: github.com/Road-Hammer
Telegram: t.me/NEPA_BBS
LinkedIn: in/roadhammer
Facebook: profile
YouTube: @1stRoadhammer
X: @1stRoadhammer

Privacy

STWL does not sell user data.

Susquehanna Timberwolf Lines LLC does not sell, rent, trade, or broker user, driver, customer, vendor, or operational data to third parties. Data collected through STWL systems, including Road Hawk, is used only for authorized business, operational, compliance, safety, support, recordkeeping, and service-improvement purposes.

STWL does not use user data for third-party advertising markets, data-broker resale, or unrelated commercial profiling.

Any sharing of information is limited to what is necessary to provide services, comply with law, protect the business, support authorized operations, or fulfill user-approved requests.

The web dashboard includes a Privacy page (/privacy) with the Road Hawk–specific notice and full STWL statement.

Copyright and Trademark Notice

Road Hawk™ is a Road Hammer™ product developed for STWL operations.

Road Hawk™ and Road Hammer™ are trademarks and/or service marks claimed by Susquehanna Timberwolf Lines LLC. No permission is granted to copy, reuse, sell, sublicense, distribute, or commercially exploit STWL software, branding, documentation, workflows, logos, names, or related materials unless expressly authorized in writing by Susquehanna Timberwolf Lines LLC.

No public license is currently granted.

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
.vscode		.vscode
Screenshots		Screenshots
archive		archive
data		data
road_hawk_updates		road_hawk_updates
scripts		scripts
src		src
tests		tests
web		web
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
COPYRIGHT.md		COPYRIGHT.md
README.md		README.md
Road_Hawk		Road_Hawk
Road_Hawk.py		Road_Hawk.py
SECURITY_AUDIT_2026-07-11.md		SECURITY_AUDIT_2026-07-11.md
auto_update.py		auto_update.py
pyproject.toml		pyproject.toml
system_log.txt		system_log.txt

Navigation Menu

Repository files navigation

Road Hawk Version 0.0.2

Status

License status

Deployment modes

Platform notes

Quick Start (CLI)

Web UI

STWL brand assets

Document intake (Coyote Round 2)

Updating Road Hawk

Bump the package version

Pull updates (driver laptop, shop PC, fleet server)

Push updates (maintainer / Road Hammer dev)

Tests

Project Structure

Contact

Privacy

Copyright and Trademark Notice

About

Releases

Packages

Used by

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Road Hawk Version 0.0.2

Status

License status

Deployment modes

Platform notes

Quick Start (CLI)

Web UI

STWL brand assets

Document intake (Coyote Round 2)

Updating Road Hawk

Bump the package version

Pull updates (driver laptop, shop PC, fleet server)

Push updates (maintainer / Road Hammer dev)

Tests

Project Structure

Contact

Privacy

Copyright and Trademark Notice

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages