Skip to main content

End-to-End Journeys

This chapter traces the principal journeys a person takes through Fyndow, from first sign-up to the closing of a job. Each journey is a chain of API operations across several backend modules — scheduling, quoting, invoicing, orders, payments, and notifications. The diagrams here are sequence diagrams: they show who talks to what, and in what order. For the formal status lifecycles those operations move records through, see State Machines. For the messages each step emits, see Notifications & Digests.

Two roles recur throughout:

  • Customer — the person searching, booking, buying, and paying.
  • Provider — the owner of a business who fulfils the work and receives funds.

A provider can also act as a customer; the API distinguishes the two views with a viewAs query parameter on listing endpoints rather than separate accounts.

1. Onboarding​

Onboarding turns a visitor into a participant. Fyndow keeps the first step deliberately slim — sign-up captures identity, and a provider supplies only a business name and city before they can begin. Richer profile data (services, availability, credentials, payouts) is filled in afterward, so the path to a first booking is short.

Every account starts in the customer role. Becoming a provider is a role upgrade rather than a separate registration, after which the person owns a business entity that scopes the business tools.

Connecting a Stripe Connect payout account is a prerequisite for receiving money, not for existing on the platform — a provider can list services and build a profile before payouts are wired. Availability is set against the business, and is required before customers can book concrete times (see Booking).

2. Booking → Payment → Review​

This is Fyndow's core service loop. A customer requests a time, the provider confirms it, the work happens, money changes hands, and a review closes the loop.

The booking is created in pending. Before the row is written, the scheduling service runs two guards against the chosen window: a double-booking check (no overlapping pending/confirmed/in_progress booking on the same business and date) and a time-block check (the provider has not marked the window off for lunch, vacation, etc.). Either guard failing returns a "this time is no longer available" error rather than creating a conflicting booking.

A few details worth noting:

  • Auto-created clients. The first time a customer books with a provider, the clients service records a lightweight client contact on the provider's side, so a one-off booking begins building a relationship history.
  • Confirmed bookings sync to Google Calendar. When a provider confirms, the scheduling service best-effort creates a calendar event and stores its id on the booking; cancellation deletes it; reschedule updates it. Calendar sync never blocks the status change.
  • Cancellation can trigger a refund. Cancelling a paid booking runs the provider's cancellation policy (flexible / moderate / strict) through the payments service to compute any refund. This is distinct from the platform floor for no-shows and fraud, which is handled through disputes. See State Machines for the exact booking transitions.

3. Order → Fulfillment​

The marketplace loop handles physical/stocked goods rather than time. A customer fills a cart, checks out, pays, and the provider fulfils.

Checkout has one structural subtlety: a single cart can span multiple businesses, and Fyndow splits it into one order per business at checkout. Each order is independently priced, fulfilled, and notified. Because of how the database layer handles writes, orders and their items are written sequentially rather than in a single multi-statement transaction.

Checkout validates that every product still has enough stock and decrements inventory as orders are written. A new order is pending until a successful payment moves it to confirmed when the payment-confirmation webhook arrives. From there only the seller advances the order through processing, shipped, and delivered. An unpaid (pending) order can still be cancelled by the customer — which permanently deletes it and its items — but a paid order cannot be cancelled through this flow (that would be a return, which is out of scope). The fulfillment status set is enumerated in State Machines.

4. Dispute Lifecycle​

When something goes wrong — a no-show, non-delivery, or a service not as described — the customer can open a dispute from the booking or order. Disputes are the platform's trust backstop and override the provider's own cancellation policy: the platform floor (no-show / non-delivery / fraud → full refund) is resolved here, through admin mediation rather than automatically.

:::note TODO The areas this chapter covers — bookings and scheduling, orders, invoicing, quoting, notifications, and digests — reference disputes only at their edges: the scheduling flow notes that the platform refund floor "is handled separately via the disputes + admin-refund flow", and the notification event catalog defines dispute_opened, dispute_response, and dispute_resolved (all routed to email + push). The full dispute state machine and admin mediation steps belong to the disputes area, which this Part does not cover in depth. The lifecycle below is therefore a high-level outline grounded in the notification events; see the dedicated disputes documentation for authoritative detail. :::

The three dispute events are classified as money-and-commitment notifications, so they reach the recipient by email and push in addition to the in-app feed — see Notifications & Digests.

5. Quote → Invoice → Payment​

For project-style work, a provider sends a quote, the customer accepts it, and Fyndow converts it directly into an invoice. This conversion is a small piece of controller orchestration: accepting a quote both updates the quote and calls the invoicing service to mint the invoice from the same line items, in one request.

