RFC: Clockwork is the quote-to-order journey we cannot show clients today - #25
RFC: Clockwork is the quote-to-order journey we cannot show clients today#25jameskurz-filecoin wants to merge 6 commits into
Conversation
| ## TL;DR | ||
|
|
||
| I propose that Fil One adopt | ||
| [Clockwork](https://github.com/fil-one/clockwork) as a standalone service for |
There was a problem hiding this comment.
What is Clockwork? Is this an off the shelf tool or something you built? Is there some documentation I can read about who it's for, what it is, how it works, infra requirements and what running it looks like day-to-day?
EDIT: I see there is a docs directory in the repo but a lot of them seem impenetrable to human understanding e.g. release-candidate-report.md. Where should I start with docs?
A few questions off the top of my head:
- Who is this for? Is it for selling to regional providers or fil.one customers?
- Who uses this? Is this for us to use or customers...or both?
- What does "One artifact chain, no re-keying" mean? (from README)
- Who has been involved in the creation of clockwork? Do we have buy in that our iternal teams would use this yet?
There was a problem hiding this comment.
Rewrote the opening. Clockwork is a web app I built (Next.js + Postgres + Stripe). Not off the shelf, not something we sell. README + the live demo are the right start; skip the docs/ folder. Password is going in the FF 1Password vault. I will also schedule a 45-minute demo.
| - Which system should write to Stripe, provisioning, or CRM? | ||
| - How do we reconcile and recover after a partial failure? | ||
|
|
||
| Clockwork was built to make those relationships explicit. It provides one |
There was a problem hiding this comment.
By the looks of it, clockwork is a custom AI built CRM tool. My immediate concern is that this seems to be a big chunk of code the engineering team will become responsible for and we currently have no idea what it does or how it works. I think a prerequisite to approving the PR would be to demo/intro the team to clockwork, accompanied with a technical deep dive?
I'm curious to know why we built it from scratch? Is there no existing tool we can use for this? Building our own gives us a lot of freedom for it to work exactly the way we want it to, but we become responsible for fixing bugs, security, maintenance and features which may detract from the team's main focus.
There was a problem hiding this comment.
That is a fair read of the risk. I built it, with a lot of AI, and nobody on the team has reviewed it. The rewritten RFC makes a demo + tech walkthrough a prerequisite, and treats 'buy Chargebee / Stripe Billing + HubSpot instead' as a valid outcome. I am not asking anyone to own this codebase on the basis of this document alone.
| records, with idempotent workflows, audit history, generated documents, and | ||
| provider boundaries. | ||
|
|
||
| The implementation now exists and can be evaluated as a product. The remaining |
There was a problem hiding this comment.
can be evaluated as a product
We are not selling it though...right? This is just a tool for us?
There was a problem hiding this comment.
Correct. Internal tool for FF (and later a portal customers/partners log into). Not a product we sell.
| | Authentication | Fil One Auth0 remains the identity authority for existing users. Clockwork receives a verified subject mapping; email matching is not authorization. | | ||
| | Organizations and tenants | Fil One organization and tenant IDs remain the product identity. Clockwork owns the related commercial account and roles. | | ||
| | Products, resources, and raw usage | Fil One owns provisionable capability, storage resources, entitlements, and raw measurements. | | ||
| | Pricing, agreements, quotes, and orders | Clockwork owns approved commercial configuration and workflow. Accepted lines map to versioned Fil One product capabilities. | |
There was a problem hiding this comment.
Clockwork owns approved commercial configuration and workflow.
What does this mean?
Accepted lines map to versioned Fil One product capabilities.
Accepted lines?
There was a problem hiding this comment.
'Approved commercial configuration' meant: the quote, the price, the order. 'Accepted lines' meant line items on an accepted quote — e.g. 100 TB in eu-central-3 — which have to match a real Fil One SKU or the order stops. Both are now in plain language in the RFC.
| | Organizations and tenants | Fil One organization and tenant IDs remain the product identity. Clockwork owns the related commercial account and roles. | | ||
| | Products, resources, and raw usage | Fil One owns provisionable capability, storage resources, entitlements, and raw measurements. | | ||
| | Pricing, agreements, quotes, and orders | Clockwork owns approved commercial configuration and workflow. Accepted lines map to versioned Fil One product capabilities. | | ||
| | Stripe and billing | The current integration remains authoritative at first. Exactly one service writes each customer, subscription, meter, invoice, or payment domain after an explicit cutover. | |
There was a problem hiding this comment.
I'm not sure I have a clear enough picture of how things work with billing (Stripe) and auth (Auth0) with the two services. It seems that Fil One initially continues be the integration point but I don't understand how users interact with Clockwork? Are we just sending requests back to Fil One to get things done? Does Fil One become a proxy for these Stripe and Auth0?
There was a problem hiding this comment.
Today Fil One is the Stripe writer for PAYG, and it stays that way. Clockwork would not write Stripe, Auth0, or Forge until a later explicit decision. Users would use Clockwork's own UI for quotes/orders; Clockwork would later call Fil One to provision. There is no proxy and no machine API yet — that API is the work, not something already shipped.
| | Migration | Fil One remains source authority until a per-account cutover. Clockwork owns migration-run, mapping, and projection evidence. | | ||
|
|
||
| The field-level design is already documented in Clockwork's | ||
| [adjacent-service integration boundary](https://github.com/fil-one/clockwork/blob/55b4082d380e086b29da7e76f4e060d19cbb49a6/docs/adjacent-service-integration.md). |
There was a problem hiding this comment.
This mentions WorkOS a lot - how does WorkOS fit in with everything?
I'd like to see specifics of the proposed API.
This sounds like a lot of integration work 😬
There was a problem hiding this comment.
WorkOS is only how Clockwork's demo logs people in. Fil One stays on Auth0. If we keep Clockwork we either federate Auth0 into it or rip WorkOS out; I have not done that. There is no Fil One↔Clockwork API to show yet. I agree the integration is large, which is why the ask is a demo and a yes/no/buy-instead, not a cutover.
| Map Auth0 issuer and subject to the Clockwork user, and map each Fil One | ||
| organization to a Clockwork account. Missing or ambiguous mappings fail closed. | ||
| We should decide whether this is federation or an explicit account-link step | ||
| after reviewing the current Auth0 setup. |
There was a problem hiding this comment.
So this is a one time migration as well as ongoing new user registration.
There was a problem hiding this comment.
Yes. Existing accounts would need an explicit link (not email matching). New signups would need an ongoing path. Neither is designed. Called out in the rewrite.
| [`55b4082`](https://github.com/fil-one/clockwork/tree/55b4082d380e086b29da7e76f4e060d19cbb49a6). | ||
|
|
||
| - The [live guided demo](https://clockwork-commerce-demo.netlify.app/) exercises | ||
| customer, partner, and internal-operator workflows with resettable demo data. |
There was a problem hiding this comment.
Can you please share the password with the team via the FF 1password vault?
There was a problem hiding this comment.
Will do. Putting the demo password in the FF 1Password vault today.
|
|
||
| ## Decisions needed | ||
|
|
||
| 1. Do we want Clockwork to become Fil One's commerce service? |
There was a problem hiding this comment.
Is this a question for engineering?
All things considered I'd prefer us to adopt an off-the-shelf solution. So the question for me is more: are the engineering team comfortable taking on responsibility for Clockwork given the benefits it brings to other internal teams and our customers?
There was a problem hiding this comment.
Yes — it is a question for engineering, and your preference for a vendor is now a first-class option in the RFC. The question is exactly: after a demo, are we more comfortable owning this repo or buying something?
| ## Decisions needed | ||
|
|
||
| 1. Do we want Clockwork to become Fil One's commerce service? | ||
| 2. Which team should own it after adoption? |
There was a problem hiding this comment.
I assume this means who is responsible for uptime, maintenance, bug fixes, feature additions, security fixes....not who in FF is going to use it to engage with customers?
There was a problem hiding this comment.
Yes. Uptime, bugs, security, features. Not who talks to customers.
Alan asked what Clockwork is, who it is for, whether we sell it, why we did not buy a vendor, and what engineering would be on the hook for. This version answers those in order and shrinks the ask to a demo plus a yes/no/buy-instead decision.
jameskurz-filecoin
changed the title
|
@alanshaw thanks — you were asking the right questions and the old RFC did not answer them. Rewrote it. Clockwork is an internal quote-to-cash app I built. We would not sell it. Engineering owning it means uptime / bugs / security, which is a real cost, and buying a vendor is a valid outcome. I will:
Please do not treat this as an incoming dependency of POSIX or the console until after that. |
|
Follow-up: opened https://github.com/fil-one/clockwork/pull/35 so the README is a front door instead of a brochure. Not merging it myself — that is the old habit I am trying to break. |
The demo is a password plus a persona cookie, not WorkOS. WorkOS is how the real app would log people in. Fil One stays on Auth0. A vendor is an equal outcome, not a consolation prize.
Demo is Netlify plus a password. Production would be Vercel, WorkOS, and Postgres. Fil One stays on Auth0. A vendor is allowed to win.
jameskurz-filecoin
changed the title
|
@alanshaw second pass, after reading the Clockwork repo. Correction to my earlier replies: the demo does not use WorkOS. It is a shared password, then a persona picker. WorkOS is how the real app would log people in. Fil One stays on Auth0. There is no Fil One API. Start here: https://clockwork-commerce-demo.netlify.app/ — I still owe you the password in the FF 1Password vault before we sit down. |
…ries Not pushed. Demo first, then pilot / buy / kill. PAYG stays on Fil One.
jameskurz-filecoin
changed the title
|
@alanshaw rewritten around the customer path, not the service boundaries. Start here: https://clockwork-commerce-demo.netlify.app/ — shared password (Netlify env; I will put it in the FF 1Password vault before we sit down). Demo login is a password plus a persona picker, not WorkOS. This RFC is: we cannot show quote → accept → order to enterprise/partner conversations today. Clockwork is a prototype of that journey. After a 45-minute demo, decide pilot / buy (Chargebee or Stripe Billing + HubSpot) / kill. Off-the-shelf is allowed to win. PAYG in Fil One stays as it is. |
|
@jameskurz-filecoin just to file that I think ultimately @christopherrocco is the real decider here in terms of where this sits on product priorities -- we can review, but ultimately prioritizing integration is a product decision. |
Makes absolute sense to me; should have flagged him first from the outset. Let's make sure to discuss this as a sprint candidate Monday @christopherrocco |
3 participants
📖 Preview
Enterprise and partner conversations still cannot walk quote → accept → order in one place. Clockwork is a working prototype of that journey (not a product we sell).
Ask: 45-minute demo, then pilot this, trial a vendor, or kill it.
Demo: https://clockwork-commerce-demo.netlify.app/