Initial: keryx-bff project files
This commit is contained in:
David Kong
parent
f2544cca15
commit
5b37b5982d
2 changed files with 1528 additions and 0 deletions
898
DESIGN.md
Normal file
898
DESIGN.md
Normal file
|
|
@ -0,0 +1,898 @@
|
||||||
|
# Keryx — iOS/iPad Hermes Client Design Document
|
||||||
|
|
||||||
|
**Project:** Keryx (iOS/iPad native Hermes client)
|
||||||
|
**BFF:** Keryx BFF (`keryx-bff`, Python FastAPI + Strawberry GraphQL)
|
||||||
|
**Status:** v3 — iOS app refined ✅
|
||||||
|
**Date:** 2026-07-03
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Overview](#1-overview)
|
||||||
|
2. [Architecture](#2-architecture)
|
||||||
|
3. [iOS App](#3-ios-app)
|
||||||
|
4. [BFF (Backend For Frontend)](#4-bff-backend-for-frontend)
|
||||||
|
5. [API Contract](#5-api-contract)
|
||||||
|
6. [Data Storage](#6-data-storage)
|
||||||
|
7. [Security](#7-security)
|
||||||
|
8. [Deployment](#8-deployment)
|
||||||
|
9. [MVP Feature Matrix](#9-mvp-feature-matrix)
|
||||||
|
10. [Post-MVP Roadmap](#10-post-mvp-roadmap)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Overview
|
||||||
|
|
||||||
|
Keryx is a native iOS/iPadOS app that replaces the Hermes WebUI. It connects to a user's self-hosted Hermes Agent instance via a Python BFF service. The BFF owns the app experience — it provides page-shaped responses (feed of UI components) rather than raw data. The iOS app is a native component renderer using TCA for state management.
|
||||||
|
|
||||||
|
### Key Decisions
|
||||||
|
|
||||||
|
| Decision | Choice | Rationale |
|
||||||
|
|---|---|---|
|
||||||
|
| Minimum iOS version | **iOS 20 beta** | Strict Swift 6 concurrency, latest SwiftUI, on-device ML |
|
||||||
|
| App architecture | **TCA (The Composable Architecture)** | Central store for multi-session state, SSE event→action mapping, testability |
|
||||||
|
| App state management | **Feature-scoped reducers** compose into `AppReducer` | Each screen independent, parent routes navigation |
|
||||||
|
| GraphQL client | **None — raw `URLSession` + `Codable`** | No Apollo overhead; AI generates DTOs from schema |
|
||||||
|
| SSE streaming | `Effect.run` + `for try await` | Idiomatic TCA pattern, native URLSession bytes |
|
||||||
|
| SSE parser | **Inline, ~50 lines** | Zero dependencies, no external package |
|
||||||
|
| Page rendering | **Per-screen `ForEach`** | Each module owns its rendering; no shared FeedView switch |
|
||||||
|
| UI models | **DTO → Mapper → Canonical per module** | Schema changes only touch DTO + Mapper, View never references DTO |
|
||||||
|
| BFF language | **Python (FastAPI + Strawberry)** | Same language as Hermes, GraphQL for version-safe queries |
|
||||||
|
| API style | **Hybrid GraphQL + SSE** | GraphQL for page data, SSE for chat streaming |
|
||||||
|
| Chat protocol | **Hermes `/api/sessions/{id}/chat/stream`** | Native session-managed streaming |
|
||||||
|
| SSE events | `component`, `chunk`, `component_patch`, `component_complete`, `done` | Maps 1:1 to feed array mutations |
|
||||||
|
| Streaming transport | **SSE** | Works through proxies, native URLSession support |
|
||||||
|
| Auth | **Bearer token in iOS Keychain** | Matches Hermes API Server auth model |
|
||||||
|
| Connection setup | **Native SwiftUI screen + QR code scan** | VisionKit camera, QR encodes URL + API key |
|
||||||
|
| QR generation | **`scripts/generate-setup-qr.py`** in BFF repo | Run by user or Hermes agent on the server |
|
||||||
|
| Deep links | **Internal `keryx://` only** | All links generated by BFF; external link mapping is post-MVP |
|
||||||
|
| Pagination | **None — load full lists** | 82 sessions currently; ~3 MB even for 10,000 sessions |
|
||||||
|
| Deploy model | **systemd user service** | Matches Hermes gateway deployment pattern |
|
||||||
|
| Dependencies | **uv** for Python, **loguru** for logging | Modern, fast, clean |
|
||||||
|
| File staging cleanup | **Lifespan scheduled task** — daily, delete files >30 days | Automatic |
|
||||||
|
| Conversation mappings | **Never deleted** | Simpler lifecycle, Hermes manages sessions |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────┐ GraphQL + SSE ┌─────────────────┐ HTTP ┌─────────────────┐
|
||||||
|
│ │──────────────────→│ │──────────────→│ │
|
||||||
|
│ iOS / iPad │ app_data, pages │ Keryx BFF │ Hermes API │ Hermes Agent │
|
||||||
|
│ (SwiftUI) │←──────────────────│ (FastAPI) │←──────────────│ (API Server) │
|
||||||
|
│ + TCA │ SSE feed stream │ Strawberry GQL │ SSE stream │ │
|
||||||
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||||
|
│
|
||||||
|
│ filesystem
|
||||||
|
▼
|
||||||
|
┌─────────────────┐
|
||||||
|
│ Workspace dir │
|
||||||
|
│ (read-only) │
|
||||||
|
└─────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Design Principles
|
||||||
|
|
||||||
|
- **The BFF owns the app experience** — titles, labels, layout, navigation, empty states all come from the server
|
||||||
|
- **The iOS app is a component renderer** — it receives typed UI components (`session_card`, `message_bubble`, `tool_call_card`, etc.) and renders them natively
|
||||||
|
- **Version-safe via GraphQL** — old apps never query for component types they can't render
|
||||||
|
- **Feed array pattern** — every page is `{header, items[], footer}` where `items` is a heterogeneous array of typed components
|
||||||
|
- **Canonical UI models per module** — DTOs from GraphQL are mapped to module-local canonical types; schema changes only affect DTO + Mapper
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. iOS App
|
||||||
|
|
||||||
|
### Tech Stack
|
||||||
|
|
||||||
|
| Layer | Technology |
|
||||||
|
|---|---|
|
||||||
|
| Architecture | **TCA** (`swift-composable-architecture`, `swift-dependencies`) |
|
||||||
|
| UI Framework | **SwiftUI** (iOS 20 SDK) |
|
||||||
|
| Navigation | `NavigationSplitView` (adaptive: iPhone push, iPad multi-column) |
|
||||||
|
| Networking | **Raw `URLSession`** + `Codable` for GraphQL (no Apollo) |
|
||||||
|
| SSE reader | **Inline parser** (~50 lines), `URLSession.bytes` async sequence |
|
||||||
|
| State management | **Feature-scoped `@Reducer`** composable in `AppReducer` |
|
||||||
|
| Local storage | `Keychain` (credentials), `UserDefaults` (preferences) |
|
||||||
|
| Audio | `AVSpeechRecognizer` (on-device STT) |
|
||||||
|
| Camera / QR | `VisionKit.DataScannerViewController` (iOS 20 native) |
|
||||||
|
| File picker | `UIDocumentPickerViewController` / `FileDocument` |
|
||||||
|
| Drag & drop | `DropDelegate` on compose area (iPad) |
|
||||||
|
| Markdown rendering | Custom renderer per component type |
|
||||||
|
| Deep links | `keryx://` URL scheme, parsed in `AppReducer` |
|
||||||
|
|
||||||
|
### Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Keryx/
|
||||||
|
├── KeryxApp.swift # @main, store init
|
||||||
|
├── App/
|
||||||
|
│ ├── Reducers/
|
||||||
|
│ │ └── AppReducer.swift # Root reducer, navigation, deep links
|
||||||
|
│ ├── Views/
|
||||||
|
│ │ ├── MainSplitView.swift # NavigationSplitView + tab routing
|
||||||
|
│ │ └── DeepLinkHandler.swift # keryx:// URL parsing + dispatch
|
||||||
|
│ └── Models/
|
||||||
|
│ └── AppState.swift # Root app state, composed from modules
|
||||||
|
│
|
||||||
|
├── Shared/ # Cross-cutting, no screen-specific logic
|
||||||
|
│ ├── Networking/
|
||||||
|
│ │ ├── BFFClient.swift # URLSession + GraphQL query runner
|
||||||
|
│ │ ├── SSEReader.swift # ~50 line SSE parser
|
||||||
|
│ │ ├── AuthMiddleware.swift # Bearer token injection
|
||||||
|
│ │ └── DTOs/ # Raw GraphQL response types
|
||||||
|
│ │ ├── AppDataDTO.swift
|
||||||
|
│ │ ├── PageDTO.swift
|
||||||
|
│ │ └── SessionDTO.swift
|
||||||
|
│ ├── Models/
|
||||||
|
│ │ ├── FeedComponent.swift # Canonical UI enum (shared by all modules)
|
||||||
|
│ │ ├── DeepLink.swift # Parsed deep link enum
|
||||||
|
│ │ └── AppData.swift # Canonical app data model
|
||||||
|
│ ├── Services/
|
||||||
|
│ │ ├── KeychainService.swift
|
||||||
|
│ │ └── AudioService.swift
|
||||||
|
│ └── Views/
|
||||||
|
│ ├── CodeBlockView.swift
|
||||||
|
│ ├── EmptyStateView.swift
|
||||||
|
│ └── ErrorBannerView.swift
|
||||||
|
│
|
||||||
|
├── Sessions/ # Module: sessions list
|
||||||
|
│ ├── Reducers/
|
||||||
|
│ │ └── SessionsListReducer.swift
|
||||||
|
│ ├── Views/
|
||||||
|
│ │ └── SessionCardView.swift # Renders session_card component
|
||||||
|
│ ├── Models/
|
||||||
|
│ │ └── SessionCard.swift # Canonical UI model
|
||||||
|
│ └── Services/
|
||||||
|
│ └── SessionsMapper.swift # DTO → SessionCard
|
||||||
|
│
|
||||||
|
├── Chat/ # Module: chat view
|
||||||
|
│ ├── Reducers/
|
||||||
|
│ │ └── ChatReducer.swift # SSE event → feed state
|
||||||
|
│ ├── Views/
|
||||||
|
│ │ ├── ChatView.swift # ForEach over feed, includes compose bar
|
||||||
|
│ │ ├── MessageBubbleView.swift
|
||||||
|
│ │ ├── ThinkingBlockView.swift
|
||||||
|
│ │ ├── ToolCallCardView.swift
|
||||||
|
│ │ └── ComposeBarView.swift
|
||||||
|
│ ├── Models/
|
||||||
|
│ │ ├── ChatState.swift # Canonical chat state
|
||||||
|
│ │ └── SSEEvent.swift # Parsed SSE event (component, chunk, etc.)
|
||||||
|
│ └── Services/
|
||||||
|
│ └── ChatMapper.swift # SSE event → FeedComponent
|
||||||
|
│
|
||||||
|
├── Workspace/ # Module: file browser
|
||||||
|
│ ├── Reducers/
|
||||||
|
│ │ └── WorkspaceReducer.swift
|
||||||
|
│ ├── Views/
|
||||||
|
│ │ └── FileRowView.swift # Renders file_row component
|
||||||
|
│ ├── Models/
|
||||||
|
│ │ └── FileNode.swift # Canonical file model
|
||||||
|
│ └── Services/
|
||||||
|
│ └── WorkspaceMapper.swift # DTO → FileNode
|
||||||
|
│
|
||||||
|
├── Settings/ # Module: connection config
|
||||||
|
│ ├── Reducers/
|
||||||
|
│ │ └── SettingsReducer.swift
|
||||||
|
│ ├── Views/
|
||||||
|
│ │ ├── SetupView.swift # First-launch connection screen
|
||||||
|
│ │ └── QRScannerView.swift # VisionKit camera scanner
|
||||||
|
│ └── Models/
|
||||||
|
│ └── ConnectionConfig.swift # Canonical config model
|
||||||
|
│
|
||||||
|
└── Resources/
|
||||||
|
├── Assets.xcassets
|
||||||
|
└── Info.plist
|
||||||
|
```
|
||||||
|
|
||||||
|
### Module Rules
|
||||||
|
|
||||||
|
| Rule | Why |
|
||||||
|
|---|---|
|
||||||
|
| `Shared/Networking/DTOs/` contain raw GraphQL types | Single point of change when schema evolves |
|
||||||
|
| Each module has own `Models/` with canonical types | No module imports another module's models |
|
||||||
|
| Each module has `Services/*Mapper.swift` | Mapping DTO → canonical model is explicit and testable |
|
||||||
|
| `FeedComponent.swift` lives in `Shared/Models/` | All modules produce feed items — one canonical enum |
|
||||||
|
| Mapper never touches a View | Separation of concerns |
|
||||||
|
| Reducer only operates on canonical models | Schema change = DTO + Mapper update only, reducer tests stay green |
|
||||||
|
| Per-screen `ForEach` loops | Each screen owns rendering independently; no shared `FeedView` |
|
||||||
|
|
||||||
|
### TCA Architecture
|
||||||
|
|
||||||
|
The `AppReducer` composes feature-scoped reducers and handles navigation via `StackState`:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
@Reducer
|
||||||
|
struct AppReducer {
|
||||||
|
@ObservableState
|
||||||
|
struct State: Equatable {
|
||||||
|
var path = StackState<Path.State>()
|
||||||
|
var sessionsList = SessionsListReducer.State()
|
||||||
|
var settings = SettingsReducer.State()
|
||||||
|
}
|
||||||
|
|
||||||
|
enum Action {
|
||||||
|
case path(StackActionOf<Path>)
|
||||||
|
case sessionsList(SessionsListReducer.Action)
|
||||||
|
case settings(SettingsReducer.Action)
|
||||||
|
case deepLink(URL)
|
||||||
|
}
|
||||||
|
|
||||||
|
var body: some ReducerOf<Self> {
|
||||||
|
Scope(state: \.sessionsList, action: \.sessionsList) {
|
||||||
|
SessionsListReducer()
|
||||||
|
}
|
||||||
|
Scope(state: \.settings, action: \.settings) {
|
||||||
|
SettingsReducer()
|
||||||
|
}
|
||||||
|
Reduce { state, action in
|
||||||
|
switch action {
|
||||||
|
case .deepLink(let url):
|
||||||
|
// Parse keryx:// → route navigation or dispatch action
|
||||||
|
return .none
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
}
|
||||||
|
.forEach(\.path, action: \.path)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Each feature reducer (e.g. `ChatReducer`) receives SSE events through TCA's `Effect.run`:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
case .sendMessage(let text):
|
||||||
|
return .run { [sessionId = state.sessionId] send in
|
||||||
|
let stream = try await bffClient.streamChat(sessionId, text)
|
||||||
|
for try await event in stream {
|
||||||
|
switch event {
|
||||||
|
case .component(let type, let id, let data):
|
||||||
|
await send(.feedEvent(.componentReceived(type, id, data)))
|
||||||
|
case .chunk(let componentId, let text):
|
||||||
|
await send(.feedEvent(.chunkReceived(componentId, text)))
|
||||||
|
case .componentPatch(let id, let data):
|
||||||
|
await send(.feedEvent(.patchReceived(id, data)))
|
||||||
|
case .componentComplete(let id, let usage):
|
||||||
|
await send(.feedEvent(.completeReceived(id, usage)))
|
||||||
|
case .done:
|
||||||
|
await send(.feedEvent(.streamComplete))
|
||||||
|
case .error(let code, let message):
|
||||||
|
await send(.feedEvent(.streamError(code, message)))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Connection Setup Flow
|
||||||
|
|
||||||
|
**First launch:**
|
||||||
|
```
|
||||||
|
1. App launches → no stored credentials → show SetupView (native SwiftUI)
|
||||||
|
2. User enters BFF URL + API Key manually, OR taps "Scan QR"
|
||||||
|
3. QR scan: VisionKit camera reads keryx:// URL → decodes JSON → fills fields
|
||||||
|
4. Tap "Connect" → POST to BFF /v1/ios/health to validate
|
||||||
|
5. Success → save to Keychain → fetch app_data → render main app
|
||||||
|
6. Failure → show error, fields stay filled, user can retry
|
||||||
|
```
|
||||||
|
|
||||||
|
**Subsequent launches & foregrounds:**
|
||||||
|
```
|
||||||
|
1. Read credentials from Keychain
|
||||||
|
2. Fetch /v1/ios/app_data
|
||||||
|
3. If 401 → show SetupView (credentials expired)
|
||||||
|
4. If 200 → render main app from app_data
|
||||||
|
```
|
||||||
|
|
||||||
|
SetupView is the only hardcoded screen in the app. Every other screen comes from BFF endpoints.
|
||||||
|
|
||||||
|
### Deep Link Routing
|
||||||
|
|
||||||
|
All navigation is driven by `keryx://` deep links. Links come from BFF responses (`header.actions`, component `actions`, `footer`). The `AppReducer` parses and routes them:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
case .deepLink(let url):
|
||||||
|
switch url.toDeepLink() {
|
||||||
|
case .chat(let id):
|
||||||
|
state.path.append(.chat(ChatReducer.State(sessionId: id)))
|
||||||
|
case .deleteSession(let id):
|
||||||
|
return .send(.sessionsList(.deleteSession(id)))
|
||||||
|
case .newChat:
|
||||||
|
return .run { send in
|
||||||
|
let session = try await bffClient.createSession()
|
||||||
|
await send(.deepLink(URL(string: "keryx://chat/\(session.id)")!))
|
||||||
|
}
|
||||||
|
case .sessions:
|
||||||
|
state.path.removeAll()
|
||||||
|
// ...
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Deep link registry (see `DOMAIN.md` for full list): `keryx://sessions`, `keryx://new-chat`, `keryx://chat/{id}`, `keryx://delete/{id}`, `keryx://rename/{id}`, `keryx://workspace`, `keryx://workspace/{path}`, `keryx://settings`.
|
||||||
|
|
||||||
|
### Per-Screen Rendering
|
||||||
|
|
||||||
|
Each screen module renders its own feed via a direct `ForEach` loop — no shared `FeedView` switch:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
// SessionsListView (in Sessions/Views/)
|
||||||
|
var body: some View {
|
||||||
|
List {
|
||||||
|
ForEach(store.items, id: \.id) { component in
|
||||||
|
SessionCardView(component: component)
|
||||||
|
}
|
||||||
|
if let emptyState = store.emptyState {
|
||||||
|
EmptyStateView(emptyState: emptyState)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// ChatView (in Chat/Views/)
|
||||||
|
var body: some View {
|
||||||
|
ScrollView {
|
||||||
|
LazyVStack(spacing: 0) {
|
||||||
|
ForEach(store.feed, id: \.id) { component in
|
||||||
|
switch component.type {
|
||||||
|
case .messageBubble:
|
||||||
|
MessageBubbleView(component: component)
|
||||||
|
case .thinkingBlock:
|
||||||
|
ThinkingBlockView(component: component)
|
||||||
|
case .toolCallCard:
|
||||||
|
ToolCallCardView(component: component)
|
||||||
|
case .codeBlock:
|
||||||
|
CodeBlockView(component: component)
|
||||||
|
default:
|
||||||
|
EmptyView()
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
.safeAreaInset(edge: .bottom) {
|
||||||
|
ComposeBarView(...)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Unknown component types are silently skipped via `default: EmptyView()`.
|
||||||
|
|
||||||
|
### SSE Reader (Inline Parser)
|
||||||
|
|
||||||
|
The SSE parser is ~50 lines, lives in `Shared/Networking/SSEReader.swift`:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
struct SSEEvent: Equatable {
|
||||||
|
enum Name: String {
|
||||||
|
case component, chunk, componentPatch = "component_patch",
|
||||||
|
componentComplete = "component_complete", done, error
|
||||||
|
}
|
||||||
|
let name: Name
|
||||||
|
let data: Data
|
||||||
|
}
|
||||||
|
|
||||||
|
extension AsyncSequence where Element == UInt8 {
|
||||||
|
func sseEvents() -> AsyncStream<SSEEvent> {
|
||||||
|
AsyncStream { continuation in
|
||||||
|
// Split on "\n\n", parse "event:" and "data:" lines
|
||||||
|
// Decode data JSON
|
||||||
|
// continuation.yield(SSEEvent(name: ..., data: ...))
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Usage in `ChatReducer`:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
let stream = try await session.bytes(for: request)
|
||||||
|
.sseEvents()
|
||||||
|
for try await event in stream { ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Screens
|
||||||
|
|
||||||
|
| Screen | Source | Component Types | Module |
|
||||||
|
|---|---|---|---|
|
||||||
|
| **Connection Setup** | First launch (native) | N/A — hardcoded fields + QR scanner | `Settings/` |
|
||||||
|
| **Sessions List** | `app_data` → `page(id: "sessions")` | `session_card` | `Sessions/` |
|
||||||
|
| **Chat View** | `keryx://chat/{id}` deep link | `message_bubble`, `thinking_block`, `tool_call_card`, `code_block` + `compose_bar` footer | `Chat/` |
|
||||||
|
| **Workspace Files** | Tab link → `page(id: "workspace")` | `file_row` | `Workspace/` |
|
||||||
|
| **Settings** | Tab link | Server-driven (post-MVP native) | `Settings/` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. BFF (Backend For Frontend)
|
||||||
|
|
||||||
|
### Identity
|
||||||
|
|
||||||
|
- **Name:** `keryx-bff`
|
||||||
|
- **Stack:** Python 3.12+, FastAPI + Strawberry GraphQL + uvicorn
|
||||||
|
- **Config file:** `~/.keryx/config.yaml`
|
||||||
|
- **Service file:** `~/.config/systemd/user/keryx-bff.service`
|
||||||
|
|
||||||
|
### Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
keryx-bff/
|
||||||
|
├── pyproject.toml
|
||||||
|
├── README.md
|
||||||
|
├── scripts/
|
||||||
|
│ └── generate-setup-qr.py # Reads config.yaml → QR code PNG
|
||||||
|
├── src/
|
||||||
|
│ ├── server.py # FastAPI app, lifespan, router/GraphQL includes
|
||||||
|
│ ├── core/
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── config.py # Pydantic config model (load YAML)
|
||||||
|
│ │ ├── auth.py # Bearer token middleware
|
||||||
|
│ │ ├── lifespan.py # App startup/shutdown lifecycle
|
||||||
|
│ │ ├── db.py # SQLite for keryx.db (WAL mode)
|
||||||
|
│ │ └── exceptions.py # Global exception handlers
|
||||||
|
│ ├── models/
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── graphql.py # Strawberry schema: Query, Mutation
|
||||||
|
│ │ ├── app_data.py # AppData, Navigation, Tab, FeatureFlags
|
||||||
|
│ │ ├── page.py # Page, Header, Footer, FeedComponent union
|
||||||
|
│ │ ├── components.py # SessionCard, MessageBubble, ToolCallCard, etc.
|
||||||
|
│ │ ├── chat.py # Chat request + SSE event models
|
||||||
|
│ │ ├── workspace.py # FileNode, FileContent
|
||||||
|
│ │ └── health.py # HealthResponse
|
||||||
|
│ ├── routes/
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── app_data.py # GET /v1/ios/app_data
|
||||||
|
│ │ ├── chat_stream.py # POST /v1/ios/chat/{id}/stream (SSE)
|
||||||
|
│ │ ├── attach.py # POST /v1/ios/chat/{id}/attach
|
||||||
|
│ │ └── workspace.py # GET /v1/ios/workspace/*
|
||||||
|
│ ├── services/
|
||||||
|
│ │ ├── __init__.py
|
||||||
|
│ │ ├── hermes_client.py # httpx async client for Hermes API
|
||||||
|
│ │ ├── page_builder.py # Build feed arrays from Hermes data
|
||||||
|
│ │ └── staging.py # File upload staging + cleanup schedule
|
||||||
|
│ └── lib/
|
||||||
|
│ ├── __init__.py
|
||||||
|
│ └── deep_link.py # Link builder helpers
|
||||||
|
└── tests/
|
||||||
|
├── conftest.py
|
||||||
|
├── test_app_data.py
|
||||||
|
├── test_chat_stream.py
|
||||||
|
├── test_attach.py
|
||||||
|
├── test_workspace.py
|
||||||
|
└── test_graphql.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### Dependencies (`pyproject.toml`)
|
||||||
|
|
||||||
|
```toml
|
||||||
|
[project]
|
||||||
|
name = "keryx-bff"
|
||||||
|
version = "0.1.0"
|
||||||
|
requires-python = ">=3.12"
|
||||||
|
dependencies = [
|
||||||
|
"fastapi>=0.115",
|
||||||
|
"strawberry-graphql>=0.260",
|
||||||
|
"strawberry-graphql[fastapi]",
|
||||||
|
"uvicorn[standard]",
|
||||||
|
"pydantic>=2.0",
|
||||||
|
"pydantic-settings",
|
||||||
|
"httpx>=0.28",
|
||||||
|
"python-multipart",
|
||||||
|
"pyyaml",
|
||||||
|
"loguru",
|
||||||
|
"aiosqlite",
|
||||||
|
"qrcode", # for generate-setup-qr.py
|
||||||
|
]
|
||||||
|
|
||||||
|
[tool.uv]
|
||||||
|
dev-dependencies = [
|
||||||
|
"pytest>=8",
|
||||||
|
"pytest-asyncio",
|
||||||
|
"httpx",
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Config (`~/.keryx/config.yaml`)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
app:
|
||||||
|
name: "Keryx"
|
||||||
|
version: "0.1.0"
|
||||||
|
supported_app_versions: "^1.0.0"
|
||||||
|
|
||||||
|
server:
|
||||||
|
host: "0.0.0.0"
|
||||||
|
port: 8643
|
||||||
|
api_key: "keryx-bff-change-me"
|
||||||
|
|
||||||
|
hermes:
|
||||||
|
api_url: "http://127.0.0.1:8642"
|
||||||
|
api_key: "hermes-api-server-key"
|
||||||
|
workspace_path: "/home/david/workspace"
|
||||||
|
|
||||||
|
bff:
|
||||||
|
staging_dir: "/tmp/keryx"
|
||||||
|
db_path: "/home/david/.keryx/keryx.db"
|
||||||
|
max_upload_size_mb: 50
|
||||||
|
staging_cleanup_days: 30
|
||||||
|
```
|
||||||
|
|
||||||
|
### BFF SQLite DB (`keryx.db`)
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Minimal. Only for push tokens (post-MVP).
|
||||||
|
PRAGMA journal_mode=WAL;
|
||||||
|
|
||||||
|
CREATE TABLE IF NOT EXISTS push_tokens (
|
||||||
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||||
|
device_token TEXT NOT NULL,
|
||||||
|
device_name TEXT,
|
||||||
|
created_at REAL NOT NULL,
|
||||||
|
last_seen_at REAL NOT NULL
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
### GraphQL Schema (Strawberry)
|
||||||
|
|
||||||
|
```graphql
|
||||||
|
type Query {
|
||||||
|
appData: AppData!
|
||||||
|
page(id: ID!, sessionId: ID): Page!
|
||||||
|
session(id: ID!): SessionInfo
|
||||||
|
}
|
||||||
|
|
||||||
|
type AppData {
|
||||||
|
app: AppInfo!
|
||||||
|
navigation: Navigation!
|
||||||
|
defaults: Defaults!
|
||||||
|
features: FeatureFlags!
|
||||||
|
}
|
||||||
|
|
||||||
|
type AppInfo {
|
||||||
|
name: String!
|
||||||
|
version: String!
|
||||||
|
minSupportedVersion: String!
|
||||||
|
supportedVersions: String!
|
||||||
|
forceUpdateUrl: String
|
||||||
|
}
|
||||||
|
|
||||||
|
type Navigation {
|
||||||
|
primaryTab: Tab!
|
||||||
|
tabs: [Tab!]!
|
||||||
|
}
|
||||||
|
|
||||||
|
type Tab {
|
||||||
|
id: String!
|
||||||
|
icon: String!
|
||||||
|
label: String!
|
||||||
|
link: String!
|
||||||
|
}
|
||||||
|
|
||||||
|
type Page {
|
||||||
|
id: String!
|
||||||
|
header: Header
|
||||||
|
emptyState: EmptyState
|
||||||
|
items: [FeedComponent!]!
|
||||||
|
footer: Footer # only compose_bar or null
|
||||||
|
}
|
||||||
|
|
||||||
|
type Header {
|
||||||
|
title: String
|
||||||
|
subtitle: String
|
||||||
|
actions: [LinkAction!]
|
||||||
|
}
|
||||||
|
|
||||||
|
type EmptyState {
|
||||||
|
icon: String
|
||||||
|
title: String!
|
||||||
|
subtitle: String
|
||||||
|
action: LinkAction
|
||||||
|
}
|
||||||
|
|
||||||
|
union FeedComponent = SessionCard | MessageBubble | ThinkingBlock
|
||||||
|
| ToolCallCard | FileRow | CodeBlock
|
||||||
|
| Divider | ComposeBar
|
||||||
|
|
||||||
|
union Footer = ComposeBarLoader
|
||||||
|
|
||||||
|
type SessionCard {
|
||||||
|
id: String!
|
||||||
|
title: String
|
||||||
|
modelBadge: String
|
||||||
|
messageCount: Int!
|
||||||
|
timestamp: String!
|
||||||
|
preview: String
|
||||||
|
actions: [Action!]!
|
||||||
|
}
|
||||||
|
|
||||||
|
type MessageBubble {
|
||||||
|
id: String!
|
||||||
|
role: MessageRole!
|
||||||
|
text: String
|
||||||
|
streaming: Boolean!
|
||||||
|
timestamp: Float
|
||||||
|
attachments: [Attachment!]
|
||||||
|
}
|
||||||
|
|
||||||
|
# ... etc for each component type
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note:** No `cursor` or `limit` parameters — all lists load in full.
|
||||||
|
|
||||||
|
### QR Code Generation (`scripts/generate-setup-qr.py`)
|
||||||
|
|
||||||
|
```python
|
||||||
|
#!/usr/bin/env python3
|
||||||
|
"""Generate a QR code for Keryx setup.
|
||||||
|
|
||||||
|
Reads the BFF config and outputs a QR code PNG that the iOS app
|
||||||
|
can scan from the SetupView to auto-configure the connection.
|
||||||
|
|
||||||
|
Usage:
|
||||||
|
python scripts/generate-setup-qr.py [--output setup.png]
|
||||||
|
"""
|
||||||
|
import json, qrcode, yaml
|
||||||
|
from pathlib import Path
|
||||||
|
|
||||||
|
config_path = Path.home() / ".keryx" / "config.yaml"
|
||||||
|
config = yaml.safe_load(config_path.read_text())
|
||||||
|
|
||||||
|
payload = {
|
||||||
|
"v": 1,
|
||||||
|
"url": f"https://{config['server']['host']}:{config['server']['port']}",
|
||||||
|
"key": config["server"]["api_key"],
|
||||||
|
}
|
||||||
|
|
||||||
|
img = qrcode.make(json.dumps(payload))
|
||||||
|
img.save("keryx-setup.png")
|
||||||
|
print("QR code saved to keryx-setup.png")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Build Phases
|
||||||
|
|
||||||
|
| Phase | Modules | Milestone |
|
||||||
|
|---|---|---|
|
||||||
|
| **1. Core** | `config.py`, `auth.py`, `lifespan.py`, `server.py` | BFF starts, responds to health |
|
||||||
|
| **2. app_data** | `app_data.py` route + `graphql.py` Query | iOS app fetches startup config |
|
||||||
|
| **3. GraphQL pages** | `page_builder.py`, component models, sessions | Sessions list renders via GraphQL |
|
||||||
|
| **4. SSE streaming** | `chat_stream.py`, `hermes_client.py` | Chat works with streaming components |
|
||||||
|
| **5. File ops** | `attach.py`, `staging.py`, workspace | File upload + workspace browsing |
|
||||||
|
| **6. Polish** | Error handling, logging, tests, systemd, QR script | Production-ready |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. API Contract
|
||||||
|
|
||||||
|
### `GET /v1/ios/app_data`
|
||||||
|
|
||||||
|
Called on every app launch and foreground. Returns the full startup config.
|
||||||
|
|
||||||
|
### `POST /v1/ios/chat/{session_id}/stream`
|
||||||
|
|
||||||
|
Sends a message and returns an SSE stream of feed component events.
|
||||||
|
|
||||||
|
**Request:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"message": "What files are in my project?",
|
||||||
|
"model": "deepseek-v4-flash",
|
||||||
|
"attachments": [
|
||||||
|
{"staging_path": "/tmp/keryx/abc123/report.pdf", "name": "report.pdf"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**SSE Response (stream):**
|
||||||
|
```
|
||||||
|
event: component
|
||||||
|
data: {"type": "message_bubble", "id": "msg_1", "data": {"role": "user", "text": "What files are in my project?"}}
|
||||||
|
|
||||||
|
event: component
|
||||||
|
data: {"type": "tool_call_card", "id": "tc_1", "data": {"tool": "terminal", "command": "ls -la", "status": "running"}, "streaming": true}
|
||||||
|
|
||||||
|
event: component_patch
|
||||||
|
data: {"id": "tc_1", "data": {"status": "completed", "output": "src/\ntests/\nREADME.md"}}
|
||||||
|
|
||||||
|
event: component
|
||||||
|
data: {"type": "message_bubble", "id": "msg_2", "data": {"role": "assistant", "text": "", "code_blocks": []}, "streaming": true}
|
||||||
|
|
||||||
|
event: chunk
|
||||||
|
data: {"component_id": "msg_2", "text": "Your project"}
|
||||||
|
|
||||||
|
event: chunk
|
||||||
|
data: {"component_id": "msg_2", "text": " contains a FastAPI"}
|
||||||
|
|
||||||
|
event: chunk
|
||||||
|
data: {"component_id": "msg_2", "text": " server."}
|
||||||
|
|
||||||
|
event: component_complete
|
||||||
|
data: {"id": "msg_2", "usage": {"input_tokens": 16267, "output_tokens": 20}}
|
||||||
|
|
||||||
|
event: done
|
||||||
|
data: {}
|
||||||
|
```
|
||||||
|
|
||||||
|
### `POST /v1/ios/chat/{session_id}/attach`
|
||||||
|
|
||||||
|
Upload a file for the chat session.
|
||||||
|
|
||||||
|
**Request:** `multipart/form-data` — field `file`
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"staging_path": "/tmp/keryx/abc123/report.pdf",
|
||||||
|
"name": "report.pdf",
|
||||||
|
"size": 245760,
|
||||||
|
"mime_type": "application/pdf"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Data Storage
|
||||||
|
|
||||||
|
### iOS Device (Keychain)
|
||||||
|
|
||||||
|
| Item | Key |
|
||||||
|
|---|---|
|
||||||
|
| BFF URL | `keryx_bff_url` |
|
||||||
|
| API Key | `keryx_api_key` |
|
||||||
|
|
||||||
|
### iOS Device (UserDefaults)
|
||||||
|
|
||||||
|
| Key | Type | Default |
|
||||||
|
|---|---|---|
|
||||||
|
| `last_session_id` | String | nil |
|
||||||
|
| `last_active_model` | String | nil (use BFF default) |
|
||||||
|
|
||||||
|
### BFF SQLite (`keryx.db`)
|
||||||
|
|
||||||
|
Just `push_tokens` (post-MVP).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Security
|
||||||
|
|
||||||
|
| Concern | Measure |
|
||||||
|
|---|---|
|
||||||
|
| Auth in transit | HTTPS required. HTTP returns 426 Upgrade Required. |
|
||||||
|
| Auth at rest | API key in iOS Keychain (Secure Enclave) |
|
||||||
|
| BFF auth | Bearer token middleware on all endpoints |
|
||||||
|
| File upload safety | MIME validation, 50 MB cap, `..` path traversal blocked |
|
||||||
|
| Workspace safety | `..` / absolute paths blocked. Reads under configured root only |
|
||||||
|
| Hermes API key | Stored in BFF config, never exposed to iOS app |
|
||||||
|
| GraphQL depth limiting | Max query depth enforced (default: 5 levels) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Deployment
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- Hermes Agent with API Server enabled (`API_SERVER_ENABLED=true`)
|
||||||
|
- Python 3.12+
|
||||||
|
- `uv`
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Create project
|
||||||
|
mkdir -p ~/apps/keryx-bff && cd ~/apps/keryx-bff
|
||||||
|
|
||||||
|
# Install deps
|
||||||
|
uv sync
|
||||||
|
|
||||||
|
# Create config
|
||||||
|
mkdir -p ~/.keryx
|
||||||
|
# ... write config.yaml ...
|
||||||
|
|
||||||
|
# Create staging dir
|
||||||
|
mkdir -p /tmp/keryx
|
||||||
|
|
||||||
|
# Generate QR code (optional — for iOS app setup)
|
||||||
|
python scripts/generate-setup-qr.py
|
||||||
|
```
|
||||||
|
|
||||||
|
### systemd Service (`~/.config/systemd/user/keryx-bff.service`)
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[Unit]
|
||||||
|
Description=Keryx BFF – Hermes iOS/iPad Backend For Frontend
|
||||||
|
After=hermes-gateway.service
|
||||||
|
BindsTo=hermes-gateway.service
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=simple
|
||||||
|
ExecStart=%h/apps/keryx-bff/.venv/bin/uvicorn src.server:app --host 0.0.0.0 --port 8643
|
||||||
|
WorkingDirectory=%h/apps/keryx-bff
|
||||||
|
Restart=on-failure
|
||||||
|
RestartSec=5
|
||||||
|
Environment=KERYX_CONFIG=%h/.keryx/config.yaml
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=default.target
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl --user daemon-reload
|
||||||
|
systemctl --user enable --now keryx-bff
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. MVP Feature Matrix
|
||||||
|
|
||||||
|
### BFF (Python / FastAPI)
|
||||||
|
|
||||||
|
| Feature | Status |
|
||||||
|
|---|---|
|
||||||
|
| `GET /v1/ios/app_data` on startup/foreground | ✅ |
|
||||||
|
| GraphQL `Query.appData` | ✅ |
|
||||||
|
| GraphQL `Query.page` for sessions (full list, no pagination) | ✅ |
|
||||||
|
| GraphQL `Query.page` for workspace (full tree, no pagination) | ✅ |
|
||||||
|
| GraphQL `Query.page` for chat (historical messages) | ✅ |
|
||||||
|
| SSE streaming via `POST /v1/ios/chat/{id}/stream` | ✅ |
|
||||||
|
| SSE events: `component`, `chunk`, `component_patch`, `component_complete`, `done` | ✅ |
|
||||||
|
| Feed component: `session_card` | ✅ |
|
||||||
|
| Feed component: `message_bubble` | ✅ |
|
||||||
|
| Feed component: `thinking_block` | ✅ |
|
||||||
|
| Feed component: `tool_call_card` | ✅ |
|
||||||
|
| Feed component: `file_row` | ✅ |
|
||||||
|
| Feed component: `code_block` | ✅ |
|
||||||
|
| Feed component: `divider` | ✅ |
|
||||||
|
| Feed component: `compose_bar` | ✅ |
|
||||||
|
| Footer type: `compose_bar` | ✅ |
|
||||||
|
| File attach upload (multipart, staging, MIME validation, 50 MB cap) | ✅ |
|
||||||
|
| Workspace file tree (full, no pagination) | ✅ |
|
||||||
|
| Workspace file read (`..` traversal blocked) | ✅ |
|
||||||
|
| File staging 30-day cleanup (lifespan scheduled task) | ✅ |
|
||||||
|
| Bearer auth middleware | ✅ |
|
||||||
|
| Hermes API health check on startup | ✅ |
|
||||||
|
| `scripts/generate-setup-qr.py` | ✅ |
|
||||||
|
| loguru logging | ✅ |
|
||||||
|
| uv dependency management | ✅ |
|
||||||
|
| systemd service deployment | ✅ |
|
||||||
|
| Tests: health, app_data, chat stream, attach, workspace, GraphQL | ✅ |
|
||||||
|
|
||||||
|
### iOS App (Swift / TCA)
|
||||||
|
|
||||||
|
| Feature | Status |
|
||||||
|
|---|---|
|
||||||
|
| TCA architecture with feature-scoped reducers | ✅ |
|
||||||
|
| Modular project structure (Shared, Sessions, Chat, Workspace, Settings) | ✅ |
|
||||||
|
| DTO → Mapper → Canonical pipeline per module | ✅ |
|
||||||
|
| Per-screen `ForEach` rendering (no shared FeedView) | ✅ |
|
||||||
|
| Inline SSE parser (~50 lines) | ✅ |
|
||||||
|
| SSE → TCA via `Effect.run` + `for try await` | ✅ |
|
||||||
|
| `keryx://` deep link routing through `AppReducer` | ✅ |
|
||||||
|
| Connection setup screen (native SwiftUI, URL + API key) | ✅ |
|
||||||
|
| QR code scanner (VisionKit DataScannerViewController) | ✅ |
|
||||||
|
| Keychain credential storage | ✅ |
|
||||||
|
| Bearer token injection on all requests | ✅ |
|
||||||
|
| Sessions list (fetch full, render session_cards) | ✅ |
|
||||||
|
| Chat view: send message, receive SSE stream, render feed | ✅ |
|
||||||
|
| Chat view: append component, chunk text, patch metadata, complete | ✅ |
|
||||||
|
| Chat view: `compose_bar` in footer | ✅ |
|
||||||
|
| File attach (picker + upload) | ✅ |
|
||||||
|
| iPad drag & drop on compose area | ✅ |
|
||||||
|
| Voice input (on-device AVSpeechRecognizer) | ✅ |
|
||||||
|
| Model selector in chat (list from BFF) | ✅ |
|
||||||
|
| Workspace file browser (full tree, tap to preview) | ✅ |
|
||||||
|
| NavigationSplitView (iPad multi-column, iPhone push) | ✅ |
|
||||||
|
| Pull-to-refresh sessions list | ✅ |
|
||||||
|
| Swipe to delete sessions | ✅ |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Post-MVP Roadmap
|
||||||
|
|
||||||
|
- Push notifications (APNs)
|
||||||
|
- Multiple Hermes server profiles
|
||||||
|
- Message search within sessions
|
||||||
|
- Message editing / deletion
|
||||||
|
- Image preview inline in chat
|
||||||
|
- Offline message queue
|
||||||
|
- Dark mode testing
|
||||||
|
- Share extension (share URLs/files from other apps)
|
||||||
|
- Keyboard shortcuts (iPad)
|
||||||
|
- Multi-window (Stage Manager)
|
||||||
|
- Local model fallback (on-device ML)
|
||||||
|
- External deep link mapping (e.g. from notifications)
|
||||||
630
DOMAIN.md
Normal file
630
DOMAIN.md
Normal file
|
|
@ -0,0 +1,630 @@
|
||||||
|
# Keryx — Domain Language & Conventions
|
||||||
|
|
||||||
|
**Purpose:** Define every term, convention, and naming rule used across Keryx (iOS app + BFF). The iOS app design, code, UI labels, and deep links must match this document exactly. If a term appears in the UI, a GraphQL query, or a deep link, it is defined here.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Core Concepts](#1-core-concepts)
|
||||||
|
2. [UI Component Taxonomy](#2-ui-component-taxonomy)
|
||||||
|
3. [Page Structure](#3-page-structure)
|
||||||
|
4. [Navigation & Deep Links](#4-navigation--deep-links)
|
||||||
|
5. [SSE Streaming Events](#5-sse-streaming-events)
|
||||||
|
6. [GraphQL Conventions](#6-graphql-conventions)
|
||||||
|
7. [UI Labels & Copy](#7-ui-labels--copy)
|
||||||
|
8. [Iconography](#8-iconography)
|
||||||
|
9. [State Terminology](#9-state-terminology)
|
||||||
|
10. [Conventions](#10-conventions)
|
||||||
|
11. [Appendix: Hermes API Mapping](#11-appendix-hermes-api-mapping)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Core Concepts
|
||||||
|
|
||||||
|
### Keryx
|
||||||
|
The iOS/iPadOS app. Named after the *keryx* (κήρυξ) — the ancient Greek herald who precedes the main messenger (Hermes). The app is the herald that announces what Hermes has to say.
|
||||||
|
|
||||||
|
### Keryx BFF
|
||||||
|
The Python FastAPI + Strawberry GraphQL backend that the iOS app communicates with. Owns the app experience — drives content, layout, labels, and navigation. Not a thin proxy.
|
||||||
|
|
||||||
|
### Hermes Agent
|
||||||
|
The underlying AI agent framework running on the user's server. Keryx never talks to Hermes directly; all communication goes through the Keryx BFF.
|
||||||
|
|
||||||
|
### Session
|
||||||
|
A single conversation with Hermes. Has an ID, a model, a start time, messages, and token usage. Sessions are created and managed by the Hermes API server. Keryx references them by their Hermes session ID.
|
||||||
|
|
||||||
|
### Conversation
|
||||||
|
Synonym for **Session** in user-facing contexts. In code and APIs, use `session`. In UI labels, prefer "Conversation" or "Chat".
|
||||||
|
|
||||||
|
### Message
|
||||||
|
A single turn in a session. Has a role (`user` or `assistant`), content, and a timestamp. Messages are never deleted by Keryx.
|
||||||
|
|
||||||
|
### Component
|
||||||
|
A single piece of UI rendered inside a page feed. Every component has a `type`, an `id`, `data`, and `actions`. See [UI Component Taxonomy](#2-ui-component-taxonomy) for the full list.
|
||||||
|
|
||||||
|
### Feed
|
||||||
|
The ordered array of `items` within a `page`. The iOS app renders components in array order, left-to-right, top-to-bottom.
|
||||||
|
|
||||||
|
### Page
|
||||||
|
A full-screen view presented by the iOS app. Every page has the structure `{header, items[], footer}`. The BFF builds pages; the iOS app renders them.
|
||||||
|
|
||||||
|
### Workspace
|
||||||
|
A directory on the Hermes server containing project files the user interacts with. Defined by a single root path in the BFF config. Read-only.
|
||||||
|
|
||||||
|
### Deep Link
|
||||||
|
A `keryx://` URL that the iOS app uses for all navigation and actions. No screen transitions happen without a deep link. See [Navigation & Deep Links](#4-navigation--deep-links).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. UI Component Taxonomy
|
||||||
|
|
||||||
|
Every component has this shape:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "component_type_name",
|
||||||
|
"id": "unique_identifier",
|
||||||
|
"data": { ... },
|
||||||
|
"actions": [
|
||||||
|
{"type": "tap|swipe_left|swipe_right", "label": "Action", "style": "normal|destructive", "link": "keryx://..."}
|
||||||
|
],
|
||||||
|
"streaming": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`streaming` is `true` when the component is still receiving data via the SSE stream. The iOS app may show a shimmer/typing indicator for streaming components.
|
||||||
|
|
||||||
|
### 2.1 `session_card`
|
||||||
|
|
||||||
|
A session/conversation in the sessions list.
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | String | ✅ | Hermes session ID |
|
||||||
|
| `title` | String? | ❌ | Session title. `null` if untitled. |
|
||||||
|
| `model_badge` | String? | ❌ | Model name shown as a badge (e.g. "deepseek-v4-flash") |
|
||||||
|
| `message_count` | Int | ✅ | Total messages in the session |
|
||||||
|
| `timestamp` | String | ✅ | Relative time string (e.g. "2m ago", "Yesterday") — generated by BFF |
|
||||||
|
| `preview` | String? | ❌ | First ~80 chars of the session for preview |
|
||||||
|
|
||||||
|
**Display rules:**
|
||||||
|
- If `title` is `null`, show the `preview` as the primary text (truncated to 1 line)
|
||||||
|
- If `title` is set, show `title` as primary, `preview` as secondary
|
||||||
|
- `model_badge` shown as a rounded pill
|
||||||
|
- `timestamp` right-aligned
|
||||||
|
- Swipe left reveals "Delete" (destructive)
|
||||||
|
|
||||||
|
### 2.2 `message_bubble`
|
||||||
|
|
||||||
|
A single message in a conversation.
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | String | ✅ | Message ID from Hermes |
|
||||||
|
| `role` | Enum | ✅ | `"user"` or `"assistant"` |
|
||||||
|
| `text` | String? | ❌ | Message content. May be empty during streaming. |
|
||||||
|
| `streaming` | Bool | ✅ | `true` while assistant is still generating |
|
||||||
|
| `timestamp` | Float? | ❌ | Unix timestamp |
|
||||||
|
| `model` | String? | ❌ | Model used for this response (assistant only) |
|
||||||
|
| `attachments` | [Attachment]? | ❌ | Files attached to this message |
|
||||||
|
|
||||||
|
**`Attachment`:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"name": "report.pdf",
|
||||||
|
"size": 245760,
|
||||||
|
"mime_type": "application/pdf"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Display rules:**
|
||||||
|
- User messages: right-aligned, tinted background
|
||||||
|
- Assistant messages: left-aligned, default background
|
||||||
|
- `model` shown as a small label above assistant messages
|
||||||
|
- Streaming messages show a blinking cursor at end of text
|
||||||
|
|
||||||
|
### 2.3 `thinking_block`
|
||||||
|
|
||||||
|
Collapsible reasoning from the assistant.
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | String | ✅ | Unique ID |
|
||||||
|
| `text` | String | ✅ | Reasoning content |
|
||||||
|
| `collapsed_by_default` | Bool | ❌ | Default: `true` |
|
||||||
|
|
||||||
|
**Display rules:**
|
||||||
|
- Tappable header "Thinking..."
|
||||||
|
- Expand/collapse animation
|
||||||
|
- Grey/dim text when collapsed
|
||||||
|
- Header shows token count if available
|
||||||
|
|
||||||
|
### 2.4 `tool_call_card`
|
||||||
|
|
||||||
|
A tool invocation by Hermes (terminal, web search, file read, etc.).
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | String | ✅ | Unique ID |
|
||||||
|
| `tool` | String | ✅ | Tool name (e.g. "terminal", "web_search") |
|
||||||
|
| `command` | String? | ❌ | The command/query |
|
||||||
|
| `status` | Enum | ✅ | `"running"`, `"completed"`, `"failed"` |
|
||||||
|
| `output` | String? | ❌ | Tool output (truncated) |
|
||||||
|
| `duration_ms` | Int? | ❌ | Execution time |
|
||||||
|
|
||||||
|
**Display rules:**
|
||||||
|
- Show tool icon + name as a compact card
|
||||||
|
- Show command as monospaced text
|
||||||
|
- Status indicator: spinner (running), checkmark (completed), X (failed)
|
||||||
|
- Tappable to expand full output (post-MVP)
|
||||||
|
|
||||||
|
### 2.5 `file_row`
|
||||||
|
|
||||||
|
A file or directory in the workspace browser.
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | String | ✅ | File path (used as identifier) |
|
||||||
|
| `name` | String | ✅ | File/directory name |
|
||||||
|
| `is_directory` | Bool | ✅ | True if directory |
|
||||||
|
| `size` | Int? | ❌ | File size in bytes (null for directories) |
|
||||||
|
| `mime_type` | String? | ❌ | MIME type for files |
|
||||||
|
| `modified_at` | String? | ❌ | Relative time string |
|
||||||
|
| `children` | [FileRow]? | ❌ | When depth > 0, nested files |
|
||||||
|
|
||||||
|
**Display rules:**
|
||||||
|
- Directory icon (folder) or file icon based on type
|
||||||
|
- Tap on directory → navigates into it
|
||||||
|
- Tap on file → opens preview (post-MVP: in-app viewer)
|
||||||
|
- Indentation for nested children
|
||||||
|
|
||||||
|
### 2.6 `code_block`
|
||||||
|
|
||||||
|
A rendered code snippet inside a message_bubble. When Hermes returns markdown with code fences, the BFF extracts them into standalone components.
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | String | ✅ | Unique ID |
|
||||||
|
| `language` | String? | ❌ | Language identifier (e.g. "python", "json") |
|
||||||
|
| `code` | String | ✅ | The code content |
|
||||||
|
| `streaming` | Bool | ✅ | `true` while still receiving code |
|
||||||
|
|
||||||
|
**Display rules:**
|
||||||
|
- Monospaced font, syntax highlighting (SF Mono)
|
||||||
|
- Language badge in top-right
|
||||||
|
- Copy button in top-right (copy to clipboard)
|
||||||
|
- Scrollable horizontal for long lines
|
||||||
|
|
||||||
|
### 2.7 `divider`
|
||||||
|
|
||||||
|
A visual separator.
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | String | ✅ | Unique ID |
|
||||||
|
| `label` | String? | ❌ | Optional text in the divider |
|
||||||
|
|
||||||
|
**Display rules:**
|
||||||
|
- Thin horizontal line
|
||||||
|
- If `label` present, text centered in the line
|
||||||
|
|
||||||
|
### 2.8 `compose_bar`
|
||||||
|
|
||||||
|
The chat input area. Only appears in the `footer` of a chat page, never in `items`.
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `id` | String | ✅ | Always `"compose"` |
|
||||||
|
| `placeholder` | String | ✅ | Placeholder text (e.g. "Ask something...") |
|
||||||
|
| `actions` | ComposeActions | ✅ | Deep links for send, attach, voice |
|
||||||
|
| `disabled` | Bool | ✅ | `true` while a message is being sent/streaming |
|
||||||
|
|
||||||
|
**`ComposeActions`:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"send": "keryx://chat/{id}/send",
|
||||||
|
"attach": "keryx://chat/{id}/attach",
|
||||||
|
"voice": "keryx://chat/{id}/voice"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Display rules:**
|
||||||
|
- Fixed at bottom of screen
|
||||||
|
- Text field + send button + attach button + voice button
|
||||||
|
- Disabled state: greyed out, non-interactive
|
||||||
|
- Shows attachment chip when a file is staged
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Page Structure
|
||||||
|
|
||||||
|
Every page response has this structure:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"page": {
|
||||||
|
"id": "string",
|
||||||
|
"header": { ... } | null,
|
||||||
|
"items": [ ... ],
|
||||||
|
"footer": { ... } | null
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Header
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"title": "Conversations",
|
||||||
|
"subtitle": "82 total",
|
||||||
|
"actions": [
|
||||||
|
{"icon": "plus", "label": "New Chat", "link": "keryx://new-chat"}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Field | Type | Required | Description |
|
||||||
|
|---|---|---|---|
|
||||||
|
| `title` | String? | ❌ | Main header text |
|
||||||
|
| `subtitle` | String? | ❌ | Smaller text below title |
|
||||||
|
| `actions` | [LinkAction]? | ❌ | Right-side action buttons |
|
||||||
|
|
||||||
|
### Footer
|
||||||
|
|
||||||
|
The footer is either `null` (no footer) or contains the compose bar for chat pages. There is no pagination — all lists load in full.
|
||||||
|
|
||||||
|
```json
|
||||||
|
// Chat page footer
|
||||||
|
{
|
||||||
|
"type": "compose_bar",
|
||||||
|
"placeholder": "Ask something...",
|
||||||
|
"actions": {
|
||||||
|
"send": "keryx://chat/{id}/send",
|
||||||
|
"attach": "keryx://chat/{id}/attach",
|
||||||
|
"voice": "keryx://chat/{id}/voice"
|
||||||
|
},
|
||||||
|
"disabled": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Type | Description |
|
||||||
|
|---|---|
|
||||||
|
| `compose_bar` | Chat input area (chat page only) |
|
||||||
|
| `null` | No footer (settings page, workspace, sessions list) |
|
||||||
|
|
||||||
|
### Empty State
|
||||||
|
|
||||||
|
When `items` is empty, the BFF may include an `empty_state` field at the page level (not inside `header`):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"page": {
|
||||||
|
"id": "sessions",
|
||||||
|
"header": {"title": "Conversations"},
|
||||||
|
"empty_state": {
|
||||||
|
"icon": "message",
|
||||||
|
"title": "No conversations yet",
|
||||||
|
"subtitle": "Start a new chat to begin",
|
||||||
|
"action": {"label": "Start Chat", "link": "keryx://new-chat"}
|
||||||
|
},
|
||||||
|
"items": [],
|
||||||
|
"footer": null
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The iOS app shows the empty state view when `items.length === 0` and `empty_state` is present.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Navigation & Deep Links
|
||||||
|
|
||||||
|
All navigation is driven by `keryx://` deep links. The iOS app registers the `keryx` URL scheme and routes links to screens. No screen transitions are hardcoded.
|
||||||
|
|
||||||
|
### Link Format
|
||||||
|
|
||||||
|
```
|
||||||
|
keryx://<action>/<param>?query=val
|
||||||
|
```
|
||||||
|
|
||||||
|
### Deep Link Registry
|
||||||
|
|
||||||
|
| Link | Action | Description |
|
||||||
|
|---|---|---|
|
||||||
|
| `keryx://sessions` | Present | Sessions list page |
|
||||||
|
| `keryx://new-chat` | Present | Create new session → navigate to chat |
|
||||||
|
| `keryx://chat/{session_id}` | Present | Open chat view for an existing session |
|
||||||
|
| `keryx://chat/{session_id}/send` | Action | Send message (POST) — triggered by compose bar |
|
||||||
|
| `keryx://chat/{session_id}/attach` | Action | Attach file (POST) — triggered by compose bar |
|
||||||
|
| `keryx://chat/{session_id}/voice` | Action | Start voice input — triggered by compose bar |
|
||||||
|
| `keryx://delete/{session_id}` | Action | Delete a session |
|
||||||
|
| `keryx://rename/{session_id}` | Action | Rename a session |
|
||||||
|
| `keryx://workspace` | Present | Workspace file browser page |
|
||||||
|
| `keryx://workspace/{path}` | Present | Navigate into a directory in workspace |
|
||||||
|
| `keryx://workspace/read/{path}` | Present | Preview a workspace file |
|
||||||
|
| `keryx://settings` | Present | Settings page |
|
||||||
|
| `keryx://release-notes` | Present | Release notes / changelog |
|
||||||
|
| `keryx://{anything}` | Fallback | Open in system browser or show error |
|
||||||
|
|
||||||
|
### Navigation Rules
|
||||||
|
|
||||||
|
1. **Present** links push a new page onto the navigation stack (iPhone) or select a column (iPad)
|
||||||
|
2. **Action** links trigger a side effect (POST, DELETE) and are handled without navigation
|
||||||
|
3. The app never constructs URLs dynamically — all links come from BFF responses
|
||||||
|
4. Unknown link schemes are silently dropped (app doesn't crash)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. SSE Streaming Events
|
||||||
|
|
||||||
|
The SSE protocol for `POST /v1/ios/chat/{session_id}/stream`.
|
||||||
|
|
||||||
|
### Event: `component`
|
||||||
|
|
||||||
|
Sent when a new UI component should be appended to the feed.
|
||||||
|
|
||||||
|
```json
|
||||||
|
event: component
|
||||||
|
data: {"type": "message_bubble", "id": "msg_1", "data": {"role": "user", "text": "Hello"}}
|
||||||
|
```
|
||||||
|
|
||||||
|
**iOS action:** Append a new `FeedComponent` to `items[]`. Set `streaming: true` if the component may receive further updates.
|
||||||
|
|
||||||
|
### Event: `chunk`
|
||||||
|
|
||||||
|
Sent when text content should be appended to an existing component.
|
||||||
|
|
||||||
|
```json
|
||||||
|
event: chunk
|
||||||
|
data: {"component_id": "msg_2", "text": "def fibonacci"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**iOS action:** Find component by `component_id` in `items[]`. Append `text` to its `data.text` field. Re-render in place.
|
||||||
|
|
||||||
|
### Event: `component_patch`
|
||||||
|
|
||||||
|
Sent when a component's metadata should be updated (e.g. tool status change).
|
||||||
|
|
||||||
|
```json
|
||||||
|
event: component_patch
|
||||||
|
data: {"id": "tc_1", "data": {"status": "completed", "output": "src/\ntests/"}}
|
||||||
|
```
|
||||||
|
|
||||||
|
**iOS action:** Find component by `id`. Deep-merge `data` into the component's existing `data`. Fields not in `data` are preserved.
|
||||||
|
|
||||||
|
### Event: `component_complete`
|
||||||
|
|
||||||
|
Sent when a component is finalised (no more updates).
|
||||||
|
|
||||||
|
```json
|
||||||
|
event: component_complete
|
||||||
|
data: {"id": "msg_2", "usage": {"input_tokens": 16267, "output_tokens": 20}}
|
||||||
|
```
|
||||||
|
|
||||||
|
**iOS action:** Find component by `id`. Set `streaming: false`. Merge any additional `data` fields (e.g. `usage`).
|
||||||
|
|
||||||
|
### Event: `done`
|
||||||
|
|
||||||
|
Sent when the stream is complete.
|
||||||
|
|
||||||
|
```json
|
||||||
|
event: done
|
||||||
|
data: {}
|
||||||
|
```
|
||||||
|
|
||||||
|
**iOS action:** Close SSE connection. Re-enable the send button. The `compose_bar` in the footer should set `disabled: false`.
|
||||||
|
|
||||||
|
### Error Handling
|
||||||
|
|
||||||
|
If the BFF encounters an error mid-stream:
|
||||||
|
|
||||||
|
```json
|
||||||
|
event: error
|
||||||
|
data: {"code": "hermes_unreachable", "message": "Hermes API server is not responding"}
|
||||||
|
```
|
||||||
|
|
||||||
|
**iOS action:** Show inline error banner at the bottom of the feed. The stream is not closed — the user can retry.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. GraphQL Conventions
|
||||||
|
|
||||||
|
### Naming
|
||||||
|
|
||||||
|
| Convention | Rule | Example |
|
||||||
|
|---|---|---|
|
||||||
|
| Queries | `camelCase` | `appData`, `sessionList` |
|
||||||
|
| Mutations | `camelCase`, verb-first | `sendMessage`, `deleteSession` |
|
||||||
|
| Types | `PascalCase` | `AppData`, `SessionCard` |
|
||||||
|
| Fields | `camelCase` | `modelBadge`, `messageCount` |
|
||||||
|
| Enums | `PascalCase` | `MessageRole`, `ToolStatus` |
|
||||||
|
| Enum values | `SCREAMING_SNAKE_CASE` | `USER`, `ASSISTANT`, `COMPLETED` |
|
||||||
|
|
||||||
|
### Union Types for Feed Components
|
||||||
|
|
||||||
|
The `FeedComponent` union type uses Strawberry's `@strawberry.type` with `@strawberry.union`. The iOS app receives the `__typename` field to determine which fragment to use:
|
||||||
|
|
||||||
|
```graphql
|
||||||
|
query SessionList {
|
||||||
|
page(id: "sessions") {
|
||||||
|
items {
|
||||||
|
__typename
|
||||||
|
... on SessionCard {
|
||||||
|
id title modelBadge messageCount timestamp preview
|
||||||
|
}
|
||||||
|
... on Divider {
|
||||||
|
id label
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pagination
|
||||||
|
|
||||||
|
No pagination. All lists load in full — sessions, workspace trees, and chat message histories. The page query returns every item at once.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. UI Labels & Copy
|
||||||
|
|
||||||
|
### Standard Labels
|
||||||
|
|
||||||
|
| Context | Label | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| App display name | **Keryx** | Not "Keryx iOS" or "Keryx Client" |
|
||||||
|
| Tab: sessions | **Chats** | User-friendly term |
|
||||||
|
| Tab: workspace | **Files** | |
|
||||||
|
| Tab: settings | **Settings** | |
|
||||||
|
| New chat button | **New Chat** | |
|
||||||
|
| Delete action | **Delete** | Destructive |
|
||||||
|
| Rename action | **Rename** | |
|
||||||
|
| Send button | *(None — icon only)* | Paper plane icon |
|
||||||
|
| Attach button | *(None — icon only)* | Paperclip icon |
|
||||||
|
| Voice button | *(None — icon only)* | Microphone icon |
|
||||||
|
| Empty sessions | **No conversations yet** | |
|
||||||
|
| Empty workspace | **No files yet** | |
|
||||||
|
| Model selector | *(None — label varies)* | e.g. "DeepSeek V4 Flash" |
|
||||||
|
| Streaming indicator | *(None — visual only)* | Blinking cursor / shimmer |
|
||||||
|
| Connection: loading | **Connecting...** | |
|
||||||
|
| Connection: error | **Could not connect** | With retry button |
|
||||||
|
| Session: untitled | *(Show first 80 chars of preview)* | Not "Untitled" |
|
||||||
|
| Delete confirmation | **Delete conversation?** | Action sheet |
|
||||||
|
|
||||||
|
### Tone & Voice
|
||||||
|
|
||||||
|
- **Friendly but direct** — the app is a tool, not a companion
|
||||||
|
- **Minimal labels** — every visible word serves a purpose
|
||||||
|
- **No "wizard" or "magic" language** — Hermes is an agent, not a magician
|
||||||
|
- **Use "Chat", not "Chat with Hermes" or "Conversation with AI"**
|
||||||
|
- **Use "Files", not "Workspace Files" or "Project Files"**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Iconography
|
||||||
|
|
||||||
|
### SF Symbols Mappings
|
||||||
|
|
||||||
|
| Context | SF Symbol Name | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| Tab: Chats | `message.fill` | |
|
||||||
|
| Tab: Files | `folder.fill` | |
|
||||||
|
| Tab: Settings | `gearshape.fill` | |
|
||||||
|
| New chat | `plus` | |
|
||||||
|
| Send | `paperplane.fill` | |
|
||||||
|
| Attach | `paperclip` | |
|
||||||
|
| Voice | `mic.fill` | |
|
||||||
|
| Delete | `trash.fill` | |
|
||||||
|
| Rename | `pencil` | |
|
||||||
|
| Copy code | `doc.on.doc` | |
|
||||||
|
| Expand | `chevron.down` | |
|
||||||
|
| Collapse | `chevron.right` | |
|
||||||
|
| Directory | `folder` | Non-filled for file rows |
|
||||||
|
| File (generic) | `doc` | |
|
||||||
|
| File (code) | `doc.text` | |
|
||||||
|
| File (image) | `photo` | |
|
||||||
|
| File (PDF) | `doc.richtext` | |
|
||||||
|
| Empty state | `tray` | |
|
||||||
|
| Success | `checkmark.circle.fill` | Green |
|
||||||
|
| Error | `xmark.circle.fill` | Red |
|
||||||
|
| Pending | `ellipsis` | Animated |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. State Terminology
|
||||||
|
|
||||||
|
### Connection States
|
||||||
|
|
||||||
|
| State | BFF `app_data` field | iOS App Behaviour |
|
||||||
|
|---|---|---|
|
||||||
|
| **Connected** | `server.hermes_connected: true` | Normal operation |
|
||||||
|
| **Hermes Unreachable** | `server.hermes_connected: false` | Show banner "Hermes is not responding. Responses may be delayed." |
|
||||||
|
| **BFF Error** | 500 / timeout | Show error screen with retry |
|
||||||
|
| **Version Mismatch** | `app.force_update_url` not null | Show force-update screen until app is updated |
|
||||||
|
|
||||||
|
### Session States
|
||||||
|
|
||||||
|
| State | BFF Signal | iOS App Behaviour |
|
||||||
|
|---|---|---|
|
||||||
|
| **Loading** | N/A (page fetch in progress) | Shimmer / skeleton |
|
||||||
|
| **Loaded** | Items array populated | Render feed |
|
||||||
|
| **Empty** | `empty_state` present, `items` empty | Render empty state |
|
||||||
|
| **Error** | Error in response | Show error with retry button |
|
||||||
|
|
||||||
|
### Component States
|
||||||
|
|
||||||
|
| State | `streaming` field | iOS App Behaviour |
|
||||||
|
|---|---|---|
|
||||||
|
| **Static** | `false` | Render normally |
|
||||||
|
| **Streaming** | `true` | Show shimmer/blinking cursor |
|
||||||
|
| **Updating** | `true` (with `chunk` events arriving) | Append text in place |
|
||||||
|
| **Complete** | `false` (after `component_complete`) | Remove shimmer, show final content |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Conventions
|
||||||
|
|
||||||
|
### Naming
|
||||||
|
|
||||||
|
| Domain | Convention | Example |
|
||||||
|
|---|---|---|
|
||||||
|
| Files | `snake_case` | `session_card`, `keryx_bff` |
|
||||||
|
| GraphQL fields | `camelCase` | `messageCount`, `createdAt` |
|
||||||
|
| Component types | `snake_case` | `message_bubble`, `tool_call_card` |
|
||||||
|
| Deep links | `keryx://resource/action` | `keryx://chat/{id}/send` |
|
||||||
|
| SSE events | `lowercase_snake` | `component_complete`, `component_patch` |
|
||||||
|
| Config keys | `snake_case` | `staging_cleanup_days` |
|
||||||
|
| HTTP headers | `Pascal-Case` | `Authorization`, `Content-Type` |
|
||||||
|
| Enum values (Swift) | `lowerCamelCase` | `.user`, `.assistant` |
|
||||||
|
| Enum values (Python) | `SCREAMING_SNAKE` | `USER`, `ASSISTANT` |
|
||||||
|
|
||||||
|
### Dates & Times
|
||||||
|
|
||||||
|
- **BFF → iOS:** Relative time strings for display ("2m ago", "Yesterday", "3 weeks ago")
|
||||||
|
- **BFF → iOS:** Unix timestamps (Float) for sorting
|
||||||
|
- **BFF generation:** Use user's timezone (configured in BFF, or sent by iOS app in headers)
|
||||||
|
- **iOS display:** Never show raw timestamps to users
|
||||||
|
|
||||||
|
### Files
|
||||||
|
|
||||||
|
- **File sizes** returned as bytes (Int). iOS converts for display (KB, MB, etc.)
|
||||||
|
- **MIME types** follow standard IANA values (`application/pdf`, `text/plain`, `image/png`)
|
||||||
|
- **Workspace paths** are always relative to the configured workspace root. The BFF resolves absolute paths internally.
|
||||||
|
|
||||||
|
### Errors
|
||||||
|
|
||||||
|
| Error Code | HTTP Status | Meaning |
|
||||||
|
|---|---|---|
|
||||||
|
| `auth_invalid` | 401 | API key missing or wrong |
|
||||||
|
| `session_not_found` | 404 | Session ID doesn't exist |
|
||||||
|
| `file_too_large` | 413 | Upload exceeds `max_upload_size_mb` |
|
||||||
|
| `unsupported_file_type` | 415 | MIME type not allowed |
|
||||||
|
| `hermes_unreachable` | 502 | Hermes API server not responding |
|
||||||
|
| `hermes_error` | 502 | Hermes returned an error |
|
||||||
|
| `workspace_out_of_bounds` | 403 | Path traversal attempt blocked |
|
||||||
|
| `rate_limited` | 429 | Too many requests |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Appendix: Hermes API Mapping
|
||||||
|
|
||||||
|
This documents how BFF concepts map to Hermes API Server endpoints and data.
|
||||||
|
|
||||||
|
| Keryx Concept | Hermes API Endpoint | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| Session ID | API Server session ID | Direct 1:1 mapping |
|
||||||
|
| Create session | `POST /api/sessions` | Returns Hermes session ID |
|
||||||
|
| Session list | `GET /api/sessions` | BFF transforms to session_card components |
|
||||||
|
| Session messages | `GET /api/sessions/{id}/messages` | BFF transforms to message_bubble + thinking_block + tool_call_card |
|
||||||
|
| Delete session | `DELETE /api/sessions/{id}` | |
|
||||||
|
| Rename session | `PATCH /api/sessions/{id}` | Update `title` field |
|
||||||
|
| Send message | `POST /api/sessions/{id}/chat/stream` | SSE stream of events |
|
||||||
|
| Model list | `GET /v1/models` | Proxied through BFF |
|
||||||
|
| Health check | `GET /v1/health` | |
|
||||||
|
| File upload | *(Not in Hermes API)* | BFF handles staging |
|
||||||
|
| Workspace files | *(Not in Hermes API)* | BFF reads filesystem |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*This document is the source of truth for all naming, terminology, and conventions used in the Keryx project. If a UI label, GraphQL field, deep link, or code identifier contradicts this document, this document wins.*
|
||||||
Loading…
Add table
Reference in a new issue