Plan prevouch: specification and four-design prototype #1

New issue

Open

opened 2026-10-20 21:28:50 +00:00 by phg · 0 comments

phg commented

2026-10-20 21:28:50 +00:00

Owner

Destination

An implementation-ready specification for prevouch, validated with a navigable prototype that switches live between four designs: Gumroad-inspired, Minimal, Apple System 7, and Papercut. Completion means the product, integration, operational, allocation-policy, central-purchase, funding/refund, and UX decisions needed for implementation are settled.

Notes

Planning effort: decision tickets resolve questions. The four-design prototype is a disposable discussion artifact; building and deploying the production application is a later effort.
One hackerspace per installation, multiple events, separate queues. Design for different events; validate the first automatic email adapter against Congress/pretix messages.
People sign up and add themselves to an event queue. Self +n means n+1 ticket requests. Support First come, first served, Shuffled (grouped), and Shuffled (everyone), with multiple usable vouchers available concurrently, including an initial batch of eight. The ordering contract is recorded in Define allocation policies and organizer-triggered shuffling.
A buyer supplies a prevouch-owned return address to the ticket seller so successor vouchers return to the application. The buyer is the member in self-purchase mode and the Orga-team in central-purchase mode. Allocate usable successors under the selected policy; they are not reserved to the person whose purchase produced them. Replication/correlation evidence remains applicable.
Support self-purchase and central purchase by an Orga-team; purchase-mode scope and fulfillment live in Define central-purchase workflow and fulfillment. In self-purchase mode deliver vouchers by templated email to a selectable delivery address, defaulting to account email. In central purchase members never receive voucher codes: the Orga-team buys for them, with upfront bank-payment tracking and return of unused funds when tickets cannot be bought, specified in Define upfront-payment tracking and refunds for central purchases. Offer optional PWA push notifications, including current Apple support.
Signup modes: open, disabled, or invitation-only. Invitations work through codes and URLs and may allow one use, a finite number of uses, or unlimited uses. Configured OAuth2 login must create a missing account even when signup is disabled. Preserve this requirement when settling admission and identity rules.
Prototype member, administrator, and Orga-team journeys with simulated integrations: all allocation policies, both purchase modes, voucher arrivals, email previews, bank-payment and refund states, organizer purchases, login states, and notification states. All four designs cover the same flows and preserve state when switched live.
Requested frontend version: Tailwind CSS 4.3. Research must verify availability and document any mismatch without silently substituting a version.
No existing deployment, backend, database, mail-server, or OAuth-provider constraints. The repository currently contains agent guidance only.
Consult wayfinder and domain-modeling each session; consult grilling for conversational tickets, research for investigations, and prototype plus frontend-design for the prototype. Follow AGENTS.md and docs/agents/{domain,issue-tracker,triage-labels}. Root GLOSSARY.md holds the shared language; ADRs belong in docs/adr only when justified.
The supplied private 39C3 email is available in the originating T3 thread. It establishes presale access subject to availability, not replication timing or successor correlation. Do not publish its voucher code, personal addresses, message identifiers, or redeem URL in issues or research assets; use redacted evidence.
Design references: https://gumroad.com/ ; https://vintageapple.org/inside_r/pdf/Human_Interface_Guidelines_1992.pdf ; https://www.figma.com/community/file/1212824087404329646/system-7-apple-macos-7-like-ui-kit .
Tracker convention: children begin with Part of #<map> and are indexed below in frontier order. Use native blocking relationships. Open, unassigned children whose blockers are closed are takeable. Assign to the driving developer before working; record answers in resolution comments and only gists here.

Decisions so far

Establish current Apple PWA push capabilities and constraints: Apple mobile push requires a Home Screen web app and user consent; Declarative Web Push can work without a service worker, but push cannot prove voucher redemption.
Establish Congress voucher replication and incoming-email evidence: Congress vouchers are single-use and class-dependent; replication has an order-age gate and Friends Ticket exceptions; recipient routing needs further evidence.
Validate the four design references and Tailwind CSS 4.3: Tailwind 4.3 is available and all supplied references were inspected; four-theme switching is feasible, with visual and interaction choices left for the prototype.
Define allocation policies and organizer-triggered shuffling: Organizers start all three event-wide policies; shuffled orders stay fixed with later entries at the end, and the policy locks after the first voucher sent or central ticket bought.
Define central-purchase workflow and fulfillment: Event-wide purchase mode locks at the first binding order; exclusive organizer claims support manual checkout and seller-direct ticket access, with fulfillment requiring confirmed payment and seller sending to the holder.
Define upfront-payment tracking and refunds for central purchases: Manual bank records, dynamic per-holder ticket tiers, funding-based skips that preserve order, and separate purchase/refund holds with bank-confirmed refunds.
Define ticket-request allocation and fulfillment: Composed lifecycle across all policies and both purchase modes, with per-request eligibility/reservations, distinct fulfillment evidence, safe withdrawal/recovery, and explicit unserved finalization.

Not yet specified

