# Decisions for Jonathan Nonfinal architecture review · 0.4.0. Generated from `assets/review-model.js`; edit that source and rerun `node tools/generate-docs.js`. The ordered milestones, spikes, publication proposal and pricing tasks are in the [proposed implementation plan](../implementation-plan.md), which remains unapproved. The illustrated workbench screen `implementation-plan.html` is not in this package. The guide’s milestone figures are on the [implementation roadmap](../../roadmap.html#milestones). ## decide Now ### id DJ-11 ### group now ### priority 0 ### question Launch with two bounded scrapers and a reserved operating budget? ### recommendation Propose two sources with 200 listings each, daily refreshes and application admission quotas. Price every required recurring service within the confirmed USD 50/month ceiling. ### reason A narrow workload leaves room for uncertainty while measuring real source behavior. ### alternatives - Reduce listings or browser dependence if the service inventory does not fit. - Defer paid launch until required services and source behavior are priced. ### consequences Optional browser, LLM and replay work pauses before the reserve is consumed. Accepted data stays available with honest stale/deferred status. ### status Proposed — awaiting Jonathan’s acceptance ### evidence Itemized service prices and allowance allocation; database active time; parser failures; review effort; measured source access. ### link cost.html#launch-budget ### id DJ-09 ### question Adopt tenant-private catalogs as the initial baseline? ### recommendation Yes: tenant isolation from day one, with catalog identity modeled separately. ### reason Ownership, access, and publication stay explicit without deciding shared governance prematurely. ### alternatives - Shared catalogs plus private overlays - Single implicit global catalog ### consequences Cross-tenant sharing later needs migration and permissions design; current keys and events carry tenant and catalog. ### status Proposed — Jonathan’s acceptance needed ### evidence Confirm intended tenants, sharing needs, and public publication authority. ### link atlas.html#ADR-008 ### group now ### priority 1 ### id DJ-10 ### question Who may authorize public publication? ### recommendation An operator admin with publications:write releases an accepted revision and allowlisted explanations. ### reason Automatic internal acceptance is not consent to expose source evidence or operational metadata. ### alternatives - Explicit per-catalog publication policy after review - Every accepted fact public by default ### consequences An accepted correction may remain private. Public item, listing and inventory views move together only when its authorized release applies; withdrawal timing still needs an agreed operational target. ### status Proposed — Jonathan’s acceptance needed ### evidence Approve release roles, fields, observation-metadata permission, and withdrawal expectations. ### link data.html#publication ### group now ### priority 2 ### id DJ-02 ### question Use relational accepted state with a transactional outbox? ### recommendation Keep accepted facts in relational tables, preserve immutable evidence and decisions, and commit each integration event with its state change. ### reason Relational state supports operational queries; the outbox reliably carries accepted changes. ### alternatives - Relational + outbox (recommended) - Event sourcing for identity aggregates only - Full event sourcing ### consequences Operational queries stay straightforward. Recovery depends on coordinated snapshots and retained events; the bounded outbox is not a permanent event-sourcing log. ### status Open — Jonathan’s decision needed ### evidence SPK-01 proves transaction atomicity; SPK-05 proves snapshot and retained-tail recovery. ### link atlas.html#ADR-003 ### group now ### priority 3 ### id DJ-04 ### question Recovery objectives (RPO/RTO) for the resolver database and evidence store? ### recommendation Set the maximum tolerable loss of accepted data and the maximum service outage for the resolver and evidence store before choosing backup commitments. ### reason Recovery targets determine backups, cost and incident procedures. ### alternatives - Provider PITR defaults - Stricter targets with replicas - Evidence store replication ### consequences These targets determine backup/PITR plans, restore procedures and cost. Product projections can be rebuilt; lost source evidence and decisions cannot be assumed recoverable. ### status Open — Jonathan’s decision needed ### evidence Jonathan supplies business loss/outage tolerances; SPK-05 measures whether the proposed restore and rebuild can meet them. ### link atlas.html#ADR-004 ### group now ### priority 4 ### id DJ-05 ### question Who approves identity-relevant attribute definitions and item splits? ### recommendation Require a human to approve identity-relevant definitions and splits, and separately authorize activation of a backfilled, collision-free identity generation. ### reason Identity changes can split products and invalidate downstream mappings. ### alternatives - Human always (recommended) - Auto-publish when deterministic evidence is unanimous ### consequences Captures and replay remain pinned to explicit rules. Unresolved splits hold affected claims and delay activation instead of silently changing identity. ### status Open — Jonathan’s decision needed ### evidence Review ownership of definition approval, split decisions and rule activation; then exercise concurrent capture/backfill in the implementation. ### link atlas.html#ADR-005 ### group now ### priority 5 ### id DJ-06 ### question First real source for measurements? ### recommendation Keep Pantry & Pour as a deterministic fictional fixture; choose a real authorized source separately ### reason A fictional fixture proves deterministic behavior, not access or source economics. ### alternatives - Public feed with stable identifiers - Partner API with permission - Browser storefront after feasibility review ### consequences The fictional Pantry & Pour fixture keeps the implementation slice deterministic. Only an authorized real source can establish access, parser reliability, browser demand and cost. ### status Open — Jonathan’s decision needed ### evidence Confirm source permission and stable identifiers, then measure fetch success, extraction quality, freshness and human review workload. ### link atlas.html#SPK-03 ### group now ### priority 6 ### id DJ-01 ### question Physical database topology? ### recommendation Start with one managed PostgreSQL instance, separate resolver and product schemas, and service-specific database roles. ### reason Keep transaction and operations complexity bounded during the initial slice. ### alternatives - Shared instance (recommended) - Separate instances now - PostgreSQL resolver + D1 product ### consequences This keeps the first deployment smaller, but the services share a database failure boundary. Moving to separate instances later adds an explicit migration. Any topology or runtime must include all required recurring services within the confirmed USD 50/month ceiling; measure active database time before selecting it. ### status Open — Jonathan’s decision needed ### evidence SPK-01 must prove transaction and role isolation through the selected driver and pool. ### link atlas.html#ADR-002 ### group now ### priority 7 ### id DJ-08 ### question Decision history retention? ### recommendation Retain decision history as immutable records, with correction represented by a new linked decision. ### reason Corrections need a durable explanation without rewriting earlier decisions. ### alternatives - Permanent (recommended) - Bounded with archival export ### consequences Operators can explain how an identity changed. Storage, access control and eventual evidence-retention policy must support that audit history. ### status Open — Jonathan’s decision needed ### evidence Confirm retention and privacy requirements before final storage policy; restrict application roles from deleting decisions. ### link atlas.html#ADR-003 ### group now ### priority 8 ## validate Through Spike ### id DJ-03 ### question Outbox retention window? ### recommendation Keep bounded event retention with rebuild leases and durable live-consumer protection. Treat 14 days only as a placeholder until recovery is measured. ### reason Retained events must outlive recovery lag; a lease overrides ordinary pruning. ### alternatives - Bounded window (recommended) - Permanent outbox as replay log ### consequences An active rebuild or stalled consumer can extend storage beyond the age window. Set the final duration and alerts from measured rebuild time and lag. ### status Open — Jonathan’s decision needed ### evidence SPK-05 measures pruning during rebuild, progress after cutover, gaps, restore fencing and peak retention growth. ### link atlas.html#SPK-05 ### group spike ### priority 1 ### id DJ-07 ### question Resolver runtime? ### recommendation Trial Workers and Hyperdrive for intake, administration and job consumers, with portable domain code and a Node-container fallback if transaction requirements fail. ### reason Keep domain logic portable while testing the proposed deployment. ### alternatives - Workers + Hyperdrive (recommended) - Node container near the database ### consequences This avoids committing to a runtime before proving writer locks, transaction lifetimes and error handling. A failed spike changes deployment adapters, not domain contracts. Any topology or runtime must include all required recurring services within the confirmed USD 50/month ceiling; measure active database time before selecting it. ### status Open — Jonathan’s decision needed ### evidence SPK-01 covers transactional cursor contention, all-or-nothing writes, role boundaries and driver/pool behavior. ### link atlas.html#SPK-01 ### group spike ### priority 2 ## additional Spikes ### id SPK-02 ### recommendation Exercise duplicate, reordered and dependency-blocked delivery. ### consequences Prove durable inbox/application behavior before trusting the queue integration. ### id SPK-03 ### recommendation Measure an authorized real source on the intended collector runtime. ### consequences Replace assumed browser schedules, extraction success and review effort with observations. ### id SPK-04 ### recommendation Measure representative product filters and offer queries. ### consequences Choose indexes or a search service from latency and query plans, not anticipated scale. ## defer ### id defer-sharing ### title Shared catalogs and private overlays ### recommendation Keep tenant-private catalogs for the initial slice; revisit sharing when actual collaboration needs are known. ### consequences A future sharing model requires ownership, permissions and migration design. ### link atlas.html#ADR-008 ### id defer-projection-store ### title Alternative projection stores and dedicated search ### recommendation Begin with PostgreSQL projections. Consider D1 only if the store decision remains open, and add search infrastructure only if representative queries need it. ### consequences Avoid another datastore until SPK-04 measurements justify it; SPK-06 remains conditional. ### link atlas.html#SPK-06 ### id defer-event-sourcing ### title Full event sourcing ### recommendation Revisit only if temporal reconstruction needs exceed immutable evidence, decisions and revisioned relational state. ### consequences Adopting it later would change event retention, schema evolution and recovery responsibilities. ### link atlas.html#ADR-003