local-workflow-core

local-workflow-core is a local-first execution layer for business orchestration, data transformation, and audit trails. It helps teams phase out direct dependency on ERP/SaaS/Excel while keeping operations running.

10-Second Pitch

Run workflows locally, normalize incoming business data into canonical contracts, and emit tamper-evident audit evidence by default.

Why This Exists

Many teams are locked into vendor-specific APIs and spreadsheet-heavy operations. This project provides an OSS control plane that:

• orchestrates workflows locally,
• transforms heterogeneous records into canonical schema,
• records tamper-evident audit events,
• supports staged migration (shadow -> canary -> full) with rollback.

Scope

In scope:

• local-first workflow orchestration core,
• canonical data transformation layer,
• append-only audit ledger,
• adapter/port abstraction for external systems.

Out of scope (v0.x):

• full ERP replacement,
• vendor-specific enterprise packs,
• guaranteed fully cloudless runtime.

Project Layout

src/local_workflow_core/
  api/             # FastAPI surface
  domain/          # Core domain models
  ports/           # Interface contracts
  adapters/        # Vendor/system adapters
  orchestration/   # Workflow engine
  transform/       # Canonical transformation
  audit/           # Audit ledger
  policy/          # Runtime and release policy checks

Quick Start

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest
uvicorn local_workflow_core.api.app:app --reload

Workflow Templates (Initial 5 Workflow Templates)

• configs/workflows/order_intake_workflow.json
• configs/workflows/invoice_reconciliation_workflow.json
• configs/workflows/journal_audit_workflow.json
• configs/workflows/erp_order_snapshot_workflow.json
• configs/workflows/saas_auth_smoke_workflow.json (socket-free offline mock transport supported)

Run all templates offline:

make run-workflows
make sli-offline
make sli-gate-offline

Run full offline verification in deterministic order:

make verify-offline

Run extended offline governance and rollout checks:

make sbom-offline
make sbom-gate-offline
make rollout-guard-offline
make sli-history-offline
make audit-integrity-gate-offline
make checksum-gate-offline

Run the full governance bundle in one command:

make verify-governance-offline

Prepare sample ERP DB explicitly:

make init-sample-erp

Run one workflow explicitly:

PYTHONPATH=src python scripts/run_workflow.py \
  --workflow configs/workflows/order_intake_workflow.json \
  --rollout-mode full \
  --pretty

Run SaaS auth smoke flow offline (no socket bind):

make run-saas-auth-smoke-offline

This runs api_key, bearer (env), and oauth_client_credentials auth checks from configs/workflows/saas_auth_smoke_workflow.json via in-process mocked transport.

Optional env overrides:

• LWC_SAAS_API_KEY
• LWC_SAAS_BEARER_TOKEN
• LWC_SAAS_OAUTH_CLIENT_ID
• LWC_SAAS_OAUTH_CLIENT_SECRET
• LWC_SAAS_OAUTH_ACCESS_TOKEN

Offline Validation (No External Package Install)

If your environment cannot install packages from the internet, run:

make test-offline

This executes the standard-library unittest suite with PYTHONPATH=src.

API (initial)

• GET /health
• GET /config
• POST /workflow-runs

Governance and Security

• License: Apache-2.0
• Security reporting: see SECURITY.md
• Contribution process: see CONTRIBUTING.md
• Project governance: see GOVERNANCE.md
• Release process: see RELEASING.md

Roadmap (near term)

1. Add strict contract tests for adapters.
2. Add signed release artifacts + SBOM CI gate.
3. Add canary/rollback policy automation.

Offline Release Gate

make gate-offline

This checks required OSS governance files and enforces critical=0 and high=0 inputs.

Offline Operations Playbook (SBOM / Rollout / SLI History / Integrity)

Use make verify-governance-offline for the default offline governance flow:

make verify-governance-offline

Equivalent explicit sequence:

