Skip to main content

Architecture

Documentation Map​

Architecture

System Overview​

jhf-web is a static-first website with a narrow serverless intake surface.

Core flow:

  1. static HTML, JS, locale JSON, and assets are built into .pages-dist
  2. Cloudflare Pages serves the public site and runs Pages Functions
  3. contact and early-access forms POST to /api/contact
  4. /api/contact validates Turnstile and either:
    • forwards normalized payloads to an external webhook
    • or falls back to a mailto response
  5. a mirrored Docker/nginx host on <internal-runtime-redacted> exists for controlled operational checks

Main Components​

  • static page surface: *.html, assets/, locales/
  • client runtime: assets/js/
  • intake API: functions/api/contact.ts
  • runtime visibility surfaces:
    • functions/health.ts
    • functions/ready.ts
  • build and verification helpers: scripts/
  • mirrored host runtime:
    • Dockerfile
    • docker-compose.yml
    • nginx.conf

Data Flow​

Public content flow​

Browser -> Cloudflare Pages -> HTML/JS/locales/assets

Intake flow​

Browser form -> /api/contact -> Turnstile verification -> normalized payload -> optional webhook -> success/fallback response

Mirror runtime flow​

Git/Gitea -> deployment sync -> Docker/nginx on <internal-runtime-redacted> -> optional exporter on :9113

External And Internal Interfaces​

  • public website routes
  • /api/contact
  • /health
  • /ready
  • optional outbound webhook via CONTACT_WEBHOOK_URL
  • host-only:
    • /admin/
    • /nginx_status
    • :9113/metrics

Dependencies​

  • Cloudflare Pages
  • Cloudflare Turnstile
  • Gitea CI/package path
  • optional Docker mirror host
  • optional external intake webhook

Operating Assumptions​

  • Linux runner CI is authoritative
  • Gitea remains source of truth
  • public production path is Cloudflare Pages
  • mirrored host runtime is useful but secondary

Role In Helpifyr​

This repo is the public presence and intake edge, not the backend system of record.

Expected Role Toward helpifyr-fabric​

  • expose identity, capabilities, and current runtime surfaces
  • contribute status/readiness/presence signals
  • remain mostly read-only from Fabric's perspective

License​

AGPLv3. See LICENSE (LICENSE).

Learn more at helpifyr.com.