# Echo Prayer Integration Platform — Project Scope & Functionality Spec

**Status:** Draft for hand-off to build agent
**Author context:** Steven D. Mikel / CompEdge Solutions
**Date drafted:** 2026-08-03
**Origin:** Extracted from the emmanuellc.org (Emmanuel Lutheran Church) prayer-form
integration, discovered while diagnosing a production outage of that integration on
2026-08-03. That incident is documentation, not a blocker — see "Reference
Implementation" below for exactly what already works and should be reused, not
rebuilt from scratch.

---

## 1. Vision

Today, "Echo Prayer relay" is a single-tenant, hand-built PHP script living inside
one church's website project (emmanuellc.org). It works, but it's bespoke: one
config array, one set of hardcoded feed IDs, one API key per feed, no admin UI, no
self-service, no way to onboard a second church without copy-pasting the whole
thing and hand-editing PHP.

The goal is to extract this into its **own standalone project** — first as a
reusable multi-tenant relay service CompEdge can stand up for any client church in
minutes, and eventually (if traction justifies it) as a **subscription SaaS product**
any church using Echo Prayer (or a Squarespace/Wix/WordPress site with a prayer
request form) can sign up for directly, independent of CompEdge doing custom dev
work per client.

This document defines scope and functional requirements only. It is written so
another build agent can pick it up cold and implement Phase 1 without needing this
conversation's context.

---

## 2. Reference Implementation (study this first, reuse liberally)

Location: `E:\xampp\htdocs\emmanuellc.org` (local clone; origin on Gitea at
`CompEdgeSolutions/emmanuellc.org`). Production instance currently lives at
`https://elc-poc.compedgesolutions.us` on the old LAMP box (146.190.73.121, PHP
8.3-FPM).

Key files to read before building anything:

| File | What it does |
|---|---|
| `api/echo-prayer-submit.php` | The entire relay: CORS, honeypot, rate limit, spam scoring, field validation, Echo Prayer payload mapping, cURL relay, structured JSON response. This is the reference algorithm for Phase 1's core endpoint. |
| `vendor/compedgesolutions/spam-shield/src/SpamProtect.php` | Shared spam-protection library (`sp_honeypot_tripped`, `sp_rate_ok`, `sp_spam_score` with site-type overlays like `'ministry'`). Already a separate Gitea-hosted package — reuse as a Composer dependency, don't fork it. |
| `squarespace/congregation-prayer-form.html`, `squarespace/prayer-modal-launcher.html`, `squarespace/simplypray-form.html` | Three real embed variants currently live in production (pasted into Squarespace custom-HTML blocks): a full inline form, a modal/launcher variant, and a simplified variant. These are the actual UX patterns end users interact with today — treat them as the three embed "themes" Phase 1 must support generating. |
| `composer.json` | Shows the current dependency shape: `php >=8.1`, `compedgesolutions/spam-shield`. **Known issue:** its repository VCS URL still points at a dead GitHub remote (`git@github.com:SDMikel/spam-shield.git`) — the new project's `composer.json` must point at the Gitea mirror instead (`ssh://git@git.compedgesolutions.us:2222/CompEdgeSolutions/spam-shield.git`, confirm exact path before use). |

Current architecture in one sentence: a single PHP file holds a hardcoded
`$FEED_CONFIG` array keyed by `feed_slug`, each entry mapping to one Echo Prayer
`api_key` + `feedId` + `redirect_url`; the client posts JSON or form-encoded data,
the server validates/sanitizes/spam-checks it, maps it into Echo Prayer's payload
shape, and relays it server-side via cURL so the API key never reaches the browser.

**What Phase 1 must generalize:** that hardcoded array becomes a **database table**,
so onboarding a new church/feed is a data operation, not a code deploy.

---

## 3. Phasing

### Phase 1 — Standalone multi-tenant relay (subdomain, CompEdge-operated)
Move the relay off emmanuellc.org's docroot into its own project/subdomain (e.g.
`prayerlink.compedgesolutions.us` — naming TBD, see §9). Multi-tenant from day one
at the data layer (tenants/feeds table), but still CompEdge-provisioned — no
public signup yet. Every current emmanuellc.org feed migrates here with zero
behavior change from the church's/visitor's point of view.

