Skip to content
Sanmopia Modernization

ADR 012 Frontend Static Atomic Shell

Switch to Zen Mode

Context

Section titled “Context”

Reservation, pricing, payment, payout, settlement, document access, and actor capability are security-sensitive backend decisions. Mirroring backend feature slices or policy models in browser code creates competing authority.

Decision

Section titled “Decision”

Frontend is static Astro shell organized with Atomic Design. It has no src/features/** layer and no business authority.

Allowed ownership:

  • src/pages/**: route assembly and approved backend projection loading only.
  • src/ui/atoms/**: primitive controls.
  • src/ui/molecules/**: composed controls.
  • src/ui/organisms/**: task-flow presentation.
  • src/ui/templates/**: page layouts and projection formatting.
  • src/lib/*-client.ts: typed backend API wrappers.
  • src/lib/supabase/**: approved authentication/session wrapper only.
  • NanoStores: ephemeral input, disclosure, selection, loading, and retry state.

Disallowed ownership:

  • src/features/** in target tree.
  • pricing, discount, refund, payout, or settlement arithmetic.
  • reservation or workflow transition rules.
  • local RBAC, capability, eligibility, or readiness derivation.
  • durable audit, idempotency, reconciliation, or repair state.
  • direct provider, raw Supabase data, generated-client, or unrestricted fetch bypasses around approved backend clients.

Frontend may submit intent and expected revisions. Backend command responses and query projections remain authority for amounts, statuses, capabilities, readiness, conflicts, and workflow progress. Formatting returned amounts or labels is presentation, not recomputation.

Enforcement

Section titled “Enforcement”

ESLint rejects files and imports under src/features/**, enforces Atomic Design dependency direction, blocks direct fetch, and restricts direct Supabase and generated-client imports. Tests use colocated *_test.ts names.

Static rules prove folder/import shape, not semantic absence of business logic. Review and tests must reject UI stores that infer capability or lifecycle state from free text, role labels, URL values, or local defaults.

Implementation Evidence

Section titled “Implementation Evidence”

Known Gaps

Section titled “Known Gaps”

Implementation remains partial. Committed family-assisted reservation store still defaults and derives canBookForMother, payment-delegation status, and payment-method availability from local conversational input. Those fields must come from backend capability/projection contracts or remain clearly non-authoritative draft input before this ADR can be marked implemented.

Frontend 8a9a6f5 removes reservation-smoke-scenarios, smoke settlement DTOs, ledger preparation math, proof rendering, and query flags from production src/**. Dev-smoke orchestration now lives only in Playwright. It also stops deriving workflow retry/cancel actions from workflow status and stops assigning warning tone from reconciliation amount. ESLint rejects smoke endpoint literals and SmokeSettlement imports under production source.

Manual payment receipt stays locked when backend command draft lacks expectedPaymentRevision; frontend does not invent revision 0. Remaining contract work must add that revision to generated backend/contract projection.

Payment provider checkout uses backend-owned PaymentProviderHandoffSession from POST /reservation-payment-pre-registrations. Frontend may render the card-flow step, show method/expiry/amount from the response, and submit the handoff reference to approved backend/provider wrappers. Frontend must not create or mutate provider route, return path, expected payment revision, amount, fingerprint, provider payload, or provider-specific approval request fields.

Reservation financial lifecycle mutation is not part of the browser API surface. Frontend booking clients may start reservation booking, read workflow progress, read mother-visible charge summary, request payment pre-registration handoff, and read account-disclosure readiness/grant projections. Service delivery, caregiver payout preparation, branch settlement preparation, HQ settlement preparation, settlement completion, and financial lifecycle workflow start stay in backend commands or non-browser Playwright/backend drivers.

No current src/features/** tree exists at pinned revision. That removes folder-level drift but does not close semantic UI-authority debt above.

Consequences

Section titled “Consequences”

Missing business facts block frontend completion until backend contracts expose them. UI cannot fill contract gaps with local policy or fake authority.

Revision History

Section titled “Revision History”
  • 2026-07-09: accepted static Atomic Design shell boundary.
  • 2026-07-10: removed stale feature-folder debt claim and recorded remaining semantic UI-authority gap.
  • 2026-07-11: moved smoke settlement orchestration out of production source, removed workflow/action and reconciliation-tone inference, added revision fail-closed behavior, and improved neutral desktop/mobile reservation progress.
  • 2026-07-12: recorded backend-owned checkout handoff session boundary; browser remains presentation-only for provider payment entry.
  • 2026-07-13: removed frontend booking-client financial lifecycle mutation helpers from allowed browser API surface; reservation-to-settlement proof now must use backend-owned commands or Playwright backend driver.