FlexSlot

Fill fully booked slots through agreed booking moves, with PayPal payments and fixed partial refunds.

Comment

Inspiration

A salon is fully booked at the only time a new customer can visit. An existing customer might be willing to move, but the shop needs a workable alternative, everyone's agreement, and a reliable way to handle the payment and compensation.

FlexSlot focuses on that one opportunity. The new customer pays the salon. The salon compensates the existing customer by partially refunding their original payment. The project connects scheduling, consent and payment recovery in one small workflow.

What it does

The demo uses one fictional salon, one stylist, two services and one swap between an existing customer, A, and a new customer, B.

  1. A has paid for a booking and registers acceptable alternative times in advance. Compensation is fixed at USD 10.00 in the demo.
  2. B describes when they need an appointment. Gemini on Vertex AI turns free text into proposed conditions and asks for clarification when needed. Each customer checks and confirms their conditions.
  3. Server code checks service duration, opening hours, available slots and the confirmed constraints. The shop sees either a feasible proposal or the reasons it cannot work.
  4. The shop, A and B approve the specific terms. B then approves payment through PayPal Sandbox.
  5. FlexSlot authorizes B's payment, rechecks the conditions, captures the payment and confirms both booking changes in one database transaction. It then requests the agreed partial refund against A's original captured payment.

The owner and the two customers have separate screens, in English or Japanese. Booking status, B's payment and A's compensation have separate progress indicators. Mock and connected modes are labelled throughout. All PayPal payments in this project use Sandbox test money.

Why compensation instead of a general discount?

A weekday discount can attract someone who has not booked yet. FlexSlot addresses a specific conflict after a slot is already booked: A can move, B cannot, and an eligible alternative slot is available. If a normal discount would produce the same outcome, FlexSlot does not assume it is better.

The owner sees an estimate, not a promise of profit. The sample is USD 60.00 additional revenue − 10.00 compensation − 15.00 additional service cost − 2.50 payment-related costs − 12.00 opportunity cost = USD 20.50 estimated additional profit. These are fictional assumptions; USD 2.50 is not a quoted PayPal fee. The opportunity cost represents the expected value of selling A's alternative slot to someone else. No measured salon results are claimed.

Compensation does not increase while a customer waits, and each booking can receive it once. These limits reduce some incentives to hold busy slots for compensation; they do not eliminate strategic behaviour or prove demand.

Design decisions

  • Money always flows between a customer and the shop. B pays the shop the normal price; the shop refunds a fixed part of A's own original payment. Customers never pay each other, which avoids person-to-person money transfer and keeps one merchant responsible for every payment and refund.
  • A opts in before anyone asks. A registers when they could move, and the fixed compensation is set at that moment. Only people who agreed in advance are ever asked, the program can check a swap at once, and nobody negotiates the amount.
  • One existing customer is asked at a time. This demo handles one matching A and one B. Multiple-customer chains and competing offers are outside its scope.
  • B pays last. The shop approves, then A agrees, then B approves the payment. FlexSlot authorizes first, checks the terms again, and only then captures; if the check fails, it releases the authorization instead of charging.

How it is built

PayPal is part of the core workflow. Orders v2 and Payments v2 support approval, authorization, capture, partial refund, authorization void and a recovery refund to B if the booking cannot be committed after capture. A database transaction cannot atomically include PayPal, so each payment operation is recorded before dispatch, with its fixed input and request identifier. Recovery uses stored results, queries and, where appropriate, a retry of the same operation with the same request ID. Related order and capture queries help verify the recipient, amount and resource relationships before dependent steps continue. Verified webhooks prompt queries; their payloads do not directly settle a booking or payment.

AI interprets free text. The connected configuration uses gemini-3.5-flash-lite on Vertex AI with server-side Application Default Credentials. Structured output contains scheduling conditions and clarification questions, not payment amounts or approval commands. The person confirms the interpretation; program checks enforce payment terms, authority and availability. The model can still misunderstand a date or service, so a schema does not replace review of its answer. If AI is unavailable, the app explicitly offers manual entry instead of silently switching to mock AI.

