Bin Buddy

How to use Bin Buddy

Trust-first trash and recycle bin movement service. W-2 employee drivers, before-and-after photo proof of every movement, recurring billing, and a back-office that runs the operation from one screen — Scottsdale launch, designed to scale.

1. 1

   Register as System — Cascade target of AuthIdentityCreated — attach a bin-buddy role to an existing AuthIdentity. The route handler / PM that orchestrates signup dispatches AuthIdentity.SignUp first, then this once the identity exists. → Account Registered

   Account

2. 2

   Change Role as Owner — Promote or demote an Account between roles. Audit-logged via AuditLog (i94). → Account Role Changed

   Account

3. 3

   Request as Customer — Customer adds a Royalty service from the homeowner portal. Charges through Stripe ; on success the AddOn lands here and a ServiceTask is generated. → Add On Requested

   Add On

4. 4

   Complete as System — ServiceTask the AddOn produced was completed — close the AddOn so it stops generating new tasks (one_time only). → Add On Completed

   Add On

5. 5

   Cancel as Admin — Cancel a recurring AddOn (monthly bin cleaning). Customer or admin can dispatch. → Add On Canceled

   Add On

6. 6

   Set Inventory as Customer — Captured during signup — customer declares how many trash and recycle bins they have and where they're stored. Defaults to 1 of each if customer doesn't specify. → Bin Inventory Set

   Bin Inventory

7. 7

   Update Bin Count as Admin — Adjust the bin count — used when a driver reports extra unregistered bins, or the customer adds bins themselves and asks for the account update. → Bin Count Updated

   Bin Inventory

8. 8

   Add Extra Bin as Admin — Increment extra_bin_count when an extra bin lives at the property beyond the plan baseline. Triggers the Royalty add-on flow (i91) for monthly billing. → Extra Bin Added

   Bin Inventory

9. 9

   Update Storage Location as Customer — Customer updates where the bins live (e.g. moved them from the side of the garage to behind the gate). Driver app reads this on every stop. → Storage Location Updated

   Bin Inventory

10. 10

    Refresh as System — Pull the latest published schedule from the city's open-data source and replace the cached row for this street range. Triggered weekly by a scheduled cadence ; the :city_schedule adapter handles the per-city HTTP fetch and normalization. → City Calendar Refreshed

    City Calendar

11. 11

    Lookup By Address as Public — Signup-time lookup : given an address line and zip, return the trash and recycle days for the matching street range. The :city_schedule adapter intercepts and routes to the per-city backend ; on hit it cascades into ServiceAddress.UpdatePickupDays. Miss falls through to the manual day picker. → City Calendar Looked Up

    City Calendar

12. 12

    Create Customer as System — Register a customer record at the payment processor. Tonight (i83 walking skeleton) the application service composition is imperative in the worker route handler ; once i268 lands, the runtime walks the hecksagon binding → :stripe family → framework/providers/stripe.hecksagon's create_customer endpoint and the dispatch chain runs declaratively. → Processor Customer Created

    Credit Card Processing

13. 13

    Attach Payment Method as System — Link a tokenized payment method (from the frontend Stripe Elements form, never raw card data) to the processor customer. → Processor Payment Method Attached

    Credit Card Processing

14. 14

    Create Subscription as System — Start a recurring charge schedule. Returns the processor's subscription id which lands on the Subscription aggregate (when ServiceAddress + Plan flows ship to give Subscription.Subscribe its required cross-references). → Processor Subscription Created

    Credit Card Processing

15. 15

    Register Customer as Public — Create a Customer profile during the homeowner-portal signup flow. Dispatches after Account.Register lands so the account_email is known. The CustomerSignup application service supplies stripe_customer_id after the CreditCardProcessing.CreateCustomer operation lands ; Stripe sub_… ids land on Subscription records (which are identified_by sub_…) — a Customer can have many Subscriptions but one Stripe customer. → Customer Registered

    Customer

16. 16

    Update Contact as Self — Customer updates their own contact info from the homeowner portal. Admin can also do this from the admin portal on the customer's behalf. → Customer Contact Updated

    Customer

17. 17

    Add Note as Support — Append a back-office note to the customer record (e.g. 'prefers driver to use side gate', 'past dispute resolved'). → Customer Note Added

    Customer

