# KirinCode Mobile — Architecture

## Overview

Mobile apps (iOS / Android / HarmonyOS) that mirror the desktop experience:
- AI chat sessions with build/plan/debug/solo modes
- Auto-memory and skill system sync
- Workflow engine triggers
- Real-time cloud sync across all devices

## Architecture

```
┌─────────────────────────────────────────────────────┐
│                    Mobile Clients                     │
├──────────────┬──────────────┬────────────────────────┤
│   iOS App    │  Android App │  HarmonyOS App         │
│  (React Ntv) │ (React Ntv)  │  (ArkUI)              │
│  SwiftUI     │  Jetpack     │  @ohos.net.http        │
│  bridge      │  Compose     │                        │
└──────┬───────┴──────┬───────┴──────────┬─────────────┘
       │              │                  │
       └──────────────┼──────────────────┘
                      │ HTTPS + WebSocket
              ┌───────▼──────────┐
              │   Cloud Server   │
              │  (Bun + Elysia)  │
              │                  │
              │  /api/v1/        │
              │   - sessions     │
              │   - memory       │
              │   - skills       │
              │   - workflows    │
              │   - auth         │
              │   - sync (WS)    │
              └───────┬──────────┘
                      │
              ┌───────▼──────────┐
              │   PostgreSQL     │
              │   + pgvector     │
              │                  │
              │   Tables:        │
              │   - users        │
              │   - sessions     │
              │   - messages     │
              │   - memory_entries│
              │   - skills       │
              │   - workflows    │
              │   - sync_log     │
              └──────────────────┘
```

## Sync Protocol

### Real-time Sync (WebSocket)

```
Client ──connect──> Server
Client <──session:updated── Server
Client ──prompt──> Server
Client <──message:streaming── Server
Client <──message:completed── Server
```

### Offline Support

- All data cached locally (SQLite on mobile)
- Queue mutations when offline
- Replay on reconnect
- Conflict resolution: last-write-wins with server timestamp

## Data Model

### Sessions
```sql
CREATE TABLE sessions (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  title TEXT,
  agent TEXT DEFAULT 'build',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW(),
  archived BOOLEAN DEFAULT FALSE
);
```

### Memory
```sql
CREATE TABLE memory_entries (
  id UUID PRIMARY KEY,
  user_id UUID NOT NULL,
  project_hash TEXT NOT NULL,
  category TEXT,
  content TEXT,
  embedding VECTOR(1536),
  created_at TIMESTAMPTZ DEFAULT NOW()
);
```

## API Endpoints

### Auth
- `POST /api/v1/auth/login` — email + password
- `POST /api/v1/auth/register` — create account
- `POST /api/v1/auth/refresh` — refresh JWT

### Sessions
- `GET /api/v1/sessions` — list user sessions
- `POST /api/v1/sessions` — create session
- `POST /api/v1/sessions/:id/prompt` — send prompt
- `GET /api/v1/sessions/:id/messages` — get messages

### Sync
- `WS /api/v1/sync` — real-time sync channel
- `POST /api/v1/sync/push` — push offline changes
- `GET /api/v1/sync/pull?since=<timestamp>` — pull changes

### Memory & Skills
- `GET /api/v1/memory` — list memory entries
- `POST /api/v1/memory` — create memory entry
- `GET /api/v1/skills` — list skills
- `POST /api/v1/skills` — create skill

## Mobile App Screens

```
Navigation:
├── Sessions (list)
│   └── Chat (detail)
│       ├── MessageList
│       ├── ModeSelector (build/plan/debug/solo)
│       └── InputBar
├── Memory (search + list)
├── Skills (list + detail)
├── Workflows (list + detail)
└── Settings
    ├── Model config
    ├── Account
    └── Sync status
```