ARCH-001 — Establish secure-commerce architecture and an atomic execution backlog

Problem

The repository lacked one authoritative system design, Stripe/race/merchandise integrity model, dated security risk register, operations runbook, launch gates, and one-agent issue decomposition. Historical docs also presented stale deployment and waiver assumptions as current.

Outcome

Publish a root documentation set that clearly separates assessment baseline, working-tree remediation, target architecture, residual launch blockers, operator procedures, and atomic issue ownership.

Scope

Root README, SYSTEM_DESIGN.md, STRIPE_COMMERCE_DESIGN.md, SECURITY.md, OPERATIONS_RUNBOOK.md, IMPLEMENTATION_PLAN.md
GITHUB_ISSUES.md, GITHUB_ISSUE_SLICES.md, and repository AGENTS.md
Safe environment-name examples and ignore rules
Historical banners/corrections under docs/
No cloud/provider configuration, deployment, or legal approval

Acceptance criteria

Current and target architecture, trust boundaries, invariants, data/state models, and failure recovery are documented.
Live commerce is explicitly blocked until every P0 gate has code, tests, configuration, monitoring, owner, and staging evidence.
Parent trackers and one-agent children include dependencies, proof, and stop conditions.
Inventory semantics, payment/webhook behavior, privacy/security risks, and operational drills are unambiguous.
Historical docs cannot be mistaken for current security or waiver instructions.
Relative Markdown links and diagnostic build pass.

Dependencies

None. This issue publishes the coordination source; implementation children remain independently claimable and closable.

Coordination

A verified local working-tree implementation predates publication of this issue. This issue records the exact ownership boundary before any further editing or PR work. The existing diff must be isolated onto the claimed branch before review; unrelated changes and the pre-existing public/sitemap.xml modification are excluded.

Do not edit the listed paths or duplicate this outcome while the issue is assigned and has a valid timestamped CLAIMED marker.

CLAIMED by Codex agent /root at 2026-07-12T20:50:26Z; branch codex/issue-104-secure-commerce-docs.

Existing shared working-tree implementation predates issue publication. I will isolate this outcome onto the named branch serially before opening a PR; no unrelated dirty path is included.

User-directed documentation addendum (2026-07-12):

Expand this claimed documentation outcome with an officer-continuity layer for a nontechnical backup maintainer:

root OFFICER_START_HERE.md: one-screen entry point and reusable one-line AI request
root OFFICER_HANDBOOK.md: short, numbered procedures with page/data/deployment diagrams, proof/rollback steps, access continuity, and stop conditions
README.md: officer-first link before engineering material
AGENTS.md: permanent plain-language documentation contract for every future issue
docs/CONTENT_GUIDE.md: route officers to the new handbook and remove any implication that code edits or a green workflow prove a live update
basic Google Doc entry point for officer sharing; no secrets, private links, personal data, or provider configuration

Documentation must clearly separate: code changed, code merged, frontend live, Firebase/backend live, and external provider configuration verified. The current Netlify/GitHub Pages split and Firebase deploy skip remain explicit warnings.

No production, DNS, provider, legal, payment, or data mutation is included.

SOLE ACTIVE OUTCOME at 2026-07-12T21:53:48.542Z. #104 remains the only status:in-progress item. User-directed officer-continuity documentation is being added within this claimed boundary. #104 exclusively owns .env.example, functions/.env.example, functions/.secret.local.example, and every .gitignore hunk; #99 depends on #104 and owns none of those artifacts. The old shared checkout has not yet been transplanted to the claimed branch, so this is not an extraction-start claim. At isolation time I will post the required EXTRACTION STARTED marker and base it on refreshed main ce22c11 or later, preserving merged #98 behavior. After #104 completes, #103 is the next extraction by dependency leverage.

Google Doc entry-point evidence (2026-07-12):

