Skip to content

Getting Started

Welcome to Mainframe Assist — auto-remediation for failed z/OS batch jobs. A failed job is captured from the JES spool, an agentic brain diagnoses it and proposes a fix plan, a human approves (HITL), the fix executes on the mainframe, and the result is verified against explicit success criteria — all visible in the web UI at /remediations.

Repository layout

autofix/               The auto-fix system (the product)
  orchestrator/        Cloud Run control plane: lifecycle state machine, plan
                       validation/gating, chat HITL, self-learning KB, costs
  bridge/              Cloud Run singleton with mainframe hands (Zowe CLI):
                       failure watcher, executor, agentic brain (Claude on
                       Azure AI Foundry), spool capture + digest
  e2e/                 Playwright specs for the UI

benchmark/             Reproducible mainframe failure suites (SEQPROC classes,
                       CardDemo, PayrollDemo, Suite X) + verify_criteria.py

ui/                    Next.js web app (login, /remediations cockpit, /admin)

services/
  incident_intake/     Auth backend (register/login/sessions/admin roles) —
                       serves /api/auth/* behind the load balancer

shared/                Adapter library used by incident_intake
design/                Brand assets
docs/                  Specs and plans

The three isolated services

Service Image Role
autofix-orchestrator Cloud Run (public) Lifecycle state machine, plan validation, HITL chat, self-learning KB, cost ledger. Owns Firestore + GCS. Never touches the mainframe.
autofix-bridge Cloud Run (private, min=max=1) The only service that reaches z/OSMF. Failure watcher, executor, agentic brain (Claude Sonnet 4.5 on Azure AI Foundry), spool capture + digest.
lucent-ui Cloud Run + LB Next.js dashboard (login, /remediations, /admin).

Everything is isolated under autofix-* names (Cloud Run, GCS buckets, Firestore autofix_* collections, secrets). The orchestrator is the only Firestore/GCS owner; the bridge is the only component that reaches z/OSMF.

Deploys

  • autofix-orchestrator / autofix-bridge: autofix/*/cloudbuild.yaml via scripts/_autofix_deploy_*.sh (scripts/ is local-only, gitignored).
  • lucent-ui: autofix/ui_cloudbuild.yaml + scripts/_autofix_ui_redeploy.sh.

Full deployment reference: AutoFix services deploy and Developer setup.

Local development

For local development (Docker-only, no mainframe), the flow is:

# One-time bootstrap (installs Java, gcloud SDK, Python venv, npm deps)
bash scripts/bootstrap_local.sh

# Start the stack (Firestore emulator + intake + orchestrator + Next.js UI)
bash scripts/run_local.sh

# When run_local.sh prints all-green, open:
# http://localhost:3000

See Developer setup for the full walkthrough (WSL setup, gcloud auth, docker compose, live regression tests).

Adding a new page to this wiki

  1. Create the markdown under docs/ (e.g. docs/my-page.md).
  2. Add it to nav: in mkdocs.yml.
  3. Preview with mkdocs serve, then run ./deploy.sh from the wiki repo root.

See the GCP wiki deployment guide for one-time infrastructure and wiki README for the day-to-day flow.

History

The legacy incident→briefing (Lucent Spool triage) and incident→plan pipelines (agents/, plan_agents/, feedback_agents/, their services and infra) were removed from code and GCP in July 2026. services/incident_intake + shared/ remain solely as the auth backend for the UI. See git history before branch autofix-5 for the old systems.

Where to next