18. 18

    Submit as Public — Applicant fills out the form on the driver portal (i47) and submits. Captures contact + DL info ; the PM picks up from here. → Driver Application Submitted

    Driver Application

19. 19

    Request Background Check as Admin — Admin (or V2 adapter) starts the background check. V1.1 ships with admin manually clicking after they've initiated the off-system check. → Background Check Requested

    Driver Application

20. 20

    Approve as Admin — Background check passed ; admin approves the applicant. The PM cascades AuthIdentity.SignUp → Account.Register with role=driver (i264 split). → Driver Approved

    Driver Application

21. 21

    Reject as Admin — Disqualifier surfaced ; reject the applicant with reason. Terminal. → Driver Rejected

    Driver Application

22. 22

    Mark Active as System — Account.Register completed (cascade from Approve via AuthIdentity ; i264) ; the application moves to active. Terminal happy state. → Driver Activated

    Driver Application

23. 23

    Send Sms as System — Send an SMS message via the configured :sms provider (Twilio today). The hecksagon binding resolves the call ; the provider's message SID lands on the SmsSent event for audit + delivery tracing. → Sms Sent

    Notifications

24. 24

    Send Email as System — Send an email via the configured :email provider (Resend today). The hecksagon binding resolves the call ; the provider's message id lands on the EmailSent event for audit + delivery tracing. Mirrors the SendSms surface : domain code carries just to + subject + body, the world's resend block + the framework provider hecksagon handle credentials and HTTP shape. → Email Sent

    Notifications

25. 25

    Send Welcome Email as System — Send the homeowner welcome email — fires from the WelcomeOnRegister policy after Account.Register. The :email adapter (Resend) composes subject + body from the welcome template and delivers ; EmailSent records the provider's response id. → Welcome Email Sent

    Notifications

26. 26

    Send Route Assignment Pending as System — Send the 'we're currently assigning your route' email — fires from the RouteAssigningOnSubscribe policy after Subscription.Subscribe. Reassures the homeowner their first pickup is being scheduled. The :email adapter composes subject + body and delivers ; RouteAssignmentPendingEmailSent records the provider's response id. → Route Assignment Pending Email Sent

    Notifications

27. 27

    Upload as Driver — Driver-app POSTs the image to the upload endpoint ; the :object_store adapter writes to S3 (or wherever the world points) and returns a URL. This command records the row. → Photo Uploaded

    Photo

28. 28

    Flag as Owner — Owner flags a photo for review (e.g. driver photographed wrong address). Flagged photos hide from customer until reviewed. → Photo Flagged

    Photo

29. 29

    Register Plan as Owner — Create a new plan in the catalog. Owner-only ; existing subscribers aren't affected. → Plan Registered

    Plan

30. 30

    Reprice as Owner — Change the monthly price. Existing subscribers keep their snapshotted price (grandfathered) ; new signups get the new price. → Plan Repriced

    Plan

31. 31

    Retire as Owner — Remove a plan from the catalog so new signups can't pick it. Existing subscribers continue ; they switch only via explicit ChangePlan. → Plan Retired

    Plan

32. 32

    Build as Dispatcher — Create a draft route for one worker on one date. → Route Built

    Route

33. 33

    Publish as Dispatcher — Publish the route to the driver app. → Route Published

    Route

34. 34

    Start as Driver — Driver clocks in (i20 WorkerShift cascade) and starts the route — actual_start stamped. → Route Started

    Route

35. 35

    Finish as Driver — All tasks resolved (completed or failed) — route closes. → Route Finished

    Route

36. 36

    Add Address as Customer — Customer adds their service address during signup. Geocodes via the maps adapter ; pickup days auto-populate from i85 city-schedule integration when available, otherwise manual. → Service Address Added

    Service Address

37. 37

    Update Pickup Days as Customer — Update the trash/recycle days — used when the city changes its schedule or the customer corrects an auto-populate mistake. → Pickup Days Updated

    Service Address

38. 38

    Update Access Notes as Customer — Customer updates gate code or access instructions (i10). Driver app reads these on every task. → Access Notes Updated

    Service Address

39. 39

    Activate as Admin — Mark the address as dispatchable — tasks will be generated. Driven by Subscription PM observing payment success, or admin override. → Service Address Activated

    Service Address