### Phase 2 — Self-service SaaS
Public signup, subscription billing, tenant-facing admin dashboard, embed-snippet
generator with live preview, usage-based or tiered pricing.

### Phase 3 — Own domain / brand
Spin off its own product name and domain once Phase 2 has paying tenants beyond
CompEdge's own client base.

**This spec's functional requirements below are written for Phase 1, with Phase 2
requirements clearly marked so the data model and API don't need a rewrite to get
there.**

---

## 4. Functional Requirements — Phase 1 (build this first)

### 4.1 Core relay API
- [ ] POST endpoint accepting JSON or form-encoded submissions (same dual-format
      support as the reference implementation — Squarespace embeds may post either way).
- [ ] Multi-tenant feed lookup: incoming request identifies its feed via a
      `feed_slug` (or a rotated per-tenant public token — see security note in §5),
      resolved against a **database table**, not a hardcoded array.
- [ ] Field validation identical in spirit to the reference: required fields
      (name, email, subject/request text), max length enforcement, email format
      validation, boolean normalization (anonymous/notify checkboxes).
- [ ] Payload mapping to Echo Prayer's submission API shape (`feedId`, `name`,
      `email`, `prayerFor`, `prayerTitle`, `prayerDescription`, `isAnonymous`,
      `receiveEmailNotification`) — keep this mapping isolated in its own function/
      class so a second upstream provider could be added later without touching
      the HTTP layer (see §8 open question on multi-provider support).
- [ ] Server-side cURL relay to Echo Prayer using the tenant's stored API key —
      key never sent to or exposed in the browser.
- [ ] Structured JSON response (`success`, `message`, `redirect_url`,
      `echo_response`) matching the reference contract so existing embeds keep
      working unmodified where possible.
- [ ] Open redirect protection on any client-supplied redirect path (reference
      implementation's `resolve_redirect_url()` — reuse the same allow-list logic:
      must start with `/`, no `://`, no `//`).
- [ ] CORS: reference implementation currently wildcards
      (`Access-Control-Allow-Origin: *`) with a documented TODO to restrict by
      domain. **Phase 1 should implement the restriction properly** — since feeds
      are now tenant-scoped in a database, each tenant record should carry its own
      list of allowed origins, checked and reflected (not wildcarded) per request.

### 4.2 Spam protection stack
- [ ] Honeypot field (silent-success on trip, same as reference).
- [ ] Per-IP rate limiting, configurable per tenant (reference default: 10/hour;
      make this a tenant-level setting, not a global constant).
- [ ] Keyword-based spam scoring with a `'ministry'`-style overlay (reuse
      `spam-shield`) — silent success above threshold, logged for tenant visibility
      (see admin dashboard, §4.4).
- [ ] CSRF/timing token if the embed is rebuilt from scratch (per CompEdge's
      standard 6-layer spam stack used elsewhere — see `/new-contact-form` skill
      for the full standard: honeypot, CSRF, HMAC timing, per-IP rate limit,
      keyword scoring with overlay, reCAPTCHA v3). Reference implementation
      currently lacks CSRF/HMAC-timing/reCAPTCHA — Phase 1 is the place to close
      that gap since it's a natural rebuild point.

### 4.3 Embed snippet library
- [ ] Reproduce the three existing embed themes as generated, tenant-parameterized
      snippets (not hand-edited per client): full inline form, modal/launcher, and
      simplified form — matching the UX of `congregation-prayer-form.html`,
      `prayer-modal-launcher.html`, `simplypray-form.html`.
- [ ] Each generated snippet must be self-contained (inline `<style>`/`<script>`,
      no external asset dependency) since target sites are typically
      Squarespace/Wix custom-HTML blocks with no build pipeline — same constraint
      as today.
- [ ] Snippet must point at the tenant's own feed identifier baked in at
      generation time (no client-side config needed beyond the snippet itself).

