SignPayGo

Developer Project Brief

Platform: ASP.NET MVC (latest) · PostgreSQL · Razor Views

Start URL: https://secure.signpaygo.com/signpaygo-dashboard.html

Status: HTML/CSS/JS prototypes complete — ready for back-end implementation

Document: Confidential — internal use only

1. Pages & Routing

All pages are currently static HTML prototypes. Browse every page and interaction at the URL above before writing any code. Implement each as an MVC controller action + Razor view.

1.1 Settings — Integrations Tab

The Integrations tab contains an API & Webhooks section. Hide this entire section using CSS in v1 — it will be surfaced in v2.

#api-webhooks-section { display: none; }

2. PostgreSQL Database Schema

Use snake_case table and column names throughout. Never use full_name — always split into first_name and last_name as separate columns. All tables include the following four audit columns (omitted from each table below for brevity):

created_by UUID FK → users(id)  |  created_on TIMESTAMPTZ NOT NULL DEFAULT now()
modified_by UUID FK → users(id)  |  modified_on TIMESTAMPTZ NOT NULL DEFAULT now()

Use UUID primary keys everywhere (gen_random_uuid()).

users

organizations

One user can belong to many orgs; one org can have many users (via org_members).

org_members

events

event_reminders

participants

waiver_templates

email_log

payouts

3. Third-Party Integrations

3.1 Stripe Connect — Payments & Routing

Each organization connects their own Stripe account via Stripe Connect Express. SignPayGo acts as the platform account; orgs are connected accounts. Funds flow: parent → Stripe → org's connected account (minus platform fee).

• Use Stripe Connect Express — not Standard or Custom.
• Onboarding flow: org admin clicks "Connect with Stripe" → redirect to Stripe-hosted onboarding → Stripe redirects back to /settings/stripe/callback.
• Use a branded interstitial page before the Stripe redirect — show the SignPayGo logo and a progress indicator so the user never sees a raw Stripe URL.
• Only "Create a new Stripe account" is supported in v1. Do not offer the option to link an existing Stripe account.
• Store stripe_account_id and stripe_onboarding_done on the organizations table.
• Use Stripe PaymentIntents with transfer_data.destination pointing to the connected account.
• Store all payment and payout data via Stripe webhooks (payment_intent.succeeded, charge.refunded, payout.paid, etc.).

3.1.1 Accepted Payment Methods

The parent-facing signing page must support all three of the following payment methods. Stripe handles the rendering and authentication for each — no third-party SDKs required beyond the Stripe JS library.

3.1.2 Credit Card Processing Fee

SignPayGo passes the credit card processing fee to the parent at checkout. The fee rate is configurable per organization to accommodate custom pricing agreements.

• The fee rate is stored as organizations.cc_fee_percent — type NUMERIC(5,2), default 3.90.
• The fee is calculated server-side at checkout: fee = round(event_price_cents × (cc_fee_percent / 100)). Never calculate this client-side.
• The total charged to the parent is event_price_cents + fee_cents.
• Display the fee as a line item on the checkout page before the parent confirms payment — e.g. "Registration fee: $285.00 + Processing fee (3.9%): $11.12 = Total: $296.12".
• Store the base amount and fee separately: participants.amount_paid_cents holds the total charged; add a participants.fee_cents column to record the processing fee portion for reporting.
• The organizer can update cc_fee_percent in Settings → Organization → Pricing & Billing. Changes apply only to new events — do not retroactively change fees on existing participants.
• Free events (events.price_cents = 0) skip payment entirely — no Stripe charge, no fee calculation.

3.1.3 Refunds

Full refunds are initiated by the organizer from the participant view modal. The UI confirmation is already implemented in the frontend. The server-side implementation must:

