Forms Service — Architecture

Last Updated: 2026-06-28 Status: Active Service: apps/forms-service Companion docs: forms-vision.md · api-spec.md · database.md · permissions.md · billing.md · embedding.md · webhooks.md

1. What This Service Is

Forms Service is vlozi's multi-tenant form backend — a Web3Forms-grade capture layer described in forms-vision.md. A tenant creates a form, gets a public form_id, and embeds a plain <form> (or AJAX/JSON call, or the SDK) on any website. The service filters spam, stores the submission, bills credits, notifies the owner via email, fires webhooks, and exposes analytics.

It consumes existing platform services: identity (Contact Intelligence), email delivery (Communication), file storage (Media/R2), and auth/rate-limiting (Gateway). Net-new code lives only in apps/forms-service.

2. Where It Sits in the Platform

3. Tech Stack

4. Three Request Surfaces

All three surfaces reach forms-service only through the gateway — direct worker access is rejected unless the x-gateway-key matches GATEWAY_SECRET.

5. Middleware Pipeline

Requests pass through the following layers in order (same pattern as apps/blog-service):

1. Logger            → hono/logger
2. DB Middleware     → create/cache Neon connection from FORMS_DATABASE_URL
3. Gateway Guard     → validate x-gateway-key against GATEWAY_SECRET
                       hydrate RequestContext from trusted headers
                       (admin: x-tenant-id, x-user-id, x-user-permissions)
4a. Public submit    → load form by :form_id (30s in-isolate cache)
                       → derive tenant_id from form row
                       → allowed_origins (CORS) check
                       → Spam Guard (honeypot → rate limit → Turnstile if enabled)
                       → credit gate (read tenant_credits; 5min in-isolate cache)
4b. Admin / MCP      → requireTenant → requirePermission("forms:read|write|submissions.export")
5. Route handler

Caching

6. Submission Flow (Public POST /f/:form_id)

Failure outcomes:

• Honeypot tripped → silent 200 {success:true}, stored status=spam
• Captcha fails → 400 {success:false, message:"Captcha verification failed"}, stored status=spam
• Credit insufficient → 402 Payment Required
• Validation error → 400 {success:false, message, errors}
• Rate limit → 429 {success:false, message:"Too many requests"}
• Origin not allowed → 403 {success:false, message:"Origin not allowed"}

Response shape is Web3Forms-compatible so existing Web3Forms front-ends work unchanged. Full matrix in api-spec.md.

7. Service Boundaries

8. Gateway Integration

api.vlozi.app/forms/f/*     → CORS (any-origin, POST/GET/OPTIONS)
                               → forward (no auth mw) → forms-service /f/*
 
api.vlozi.app/forms/admin/* → authMiddleware (JWT) → buildDownstreamHeaders
                               → forms-service /admin/*
 
api.vlozi.app/forms/mcp/*   → authMiddleware (JWT) → buildDownstreamHeaders
                               → forms-service /mcp/*

Headers forwarded by buildDownstreamHeaders(): x-gateway-key, x-request-id. Admin/MCP paths also inject: x-tenant-id, x-user-id, x-user-permissions. The public path additionally passes through inbound origin, cf-connecting-ip, user-agent, and referer.

Service binding in apps/gateway/wrangler.toml:

[[services]]
binding = "FORMS_SERVICE"
service = "vlozi-forms-service"

9. Environment & Bindings

Dev port: 8796 (wrangler dev).

10. Design Constraints (v1)

• No new auth primitive — the public form_id is the credential (no secret, no api-key middleware change); the admin path reuses the existing JWT/gateway flow.
• Web3Forms response compatibility — public submit returns { success, message, data } and honors redirect.
• Stateless worker — all state in Neon; form definitions cached per-isolate with 30s TTL.
• Dashboard-first delivery — every submission is stored and visible in the inbox; email is an opt-in per-form setting, never the only record.
• Spam without friction — honeypot + rate limit are always on; Turnstile is per-form opt-in for high-spam endpoints.
• Best-effort side effects — notifications, webhook delivery, and credit metering run in waitUntil() and never block the response to the visitor.