Frontend Integration Contract
Backend API contract and design decisions governing client-server communication.
[!NOTE] This document is the canonical frontend-backend contract for AnyaSelf v1. For detailed endpoint schemas, see the individual service documentation.
Design Decisions
| # | Decision | Detail |
|---|---|---|
| 1 | Voice: Model B | Client uses Gemini Live for STT/TTS only. Text turns go through Orchestrator /chat. |
| 2 | Auth: Gateway token | JWT validated at API Gateway boundary. Production target: OIDC/JWKS. |
| 3 | Boutique "stands" | Information architecture (grouped surfaces), not 3D. |
| 4 | Mobile-first | Responsive web-first. Native wrapper optional. |
| 5 | Offline tolerance | Wardrobe browsing only. Missions, approvals, checkout online-only. |
| 6 | Performance budget | Mid-tier Android: lean payloads, image memory, JS execution. |
| 7 | Client events | Domain APIs first, no separate critical-path event bus. |
Voice Loop (B-Model)
- Client captures speech → Gemini Live transcribes to text
- Client sends text to
POST /orchestrator/missions/{mId}/chat - Client speaks assistant response via TTS
- User interrupt (barge-in) stops TTS and sends new turn
Rules:
- Voice never calls internal tools directly
- Orchestrator mission state is source of truth
- Client keeps local transcript for UX; server aggregation is a separate artifact concern
Client Event Mapping
| Event | Authoritative Action | Mission Signal |
|---|---|---|
USER_LIKED_ITEM | — | POST /missions/{mId}/events |
USER_DISLIKED_ITEM | — | POST /missions/{mId}/events |
USER_TAKEOVER_START | POST /sessions/{sId}/takeover | Optional event fallback |
USER_TAKEOVER_END | POST /sessions/{sId}/release | Optional event fallback |
USER_APPROVED_REQUEST | POST /requests/{rId}/approve | Then emit event |
USER_CONFIRMED_FINAL_CHECKOUT | POST /requests/{rId}/confirm-checkout | Then emit event |
Error Envelope
All services return errors in a consistent shape:
{
"error": "ERROR_CODE",
"message": "Human-readable message"
}Validation errors include additional details:
{
"error": "VALIDATION_ERROR",
"message": "Request validation failed.",
"details": []
}