• Accept a POST to /events/{eventId}/participants/{participantId}/refund — authenticated, organizer-only.
• Verify the participant's status is signed_paid and that a stripe_payment_id exists on the record before attempting the refund.
• Issue a full refund via the Stripe Refunds API: stripe.Refunds.Create with PaymentIntent = participants.stripe_payment_id. Do not implement partial refunds in v1.
• The refund is issued to the original payment method automatically by Stripe — credit card, Apple Pay, and Google Pay are all handled the same way through the PaymentIntent.
• On success: set participants.status = 'cancelled', set participants.signed_pdf_path and signed_pdf_url to NULL (the PDF is voided but the S3 object is retained under WORM lock for legal audit purposes — do not delete it from S3).
• Log the refund to the email_log table.
• Send a confirmation email to the parent notifying them of the cancellation and refund (add a refund_confirmation email template in v1).

3.2 Google Sign-In

• Implement OAuth 2.0 / OpenID Connect using Google Identity Services.
• On first Google login: create a users row with google_sub set, password_hash NULL.
• On subsequent logins: match by google_sub first, then fall back to email (handle account-merge edge case).
• Store google_sub as a UNIQUE column. Do not rely on email alone — users can change their Google email.
• Show the "Sign in with Google" button on /login and /register pages only.

3.3 FingerprintJS — Device Identity & Fraud Prevention

• Integrate FingerprintJS Pro on the public parent-facing signing page.
• Capture the visitorId before form submission and include it in the waiver POST payload.
• Store as fingerprint_id on the participants table.
• Verify the visitorId server-side using the FingerprintJS Server API — retrieve confidence score, incognito flag, and bot detection result.
• Flag (do not auto-block) submissions with bot score > 0.7 or incognito = true for manual review.
• Do not expose FingerprintJS API keys to the client — proxy verification through your server.

3.4 Email — SendGrid or AWS SES

Use SendGrid as the primary provider (preferred) or AWS SES as fallback. Route all outbound email through a single IEmailService abstraction so the provider can be swapped without touching calling code. Track opens, clicks, and bounces via SendGrid Event Webhooks or SES SNS notifications. Write every outbound email to the email_log table including provider_msg_id. On bounce, mark the participant's email as invalid and surface a warning in the participants view.

3.4.1 Email Templates

There are three parent-facing transactional templates plus supporting organizer and system templates. The three parent templates are HTML files checked into the repository and rendered server-side with template variable substitution.

3.4.2 Invitation Email — When It Sends

The invitation email (email-invitation.html) is the very first email a parent receives. It is sent once per participant when the organizer publishes and sends the event. It is never sent again — subsequent emails are always reminders, not invitations.

• Trigger: Organizer clicks "Publish & Send" on a new event, or clicks "Add Attendee → Send Invitations" to add participants after the event is already live.
• Condition: Participant status is pending (no prior invitation sent). Check email_log for an existing invitation row for this participant_id to prevent duplicates.
• Contains: Child's name, event name/dates/location, deadline, registration fee, and a unique sign_pay_url (the public signing link scoped to this participant).
• Template variables: {{parent_first_name}}, {{child_first_name}}, {{child_last_name}}, {{event_name}}, {{org_name}}, {{event_dates}}, {{event_location}}, {{deadline_date}}, {{amount_due}}, {{sign_pay_url}}, {{organizer_name}}, {{organizer_email}}, {{unsubscribe_url}}.

3.4.3 Reminder Emails — When They Send

Reminders are configured by the organizer when creating or editing an event. Each reminder is stored as a row in event_reminders with a send_at date and an is_enabled flag. A background job (Hangfire) runs daily and dispatches any reminders whose send_at date matches today and whose sent_at is still NULL.

The reminder template is chosen dynamically per participant based on their current status at the time the job runs:

After sending each batch for a reminder row, set event_reminders.sent_at = NOW() to prevent re-sending. Log each individual email to email_log with the correct template_key.

3.4.4 Reminder Schedule — Set on the Create Event Page

The organizer configures reminder dates on the Create Event / Edit Event page in the Reminders section of the form. Each date the organizer sets creates one row in event_reminders. Reminders can be individually toggled on/off via is_enabled without deleting the row.

