# PaynuityCard.app — Technical Blueprint

Prepared October 13, 2026 (America/Chicago). Phase 1 private demonstration.

## Executive decision

Begin with a private, browser-local Card Design Studio to demonstrate the commercial experience without depending on issuance approval. The production target remains a separate Next.js/TypeScript application with its own Clerk application, Neon project, private document storage and Vercel deployment. Phase 1 is not a bank-grade production system and has no issuer connection.

## Infrastructure review — evidence and limits

Read-only review of DESKTOP-VG9JQVC at C:\Users\mathe\Documents\PaynuityAgent-V2\paynuity-agent-v2 confirmed:

- package.json declares Next.js ^16.0.0, React ^19.2.0, TypeScript ^5.9.0, @clerk/nextjs ^7.0.0, @neondatabase/serverless ^1.0.2, Persona, Resend and QR components. Dependency declarations do not establish installed versions or working integrations.
- .vercel/project.json identifies paynuity-agent-v2, project prj_2iYAYunIOWZ9CZDMikOFZIHn6MXg and team team_ZkjG9asqXgSdNkJDjBaBzl7X.
- proxy.ts uses Clerk middleware for selected routes. It is not a complete authorization review.
- lib/db.ts contains agent, application, principal, identity, event, tax and agreement schema logic, with schema changes initialized at runtime.
- Application, admin, identity, webhook, agreement, tax and health route files exist. Existence is not evidence of a successfully tested service.
- Official Paynuity logo retrieved from public/paynuity-logo.png.
- The specified directory is not a Git checkout. Connected GitHub exposes PaynuityApp/paynuity-agent-academy, whose package.json uses Vinext/Cloudflare; it is not the specified Windows stack.
- Connected Vercel exposes raise-x but returns no projects and 404 for the checkout's project ID. Access/state must be reconciled before claiming that project is operational through this connection.
- No Agent source, credentials, database or deployment was modified. No secrets were read or copied.

## Phase 1 — implemented scope

- Three concept collections; custom colors; matte, metallic and holographic treatments.
- Raster logo/background uploads (PNG/JPG/WebP, 2 MB limit), decoding and downsampling; drag positioning and accessible range controls for logos.
- Front/back concept previews; physical/virtual concept selector; simulated masked card information without network marks.
- Saved versions, side-by-side library, edit-copy and delete controls; browser-local persistence and PNG presentation export.
- Five-step fictional application with autosave and basic completion validation.
- Demo artwork/application submissions, executive queue filter, demo review actions, local activity history and JSON export.
- Readiness checklist, permanently unavailable live activation, guided executive walkthrough.
- Separate private hosted Site and dedicated source repository, not a GitHub/Vercel production deployment.

Browser drafts are local to that browser and device. This is not secure identity storage, a multi-user service, enforceable RBAC, a production audit log or an issuer-approved artwork tool. Secure document upload and real identity collection are disabled. Accounts are provided only by the hosting platform's owner-private access, not a new Clerk registration/login workflow.

## Production architecture

| Layer | Proposed implementation | Isolation / controls |
| --- | --- | --- |
| Product UI | Next.js + TypeScript; studio renderer and accessible controls | Dedicated PaynuityCard repository and deployment |
| Authentication | Separate Clerk application, organization membership and MFA policy | Separate keys, sessions and webhooks |
| Authorization | Server-side tenant membership and role checks for every operation | Applicant, tenant admin, designer, compliance reviewer, bank reviewer, executive |
| Data | Dedicated Neon PostgreSQL project; versioned migrations | tenant_id on all business records; database policies plus API authorization |
| Artwork | Private object storage; image validation, scanning and export jobs | Scoped signed URLs, ownership checks, file limits, version hashes |
| Documents | Approved private storage / identity-provider hosted collection | Minimize raw identity data; retention, deletion, encryption and access logging |
| Workflow | Server-authoritative state machine | Recorded decisions tied to program and immutable artwork versions |
| Integrations | Provider adapters, sandbox separation, signed webhooks | Replay protection, idempotency, retry handling and reconciliation |
| Operations | Error monitoring, structured audit events, backups, incident response | Redacted logs, least privilege, tested restore and release controls |

