File size: 8,185 Bytes
2b86c60 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 | # HyperFlow integration contract
This is the wiring and boundary map, not a live-provider certification. Actual passing evidence is in [status](docs/flagship/status.md). API schemas exposed by `/docs` and current source remain authoritative for field details.
## Runtime and surfaces
```mermaid
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](https://mcp.swiggy.com/builders/docs/start/authenticate/) 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](docs/flagship/operations.md). 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.
|