40. 40

    Deactivate as Admin — Stop generating tasks for this address. Driven by Subscription PM observing payment failure past grace period, or admin override (vacation hold, cancel, etc.). → Service Address Deactivated

    Service Address

41. 41

    Generate as System — Nightly task generation : for each active Subscription, produce per-day per-direction ServiceTasks. Driven by a cadence at midnight local. → Service Task Generated

    Service Task

42. 42

    Assign To Route as Dispatcher — Place a generated task on a route. Admin builds routes by zone ; this is the per-task placement. → Task Assigned To Route

    Service Task

43. 43

    Start as Driver — Driver opens the stop card in the route view ; status moves to in_progress. → Worker Started

    Service Task

44. 44

    Mark Complete as Driver — Driver completes the task with before+after photos (i18). → Service Task Completed

    Service Task

45. 45

    Report Exception as Driver — Driver picks one of nine enumerated reasons (i19) instead of completing. Optional note + optional photo. → Service Task Failed

    Service Task

46. 46

    Reassign as Dispatcher — Move the task to a different worker / route — used when one driver is overloaded or a stop is in the wrong zone. → Task Reassigned

    Service Task

47. 47

    Subscribe as Customer — Customer signs up — Stripe charge succeeds, this command records the new subscription. operational_status starts active. → Subscribed

    Subscription

48. 48

    Record Payment Failed as System — Stripe webhook (invoice.payment_failed) lands here. Starts the grace-period clock ; the Subscription PM observes and transitions to inactive after 3 retries / 7 days per the bin-buddy.world default. → Payment Failed

    Subscription

49. 49

    Record Payment Succeeded as System — Stripe webhook (invoice.payment_succeeded). Re-activates an inactive subscription if grace period was in flight. → Payment Succeeded

    Subscription

50. 50

    Activate as Admin — Mark the subscription as dispatchable. Driven by Subscription PM observing PaymentSucceeded, or admin override. → Subscription Activated

    Subscription

51. 51

    Deactivate as Admin — Stop generating tasks. Driven by Subscription PM after grace period expires, or admin override (vacation hold, cancel). → Subscription Deactivated

    Subscription

52. 52

    Cancel as Customer — Customer cancels via the homeowner portal. Stripe subscription cancels via the cascade ; tasks stop generating from cancel_date forward. → Subscription Canceled

    Subscription

53. 53

    Mark Grace Elapsed as System — Daily cadence walks `in_grace_period` ; for any subscription whose grace_period_ends_at is past, dispatches this to emit GraceElapsed. The Subscription PM observes and transitions past_due → inactive. → Grace Elapsed

    Subscription

54. 54

    Change Plan as Customer — Switch to a different Plan. Stripe subscription updates via the cascade ; the new monthly_price snapshots in. → Plan Changed

    Subscription

55. 55

    Fetch Sms Status as System — Query the configured :sms provider for the current delivery status of a previously-sent message (by its provider SID). Used for verifying message delivery during smoke tests + operational diagnostics. The hecksagon binding routes the dispatch to the same family that send_message uses, just for the GET-status endpoint. → Sms Status Fetched

    System Test

56. 56

    Fetch Email Status as System — Query the configured :email provider for the current delivery status of a previously-sent message (by its provider message id). Used for verifying email delivery during smoke tests + operational diagnostics. The hecksagon binding routes the dispatch to the same family that send_message uses, just for the status-probe endpoint. Resend exposes per-message state via its GET /emails/{id} endpoint ; this command's response normalises across providers (SendGrid, Mailgun, Postmark would carry their own status strings). → Email Status Fetched

    System Test

57. 57

    Clock In as Driver — Driver taps Clock In at the start of shift. Timestamp + GPS captured. Triggers Route.Start cascade if the driver has a route assigned for the date. → Shift Clocked In

    Worker Shift

58. 58

    Clock Out as Driver — Driver taps Clock Out at end of shift. total_minutes computed in the policy ; payroll reads this field. → Shift Clocked Out

    Worker Shift

59. 59

    Admin Edit as Admin — Back-office corrects a forgot-to-clock-out case or other anomaly. The change lands in the AuditLog (i94) with the actor and the before/after. → Shift Admin Edited

    Worker Shift