### 4.4 Tenant admin surface (minimal for Phase 1, expand in Phase 2)
- [ ] Even without public signup, Phase 1 needs *some* interface (can be
      CLI/artisan-style script or a bare internal admin page) for CompEdge staff to:
  - Create/edit a tenant + feed (Echo Prayer `api_key`, `feedId`, redirect URL,
    allowed origins, rate-limit override).
  - Regenerate/view the embed snippet for a given tenant.
  - View recent submissions/spam-block log for a tenant (for support/debugging —
    do NOT store full prayer request text longer than necessary; see §5 privacy note).

### 4.5 Data model (sketch — refine during build)
```
tenants
  id, name, created_at, status (active/suspended), plan (Phase 2), billing_ref (Phase 2)

feeds
  id, tenant_id (FK), feed_slug (public, used in embeds), echo_prayer_api_key,
  echo_prayer_feed_id, redirect_url, allowed_origins (JSON/text list),
  rate_limit_per_hour (nullable = use tenant/global default), created_at

submission_log
  id, feed_id (FK), submitted_at, outcome (success/spam_blocked/rate_limited/upstream_error),
  ip_hash (NOT raw IP — see §5), echo_prayer_submission_id (nullable)
  -- deliberately NOT storing prayer request text here; that lives in Echo Prayer,
  -- this table is for operational visibility only
```

---

## 5. Non-Functional Requirements

- **Secrets:** Echo Prayer API keys are per-tenant secrets stored in the
  database, not `.env` files (unlike CompEdge's usual single-tenant `.env`
  pattern) — but the *database credentials themselves* and any platform-wide
  secrets still follow CompEdge's standard: `E:/xampp/private/{project}.env`
  locally, `/var/private/{project}.env` in production, loaded via
  `parse_ini_file()` with `INI_SCANNER_RAW`. Never `vlucas/phpdotenv`.
- **PII/privacy:** prayer requests are inherently sensitive personal/spiritual
  data. Phase 1 should not retain prayer request text at the relay layer beyond
  what's needed to complete the cURL relay in-memory — the system of record for
  content is Echo Prayer itself. Only metadata (outcome, timestamp, hashed IP) is
  logged locally for operational/support purposes. Revisit this explicitly before
  Phase 2 public signup — will likely need a privacy policy and a data-retention
  statement regardless.
- **Rate limiting / spam:** must be tenant-configurable, not a single global
  constant (a large congregation's prayer chain will legitimately generate more
  volume than a small one).
- **CORS:** must be per-tenant allow-list, not wildcard (see §4.1).
- **Uptime/monitoring:** this is a synchronous, user-facing form submission path —
  a 502/timeout here is immediately visible to a real end user in emotional
  distress submitting a prayer request. Recommend basic uptime monitoring on the
  public endpoint from day one (matches the severity of the 2026-08-03 outage this
  spec grew out of).
- **PHP/infra baseline:** PHP 8.3 via FPM (fleet standard), MySQL (managed
  cluster per DO migration project — confirm capacity before adding new schemas;
  see `do-migration` project memory on the 1GB/75-connection managed cluster
  already near capacity), Apache vhost per fleet convention, deploy via Gitea
  (`git.compedgesolutions.us`) + `deploy.sh` pull-based flow. **Do not** configure
  any dependency against GitHub — GitHub access for this org is fully
  deprecated/suspended; all git remotes must be Gitea.

---

## 6. Functional Requirements — Phase 2 (SaaS, design for but don't build yet)