Reuse ideas before code: application shell, progress indicators, role vocabulary, disclosure versioning, review queues and provider adapter patterns. Extract reviewed components to versioned packages only after their boundaries and tests are understood. Do not carry Agent runtime schema mutation into the Card application: use reviewed migrations.

## Data model

Core entities: tenants, memberships, businesses, authorized_representatives, beneficial_owners, applications, application_versions, program_requests, designs, design_versions, documents, verification_checks, review_decisions, approval_evidence, programs, webhook_events and audit_events.

Use UUIDs, tenant-scoped indexes and foreign keys, explicit status enums, created/updated timestamps and actor attribution. An approval must bind to the exact program configuration and artwork version. Editing either invalidates relevant approvals. Rejected and withdrawn states must be explicit. Separate demo records from real operational records. No PAN, CVV, PIN or production card secrets in the application database or logs.

## Activation policy

Draft → Submitted → Verification pending → Compliance review → Artwork review → Bank review → Integration readiness → Ready for release → Active.

The server must deny activation unless: bank identity and governing agreements are verified; requested type/network/market are authorized; business and ownership reviews are cleared; compliance and artwork decisions are current; issuer approval exists; processor capability and release readiness are verified; and a permitted human release officer authorizes activation. All gates fail closed. Frontend controls are explanatory, never the enforcement boundary. Re-review is required after material changes. Separate the bank's approval from Paynuity's internal review.

## Bank and BIN evidence

The supplied spelling “Zinnus Bank” is unverified. Zenus Bank is a possible name match from public research, not a confirmed Paynuity sponsor. Its public website cannot verify a private Paynuity relationship, BIN approval, permitted network or program rights.

Required evidence: exact legal bank name and jurisdiction, executed agreement and approval correspondence, BIN sponsorship/ownership structure, approved territories/programs, network permissions, processor contract and API documentation, manufacturer specifications, cardholder agreements, program economics and operating responsibilities. Confirm platform-management versus issuance-distribution scope from contracts. Do not add network logos or bank partnership claims until authorized.

Public lead: https://zenus.com/ (name match only).

## Next implementation sequence

1. Reconcile Vercel access and establish a new private PaynuityApp/paynuity-card GitHub repository. Available GitHub tools in this session do not expose repository creation; gh is unavailable on the development computer.
2. Create/link an isolated paynuity-card Vercel project, then provision a new Neon project and separate Clerk application. Never import Agent secrets. Configure preview and production independently.
3. Migrate the validated design experience into TypeScript components and authenticated server APIs. Add durable draft/version storage and tenant-scoped design ownership.
4. Implement non-sensitive business onboarding, server validation, concurrency controls and applicant progress. Enable sensitive collection only after its secure handling workflow is approved and tested.
5. Add enforceable reviewer roles, decision history, secure documents and evidence-bound approval gates.
6. Integrate provider sandboxes based on actual contracts and API docs; test retries, duplicate callbacks and failure/reconciliation flows.
7. Complete bank/processor/network release review before production activation. Counsel and qualified security professionals determine applicable PCI DSS, GLBA, privacy, AML and consumer-protection obligations.

## Acceptance tests for production

- Registration, MFA, invitations, expiry, logout and recovery on Safari/iPhone and Windows Edge/Chrome.
- Cross-tenant reads/writes, document URL access, ID substitution and role escalation are denied.
- Draft survives refresh and another authenticated device; concurrent edits do not silently overwrite.
- Valid/invalid uploads, dimensions, scan failures, quotas, retention and download authorization.
- Saved designs match front/back exports and retain version identity on review.
- Incomplete applications cannot submit; changed approvals cannot activate a program.
- Missing/rejected/expired bank or processor evidence blocks activation through direct API calls.
- Duplicate/forged/out-of-order webhooks cannot duplicate issuance or alter approved state.
- Restore drill, redacted logs, alerting and incident-response exercise.

## Verification of Phase 1

