Skip to main content

Architecture

Documentation Map​

Architecture

System Overview​

jhf-warp is a FastAPI service that turns task and runtime context into bounded orchestration decisions. It sits between upstream task inputs, the real OpenClaw runtime, and a small number of optional downstream systems.

Main Components​

  • API layer
    • FastAPI application under src/oc_agent_manager/app.py
    • canonical exposed service surface
  • orchestration/domain layer
    • task classification, setup preview, topology, drift, rollout, and persistent-agent logic
  • runtime adapter layer
    • fixture, local CLI, and SSH/host-adjacent OpenClaw access patterns
  • persistence layer
    • Postgres operational store with Alembic migrations
    • fixture-memory fallback for development/test
  • control-plane layer
    • doubtfire-control reconcile, leases, schedule, watchdog, and dispatch-preview surfaces
  • packaging/verification layer
    • Linux Gitea CI smoke path and OCI image build/publish helper scripts

Data Flow​

  1. A caller sends task, domain, topology, or control requests to the FastAPI service.
  2. The service validates input with Pydantic models.
  3. The orchestration layer reads current runtime and persistence state.
  4. The service returns setup/runtime/topology/drift/control summaries or writes durable records.
  5. Optional outbound integrations deliver setup/sync/control information to other systems.

Internal and External Interfaces​

Internal/runtime-facing:

  • OpenClaw runtime inventory and mutation planning
  • operational Postgres store
  • control-agent callbacks

External/operator-facing:

  • health, readiness, version, and OpenAPI
  • runtime/topology/drift/audit endpoints
  • persistent-agent and control-agent governance endpoints
  • OCI registry artifact path

Dependencies​

Primary hard dependencies:

  • Python 3.12+
  • FastAPI/Pydantic
  • SQLAlchemy/Alembic/psycopg
  • OpenClaw runtime contracts

Optional or conditional dependencies:

  • Helpifyr Pattern
  • Helpifyr Spindle
  • jhf-shuttle
  • jhf-fabric as a future consumer of manifest/profile/capability surfaces

Operating Assumptions​

  • Linux CI runner behavior is the reference verification path
  • production persistence uses Postgres, not fixture-memory
  • mutating endpoints require deployment-time auth and network boundary protection
  • OpenClaw runtime state must be verified from the real host/container context when runtime questions matter

Role In The Helpifyr Ecosystem​

Within Helpifyr, jhf-warp is the orchestration/policy/control-plane service for OpenClaw-based agent teams. It is a supporting internal tool, not a public product surface.

10/10 Upgrade Direction​

The repository baseline is now aligned to a stronger target role:

  • runtime orchestration owner
  • desired-vs-actual reconciliation owner
  • runtime drift / rollout / degraded-state owner
  • delegation execution and revocation-consequence owner
  • desired-state persistence and reconcile anti-flap owner

This direction does not change the broader ecosystem truth boundaries:

  • identity truth stays with jhf-spindle
  • bundle and policy projection truth stay with jhf-fabric
  • transport truth stays with jhf-shuttle
  • OIDC/operator-context truth stays with jhf-heddle
  • secret truth stays with jhf-keystore

Expected Role Toward jhf-fabric​

jhf-fabric should treat this repository as:

  • a standalone internal service with machine-readable self-description
  • a source of runtime, topology, drift, and capability metadata
  • a candidate for future discovery, compatibility checks, and policy gating

Fabric should not yet treat it as:

  • a remote MCP server
  • a central event bus
  • a fully authenticated or registry-driven service mesh participant

License​

AGPLv3. See ../LICENSE (LICENSE). Learn more at helpifyr.com.