The app uses TypeScript, Node.js 24, SQLite, React, Vite and zod. Data persists on the server. Separate role sessions, server-side party checks, CSRF protection and version-bound approvals restrict who can act on a proposal. This is a local demonstration, with no connection to a real salon's booking system.

Challenges and what we verified

The hardest part was recovering from an uncertain payment result without treating a missing response as a failed payment. We separated obligations, attempts and API operations, and tested the boundaries around payment capture, the booking commit and compensation.

  • The final 2:17 English video records a new complete booking move using PayPal Sandbox and Vertex AI, with the same application code as the published source. Subsequent submission-document updates do not change that application code. A and B each approved a USD 60 Sandbox payment; A received a USD 10 partial refund against A's original capture. Both real Vertex requests succeeded. A read-only reconciliation of the database and fresh Sandbox queries passed all 21 checks.
  • Five Sandbox scenarios, R1–R5, exercised interruption and recovery. Response loss and refund rejection were injected, and booking conflicts were introduced deliberately; these were not PayPal outages. Process stops were actual exits. The observed final bookings and expected payment resources matched, without duplicate captures or refunds in those runs.
  • The earlier R5 scenario paused at four intermediate states. The three screens did not show the swap or compensation as completed at those pauses. A separate viewing server kept the payment workflow paused. Its stored final reconciliation report passed 14 checks. This earlier scenario used mock AI and is shown in the video as a labelled evidence summary, separate from the new real Vertex demonstration.
  • Real Sandbox webhook deliveries were signature-verified and deduplicated, and a tampered copy was rejected.
  • The most recent recorded automated check passed 402 tests, including the public-mode boundary checks, using mock or fake external services and local HTTP relay tests. That check predates this submission packaging; it was not rerun for the video. It is separate from the real Sandbox and Vertex checks.
  • Phone-width and desktop-width browser emulation, and startup from a clean clone in another folder on the same PC, were checked. These are not physical-phone or different-PC tests.

What we learned

Payment recovery depends on knowing which operation was intended, which result is confirmed and which result is still unknown. That distinction matters as much in customer-facing wording as it does in the database.

AI is useful for translating a customer's everyday language into conditions they can review. Approval, availability and money still need explicit rules and durable records.

Claude Code supported implementation and testing; Codex provided independent reviews and helped prepare submission materials. The creator defined the scope, performed account setup and approved Sandbox payments. These tools are development assistance, separate from the Vertex AI integration inside the app.

What is next

The next steps are first-time usability testing, physical-phone testing and short salon interviews. Demand and real business outcomes have not been validated. A future version could add this consent-and-payment workflow to an existing booking system; that integration is outside this demo. The submitted scope keeps compensation fixed and handles one swap between one existing customer and one new customer.

Built with

TypeScript, Node.js, SQLite, React, Vite, zod, PayPal Orders v2, PayPal Payments v2, PayPal Webhooks, Google Cloud Vertex AI, Gemini.

How judges can try it

Public demo video: Watch FlexSlot on YouTube.

Public source and README: Shartier/flexslot.

No hosted service is provided. The public source repository includes the complete English README and an account-free local demo. Install Node.js 24.22.1 or a later 24.x release, download or clone the repository, open its folder in a terminal, run npm ci and npm run dev, then open http://localhost:8787. With no .env, choose the mock AI and mock payment modes and follow the README through all three screens. These modes do not call PayPal or Google. The completed English video demonstrates real PayPal Sandbox and Vertex AI operation with test money. Login and waiting time are omitted, and retained screen footage and narration play at normal speed; the README also explains how to configure those integrations with your own credentials.

Demo and asset disclosures

The video is 2 minutes 17 seconds, with English screens, English narration and burned-in English subtitles. Historical recovery evidence is labelled separately from the recorded transaction. All salon names, customers, costs and business results are fictional. Salon images are AI-generated. English narration was generated with HeyGen Voice (Annie - Lifelike; returned engine: Orca). Third-party notices and image provenance are included in the source repository.

Share this project:

Updates

Submission history