[Docs] One deployable: describe the current architecture in README, DEPLOYMENT.md, and a new ADR - #293
Merged
Conversation
…EPLOYMENT The commerce service is gone from the tree; these are the documents that still described it. - README: delete "Why two parts" outright rather than rewriting it — there is no split left to explain, and the surrounding sections already say what the architecture is. Correct the "separate databases" architecture line: commerce truth and CMS content share the site's single D1 database, commerce in the host's per-plugin document store namespaced by plugin id and collection. - DEPLOYMENT: drop the Node + Postgres service shape entirely and renumber; there is one deployable and one database, so no shape table, no service secrets or env vars, and no asymmetric-rollback caveat (already removed with the mode plumbing — nothing left to drop). Retarget the secrets and operations sections at what actually exists: two Worker secrets, payment/email credentials in write-only plugin kv, the build-time allowedHosts perimeter, and the site-cron-drives-executor / plugin-task-every-15m cron split. - ADR-0020 (accepted): one deployable. Answers ADR-0002's five "a service may remain preferable" reasons one by one as rejected, pre-launch, with no users; records the Stripe-secret trust widening and what bounds it; fixes the settle-route requirement as public-and-must-stay-public with the unconditional Stripe HMAC as the trust anchor (correcting the planning note that called for a non-public route, which cannot receive a webhook on this stack) and names that no test pins the flag yet; states the site-owned webhook endpoint is permanent; states a future service is re-derived from the unchanged domain ports, never kept on standby. It does not deprecate ADR-0001, and says so. - ADR-0002 marked superseded in part: the split is undone, the ports-and-adapters discipline stands and is what made the deletion safe. - adr/README: the 0002 supersession, the 0018/0019 forward references resolved, the 0020 entry, and the now-reversed "separate commerce database" queued item. Docs only. pnpm lint, typecheck and format:check green; changeset status exit 0 with no new changeset (no published package changed). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CQbJYWWm8tf8owshm7XRp8
…references, and stop overselling Stripe Close the review findings on INC-D4. - README: rewrite the "three parts" intro as one deployable (the plugin owns commerce truth in-process via @otta-sh/store-emdash on ctx.storage), and fix the screenshot caption, the quick-start comment, the product-model line, the ports-and-adapters bullet, the deployment bullet, the repository-layout table (drop the two deleted packages, add the two admin ones) and the Status section. The Postgres-required concurrency line is left alone: it is a true statement about the domain contract suite, not about the deleted service. - README: the Workers deploy guide is DEPLOYMENT.md §2, not §3. - sites/staging/README: re-point every DEPLOYMENT.md citation at the new numbering and describe the real secret set; SERVICE_API_TOKEN is gone. - ADR-0018/ADR-0019: resolve the ADR-0020 forward-references in the bodies, not just in the index. - DEPLOYMENT.md: the Stripe secret key is stored but consumed by no live payment path — say so instead of promising payable checkout and refunds, and note in the egress section that payments-stripe does not yet route through ctx.http.fetch, matching ADR-0020 §2's caveat. - hold.ts: DEFAULT_HOLD_TTL_MS is both default and effective value; drop the CART_HOLD_TTL_MS citation into a deleted section. - Normalize ADR-0002's supersession wording to the repo's "partially superseded" precedent. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CQbJYWWm8tf8owshm7XRp8
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Updates README, DEPLOYMENT.md, and the ADR set to describe the actual current architecture — one deployable, the plugin owns commerce truth in-process — now that the prior increments in this work order deleted
@otta-sh/serviceand@otta-sh/store-postgres.README.md: deleted the "Why two parts" section; rewrote the "three parts" intro, architecture bullets, repository-layout table, and status paragraphs to describe the current one-deployable shape (plugin +@otta-sh/store-emdashon D1/ctx.storage, no separate service, no Postgres/Hyperdrive in the deployed path); corrected the "separate databases" line — commerce documents and CMS content share one D1 database in this build (different table prefixes:_plugin_storagevsec_*); fixed a broken DEPLOYMENT.md section cross-reference.DEPLOYMENT.md: dropped the old Node+Postgres service deployment section entirely, renumbered the remaining sections, retargeted the secrets/env sections to the real current secret set, added a section on the build-timeallowedHostsegress perimeter (with a caveat notingpayments-stripe's transport doesn't yet route through it), rewrote the cron section to match the real site-cron/plugin-task-cron split, and corrected an oversold claim about the Stripe secret key ("to take real payments and to refund") to accurately describe it as stored-but-not-yet-consumed latent infrastructure.adr/0020-one-deployable-plugin-owns-commerce-truth.md: answers ADR-0002's five "a service may remain" reasons as explicitly rejected (pre-launch, no users); states it supersedes ADR-0002 in part while the ports-and-adapters discipline ADR-0002 established still stands and is what makes the deletion safe; records the Stripe-secret trust widening honestly, including that it's latent, not yet exploited; records that the webhook settle route is intentionallypublic: true(grounded in the actual code, correcting a stale assumption in the original plan document that assumed it should be non-public) and flags that this isn't yet pinned by any test/lint/CI check as an owed follow-up; states the site-owned webhook endpoint is permanent; states a future service would be re-derived from the unchanged domain ports, never resurrected; explicitly does not deprecate ADR-0001.adr/0002-*.md: header marked "partially superseded" by ADR-0020, matching the repo's existing convention.adr/0018-*.md,adr/0019-*.md: resolved stale forward-references that previously said "ADR-0020 is still to be written."adr/README.md: index updated with ADR-0020, resolved forward-refs, struck the now-resolved "separate commerce database" queued item.sites/staging/README.md: fixed stale section-number cross-references and removed a reference to aSERVICE_API_TOKENenv var that no longer exists.sites/staging/src/lib/hold.ts: doc-comment-only fix removing a dead citation and stale "the service applies" wording.Verification
pnpm lint,pnpm typecheck,pnpm format:checkall pass;changeset statusexits 0 (docs-only, zero package bumps);sites/staging's vitest suite (40 files, 1081 tests) passes, confirming the one code-comment touch didn't affect behavior; no browser/Playwright pass needed since no rendered markup/styles/behavior changed.Notes
Two load-bearing factual corrections this increment made to the plan document's original assumptions (not bugs, but worth surfacing):
public: true, not non-public as an earlier draft of the plan assumed — grounded inpackages/plugin/src/plugin.tsand the route's own unconditional HMAC verification.Follow-up items surfaced but deliberately deferred as out of this increment's scope:
public: trueflag with a test/lint rule (recorded as owed in ADR-0020 itself).adr/0013cross-reference to a "DEPLOYMENT.md §4 'Posture'" section that no longer exists under that name.CART_HOLD_TTL_MSreferences insites/staging's product page/tests anddocs/theme/TEMPERED.mdthat repeat the same dead-citation pattern already fixed inhold.ts.Test plan
pnpm lintpnpm typecheckpnpm format:checkchangeset status(docs-only, zero package bumps)sites/stagingvitest suite (40 files, 1081 tests)🤖 Generated with Claude Code
https://claude.ai/code/session_01CQbJYWWm8tf8owshm7XRp8