Frontend Route Requirements for MiniApps

This document outlines the routes that the frontend (archety-web) needs to implement to display MiniApp UIs.

URL Pattern

The backend generates URLs in this format:

{FRONTEND_BASE_URL}/app/{app_type}/{session_id}[/{view}][/{item_id}]

Environment Variable: - FRONTEND_BASE_URL - Set to your frontend deployment URL (e.g., https://archety-web.vercel.app)

Required Routes

1. Trip Planner

Route	Description
/app/trip/{session_id}	Main trip overview with venues
/app/trip/{session_id}/map	Map view with venue markers
/app/trip/{session_id}/venue/{venue_id}	Single venue detail

API Endpoint for UI Config:

GET /miniapps/ui/{session_id}?view=overview
GET /miniapps/ui/{session_id}?view=map
GET /miniapps/ui/{session_id}?view=venue&item_id={venue_id}

2. Bill Split

Route	Description
/app/split/{session_id}	Main bill overview with items
/app/split/{session_id}/settlement	Settlement view (who pays who)

API Endpoint:

GET /miniapps/ui/{session_id}?view=overview
GET /miniapps/ui/{session_id}?view=settlement

3. Poll

Route	Description
/app/poll/{session_id}	Voting view
/app/poll/{session_id}/results	Results view

API Endpoint:

GET /miniapps/ui/{session_id}?view=overview
GET /miniapps/ui/{session_id}?view=results

4. Todo List

Route	Description
/app/todo/{session_id}	Main todo list view

API Endpoint:

GET /miniapps/ui/{session_id}?view=overview

5. Transport Solver

Route	Description
/app/transport/{session_id}	Crisis dashboard with transport options

API Endpoint:

GET /miniapps/ui/{session_id}?view=overview

Backend API Endpoints

Get UI Configuration

GET /miniapps/ui/{session_id}

Query Parameters: - view (optional): View name (overview, map, settlement, results, etc.) - item_id (optional): Item ID for detail views

Response:

{
  "app_id": "trip_planner",
  "session_id": "abc123",
  "version": "1.0",
  "title": "Tokyo Trip",
  "theme": "travel",
  "header": { ... },
  "navigation": { ... },
  "components": [ ... ]
}

Submit Action

POST /miniapps/action/{session_id}

Body:

{
  "action": "vote",
  "payload": {
    "option_id": "opt1"
  }
}

Implementation Notes

Next.js App Router Structure

app/
├── app/
│   ├── trip/
│   │   └── [session_id]/
│   │       ├── page.tsx          # /app/trip/{session_id}
│   │       ├── map/
│   │       │   └── page.tsx      # /app/trip/{session_id}/map
│   │       └── venue/
│   │           └── [venue_id]/
│   │               └── page.tsx  # /app/trip/{session_id}/venue/{venue_id}
│   ├── split/
│   │   └── [session_id]/
│   │       ├── page.tsx          # /app/split/{session_id}
│   │       └── settlement/
│   │           └── page.tsx      # /app/split/{session_id}/settlement
│   ├── poll/
│   │   └── [session_id]/
│   │       ├── page.tsx          # /app/poll/{session_id}
│   │       └── results/
│   │           └── page.tsx      # /app/poll/{session_id}/results
│   ├── todo/
│   │   └── [session_id]/
│   │       └── page.tsx          # /app/todo/{session_id}
│   └── transport/
│       └── [session_id]/
│           └── page.tsx          # /app/transport/{session_id}

Component Types

The UI config returns a components array. Each component has:

interface Component {
  type: string;      // "card_list", "poll", "map_view", "split_summary", etc.
  id: string;        // Unique ID for the component
  props: object;     // Component-specific props
}

Common Component Types: - info_banner - Alert/info message - card_list - List of venue/item cards - poll - Poll with voting options - map_view - Map with markers - split_summary - Bill split summary - settlement_list - Who owes who - action_panel - Action buttons - stats_grid - Statistics display - section_header - Section title - quick_add - Quick input field

Error Handling

If session is not found, the API returns 404. Frontend should show: - "Session not found" message - Link to create new session via iMessage

Real-time Updates

For live updates (voting, collaborative edits, presence), there are two options:

1. Polling (simple): re-fetch GET /miniapps/ui/{session_id} every N seconds.
2. WebSocket (real-time): connect to:

   wss://<backend>/ws/miniapp/{session_id}?token=<jwt>
   

3. Implemented in app/api/websocket_routes.py
4. Auth: Supabase JWT token in the token query param

Testing

Use the MCP tools to create test sessions:

# Create a test trip session
mcp__archety-dev__send_message --user_id="+1234567890" --persona_id="sage" --message="trip to Tokyo"

Then access the URL returned in the response.