How it works

The AI Builder follows a three-step flow: Describe → Build → Preview. You type a natural language description of what you want, the AI generates code and organizes it into a project, and then you can preview it instantly in the Live Preview tab.

Model selection

Archon supports multiple AI providers so you can choose the model that fits your needs and budget:

You configure your API key per provider in Settings. Archon detects which keys are available and enables the corresponding models automatically.

Streaming responses

Archon uses server-sent events (SSE) to stream the AI response token by token. You see the code being generated in real time — no waiting for the full response before anything appears.

// Streaming is handled internally by the APIClient.
// Each token is appended to the current task as it arrives.
//
// Under the hood, Archon opens an SSE connection:
//
//   POST /v1/chat/completions
//   Content-Type: application/json
//   Accept: text/event-stream
//
//   { "model": "claude-sonnet-4-20250514", "stream": true, ... }
//
// Events are parsed as they arrive and UI updates are
// batched to keep the interface responsive.

Task timeline

Every build produces a visible task timeline. Each task represents a discrete step — generating a view, writing a model, creating a style file. Tasks progress through these states:

• Pending — queued, waiting for its turn
• In Progress — actively being generated (streaming)
• Completed — finished and saved to the project
• Failed — an error occurred (can be retried)

Message queue

If you send multiple messages before the current build finishes, they're queued. Archon processes them in order — you never lose a message, and each one builds on the previous context.

Model fallback with credit handoff

If your primary model hits a rate limit or runs out of credits, Archon can automatically fall back to another configured provider. For example, if your Anthropic credits are exhausted mid-build, the system switches to OpenAI without losing context.

// Fallback configuration (Settings → API Configuration)
//
// Priority order:
//   1. Your selected primary model
//   2. Next available provider with a valid API key
//   3. Default fallback (OpenAI GPT-4o)
//
// Context is preserved across provider switches —
// the full conversation history is resent with each
// fallback request.

Follow-up suggestions

After each build completes, Archon generates contextual follow-up suggestions. These are specific to what was just built — "Add a settings page", "Change the color scheme", "Add haptic feedback". Tap a suggestion to send it as the next message, or type your own.

Conversation memory

Every message you send within a project is part of a persistent conversation. The AI has access to the full history, so you can reference earlier decisions without restating context.

Cross-session context

When you return to a project later, the conversation history is restored from the database. The AI remembers what was built before, what was changed, and what was discussed — so you can pick up exactly where you left off.

Retry and cancel

If a build fails or you change your mind:

• Retry — taps the retry button on a failed task to regenerate it with the same input
• Cancel — stops the current stream mid-generation. Partially generated files are kept
• Regenerate — re-sends the last message to get a fresh response

API usage example

Archon's API client follows a protocol-based pattern for flexibility and testing:

protocol APIClientProtocol {
    func sendMessage(
        projectId: String,
        message: String,
        model: String
    ) async throws -> AsyncStream<StreamEvent>

    func getAvailableModels() async throws -> [AIModel]
    func getConversationHistory(
        projectId: String
    ) async throws -> [ChatMessage]
}

// A typical build flow:
let stream = try await apiClient.sendMessage(
    projectId: project.id,
    message: "Build a weather app with 5-day forecast",
    model: "claude-sonnet-4-20250514"
)

for try await event in stream {
    switch event {
    case .taskStarted(let task):
        timeline.add(task)
    case .token(let text):
        currentTask.append(text)
    case .taskCompleted(let task):
        timeline.complete(task)
    case .buildFinished:
        preview.refresh()
    }
}