✦
┌──────────────┐
│ 🤖 AI Chat │
├──────────────┤
│ User: "Build │
│ a calculator"│
│ │
│ AI: ✨ Done! │
│ [streaming] │
│ ──────────▶ │
└──────────────┘
AI Chat API
Streaming responses, model fallback, credits, and conversation memory.
┌──────────┐
│ Claude │──┐
│ GPT-4 │ ├──▶ Response
│ Gemini │──┘
│ (fallback)│
└──────────┘
AI Chat API
Streaming responses, model fallback, credits, and conversation memory.
Chat Flow Overview
┌─────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ User │───▶│ Edge Fn │───▶│ AI Model │───▶│ Streaming│
│ Message │ │ /chat │ │ (Claude) │ │ Response │
└─────────┘ └─────┬────┘ └─────┬────┘ └─────┬────┘
│ │ │
┌────▼────┐ ┌─────▼─────┐ ┌─────▼─────┐
│ Credits │ │ Fallback │ │ Supabase │
│ Check │ │ (GPT-4) │ │ Storage │
└─────────┘ └───────────┘ └───────────┘
Endpoints
Base Path: /functions/v1
POST /chat
Send a message and receive a streaming AI response. Creates a persistent job that survives disconnections. Body:
ChatRequest.GET /chat/:jobId
Resume a streaming job. Returns the SSE stream from where it left off. Used for reconnection after network drops.
GET /chat/:jobId/status
Check job status without consuming the stream. Returns
{ status, progress, creditsUsed }.Streaming (SSE)
Chat responses are streamed via Server-Sent Events. The client receives incremental text chunks as the AI generates them.
data: {"type":"text","content":"I'll "}
data: {"type":"text","content":"build "}
data: {"type":"text","content":"a "}
data: {"type":"text","content":"calculator"}
data: {"type":"task_start","taskId":"abc-123"}
data: {"type":"task_progress","taskId":"abc-123","step":"Creating files"}
data: {"type":"task_complete","taskId":"abc-123"}
data: {"type":"done","creditsUsed":3}
Event Types
text
Incremental text content from the AI. Appended to the chat bubble as it arrives.
task_start
AI has begun a new task. Creates a task entry in the timeline.
task_progress
Updates the task step description and progress indicator.
task_complete
Task finished successfully. Marks the timeline entry as done.
Persistent Jobs
Chat jobs are stored server-side and survive app backgrounding, network loss, and even app kills. When the user returns to a chat, the client calls GET /chat/:jobId to resume the stream.
Job Creation
POST /chat creates a job entry in the database with status
pending. The Edge Function processes it asynchronously.Job Execution
The job status moves to
running as the AI processes the message. Events are stored as they stream.Job Completion
Status moves to
completed (or failed). All events are persisted for later retrieval.Reconnection
If the client disconnects, it can resume by calling GET with the job ID. The server replays any missed events.
Model Fallback
If the primary AI model fails or is rate-limited, the Edge Function automatically falls back to the next available model:
Priority chain: 1. Claude Sonnet 4 (primary) 2. GPT-4o (fallback 1) 3. Gemini 2.5 Flash (fallback 2) If all models fail → return 503 with retry-after header
Credits & Handoff
Credit Check
Before processing, the Edge Function checks the user's remaining credits. Returns 402 Payment Required if credits are exhausted.
Credit Deduction
Credits are deducted per message based on token count and model pricing. Deduction happens after successful completion, not at submission.
Usage Tracking
Each response includes
creditsUsed in the final SSE event. The app updates the local credit balance display.Conversation Memory
Each chat session maintains context across messages. The Edge Function retrieves the conversation history from the database and includes it in the AI prompt context.
Message Storage
Both user messages and AI responses are stored in the
chat_messages table, linked to the project.Context Window
The last N messages (configurable, default 20) are included as conversation context. Older messages are summarized.
System Prompt
A system prompt describing Archon's capabilities and the project context is prepended to every request.