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.