Key behaviours along this path:

  • Viewing is tracked. When the customer opens a sent quote or invoice, the record flips to viewed automatically — the provider can see their quote was read.
  • Acceptance auto-invoices. Accepting a quote (POST /quotes/:id/accept) returns both the accepted quote and a freshly created invoice. The invoice is born already sent, with a 30-day due date and the business's default template/accent colour, and the customer is notified immediately. A provider can also force the conversion of a non-declined quote with POST /quotes/:id/convert.
  • Payment side effects. When an invoice is marked paid — by Stripe webhook, by the provider recording an off-platform payment, or by a partial payment reaching the total — Fyndow deducts inventory for material line items, exports the invoice to a connected accounting system (if enabled), and notifies the provider. Partial (deposit / installment) payments accumulate against the running amount paid and only flip the invoice to paid once the total is covered.

The invoice and quote status sets, including overdue and expired (both applied by scheduled jobs), are documented in State Machines.

6. Community Participation​

Beyond transactions, Fyndow is a community. Participation is a lighter-weight journey: discover or join a forum (open or gated), post and reply, and stay informed. Community activity feeds the personalized digest rather than firing a flood of individual emails — new subscribed-forum posts in the last week are summarised in the user's digest.

Community-related notifications — new_post, post_reply, mention, community_join_request, community_join_approved, community_join_denied — are push-and-in-app by default and deliberately not emailed, keeping the inbox for money and commitments. The forums experience itself is outside this Part's scope; the participation surface relevant here is the notification and digest behaviour described in Notifications & Digests.

7. Posting a Public Happening​

A Happening is a time-boxed post — an event, a promotion, or an ad — and the public version reaches everyone on Fyndow, geo-aware so people nearby see what's relevant. Public reach is the one place where posting and paying meet: the author pays once, per post, and Fyndow reviews the post before it goes live. What the author buys is distribution, and the price is the same regardless of who is posting or which type they chose.

The journey threads a single record through composition, payment, review, and a timed retirement. Any signed-in person can post an event as themselves; a promotion or ad must attach to a business the author owns, and that business becomes the post's byline.

The path has a few defining moments:

  • Draft before money. A public Happening is created as a draft and is visible to no one but its author. Nothing reaches the feed until the reach fee is paid, so an abandoned draft simply never publishes.
  • Payment is the gate to review, not to the feed. A confirmed payment moves the post to pending review and notifies the author that it is queued — paying does not skip the quality check. The review is a spam-and-scam gate, not an editorial one: most posts pass quickly.
  • Approval publishes and announces. When Fyndow approves, the Happening becomes live, the author is told, and — if the post is attached to a business — its followers get a heads-up that a new Happening is out. An event posted by a person has no business followers, so that fan-out is simply skipped.
  • Rejection is recoverable. A declined post is marked rejected with a reason. The author can edit and resubmit it, which returns it to pending review for another look — fixing a problem does not require paying again.
  • Auto-expiry keeps the feed honest. A live Happening drops out of the public feed the moment its run-window closes and settles into ended. Events always carry an end; promotions and ads may not, in which case they stay live until the author removes them. Either way, nothing lingers past its relevance.

The notification side of this journey — the "awaiting review", "your happening is live", and follower fan-out messages — is catalogued in Notifications & Digests. What the reach fee buys and how the payment flows are covered in Paying for Reach; the full Happenings concept, including types and display modes, is in Happenings.

8. Posting a Community Happening​

The free counterpart to the public journey is the community Happening. Posted to a community the author already belongs to, it is visible only to that community's approved members, it costs nothing, and it goes live immediately — no payment, no review queue, no waiting. This is the everyday channel: telling the people who already share your space what's coming up.

The contrast with the public journey is the whole point:

  • Membership replaces payment. The only gate is belonging — the author must be an approved member of the community to post there, and only members can see or engage with the result. There is no fee and no Fyndow review; the community self-moderates the same way it moderates the rest of its content.
  • Live on creation. A community Happening is born live, so it never passes through draft or pending review. It still ends the same way a public one does: when its run-window closes it auto-expires to ended. Run-window dates are optional for community posts, so an undated promotion or ad stays live until the author removes it.
  • Same engagement, narrower room. Members can react and comment exactly as on a public Happening; engagement simply follows visibility, so the audience is the community rather than everyone.

How communities and their membership model work is covered in Communities & Forums; the full lifecycle and engagement rules sit in Happenings.