Created a private native Google Doc titled MPRC Website — Officer Start Here.
The private edit link is intentionally withheld from this public issue and repository; it is delivered directly to the owner.
Connector readback verified the title, officer-guide locator, one-line AI request, prohibited-data bullets, merge/Pages/Firebase/Netlify warning, and owner-action checklist.
Drive metadata reports shared=false with owner-only permission. No passwords, recovery codes, secrets, member data, or payment data are present.
External sharing is therefore not claimed complete. Required owner follow-up: move the Doc into a board-owned MPRC Drive folder named Website Continuity, share with at least two backup officers, and record a two-account open/sign-in drill.

The public officer guides record the Doc title and owner-only limitation without exposing its private URL.

EXTRACTION STARTED at 2026-07-12T22:07:55.872Z on codex/issue-104-secure-commerce-docs.

Base: ce22c11 (merged #98 preserved).

Owned paths:

README.md, AGENTS.md, SYSTEM_DESIGN.md, STRIPE_COMMERCE_DESIGN.md, SECURITY.md, IMPLEMENTATION_PLAN.md, OPERATIONS_RUNBOOK.md
GITHUB_ISSUES.md, GITHUB_ISSUE_SLICES.md, OFFICER_START_HERE.md, OFFICER_HANDBOOK.md
docs/*.md historical corrections, docs/diagrams/waiver-flow.md, docs/officers/**
.github/pull_request_template.md and .github/ISSUE_TEMPLATE/officer-change-request.md
.env.example, functions/.env.example, functions/.secret.local.example, and every .gitignore hunk

Explicit exclusions: public/sitemap.xml; all #99 runtime/callback/emulator/package/test paths; #100 Rules; #101/#102 Stripe code/tests; #103 frontend harness; and any #98 source file. Environment examples document names/safe handling only and do not prove #99 runtime isolation.

Google Doc evidence is recorded separately without exposing its private link. No provider, production, DNS, legal, payment, or data mutation is included.

EXTRACTION FINISHED / REVIEW ACTIVE at 2026-07-12T22:14:08Z.

Branch: codex/issue-104-secure-commerce-docs
Base: ce22c110f2132b157bd8a0d43b065585e0b43cb5
Commit: a4a57a71f71c4722f228f45f76cd574db6463bc3
PR: docs: add officer continuity and secure commerce guides #108
Scope: 33 ARCH-001 — Establish secure-commerce architecture and an atomic execution backlog #104-owned documentation, template, environment-example, and ignore-rule paths
Exclusions confirmed: runtime code, Firestore Rules, package/test-harness changes, public/sitemap.xml, Stripe implementation files, and merged AUTH-001A — Reject unverified targets at existing role-grant endpoints #98 source files

Checks:

Functions lint: PASS
Functions Jest: PASS, 17/17
Firestore Rules: PASS, 97/97 with Java 17
production build diagnostic: PASS
current-main frontend baseline: Login 15 tests PASS; App suite stops at TextEncoder is not defined, tracked by CI-001A — Repair the deterministic frontend test baseline #103
staged diff check: PASS
relative links: PASS, 92/92 across 29 Markdown files
secret/private-Doc-locator/excluded-path scans: PASS
independent exact staged-index review: APPROVED, no findings

The private native Google Doc entry point was created and connector-readback verified. Its owner-only URL is withheld from public GitHub. Board-owned placement, two-backup sharing, and the two-account access drill remain explicit owner follow-up.

No merge or deployment was performed. Status remains status:in-progress until review and merge.

REMOTE CHECK UPDATE at 2026-07-12T22:17:00Z:

GitHub Actions CI: PASS
- Cloud Functions lint + test: PASS
- Frontend lint + build: PASS
- Firestore security-rules tests: PASS
Netlify deploy-preview status: FAIL
- GitHub reports only Deploy Preview failed and links to Netlify-owned logs.
- No production deployment was requested or performed.
- This is retained as evidence for the documented NOT AVAILABLE YET Netlify publication procedure; an authorized Netlify owner must audit the site, branch, build, preview, log-access, and rollback path before officers receive executable instructions.

PR #108 remains open, mergeable, and review-required. No merge was performed.

REVIEW ACTIVE / OWNER APPROVAL REQUIRED.

The repository has no status:in-review label, so #104 remains status:in-progress under the established one-outcome-at-a-time protocol while PR #108 is reviewed.

Merge is intentionally paused for Dave's explicit approval because a merge to main also authorizes the repository's automatic GitHub Pages publication and Firebase deployment attempt. #103 remains queued and must not begin until #104 actually merges.

USER-AUTHORIZED DEPLOYMENT BLOCKER ADDENDUM at 2026-07-12T22:26:15Z.

Dave requested: review, polish/fix issues, then deploy.

Final documentation review found no content blocker. Deployment review found the recurring Netlify preview/production build failure. A local Netlify-style reproduction using

run-mprc.github.io@1.0.0 prebuild
node scripts/generate-sitemap.js || true

Wrote sitemap with 9 URLs → /Users/daveliu/Code/Run-MPRC.issue-104/public/sitemap.xml

run-mprc.github.io@1.0.0 build
react-scripts build

Creating an optimized production build...

Treating warnings as errors because process.env.CI = true.
Most CI servers set it automatically.

Failed to compile.

[eslint]
src/components/ObfuscatedEmail.jsx
Line 21:38: Unexpected block statement surrounding arrow body; move the returned value immediately after the => arrow-body-style

src/data.jsx
Line 1:1: Prefer default export on a file with single export import/prefer-default-export

src/index.js
Line 10:13: JSX not allowed in files with extension '.js' react/jsx-filename-extension

src/pages/about/About.jsx
Line 61:23: Do not use Array index in keys react/no-array-index-key
Line 71:23: Do not use Array index in keys react/no-array-index-key

src/pages/account/Account.tsx
Line 246:15: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 255:15: A form label must be associated with a control jsx-a11y/label-has-associated-control

src/pages/account/StravaSection.tsx
Line 187:11: JSX props should not use functions react/jsx-no-bind
Line 191:23: JSX props should not use functions react/jsx-no-bind

src/pages/admin/AdminGuard.tsx
Line 36:10: Fragments should contain more than one child - otherwise, there’s no need for a Fragment at all react/jsx-no-useless-fragment

src/pages/admin/AdminHome.tsx
Line 148:1: This line has a length of 113. Maximum allowed is 100 max-len

src/pages/admin/events/AdminEventEditor.tsx
Line 211:19: Do not use Array index in keys Line 212:11: A form label must be associated with a control Line 220:11: A form label must be associated with a control Line 228:11: A form label must be associated with a control Line 245:11: A form label must be associated with a control Line 263:13: A form label must be associated with a control Line 348:11: A form label must be associated with a control Line 362:11: A form label must be associated with a control Line 377:11: A form label must be associated with a control Line 388:13: A form label must be associated with a control Line 398:13: A form label must be associated with a control Line 410:13: A form label must be associated with a control Line 419:13: A form label must be associated with a control Line 430:11: A form label must be associated with a control Line 438:11: A form label must be associated with a control Line 449:13: A form label must be associated with a control Line 460:13: A form label must be associated with a control Line 473:13: A form label must be associated with a control Line 490:15: A form label must be associated with a control Line 501:15: A form label must be associated with a control Line 512:15: A form label must be associated with a control Line 523:15: A form label must be associated with a control Line 540:13: A form label must be associated with a control Line 548:1: This line has a length of 111. Maximum allowed is 100 Line 551:13: A form label must be associated with a control Line 569:13: A form label must be associated with a control Line 593:13: A form label must be associated with a control Line 602:13: A form label must be associated with a control Line 625:16: Do not nest ternary expressions react/no-array-index-key
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
max-len
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
jsx-a11y/label-has-associated-control
no-nested-ternary

src/pages/admin/events/AdminEventRegistrations.tsx
Line 182:3: Definition for rule 'react-hooks/exhaustive-deps' was not found react-hooks/exhaustive-deps
Line 191:13: Use object destructuring prefer-destructuring
Line 233:12: Expected a line break after this opening brace object-curly-newline
Line 233:86: Expected a line break before this closing brace object-curly-newline
Line 236:1: This line has a length of 108. Maximum allowed is 100 max-len
Line 249:9: Unexpected prompt no-alert
Line 491:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 514:1: This line has a length of 101. Maximum allowed is 100 max-len
Line 516:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 593:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 607:13: A form label must be associated with a control jsx-a11y/label-has-associated-control

src/pages/admin/members/AdminMembers.tsx
Line 60:3: Definition for rule 'react-hooks/exhaustive-deps' was not found react-hooks/exhaustive-deps

src/pages/admin/shop/AdminOrders.tsx
Line 56:3: Definition for rule 'react-hooks/exhaustive-deps' was not found react-hooks/exhaustive-deps
Line 73:22: Unexpected prompt no-alert
Line 74:18: Unexpected prompt no-alert
Line 78:17: Unexpected prompt no-alert
Line 84:11: Unexpected confirm no-alert
Line 94:18: Unexpected prompt no-alert
Line 95:9: Unexpected confirm no-alert

src/pages/admin/shop/AdminProductEditor.tsx
Line 28:13: Object properties must go on a new line if they aren't all on the same line object-property-newline
Line 28:24: Object properties must go on a new line if they aren't all on the same line object-property-newline
Line 28:41: Object properties must go on a new line if they aren't all on the same line object-property-newline
Line 29:17: Object properties must go on a new line if they aren't all on the same line object-property-newline
Line 29:28: Object properties must go on a new line if they aren't all on the same line object-property-newline
Line 29:40: Object properties must go on a new line if they aren't all on the same line object-property-newline
Line 122:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 135:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 148:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 158:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 170:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 184:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 196:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 205:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 223:16: Do not nest ternary expressions no-nested-ternary

src/pages/events/EventCalendar.tsx
Line 52:22: Do not nest ternary expressions no-nested-ternary
Line 174:24: Do not use Array index in keys react/no-array-index-key

src/pages/events/EventDetail.tsx
Line 75:26: Do not nest ternary expressions no-nested-ternary
Line 218:16: Do not nest ternary expressions no-nested-ternary
Line 220:19: Do not nest ternary expressions no-nested-ternary
Line 222:21: Do not nest ternary expressions no-nested-ternary

src/pages/events/EventRegister.tsx
Line 57:9: Prop spreading is forbidden react/jsx-props-no-spreading
Line 65:15: Prop spreading is forbidden react/jsx-props-no-spreading
Line 87:7: Prop spreading is forbidden react/jsx-props-no-spreading
Line 117:3: Definition for rule 'react-hooks/exhaustive-deps' was not found react-hooks/exhaustive-deps
Line 250:15: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 261:15: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 285:20: Do not nest ternary expressions no-nested-ternary
Line 313:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 323:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 335:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 347:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 356:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 367:11: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 387:15: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 396:15: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 411:15: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 433:15: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 452:14: Do not nest ternary expressions no-nested-ternary
Line 454:17: Do not nest ternary expressions no-nested-ternary

src/pages/events/Events.tsx
Line 124:47: Error: must be placed on a new line react/jsx-one-expression-per-line
Line 124:54: {error} must be placed on a new line react/jsx-one-expression-per-line

src/pages/joinUs/JoinUs.jsx
Line 130:1: This line has a length of 103. Maximum allowed is 100 max-len
Line 134:17: Do not use Array index in keys react/no-array-index-key

src/pages/joinUs/Route.jsx
Line 22:34: Seal Point Park → 3rd Ave Launch → Bridgeview Park → back must be placed on a new line react/jsx-one-expression-per-line
Line 25:37: ~5 miles out and back along the Bay Trail must be placed on a new line react/jsx-one-expression-per-line

src/pages/legal/Privacy.jsx
Line 15:46: Last updated: must be placed on a new line react/jsx-one-expression-per-line
Line 15:60: strong must be placed on a new line react/jsx-one-expression-per-line
Line 18:49: Before going live, replace this with a policy reviewed by counsel or generated from a reputable service. If you accept registrations from California residents you may have CCPA obligations. must be placed on a new line react/jsx-one-expression-per-line
Line 26:43: name, email, phone, role (member, admin, unverified). must be placed on a new line react/jsx-one-expression-per-line
Line 30:48: name, email, phone, date of birth, emergency contact, shirt size, event-specific responses, waiver acceptance. must be placed on a new line react/jsx-one-expression-per-line
Line 34:43: handled entirely by Stripe. MPRC does not see or store your card details. We receive a Stripe payment reference only. must be placed on a new line react/jsx-one-expression-per-line
Line 38:40: Firebase Analytics (anonymized usage) and basic server logs. must be placed on a new line react/jsx-one-expression-per-line
Line 55:36: — payment processing (subject to Stripe's Privacy Policy) must be placed on a new line react/jsx-one-expression-per-line
Line 58:45: — hosting, auth, database, email delivery must be placed on a new line react/jsx-one-expression-per-line
Line 61:48: — transactional email delivery must be placed on a new line react/jsx-one-expression-per-line
Line 68:53: {' '} must be placed on a new line react/jsx-one-expression-per-line
Line 69:89: . Contact us to request deletion of your account and associated registration data. must be placed on a new line react/jsx-one-expression-per-line
Line 75:40: {' '} must be placed on a new line react/jsx-one-expression-per-line
Line 76:82: . must be placed on a new line react/jsx-one-expression-per-line

src/pages/legal/Terms.jsx
Line 15:46: Last updated: must be placed on a new line react/jsx-one-expression-per-line
Line 15:60: strong must be placed on a new line react/jsx-one-expression-per-line
Line 18:49: Before going live, replace this content with terms reviewed by an attorney or generated from a reputable service (iubenda, Termly, Rocket Lawyer). Specific clauses you'll want to include: event cancellation and refund policy, liability waiver reference, payment dispute resolution, intellectual property, account termination, and governing law (California). must be placed on a new line react/jsx-one-expression-per-line
Line 61:58: {' '} must be placed on a new line react/jsx-one-expression-per-line
Line 62:82: . must be placed on a new line react/jsx-one-expression-per-line

src/pages/login/LoginForm.jsx
Line 117:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 130:13: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 148:16: Do not nest ternary expressions no-nested-ternary

src/pages/shop/ProductDetail.tsx
Line 46:3: Definition for rule 'react-hooks/exhaustive-deps' was not found react-hooks/exhaustive-deps
Line 78:18: Expected a line break after this opening brace object-curly-newline
Line 78:54: Expected a line break before this closing brace object-curly-newline
Line 121:17: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 137:17: A form label must be associated with a control jsx-a11y/label-has-associated-control
Line 189:18: Do not nest ternary expressions no-nested-ternary

src/services/ServiceLocatorProvider.tsx
Line 1:15: Expected a line break after this opening brace object-curly-newline
Line 1:57: Expected a line break before this closing brace object-curly-newline

src/services/hooks/useAuth.ts
Line 38:5: Arrow function expected no return value consistent-return

src/services/monitoring/sentry.ts
Line 12:5: Variable name _initialized must match one of the following formats: camelCase, PascalCase, UPPER_CASE @typescript-eslint/naming-convention
Line 12:5: Unexpected dangling '_' in '_initialized' no-underscore-dangle

src/text/ContactUs.js
Line 1:1: Prefer default export on a file with single export import/prefer-default-export fails because Create React App promotes the repository's existing ESLint warnings to build errors. GitHub's green build already disables that duplicate webpack ESLint pass and runs its own lint step separately.

#104 scope is therefore expanded by exactly one hosting configuration path: .

Planned narrow fix:

pin Node 20
record

run-mprc.github.io@1.0.0 prebuild
node scripts/generate-sitemap.js || true

Wrote sitemap with 9 URLs → /Users/daveliu/Code/Run-MPRC.issue-104/public/sitemap.xml

run-mprc.github.io@1.0.0 build
react-scripts build

Creating an optimized production build...
Compiled with warnings.