• Suggested defaults to pre-populate in the UI (organizer can change): 7 days before deadline, 3 days before deadline, 1 day before deadline.
• Organizers can add or remove reminder dates freely before the event is sent. After invitations are sent, existing reminder dates can be toggled on/off but the UI should warn before deleting a future reminder row.
• The Hangfire job should run once per day at a consistent off-peak time (e.g. 8:00 AM in the organization's timezone, or UTC if timezone is not captured).
• If a reminder send_at date is in the past and sent_at is still NULL (e.g. the job was down), skip it — do not send late reminders retroactively.

3.4.5 Template Variable Reference

All three parent-facing templates share the same variable naming convention. Populate them server-side before sending. The sign_pay_url must be a unique, participant-scoped URL — never a generic event link.

3.5 Zapier V2 — Coming Soon

Zapier integration is deferred to v2. No work required in v1. When implemented, it will fire outbound webhook triggers on key participant and event lifecycle events (signed, paid, completed). The Settings → Integrations tab shows Zapier with a "Coming Soon" badge and a disabled "Notify Me" button.

3.6 Make.com V2 — Deferred

Make.com integration is planned for v2. No work required in v1.

4. Template Data — Past vs. Library

4.1 Past Templates — Move to Database

Past templates currently load from PastTemplates.js. In the MVC implementation they must come from the waiver_templates table, scoped to the logged-in user's organization.

• Query: SELECT * FROM waiver_templates WHERE org_id = @orgId ORDER BY created_at DESC
• The "used N×" and "last used" display values come from use_count and updated_at.
• When a user applies a template to an event, increment use_count and set updated_at.
• Remove the <script src="PastTemplates.js"> tag and replace with a call to GET /api/templates/past (or a Razor partial populated server-side).

4.2 SignPayGo Library — Keep as JSON

The shared SignPayGo Library templates can remain as a static JSON file served from wwwroot for v1. No database table required.

• File location: wwwroot/data/TemplateLibrary.json
• Load client-side via fetch('/data/TemplateLibrary.json') — no change to front-end logic.
• The legal disclaimer modal and cookie (spg_lib_disclaimer_agreed) remain as-is on the client.

5. PDF Generation & Cloud Storage

5.1 Signed Waiver PDF

When a parent submits a signed waiver, the server immediately generates a locked PDF that acts as the permanent legal record. The events.waiver_content column remains the live editable version — the PDF is the frozen-at-signing snapshot. The site owner changing their waiver template after the fact has no effect on previously signed documents.

5.2 What the PDF Must Contain

• Organization name and logo
• Event name and date
• The exact waiver HTML as it existed at the moment of signing — snapshot baked into the PDF, not a link to the live version
• All field responses (allergies, emergency contact, dietary restrictions, etc.)
• Parent first name, last name, and email
• Date and time signed (UTC, formatted for display)
• Participant's drawn signature image
• Participant's drawn initials image (if captured)
• Small-print legal footer: IP address, FingerprintJS visitor ID, unique document reference (participant UUID), and a statement that this document was electronically signed

5.3 Generation & Storage Flow

1. Parent submits the signing form (POST to /sign/{slug}).
2. Server validates all required fields and the FingerprintJS visitorId.
3. Server renders the PDF server-side using a library such as PuppeteerSharp (headless Chrome) or iTextSharp / QuestPDF.
4. PDF is written to cloud storage using the path convention: waivers/{org_id}/{event_id}/{participant_id}.pdf — all three IDs are UUID v4 (never sequential integers). A UUID has ~122 bits of entropy, making path enumeration attacks computationally infeasible. Never substitute a numeric or auto-increment ID in this path.
5. The storage path and a pre-signed download URL are saved to participants.signed_pdf_path and participants.signed_pdf_url.
6. An email is sent to the parent with the PDF attached (using the receipt email template).
7. The organizer's participants view shows a "Download PDF" link using the stored URL.

5.4 Cloud Storage — AWS S3

Use AWS S3 (Simple Storage Service) for signed waiver PDF storage. S3 is object storage — files are written once, retrieved by path, and served via pre-signed URL. It is the correct service for this pattern. Do not use EFS (file system), EBS (block storage attached to a single EC2 instance), or RDS (database) for PDF storage.

5.4.1 S3 Bucket Configuration

Create a dedicated private bucket for signed waivers (e.g. signpaygo-waivers-prod). Apply all of the following settings at bucket creation — some cannot be changed after PDFs have been written.

5.4.2 IAM Access

• Create a dedicated IAM role for the application with the minimum permissions needed: s3:PutObject, s3:GetObject, s3:HeadObject scoped to the waivers bucket only.
• The application should never have s3:DeleteObject permission. Deletes are prevented by Object Lock at the storage layer, but removing the IAM permission adds a second line of defense.
• Use IAM roles (not access key/secret pairs) when running on AWS infrastructure (EC2, ECS, Lambda, Elastic Beanstalk). If running outside AWS, use a tightly scoped IAM user with programmatic access and rotate credentials regularly.
• Store credentials in environment variables / AWS Secrets Manager — never in source code or config files.

5.4.3 Pre-Signed URLs

• Generate pre-signed URLs server-side using the AWS SDK with a 15-minute expiry. Serve these to the browser — never expose the raw S3 path or bucket name to the client.
• Pre-signed URLs are the primary access control layer. Even if someone knows the storage path (waivers/{uuid}/{uuid}/{uuid}.pdf), the bucket is private and the path alone grants no access.
• When a stored URL in participants.signed_pdf_url expires, regenerate the pre-signed URL from participants.signed_pdf_path on demand. Do not re-generate the PDF itself.

5.4.4 Lifecycle Rules

• Set a lifecycle rule to transition objects to S3 Glacier Flexible Retrieval after 7 years (2555 days). This reduces storage cost significantly for old records while keeping them retrievable if legally required.
• Do not set an expiration/delete rule — Object Lock in Compliance mode will prevent deletion anyway, and expiring objects after Glacier transition creates a conflict. Omit the expiration action entirely.
• Apply the rule to the full bucket prefix (waivers/) so all signed PDFs are covered automatically.

6. Authentication & Authorization

• Use ASP.NET Core Identity with a custom Users table mapped to the schema in Section 2.
• Support two auth paths: email + password and Google Sign-In (see Section 3.2).
• Role-based authorization via org_members.role: owner, admin, staff, viewer.
• All routes under /dashboard, /events, /templates, /settings require authentication.
• The public parent-facing signing page (/sign/{slug}) is unauthenticated.
• Use sliding-window session cookies with a 30-day remember-me option.
• Enforce HTTPS everywhere. HSTS with minimum 1-year max-age.

7. Deployment & Environment

• Target: Azure App Service or AWS Elastic Beanstalk (developer's choice).
• Database: PostgreSQL 16+ via Azure Database for PostgreSQL Flexible Server or AWS RDS.
• All secrets in environment variables / Azure Key Vault / AWS Secrets Manager — never in source code or committed config files.

Required Environment Variables

• Use EF Core Migrations — never manual schema edits in production.
• Set up CI/CD from day one. GitHub Actions or Azure DevOps recommended.

8. Where to Start

Recommended build order to minimize rework:

1. Browse all pages at https://secure.signpaygo.com/signpaygo-dashboard.html — click through every interaction before writing a line of code.
2. Set up the ASP.NET MVC project, PostgreSQL connection, and EF Core migrations.
3. Implement Auth: ASP.NET Core Identity + Google Sign-In.
4. Build Dashboard and Events CRUD (create, list, detail).
5. Implement the waiver editor — server-side save/load of events.waiver_content.
6. Port Past Templates from PastTemplates.js to the waiver_templates table.
7. Implement Stripe Connect onboarding flow (Settings page).
8. Build the public parent-facing sign + pay page (/sign/{slug}).
9. Implement PDF generation on waiver submission — generate, store to cloud, save path to participants.
10. Wire up email sending: invitations, reminders, receipts (attach signed PDF to receipt email).
11. Integrate FingerprintJS on the signing page.
12. QA pass — verify API & Webhooks section is CSS-hidden in Settings / Integrations.
13. Deploy to staging and run an end-to-end test of the full parent sign + pay flow.

Questions? Contact the product team before making architectural decisions that deviate from this brief.
SignPayGo — Confidential — Internal Use Only