make run-workflows
make sbom-offline
make sbom-gate-offline
make rollout-guard-offline
make sli-history-offline
make sli-gate-offline
make audit-integrity-gate-offline
make gate-offline
make checksum-gate-offline

New target quick examples:

make audit-integrity-gate-offline
make checksum-manifest-offline
make checksum-gate-offline
make verify-governance-offline

Target summary:

• make sbom-offline: run scripts/generate_sbom_offline.py and write sbom.json.
• make sbom-gate-offline: validate SBOM policy constraints before release progression.
• make rollout-guard-offline: build data/sli-latest.json then run rollout guard in JSON mode.
• make sli-history-offline: build historical SLI output for trend/regression inspection.
• scripts/audit_integrity_gate_offline.py: reads the audit ledger and fails when chain continuity or minimum event-count checks do not pass.
• scripts/checksum_gate_offline.py: computes SHA-256 file checksums, emits a manifest snapshot when no manifest is given, and enforces manifest match in gate mode.
• make audit-integrity-gate-offline: run scripts/audit_integrity_gate_offline.py with offline defaults.
• make checksum-manifest-offline: generate a local checksum snapshot for tracked governance files.
• make checksum-gate-offline: verify tracked governance files against examples/checksum_manifest.json.

Rollout Controls

• LWC_ROLLOUT_MODE=full|shadow|canary
• LWC_CANARY_PERCENT=0..100
• LWC_AUDIT_PATH=<path>

Operator Web Console (Non-Engineer Path)

• Provide a lightweight browser UI that sequences run_workflow, rollout_guard_offline, sli_gate_offline, audit_integrity_gate_offline, and checksum_gate_offline in one guided workflow.
• Operators drive staged migration (shadow -> canary -> full) by clicking the recommended next step; the console records gate outputs, alerts on CANARY_HOLD/ROLLBACK, and preserves audit snapshots for compliance reviews.
• Shell scripts remain available for automation, while the UI surfaces the same commands with contextual explanations so non-engineers can execute migrations safely.

Operator Stage Migration Services

• scripts/operator_stage_migration.py orchestrates the CLI sequence and emits a JSON report per stage (useful for operator UIs and automation).
• scripts/operator_stage_api.py exposes that workflow via HTTP endpoints (POST /run-stage, POST /run-rollback) and mirrors the CLI summary for UI consumption. The response includes a session block (with session_id, operator_id, stage, workflow, success, and summary) so UI and auditors share the same telemetry.
• scripts/operator_stage_ci.py is the CI-friendly runner that executes the orchestrator, persists the JSON summary to artifacts/operator_stage_summary.json, and returns a nonzero exit code on gate failure.
• Operator-stage interactions append session metadata to data/operator_stage_sessions.jsonl. Each entry includes session_id, operator_id, stage, workflow, success, and the JSON summary emitted by the scripts, enabling UI and auditors to replay sessions.
• scripts/operator_stage_rollback.py provides a rollback-focused gate flow that replays rollout guard, SLI gate, audit integrity gate, and checksum gate, returning a JSON summary that the UI can display when rollback decisions are triggered.

Adapters

• in_memory: local utility actions (echo, summarize_amounts, reconciliation checks)
• csv: local CSV ingestion (load_csv, lookup_csv)
• canonical: schema normalization (to_canonical, canonical_from_rows, validate_required_fields)
• erp_sqlite: ERP-like query/execute against SQLite (query, execute)
• saas_http: SaaS-style HTTP request adapter (request)
  • auth modes:
    • api_key: { "type": "api_key", "header": "X-API-Key", "value|value_env": ... }
    • bearer: { "type": "bearer", "token|token_env": ... }
    • oauth_client_credentials: token endpoint + client credentials flow

SLI Metrics

scripts/sli_report.py computes metrics from audit ledger:

• workflow_success_rate
• workflow_completion_rate
• shadow_mismatch_rate
• dependency_call_ratio
• chain_breaks
• audit_event_count

scripts/sli_gate_offline.py enforces thresholds for offline gating.