KirinCode/packages/mobile/ARCHITECTURE.md

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

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

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