HyperFlow / INTEGRATION.md
Gaurav711's picture
Deploy 891f179
2b86c60 verified
|
Raw History Blame Contribute Delete
8.19 kB

HyperFlow integration contract

This is the wiring and boundary map, not a live-provider certification. Actual passing evidence is in status. API schemas exposed by /docs and current source remain authoritative for field details.

Runtime and surfaces

flowchart TD
  UI[React / Vite workspace] -->|Bearer session / api/v2| API[FastAPI]
  API --> DB[(PostgreSQL authoritative state)]
  Worker[Durable worker] --> DB
  Worker -. optional notification .-> Redis[Redis]
  API -->|account credential / explicit live mode| MCP[Swiggy MCP]
  API -->|explicit replay mode| Sim[Isolated simulations]
  API -->|authenticated SSE cursor| UI

Entrypoint: backend/api/main.py calls the flagship app factory. frontend/src/App.jsx currently maps public routes to the persisted, source-labelled FlagshipPages implementations: agent, store, BasketOps, delivery/courier, intelligence, guard, site scenarios, analytics, replay and case study. Earlier prototype page files remain in source. /dev/* aliases also exist; testing only aliases does not replace exercising user-facing routes.

The app also mounts public geo metadata with descriptive capability boundaries. Account-owned operations require authentication. Direct compatibility checkout returns 409 and directs users through reviewed proposals; compatibility weather/forecast/health endpoints return labelled UNAVAILABLE empty states. Legacy catch-all routes generally return 410, with explicitly declared exceptions such as health/retraining. Do not infer universal provider coverage from a v2 prefix.

The worker processes persisted training jobs and outbox notifications. /health checks the API; /ready checks schema/database and worker freshness. Redis loss must not erase jobs or SSE history.

Authentication and provider credentials

HyperFlow login is distinct from Swiggy authorization. Ordinary registration receives a server-assigned user role; administrator/operator/courier roles are provisioned. Public reviewer accounts are isolated simulations with no live-provider or paid-model authority.

Opaque sessions are stored server-side; the frontend retains its session token in browser storage and sends Authorization: Bearer …. Reload validation must not confuse an offline network error with proven session expiry. Clear account-scoped UI state when switching accounts.

Real credentials are encrypted with account-bound authenticated encryption and a persistent VAULT_SECRET_KEY. Store/refresh/disconnect operations never return token plaintext. Provider failures must not downgrade a live request to simulation.

Required Phase 1 contract:

Operation Meaning
POST /api/v2/provider/credentials Store this account's supplied access token and optional refresh/expiry metadata; storage does not establish validity
GET /api/v2/provider/credentials Return configured, verification_status, verified_at, expiry_known, and nullable expires_at; never fabricate expiry
DELETE /api/v2/provider/credentials Disconnect this account; invalidate its verification evidence
POST /api/v2/provider/verify with { "provider": "im" } Read-only authenticated discovery; return status without exposing addresses or tokens
POST /api/v2/provider/refresh Refresh current credentials safely; rotating replacements cannot overwrite a concurrent user replacement
Swiggy authorize-url/callback Registered client ID, exact configured redirect, expiring single-use state and PKCE; reject mismatch/replay

The verification addition and revised fields are present in current source; passing verification still requires current test evidence. Verification must bind to the current credential version; an old successful response cannot verify a replacement token. Outage/rate-limit failures do not prove credential revocation.

Current Swiggy authentication documentation describes refresh support. Read actual response expiry and rotating refresh token values; unknown manual-token expiry stays unknown. Do not fabricate a refresh token from an access token. Verify provider names, schemas, error codes and limits against current official documentation before modifying integrations.

Commerce sequence and contracts

  1. Parse/edit intent with /api/v2/baskets/parse; discover and plan with /api/v2/provider/read, /provider/discover and /baskets/plan. /baskets/optimize validates structured inputs.
  2. Create /api/v2/proposals, inspect the exact version and amounts, then approve at /api/v2/actions/{proposal_id}/approve with its version.
  3. Execute /api/v2/actions/{action_id}/execute using Idempotency-Key. Reusing a key with different content conflicts. Persist the attempt before external mutation.
  4. Fetch current provider cart and compare approval binding. Changed data produces a revised proposal; no silent removal, substitution or quantity change.
  5. Persist validated success/receipt, failure or uncertainty. Inspect /api/v2/actions/{action_id} and use /reconcile when appropriate. A lost order response is never a reason for blind placement retry.
  6. Subscribe to /api/v2/events, retaining event IDs; reconnect with Last-Event-ID or after. Scope history and authorization to the account, revalidate sessions and deduplicate events in consumers.

States include PROPOSED, APPROVED, EXECUTING, SUCCEEDED, FAILED, UNKNOWN and SUPERSEDED; only validated evidence permits success. Provider payment-pending evidence must remain pending. Purchases and bookings are outside the current ₹0 verification campaign.

Jobs, models and operations

Training submission returns 202 and a durable job. The implemented lifecycle includes EVALUATED before explicit administrator promotion; queued/running/insufficient/rejected/failed states remain distinct. Worker restart resumes persisted work with bounded attempts. /api/v2/models identifies serving state; promotion and rollback require administrator authority. Candidate manifests carry immutable dataset, schema, configuration and artifact identities.

Delivery enrollment, assignment, telemetry, transitions, reviews and economic inputs use /api/v2/operations/*; read operations assumptions. Provider tracking grants no authority over provider couriers. Synthetic weather, coupon, health or demand values must never appear as live observations.

Verification matrix

Boundary Required evidence Current restriction
API ↔ database Isolated migration, restart, account isolation and concurrency tests SQLite results do not establish PostgreSQL semantics
API ↔ provider Schema fixtures plus separately captured live read receipts Live discovery pending supplied token; no live transaction certification
Browser ↔ API Actual mounted-route tests, reload/account switch, offline and SSE recovery Historical browser reports need current reproduction
Worker ↔ model registry Failed write/promotion, exact artifact, rollback, concurrent serving Historical study results do not certify current serving
Operations ↔ user workflow Assignment/review tests and volunteer tasks No customer-scale fleet or merchant evidence

Durable model turns and serving qualification

Authenticated /api/v2/agent/turns and /api/v2/agent/turns/{record_id} expose only the account's persisted turn records. A stable turn ID binds the payload: completed retries return the saved response; payload changes conflict; incomplete/failed turns require inspection and an explicit new attempt. Checkpoints do not implement automatic continuation of a partially executed model loop.

Model budgets count physical outbound requests, including failed requests. Global campaign and account limits apply. Both model-enable and free-quota-confirmation flags are required. Deadlines are cooperative; provider calls already in flight can exceed the turn deadline. ML studies do not become serving candidates without both explicit quality thresholds and exact-artifact verification.