Localz — New Architecture Notes Applicable to Stated Problems (Incremental)
This run's new Architecture/ content (first-ever notes in that folder) maps directly onto several problems already documented in Projects/Localz's pre-implementation synthesis. None of this existed when that synthesis was written, so it hasn't been cross-referenced yet.
Payments — fund segregation
Localz's provider payout flow (Projects/Localz.md §3, Payments) holds consumer payment until service completion, then pays out to the provider — a marketplace "separate charge and transfer" shape, structurally identical to the problem Stripe Connect: Fund Segregation with Allocated Balances describes. Localz's stack already commits to Stripe unanimously across all three stack docs. Before implementing the payout ledger, worth deciding explicitly whether provider funds sit in Localz's general Stripe balance pre-payout (the naive, riskier default) or get modeled as an allocated/earmarked state per booking — the case study's core lesson ("design the ledger-state boundary in before a regulator or incident forces the question") applies directly, and Canada doesn't yet have a PSD3-equivalent but marketplace commingling risk is the same regardless of jurisdiction.
Payments — idempotent booking/charge requests
Localz's booking flow (mobile clients, possibly flaky connections, cash-OTP and card paths) is exactly the retry-safety problem Stripe Idempotency Keys solves. Worth requiring an Idempotency-Key on the booking-creation and charge-creation endpoints specifically — a booking API is a natural double-submission risk (tap "book" twice on a slow connection) that this pattern was designed for verbatim.
Redis — already the confirmed choice, now has design guidance
Projects/Localz.md §5 already names Redis as "mandatory even at MVP" for caching, sessions, OTP throttles, and rate limiting. Caching Strategies and Design a Rate Limiter give concrete strategy guidance that wasn't available when the stack docs were written:
- Cache-aside is the right default for listing/search cards (read-heavy, staleness-tolerant); write-around fits OTP/session tokens (write-once, read-rarely-again).
- The rate limiter challenge note's fail-open recommendation is directly relevant to Localz's OTP throttle design — decide explicitly now whether a Redis blip should fail open (let an OTP request through) or fail closed (block it), rather than leaving it as an accident of the client library's timeout behavior.
Defense in depth — security NFRs
Projects/Localz.md §4 lists "encrypted payments, secure document storage" as qualitative, unquantified NFRs — flagged in the synthesis itself as a specification gap. Defense in Depth's layer breakdown (network, edge, identity, data, application, detection) is a ready-made checklist to turn that qualitative NFR into a concrete per-layer control list — particularly relevant given Localz stores ID documents and banking details for provider KYC.
Circuit breaker — third-party dependency fan-out
Localz's backend fans out to several external dependencies per request path (Stripe, S3, the search index, SMS/OTP provider). Circuit Breaker Pattern is directly applicable at these fan-out points — worth deciding per-dependency what "known bad, stop calling" looks like before the modular monolith splits into services (the note flags fan-out points as where breakers earn the most value).