Skip to main content

Architecture

jhf-lantern is the route-aware mixed human-facing control surface for Helpifyr stack operators.

Canonical Doc Chain​

Read the live shell truth in this order:

  1. docs/ARCHITECTURE.md
  2. docs/LANTERN_MVP.md
  3. docs/HUMAN_INTERFACE_MODEL.md
  4. docs/NAVIGATION_REGISTRY.md
  5. docs/MODULE_FEATURES.md
  6. PLAN_LANTERN_PLAN_STUDIO_PHASE0_5.md for the bounded Plan Studio exception

PLAN_LANTERN_GUI.md remains a historical Phase-0 baseline and migration record. It is not the sole live shell Source of Truth after the route-aware mixed cutover.

v0 Import Normalization​

Import source:

  • https://github.com/JaddaHelpifyr/v0-lantern-implementation-plan
  • source commit: 82bdad3e50f87607df36ce5154e323c160e2e880 (GitHub PR #1 head)

Adopted from v0:

  • Vite + TanStack + React structure patterns
  • fixture/live adapter split pattern
  • shell/state decomposition pattern

Not adopted:

  • Next.js and App Router artifacts
  • non-canonical top-level routes
  • uncontrolled write/action surfaces outside admitted owner truth

Route-Aware Boundaries​

  • Lantern owns no truth.
  • Lantern owns no direct policy decisions.
  • Browser traffic must flow only through the Lantern BFF under /api/v1/lantern/*.
  • Lantern may consume bounded admitted initiator or HITL lanes, but only when owner truth explicitly publishes them.
  • Lantern owns no direct execution, approval, or materialization truth.
  • Browser traffic must flow only through the Lantern BFF under /api/v1/lantern/*.
  • Pattern owns Mission Control truth.
  • Lantern renders Mission Control UX but does not replace Pattern truth.

Current live posture on July 16, 2026:

  • shell phase: route_aware_mixed
  • shell copy and fallback posture must not collapse route_aware_mixed back into a coarse global read_only claim
  • Plan Studio: admitted Phase 0.5 lane surface
  • Inbox / approvals: admitted HITL or readback-only owner-decision posture depending on published owner packet truth
  • other routes remain a mix of admitted readback, restricted, preview, and future-contract posture

Runtime Shape​

  • lantern-ui: static frontend container
  • lantern-bff: read-only API aggregator and view-model adapter
  • live target: https://<internal-runtime-redacted>
  • live host: owner-supplied runtime host

Upstream Owners​

  • Fabric: truth, contracts, events, gates
  • Pattern: work graph, mission control truth
  • Dobby: learning and recommendation posture
  • Heddle: identity, session, claims, OIDC
  • Spindle: business context
  • Warp/OpenClaw: execution and run state
  • Tenter: voice runtime

Voice / Telephony / WebRTC Addendum​

Ownership​

  • jhf-tenter owns voice and conversation runtime.
  • Asterisk/FreePBX/SIP/WebRTC connectors are telephony runtime surfaces.
  • jhf-lantern is only the human-facing control surface.
  • Lantern owns no voice truth and stores no raw audio unless an explicit Fabric retention contract exists.

Phase 0​

Lantern may expose admitted readback or future_contract voice surfaces only:

  • Asterisk/FreePBX status
  • SIP/WebRTC gateway status
  • registered extensions/agents
  • active calls/sessions
  • failed calls
  • Tenter voice pipeline status
  • STT/TTS provider status
  • transcript/evidence links
  • recording/retention policy
  • permission state
  • source marker (fixture / live / future_contract)

No uncontrolled call start, call answer, recording control, or push-to-talk is allowed on the current shell.

Phase 1+​

Voice actions require:

  • Heddle-authenticated user/session
  • Fabric admission
  • Pattern work item when workflow-related
  • Tenter execution contract
  • Keystore secret_ref for SIP/provider credentials
  • explicit consent when audio/recording is involved
  • audit event and evidence link

Canonical Runtime Routes​

  • /
  • /quality
  • /work
  • /agents
  • /evidence
  • /operations
  • /settings

Release Eligibility Posture​

  • Public release-surface admission is bounded by contracts/admission/release_surface_inventory_v1.json.
  • Current repository history posture remains pending_history_scan in contracts/admission/repository_publication_history_posture_v1.json.
  • Active owner blocker: JaddaHelpifyr/jhf-lantern#382.
  • Repo-owned history evidence now runs through python scripts/verify_repository_history_posture.py and currently proves filtered_publication_required.
  • Live host coordinates stay in operator-only runtime runbooks and are excluded from public release-surface admission.

License: AGPLv3 Project: https://helpifyr.com