JavaScript syntax and static asset/link consistency are checked. Domain flow checks run against a minimal DOM harness; these do not establish browser rendering or accessibility. Browser automation capability is unavailable in this managed environment, so visual QA, real browser uploads/drag/export, mobile responsiveness and device-specific behavior remain unverified. Responsive CSS is implemented, not a claim of completed device testing.

## Completion status

Built: private concept experience and technical blueprint.
Provisioned: separate Sites project and Git source repository.
Not provisioned: new GitHub repository, Vercel Card project, Clerk application, Neon database or secure object storage.
Not integrated: bank, processor, network, KYB/KYC, sanctions, billing or live issuance.
Not approved: bank relationship, BIN rights, production artwork, compliance certification or release.

## Phase 1 continuation — October 14, 2026 UTC

Recovered the existing private Site source rather than creating a duplicate. Added a platform homepage, a required-field completion indicator, strict final application validation (including integer issuance volumes), duplicate application submission protection, and an immutable artwork snapshot attached to each demo review entry. No customer authentication, backend data handling or live issuing capability was enabled. Existing Windows review observations above come from the recovered blueprint; this continuation independently read the Agent Academy package.json and confirmed that it uses Vinext/Cloudflare.

The Vercel connector recognized the raise-x team but rejected creation of a separate paynuity-card project with HTTP 403 (insufficient permission). No Vercel project was created. GitHub exposes two Paynuity repositories but no repository-creation tool. The authorized desktop was listed online, but its read-only command did not return promptly. Local Vercel/GitHub CLI availability was checked; no credentials were copied from Agent.

The next essential setup is access capable of creating a private PaynuityCard GitHub repository and a new project under raise-x, followed by separate Clerk and Neon provisioning. Do not reuse any Agent database or authentication secrets. Sponsor correspondence remains necessary to confirm whether the supplied bank name refers to Zenus Bank and to establish actual program rights. This does not block the private concept experience.

## Rewards continuation — October 14, 2026 UTC

Reviewed the Alpine deck and 2026 overview. Added rewards.html and rewards-demo.js: sourced airline examples, fictional points rules and an editable contribution model that includes reward funding. commercial-review.md records slide/page findings, unsupported projection inputs, partner verification requirements and the proposed presentation sequence. Source-only backend/rewards.cjs implements in-memory server-domain rewards logic with tenant and role checks, integer balances, holds, idempotency and sandbox-only redemption. Six node:test cases pass. No backend endpoint, durable ledger, authentication or real partner integration has been deployed. Static Site remains private and browser-local. Existing production infrastructure blockers still apply.

## Application backend continuation — October 14, 2026 UTC

Source-only backend/drafts.cjs and backend/api.cjs implement non-sensitive application/design draft operations, a Fetch request handler requiring a verified session adapter, per-tenant and per-owner access, optimistic revisions, immutable submission snapshots, duplicate submissions, a reviewer queue, local transactional audit writes and explicit rejection of live activation. Local SQLite schema is backend/migrations/001-demo.sql; it is not a Neon migration. Seven request-to-SQLite tests pass, including restart persistence and stale-review rejection. No API is hosted, no UI is connected to this handler, and no real session verification exists yet. Phase-one completion criteria and remaining environment setup are documented in phase-one-status.md. Separate PostgreSQL, Clerk and private artwork storage are still needed. The rewards module remains an independent in-memory foundation.

## Visual landing update — October 14, 2026 UTC

Added three generated, user-approved campaign assets: Paynuity One Card hero, Proxy minimalist-wallet concept and coastal rewards-experience photograph. Homepage now uses a full-width narrative layout, concept gallery, experience section and design/application CTAs. Concept buttons seed a Paynuity design in the existing studio. Responsive styles preserve full hero imagery below copy on small screens. No live proxy/account aggregation, rewards transfer or issuance functionality is claimed. The unverified Visa majority-preference assertion is omitted; Visa's 2022 loyalty paper supports personalized lifestyle relevance but does not establish that claim. Static links/assets, JavaScript syntax and existing workflow checks pass. Real browser/mobile visual inspection remains unverified because supported browser automation is unavailable.