Download DECISIONS.md from Gaurav711/HyperFlow: direct link, hf CLI and curl.
- Browser
- Download file 6.26 kB
-
https://huggingface.co/spaces/Gaurav711/HyperFlow/resolve/main/DECISIONS.md
- Command line
-
hf download hf://spaces/Gaurav711/HyperFlow/DECISIONS.md
-
curl -L -o DECISIONS.md https://huggingface.co/spaces/Gaurav711/HyperFlow/resolve/main/DECISIONS.md
HyperFlow architecture decisions
Date: 20 October 2026. This register records design intent and inspected implementation; passing status belongs in status. Updates append or explicitly supersede decisions.
ADR-001 β PostgreSQL owns durable state
Context: proposals, approvals, action attempts, receipts, jobs and events must survive process and notification loss.
Alternatives: process memory; Redis authority; distributed Kafka services; a relational service with transactional events.
Decision: use PostgreSQL as authority, one API and one worker. Persist record changes with domain events. Redis is an optional notification accelerator; durable event cursors recover missed notifications. SQLite/file locks support isolated demonstrations, not proof of PostgreSQL concurrency.
Consequences: fewer moving parts and βΉ0 local deployment; correctness depends on transaction/locking tests and database recovery. Current outbox notification delivery can repeat, so consumers must deduplicate event IDs.
Evidence: backend/flagship/store.py, worker.py; separate PostgreSQL suite and restart protocol in methodology.
ADR-002 β Explicit simulation and scoped identity
Context: provider access is intermittent and replay demonstrations must remain reproducible without pretending to be live.
Alternatives: shared environment token; anonymous guest identity; silent simulation fallback; isolated explicit workspaces.
Decision: database-backed opaque sessions, server-assigned roles and account-bound encrypted provider credentials. Reviewer workspaces use labelled simulations. A live authentication failure stays a failure. Saving a real token requires a configured persistent encryption key even in demonstration mode.
Consequences: local session persistence currently uses browser storage and Authorization headers; XSS is a security boundary. No cookie/session-hardening claim is implied. Unknown token expiry stays unknown. Successful storage is not successful provider verification.
Evidence: identity/provider/API regressions; integration contract. Supersedes historical shared-token and no-refresh instructions.
ADR-003 β Proposal approval is backend authority
Context: prices, addresses and shared carts can change between planning and mutation. Instamart cart updates replace the cart.
Alternatives: prompt-only approval; direct model mutation; approval of a vague intent; exact versioned proposal.
Decision: validate exact account, provider, address, payload, cart snapshot and displayed total; serialize account/provider mutations; re-read provider state and require renewed approval after material changes. Local idempotency keys bind payloads and return durable outcomes.
Consequences: more user interaction after changes, but no silent substitution. Lost responses can leave UNKNOWN and require receipt reconciliation. Local locks and keys do not create upstream idempotency.
Evidence: commerce.py, journey/failure suites; Swiggy execution guidance.
ADR-004 β Grounded optimization before model fluency
Context: an eloquent answer cannot compensate for invalid quantities or invented catalogue values.
Alternatives: model-built catalogue and basket; cheapest-per-unit greedy selection; deterministic constraints with optional intent extraction.
Decision: preserve provider variants, validate units and constraints, minimize exact cost then normalized excess, compare with a feasible single-variant baseline. Use exhaustive small cases as oracle. Ambiguity produces clarification.
Consequences: bounded solver evaluation cannot prove arbitrary-scale optimal performance; model assistance must demonstrate incremental value. No cross-unit physical quantities are summed.
Evidence: basket.py, parsing.py; frozen solver/parser gates in methodology.
ADR-005 β Bound and measure the custom AI loop
Context: tool outputs are untrusted and model calls can cost money or repeat work.
Alternatives: framework adoption for branding; unrestricted tool loop; rules-only; bounded optional model extraction and read tools.
Decision: retain the custom loop, enforce limits and mutation boundaries in code, persist useful checkpoints, compare against rules. Freeze ten tool steps, three model requests and 60 seconds per turn; twenty requests/day and 120/campaign on verified free quota. These are required limits until verified, not a statement that current code enforces all of them.
Consequences: no paid runs in default verification. A failed model experiment may leave rules as the shipping default. Historical LangGraph naming is not proof of LangGraph orchestration.
ADR-006 β Separate real retail forecasting from censoring research
Context: public sales do not reveal lost demand or stockouts.
Decision: UCI Online Retail II remains GBP retail research with chronological baselines. Test Tobit recovery separately using known latent labels and controlled censoring. The previously inspected final period is exposed; it cannot become an unseen holdout again.
Consequences: claims are narrower and defensible. Promote the exact evaluated artifact only after meaningful configured gates, successful persistence and serving verification. Failed candidates preserve the active artifact.
Evidence: retail report, censoring report; current reproduction remains a separate release gate.
ADR-007 β Delivery evidence precedes FDE and scale claims
Decision: one volunteer pilot, reproducible deployment, incident drill and restore drill establish bounded delivery evidence. Doctor/trace are diagnostic aids. Local load, simulation and pilot findings retain their environment and sample limits.
Consequences: no enterprise readiness, customer-scale adoption, business savings, fraud accuracy or high-throughput claim without matching evidence. Preserve surfaces but flag unaudited compatibility paths explicitly.