- [ ] Public signup flow: church creates account, connects their own Echo Prayer
      account/API key (or CompEdge brokers a bulk/reseller relationship with Echo
      Prayer — **open question, needs Steve's input**, see §8).
- [ ] Subscription billing (Stripe or similar) — tiered by submission volume
      and/or number of feeds/embeds.
- [ ] Self-service tenant dashboard: manage feeds, generate/copy embed snippets
      with live preview, view submission analytics (volume over time, spam-block
      rate), manage allowed origins, adjust rate limits within plan caps.
- [ ] Tenant authentication (login, password reset, ideally magic-link or OAuth
      to lower friction for non-technical church admins).
- [ ] Super-admin (CompEdge) dashboard: cross-tenant visibility, billing status,
      support tools, ability to impersonate/debug a tenant's config.
- [ ] Onboarding wizard: guided flow from signup → Echo Prayer connection →
      embed theme selection → copy-paste snippet, minimizing support burden for
      non-technical church staff (this audience skews low-technical — design
      copy/UX accordingly, similar tone to the emmanuellc.org site's own content
      rules: answer "what is this and how do I use it" within 30 seconds).

---

## 7. Out of Scope (explicitly, for now)

- Building a competing prayer-request *platform* (i.e., replacing Echo Prayer
  itself) — this project is a relay/integration layer, not a prayer-management
  system.
- Multi-provider support beyond Echo Prayer (see §8 for whether this becomes a
  Phase 2+ consideration).
- Mobile app / native client.
- Any change to Echo Prayer's own API or account model — this project is a
  consumer of their API, not a partner integration (unless a business
  relationship with Echo Prayer changes that — again, Steve's call).

---

## 8. Open Questions (flag to Steve before/during build, don't guess)

1. **Naming.** Working subdomain suggestion: `prayerlink.compedgesolutions.us` or
   `echorelay.compedgesolutions.us` — needs a real product name if Phase 2/3 SaaS
   spin-off is genuinely pursued. Don't invent a brand identity unprompted; ask.
2. **Echo Prayer relationship.** Does each tenant church bring their own Echo
   Prayer account + API key (simplest, no business relationship needed), or does
   CompEdge pursue some kind of reseller/partner arrangement with Echo Prayer
   itself? This materially changes the Phase 2 onboarding flow.
3. **Multi-provider ambition.** Is Echo Prayer the only target platform long-term,
   or could this become a generic "prayer form → any backend" relay (Echo Prayer,
   Planning Center, ChurchTrac, etc.)? Affects how tightly Phase 1's payload-mapping
   layer should be abstracted now vs. later.
4. **Pricing model** for Phase 2 (flat tiers vs. usage-based vs. freemium) — not
   needed for Phase 1 but worth deciding early since it affects the data model's
   `plan`/`billing_ref` fields.
5. **Existing emmanuellc.org feeds' migration:** once Phase 1 is live, do the two
   existing feeds (`emmanuel-lutheran-church-prayer-chain`,
   `pastors-simply-pray-group`) cut over to the new project, or does
   emmanuellc.org's `elc-poc` endpoint keep running independently indefinitely?
   Recommend eventual cutover for a single source of truth, but this is a
   deploy-sequencing decision, not a build-agent decision.

---

## 9. Suggested MVP Definition (Phase 1 "done")

A build agent can consider Phase 1 complete when:
- [ ] New standalone project exists on its own subdomain, own Gitea repo, own
      `.env`/secrets, deployed via the standard Gitea pull-based flow.
- [ ] Database-backed multi-tenant feed config replaces the hardcoded array.
- [ ] The existing emmanuellc.org feeds can be recreated in the new system with
      byte-for-byte equivalent behavior (verified via the same kind of smoke test
      used to confirm the 2026-08-03 outage fix: CORS preflight, real POST,
      redirect resolution, spam-block behavior).
- [ ] Per-tenant CORS allow-list replaces the wildcard.
- [ ] Full spam-shield stack integrated (honeypot, rate limit, keyword scoring at
      minimum; CSRF/HMAC-timing/reCAPTCHA if time allows — see §4.2).
- [ ] At least one embed theme (start with the simplest — `simplypray-form.html`
      equivalent) generates correctly for a test tenant and submits successfully
      end-to-end against a real Echo Prayer feed.
- [ ] Basic internal admin capability exists to create tenants/feeds without
      hand-editing code (script or bare page — full dashboard is Phase 2).

---

*This document is a scope/spec only. No code has been written against it. Hand
this file to a build agent along with read access to
`E:\xampp\htdocs\emmanuellc.org` as the reference implementation.*