Further UI and domain questions revealed by reacting to the four-design prototype.
The concrete operational acceptance evidence and implementation handoff structure that emerge from the chosen allocation policies, two purchase modes, funding/refund lifecycle, integration contract, and architecture.
Seller-integration investigations, if the eventual purchase-assistance choices require evidence not yet identifiable.

Out of scope

Production implementation, deployment, real-service provisioning, and operating real voucher distribution, ticket purchases, or bank transfers/refunds in this planning effort.
Acting as the event's ticket issuer/seller or guaranteeing admission; issuance and the ticket sale remain with the external seller. Organizers' purchasing workflow, upfront bank-payment tracking, and refund workflow are in scope.
Multiple hackerspaces sharing one installation.
Shipping adapters for additional ticket sellers as part of the first validated integration.
Bank-statement import, direct bank integration, and personal-advance/organizer-reimbursement workflows: Define upfront-payment tracking and refunds for central purchases selects manual bank records and seller purchases funded from the designated account.

Child tickets

## Destination An implementation-ready specification for prevouch, validated with a navigable prototype that switches live between four designs: Gumroad-inspired, Minimal, Apple System 7, and Papercut. Completion means the product, integration, operational, allocation-policy, central-purchase, funding/refund, and UX decisions needed for implementation are settled. ## Notes - Planning effort: decision tickets resolve questions. The four-design prototype is a disposable discussion artifact; building and deploying the production application is a later effort. - One hackerspace per installation, multiple events, separate queues. Design for different events; validate the first automatic email adapter against Congress/pretix messages. - People sign up and add themselves to an event queue. Self +n means n+1 ticket requests. Support First come, first served, Shuffled (grouped), and Shuffled (everyone), with multiple usable vouchers available concurrently, including an initial batch of eight. The ordering contract is recorded in [Define allocation policies and organizer-triggered shuffling](https://git.s1q.dev/MISChaufen/prevouch/issues/14). - A buyer supplies a prevouch-owned return address to the ticket seller so successor vouchers return to the application. The buyer is the member in self-purchase mode and the Orga-team in central-purchase mode. Allocate usable successors under the selected policy; they are not reserved to the person whose purchase produced them. Replication/correlation evidence remains applicable. - Support self-purchase and central purchase by an Orga-team; purchase-mode scope and fulfillment live in [Define central-purchase workflow and fulfillment](https://git.s1q.dev/MISChaufen/prevouch/issues/15). In self-purchase mode deliver vouchers by templated email to a selectable delivery address, defaulting to account email. In central purchase members never receive voucher codes: the Orga-team buys for them, with upfront bank-payment tracking and return of unused funds when tickets cannot be bought, specified in [Define upfront-payment tracking and refunds for central purchases](https://git.s1q.dev/MISChaufen/prevouch/issues/16). Offer optional PWA push notifications, including current Apple support. - Signup modes: open, disabled, or invitation-only. Invitations work through codes and URLs and may allow one use, a finite number of uses, or unlimited uses. Configured OAuth2 login must create a missing account even when signup is disabled. Preserve this requirement when settling admission and identity rules. - Prototype member, administrator, and Orga-team journeys with simulated integrations: all allocation policies, both purchase modes, voucher arrivals, email previews, bank-payment and refund states, organizer purchases, login states, and notification states. All four designs cover the same flows and preserve state when switched live. - Requested frontend version: Tailwind CSS 4.3. Research must verify availability and document any mismatch without silently substituting a version. - No existing deployment, backend, database, mail-server, or OAuth-provider constraints. The repository currently contains agent guidance only. - Consult wayfinder and domain-modeling each session; consult grilling for conversational tickets, research for investigations, and prototype plus frontend-design for the prototype. Follow AGENTS.md and docs/agents/{domain,issue-tracker,triage-labels}. Root GLOSSARY.md holds the shared language; ADRs belong in docs/adr only when justified. - The supplied private 39C3 email is available in the originating T3 thread. It establishes presale access subject to availability, not replication timing or successor correlation. Do not publish its voucher code, personal addresses, message identifiers, or redeem URL in issues or research assets; use redacted evidence. - Design references: https://gumroad.com/ ; https://vintageapple.org/inside_r/pdf/Human_Interface_Guidelines_1992.pdf ; https://www.figma.com/community/file/1212824087404329646/system-7-apple-macos-7-like-ui-kit . - Tracker convention: children begin with `Part of #<map>` and are indexed below in frontier order. Use native blocking relationships. Open, unassigned children whose blockers are closed are takeable. Assign to the driving developer before working; record answers in resolution comments and only gists here. ## Decisions so far - [Establish current Apple PWA push capabilities and constraints](https://git.s1q.dev/MISChaufen/prevouch/issues/3): Apple mobile push requires a Home Screen web app and user consent; Declarative Web Push can work without a service worker, but push cannot prove voucher redemption. - [Establish Congress voucher replication and incoming-email evidence](https://git.s1q.dev/MISChaufen/prevouch/issues/2): Congress vouchers are single-use and class-dependent; replication has an order-age gate and Friends Ticket exceptions; recipient routing needs further evidence. - [Validate the four design references and Tailwind CSS 4.3](https://git.s1q.dev/MISChaufen/prevouch/issues/4): Tailwind 4.3 is available and all supplied references were inspected; four-theme switching is feasible, with visual and interaction choices left for the prototype. - [Define allocation policies and organizer-triggered shuffling](https://git.s1q.dev/MISChaufen/prevouch/issues/14): Organizers start all three event-wide policies; shuffled orders stay fixed with later entries at the end, and the policy locks after the first voucher sent or central ticket bought. - [Define central-purchase workflow and fulfillment](https://git.s1q.dev/MISChaufen/prevouch/issues/15): Event-wide purchase mode locks at the first binding order; exclusive organizer claims support manual checkout and seller-direct ticket access, with fulfillment requiring confirmed payment and seller sending to the holder. - [Define upfront-payment tracking and refunds for central purchases](https://git.s1q.dev/MISChaufen/prevouch/issues/16): Manual bank records, dynamic per-holder ticket tiers, funding-based skips that preserve order, and separate purchase/refund holds with bank-confirmed refunds. - [Define ticket-request allocation and fulfillment](https://git.s1q.dev/MISChaufen/prevouch/issues/5): Composed lifecycle across all policies and both purchase modes, with per-request eligibility/reservations, distinct fulfillment evidence, safe withdrawal/recovery, and explicit unserved finalization. ## Not yet specified - Further UI and domain questions revealed by reacting to the four-design prototype. - The concrete operational acceptance evidence and implementation handoff structure that emerge from the chosen allocation policies, two purchase modes, funding/refund lifecycle, integration contract, and architecture. - Seller-integration investigations, if the eventual purchase-assistance choices require evidence not yet identifiable. ## Out of scope - Production implementation, deployment, real-service provisioning, and operating real voucher distribution, ticket purchases, or bank transfers/refunds in this planning effort. - Acting as the event's ticket issuer/seller or guaranteeing admission; issuance and the ticket sale remain with the external seller. Organizers' purchasing workflow, upfront bank-payment tracking, and refund workflow are in scope. - Multiple hackerspaces sharing one installation. - Shipping adapters for additional ticket sellers as part of the first validated integration. - Bank-statement import, direct bank integration, and personal-advance/organizer-reimbursement workflows: [Define upfront-payment tracking and refunds for central purchases](https://git.s1q.dev/MISChaufen/prevouch/issues/16) selects manual bank records and seller purchases funded from the designated account. ## Child tickets  - [x] [Establish Congress voucher replication and incoming-email evidence](https://git.s1q.dev/MISChaufen/prevouch/issues/2) - [x] [Establish current Apple PWA push capabilities and constraints](https://git.s1q.dev/MISChaufen/prevouch/issues/3) - [x] [Validate the four design references and Tailwind CSS 4.3](https://git.s1q.dev/MISChaufen/prevouch/issues/4) - [x] [Define allocation policies and organizer-triggered shuffling](https://git.s1q.dev/MISChaufen/prevouch/issues/14) - [x] [Define central-purchase workflow and fulfillment](https://git.s1q.dev/MISChaufen/prevouch/issues/15) - [x] [Define upfront-payment tracking and refunds for central purchases](https://git.s1q.dev/MISChaufen/prevouch/issues/16) - [x] [Define ticket-request allocation and fulfillment](https://git.s1q.dev/MISChaufen/prevouch/issues/5) - [ ] [Obtain redacted evidence of successor-address routing](https://git.s1q.dev/MISChaufen/prevouch/issues/13) - [ ] [Choose successor routing and incoming-voucher trust rules](https://git.s1q.dev/MISChaufen/prevouch/issues/6) - [ ] [Decide stalled-voucher and delivery-failure recovery](https://git.s1q.dev/MISChaufen/prevouch/issues/7) - [ ] [Define signup, invitations, and OAuth account identity](https://git.s1q.dev/MISChaufen/prevouch/issues/8) - [ ] [Define delivery addresses, email templates, and notification preferences](https://git.s1q.dev/MISChaufen/prevouch/issues/9) - [ ] [Define administrator authority, queue visibility, and event lifecycle](https://git.s1q.dev/MISChaufen/prevouch/issues/10) - [ ] [Choose the application architecture and deployment contract](https://git.s1q.dev/MISChaufen/prevouch/issues/11) - [ ] [Evaluate member and admin journeys in four live-switchable designs](https://git.s1q.dev/MISChaufen/prevouch/issues/12)

phg added the

wayfinder:map

label

2026-10-20 21:29:12 +00:00

phg referenced this issue

2026-10-20 21:29:12 +00:00

Establish Congress voucher replication and incoming-email evidence #2

phg referenced this issue

2026-10-20 21:29:32 +00:00

Establish current Apple PWA push capabilities and constraints #3

phg referenced this issue

2026-10-20 21:29:33 +00:00