User Journeys

This page outlines the three core user journeys in Odys: professional sign-up & onboarding, customer booking, and payment processing. Each journey spans multiple systems and validation layers, and is implemented with idempotency, rate limiting, and non-blocking side effects.

The three flows

1. Professional Sign-Up & Onboarding

Begins at odys.com.br/register and ends with a live public booking page at /p/[slug]. The flow is split into two phases:

• Account creation: email-based registration with verification link
• Onboarding wizard: collects profession, availability, session duration, and pricing

The endpoint handles slug reservation with a blocklist, uses Zod for request validation, and ensures idempotency on retries. Auth state is managed via Supabase.

2. Customer Booking Flow

Starts when a client visits a professional’s /p/[slug] page and ends with a confirmed appointment. Key characteristics:

• Client-side slot rendering for fast UX
• Server-side overlap check to prevent double-booking
• Zod validation on all submission data
• Plan-based limits enforced (e.g. max monthly bookings)
• Non-blocking notifications via WhatsApp and email

The flow assumes timezone handling is client-responsible and does not use atomic locking during slot reservation, leaving a small window for race conditions [verify].

3. Payment Flow

Two distinct payment paths:

• PIX for client-to-professional session payments: uses static EMV BR Code linked to the professional’s PIX key. Settlement is peer-to-peer, zero-fee, and confirmed manually by the professional post-deposit.
• Stripe Checkout for professional-to-Odys subscription billing: hosted session, out of PCI scope.

This split avoids BACEN payment-facilitator classification and keeps transaction costs near zero for session payments.

Why these three

These flows represent the critical path of Odys: acquiring professionals (sign-up), enabling core functionality (booking), and sustaining the business (payment). Together, they touch the majority of the codebase and involve all key actors — professional, client, and platform.

What they have in common

All three flows share these implementation patterns:

• Zod validation at the boundary — every POST request body is validated before processing
• Rate limiting by IP — enforced via Upstash Ratelimit sliding windows on mutation endpoints
• Supabase auth checks — supabase.auth.getUser() is called for authenticated actions
• Non-blocking side effects — notifications are fire-and-forget, never blocking HTTP response
• Idempotent handlers — safe to retry without duplicating state

These cross-cutting concerns are detailed in the Backend section and not duplicated per flow.