Files

admin d62a850ac5 v1.2.0 - Z.AI Chat for Android with dark/light themes, 4 chat modes, streaming SSE, coding plan endpoint

2026-05-19 15:17:22 +04:00

25 KiB

Raw Blame History

Z.AI Chat for Android

Full-stack AI chat client for the Z.AI GLM Coding Plan
Native Android app with Chat, Coding, Brainstorm & Agentic modes.

Dark Mode	Light Mode

Get 10% OFF your Z.AI Coding Plan

World-class GLM-5.1 models for coding agents. Monthly access from just $18/mo.
Use the link above for an exclusive 10% discount on your subscription.

Overview
Architecture
Technology Stack
Features
Design System
Development Process
Project Structure
Building from Source
Configuration
API Reference
Changelog
License

Overview

Z.AI Chat for Android is a self-contained, production-ready Android application that connects to the Z.AI GLM Coding Plan API. It provides four specialized AI interaction modes — general Chat, Coding assistant, Brainstorm partner, and autonomous Agentic coding — all accessible from a single native Android app.

The app targets Android 15 (API 35) and Android 16 (API 36), built with Capacitor for the hybrid architecture, wrapping a performant single-page web application inside a native Android WebView.

Key Differentiators

Feature	Implementation
Zero-config start	Enter your Z.AI coding plan token and start chatting immediately
4 Specialized Modes	Each mode has a tailored system prompt optimized for its use case
Real-time Streaming	Server-Sent Events (SSE) for token-by-token response rendering
Dark & Light Themes	Full theme system with 30+ CSS custom properties per palette
Conversation Management	Multi-conversation sidebar with auto-titling and JSON export
Markdown + Code	Full GFM markdown with syntax highlighting and copy buttons
940 KB Release APK	Minified, shrunk, ProGuard-optimized, self-signed

Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────┐
│                   Android APK                        │
│                                                     │
│  ┌───────────────────────────────────────────────┐  │
│  │              Capacitor Shell                   │  │
│  │  ┌─────────────┐  ┌────────────────────────┐  │  │
│  │  │ MainActivity│  │  WebView (Chrome-based) │  │  │
│  │  │  (Java)     │──│                        │  │  │
│  │  └─────────────┘  │  ┌──────────────────┐  │  │  │
│  │                   │  │   SPA (HTML/CSS/JS)│  │  │  │
│  │  ┌─────────────┐  │  │                  │  │  │  │
│  │  │ Capacitor   │  │  │  ┌────────────┐  │  │  │  │
│  │  │ Bridge      │◄─┤  │  │  Chat UI   │  │  │  │  │
│  │  └─────────────┘  │  │  │  (Vue-like) │  │  │  │  │
│  │                   │  │  └────────────┘  │  │  │  │
│  │                   │  │                  │  │  │  │
│  │                   │  │  ┌────────────┐  │  │  │  │
│  │                   │  │  │  API Layer │  │  │  │  │
│  │                   │  │  │  (fetch)   │  │  │  │  │
│  │                   │  │  └──────┬─────┘  │  │  │  │
│  │                   │  └─────────┼────────┘  │  │  │
│  │                   └────────────┼────────────┘  │  │
│  └───────────────────────────────┼────────────────┘  │
│                                  │ HTTPS              │
└──────────────────────────────────┼────────────────────┘
                                   │
                    ┌──────────────▼──────────────┐
                    │     Z.AI Coding Plan API     │
                    │  api.z.ai/api/coding/paas/v4 │
                    │                              │
                    │  OpenAI-compatible endpoint  │
                    │  Models: GLM-5.1, GLM-5,     │
                    │  GLM-4.7, GLM-4.5-air        │
                    └─────────────────────────────┘

Component Architecture

www/
├── index.html          ← Entry point, all screens defined
├── css/styles.css      ← 30+ CSS custom properties, dual theme system
└── js/
    ├── app.js          ← Core application logic (state machine, API, UI)
    ├── marked.min.js   ← Markdown parser (GFM compatible)
    └── highlight.min.js← Syntax highlighting for 180+ languages

The app uses a state-machine pattern with three screens:

Setup Screen — API key entry, endpoint selection, mode overview
Chat Screen — Message history, mode selector, input area, sidebar
Settings Screen — API config, model tuning, theme, data management, changelog

Data Flow

User Input → State Manager → API Request Builder → fetch() → Z.AI API
                                                              │
User Sees ← Markdown Renderer ← SSE Parser ← Stream Response ◄┘
                │
                └→ Syntax Highlighter → Code Headers (Copy button)

State Management

All state is persisted in localStorage with the zai_chat_ prefix:

state = {
    apiKey,           // Bearer token for Z.AI API
    baseUrl,          // API endpoint (coding plan vs general)
    model,            // GLM model selection
    temperature,      // 0.0 - 1.0 randomness control
    maxTokens,        // 256 - 16384 response length
    streaming,        // SSE toggle
    webSearch,        // web_search tool toggle
    currentMode,      // chat | coding | brainstorm | agentic
    theme,            // dark | light
    conversations[],  // Full message history
    activeConversationId
}

Technology Stack

Frontend (WebView SPA)

Technology	Version	Purpose
HTML5	Living Standard	Semantic markup, meta viewport, PWA-ready
CSS3	Custom Properties, Grid, Flexbox	Dual-theme design system with 30+ variables
Vanilla JavaScript	ES2020 (IIFE pattern)	Zero-dependency state management, async/await
Marked.js	Latest	GitHub-Flavored Markdown parsing
Highlight.js	11.9.0	Syntax highlighting for 180+ programming languages

Android Native Layer

Technology	Version	Purpose
Capacitor	8.3.4	Hybrid app framework, WebView bridge
Android SDK	API 36	Targeting Android 16 (Baklava)
Gradle	8.14.3	Build automation
Android Gradle Plugin	8.13.0	Compilation, resource processing
JDK	21	Java compilation
ProGuard	Android Optimize	Release APK minification and shrinking

API Integration

Protocol	Implementation
OpenAI Chat Completions	POST `/chat/completions` with Bearer auth
Server-Sent Events (SSE)	`stream: true` with `ReadableStream` parsing
Web Search	Tool calling via `web_search` tool type

Build & Signing

Component	Details
Debug Keystore	`debug.keystore` — `android` / `androiddebugkey`
Release Keystore	`release.keystore` — `zaichat` / `zai-chat`
RSA Key Size	2048-bit
Validity	10,000 days

Features

1. Four Specialized Chat Modes

Each mode injects a purpose-built system prompt:

Mode	System Prompt Strategy	Use Case
Chat	Concise, knowledgeable assistant	General Q&A, explanations
Coding	Expert coder; markdown code blocks, edge cases, error handling	Code generation, debugging
Brainstorm	Creative partner; diverse ideas, trade-off evaluation	Ideation, planning
Agentic	Autonomous agent; step-by-step tasks, tool-calling format	Complex multi-step coding

2. Real-Time Streaming

Uses fetch() with ReadableStream for SSE parsing
Token-by-token rendering with Markdown re-parsing on each chunk
Abort support via AbortController — stop generation at any time

3. Dark & Light Theme System

30+ CSS Custom Properties per Theme
├── Backgrounds (7 levels: primary → code)
├── Text (3 levels: primary → muted)
├── Accent (main, hover, dim)
├── Borders
├── Status colors (danger, success, warning)
└── UI chrome (shadows, overlays, scrollbars)

Theme is toggled via:

Header button — sun/moon icon, instant toggle
Settings toggle — Dark Mode switch
Persisted — localStorage survives app restarts

4. Conversation Management

Unlimited conversations stored in localStorage
Auto-titling from first message (first 50 chars)
Sidebar with conversation list, active indicator, swipe-to-delete
JSON export for backup/migration

5. Markdown & Code Rendering

Full GitHub-Flavored Markdown (tables, task lists, strikethrough)
Syntax highlighting for 180+ languages via Highlight.js
Code block headers with language label and copy button
Inline code with distinct styling

6. Network Security

network_security_config.xml whitelists only Z.AI domains
HTTPS-only communication
android:usesCleartextTraffic="false"

Design System

Color Palette

Dark Theme (Default)

Token	Hex	Usage
`--bg-primary`	`#0f0f23`	Main background
`--bg-secondary`	`#1a1a2e`	Headers, cards
`--bg-tertiary`	`#16213e`	Tertiary surfaces
`--accent`	`#6c63ff`	Primary brand color
`--text-primary`	`#e0e0ff`	Main text
`--border`	`#2a2a4a`	Dividers

Light Theme

Token	Hex	Usage
`--bg-primary`	`#f5f5fa`	Main background
`--bg-secondary`	`#ffffff`	Headers, cards
`--bg-tertiary`	`#eef0f6`	Tertiary surfaces
`--accent`	`#6c63ff`	Primary brand color (shared)
`--text-primary`	`#1a1a2e`	Main text
`--border`	`#d8dae6`	Dividers

Typography

Font Stack: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif
Base Size: 15px
Code Font: 'Fira Code', 'JetBrains Mono', 'Cascadia Code', monospace
Code Size: 13px

Spacing & Sizing

Token	Value	Usage
`--radius`	16px	Message bubbles, cards
`--radius-sm`	10px	Buttons, inputs
`--transition`	0.2s ease	All interactive elements

Development Process

This project was built end-to-end using a systematic Plan → Code → Test → Iterate workflow powered by the Z.AI GLM-5.1 model itself (meta: the tool that built this app is powered by the same API it targets).

Phase 1: Research & Planning

Objective: Understand the Z.AI API surface and design the app architecture.

API Research: Fetched and analyzed the z-ai-sdk-python repository to understand:
- Authentication flow (Bearer token)
- Endpoint structure (OpenAI-compatible /chat/completions)
- Streaming protocol (SSE with data: lines)
- Available models and their capabilities
- Tool calling format (web search)
Endpoint Discovery: Discovered from Z.AI docs that the Coding Plan uses a dedicated endpoint:
- Coding Plan: https://api.z.ai/api/coding/paas/v4
- General API: https://api.z.ai/api/paas/v4
- This distinction was critical — using the wrong endpoint would not consume the coding plan quota.
Architecture Decision: Chose Capacitor (over Cordova/React Native) because:
- Zero-framework frontend (vanilla JS) for minimal APK size
- Direct access to native Android WebView
- Smaller learning curve for a single-developer project
- Production-ready Android project scaffolding

Phase 2: Frontend Development

Objective: Build the complete web application (HTML/CSS/JS).

Step 1: HTML Structure (index.html)

Designed three-screen layout: Setup → Chat → Settings
Semantic HTML with proper ARIA considerations
Mode selector, sidebar, conversation list
Theme toggle integration

Step 2: CSS Design System (styles.css)

Started with CSS Custom Properties for theming
Built component library: buttons, inputs, toggles, cards
Implemented responsive layout (mobile-first)
Added animations: fadeIn for messages, bounce for thinking dots, spin for loaders

Step 3: JavaScript Application (app.js)

IIFE pattern to avoid global scope pollution
State machine with localStorage persistence
API layer:
- apiRequest() for non-streaming calls
- streamResponse() with ReadableStream + TextDecoder for SSE
- AbortController for cancellation support
Markdown pipeline: marked.parse() → hljs.highlight() → DOM injection
Theme engine: data-theme attribute switching with CSS custom properties

Step 4: Theme System (v1.2.0)

Extended :root variables into dual theme blocks
[data-theme="light"] override block with 30+ light-palette values
Added applyTheme() function that:
- Sets data-theme on <html>
- Updates meta theme-color for browser chrome
- Toggles header button icon (sun/moon)
- Syncs settings toggle
- Persists to localStorage

Phase 3: Android Build Pipeline

Objective: Create a signed, optimized APK.

Step 1: Environment Setup

Downloaded JDK 21 (required by Capacitor 8.x — JDK 17 fails with invalid source release: 21)
Downloaded Android SDK Command-Line Tools (146 MB)
Installed SDK components: platforms;android-36, build-tools;36.0.0, platform-tools

Step 2: Project Scaffolding

npm init → Capacitor initialization
npx cap add android — generates full Android project
Customized AndroidManifest.xml with network security config
Added network_security_config.xml for domain whitelisting

Step 3: Build Configuration

Created debug and release keystores with keytool
Configured signingConfigs in app/build.gradle
Enabled ProGuard minification + resource shrinking for release
Set Java 17 compatibility

Step 4: Build & Sign

./gradlew assembleRelease --no-daemon  # → 940 KB release APK
./gradlew assembleDebug --no-daemon    # → 4.0 MB debug APK

Phase 4: Testing & Validation

Test	Method	Result
APK install	Manual (Android 15 emulator)	Pass
API connection	`testConnection()` with real key	Pass
Streaming	SSE parsing with real API	Pass
Theme persistence	Kill/restart app	Pass
Conversation save	Kill/restart app	Pass
Multi-conversation	Create/switch/delete	Pass
Code rendering	Python, JS, Go code blocks	Pass
Copy button	Clipboard API	Pass
Export	JSON file download	Pass
Light mode contrast	Visual inspection	Pass
ProGuard release	940 KB (77% size reduction)	Pass

Project Structure

zai-chat/
├── www/                              # Web application (SPA)
│   ├── index.html                    # Entry point with all 3 screens
│   ├── css/
│   │   └── styles.css                # Full design system + dual themes
│   └── js/
│       ├── app.js                    # Core application logic
│       ├── marked.min.js             # Markdown parser
│       └── highlight.min.js          # Syntax highlighter
│
├── android/                          # Native Android project
│   ├── app/
│   │   ├── build.gradle              # App-level build config + signing
│   │   ├── proguard-rules.pro        # ProGuard keep rules
│   │   ├── debug.keystore            # Debug signing key
│   │   ├── release.keystore          # Release signing key
│   │   └── src/main/
│   │       ├── AndroidManifest.xml   # Permissions, activities, config
│   │       ├── assets/public/        # WebView assets (copied from www/)
│   │       └── res/
│   │           ├── xml/
│   │           │   └── network_security_config.xml
│   │           ├── values/
│   │           │   ├── strings.xml
│   │           │   ├── colors.xml
│   │           │   └── styles.xml
│   │           └── mipmap-*/         # App icons
│   ├── build.gradle                  # Root build config
│   ├── variables.gradle              # SDK version constants
│   ├── settings.gradle               # Module includes
│   └── gradle/wrapper/               # Gradle wrapper
│
├── capacitor.config.json             # Capacitor configuration
├── package.json                      # NPM dependencies
└── README.md                         # This file

Building from Source

Prerequisites

Requirement	Version
Node.js	18+
JDK	21
Android SDK	Platform 36, Build-Tools 36.0.0
npm	9+

Quick Build

# Clone the repository
git clone https://github.rommark.dev/admin/Z.AI-Chat-for-Android.git
cd Z.AI-Chat-for-Android/zai-chat

# Install dependencies
npm install

# Sync web assets to Android
npx cap sync android

# Build debug APK
cd android && ./gradlew assembleDebug

# Build release APK (signed)
./gradlew assembleRelease

# APKs will be at:
# android/app/build/outputs/apk/debug/app-debug.apk
# android/app/build/outputs/apk/release/app-release.apk

Environment Setup (from scratch)

# 1. Install JDK 21
curl -fsSL "https://download.java.net/java/GA/jdk21.0.2/f2283984656d49d69e91c558476027ac/13/GPL/openjdk-21.0.2_linux-x64_bin.tar.gz" | tar xz -C /opt/
export JAVA_HOME=/opt/jdk-21.0.2

# 2. Install Android SDK
mkdir -p ~/android-sdk/cmdline-tools
curl -fsSL "https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip" -o /tmp/cmdline-tools.zip
unzip /tmp/cmdline-tools.zip -d ~/android-sdk/cmdline-tools/
mv ~/android-sdk/cmdline-tools/cmdline-tools ~/android-sdk/cmdline-tools/latest

# 3. Install SDK components
export ANDROID_HOME=~/android-sdk
yes | $ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager \
  --sdk_root=$ANDROID_HOME \
  "platforms;android-36" "build-tools;36.0.0" "platform-tools"

# 4. Set environment
export PATH=$JAVA_HOME/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/cmdline-tools/latest/bin:$PATH

Configuration

API Endpoints

Name	URL	Purpose
Coding Plan	`https://api.z.ai/api/coding/paas/v4`	GLM Coding Plan subscription
General API	`https://api.z.ai/api/paas/v4`	Pay-per-use API
China	`https://open.bigmodel.cn/api/paas/v4`	Zhipu AI (mainland China)

Available Models

Model	Description	Recommended For
`glm-5.1`	Flagship foundation model	Complex coding, agentic tasks
`glm-5-turbo`	Faster variant	Quick queries
`glm-4.7`	Previous generation	General purpose
`glm-4.5-air`	Lightweight, fast	Speed-critical tasks
`glm-5v-turbo`	Vision model	Image understanding

System Prompts

Chat Mode

You are a helpful, knowledgeable AI assistant. Be concise and accurate.

Coding Mode

You are an expert coding assistant. Write clean, efficient, well-documented code. 
Always use markdown code blocks with language tags. Explain your approach briefly 
before and after code. Handle edge cases and errors properly.

Brainstorm Mode

You are a creative brainstorming partner. Generate diverse ideas, explore 
unconventional angles, build on concepts, and help evaluate trade-offs. Think 
freely and expansively. Present ideas in organized lists or tables when appropriate.

Agentic Mode

You are an autonomous coding agent. Break down complex tasks into clear steps. 
Write production-quality code with proper error handling, tests, and documentation. 
Think through the architecture before coding. Use tool-calling format when appropriate: 
[SEARCH], [CREATE_FILE], [EDIT_FILE], [RUN_COMMAND]. Always verify your work.

API Reference

POST `/chat/completions`

Request:

{
  "model": "glm-5.1",
  "messages": [
    {"role": "system", "content": "..."},
    {"role": "user", "content": "..."},
    {"role": "assistant", "content": "..."}
  ],
  "temperature": 0.7,
  "max_tokens": 4096,
  "stream": true,
  "tools": [{"type": "web_search", "web_search": {"search_query": "...", "search_result": true}}]
}

Streaming Response (SSE):

data: {"choices":[{"delta":{"content":"Hello"},"index":0}]}
data: {"choices":[{"delta":{"content":" world"},"index":0}]}
data: [DONE]

Non-Streaming Response:

{
  "choices": [{
    "message": {"role": "assistant", "content": "Hello world"},
    "finish_reason": "stop"
  }]
}

Changelog

v1.2.0 (2026-05-19)

Added light mode / dark mode toggle
Theme persists across sessions via localStorage
Theme toggle button (sun/moon) in chat header
Theme setting in Settings > Appearance
Added changelog section to Settings
Optimized light theme color palette with 30+ CSS variables
Android theme-color meta updates on theme switch

v1.1.0 (2026-05-19)

Z.AI Coding Plan endpoint support (api.z.ai/api/coding/paas/v4)
Fixed default API base URL to use coding plan endpoint
Updated model list: GLM-5.1, GLM-5 Turbo, GLM-4.7, GLM-4.5 Air, GLM-5V Turbo
Added coding plan subscription links to setup screen

v1.0.0 (2026-05-19)

Initial release
4 chat modes: Chat, Coding, Brainstorm, Agentic
Real-time SSE streaming responses
Markdown rendering with syntax highlighting (180+ languages)
Code block headers with copy buttons
Multi-conversation management with sidebar
Settings: model, temperature, max tokens, web search, streaming
Conversation export to JSON
Android 15/16 support (targetSdk 36, compileSdk 36)
Dark theme with Material Design 3 aesthetics
Self-signed release APK (940 KB)

License

This project is licensed under the MIT License — see the LICENSE file for details.

25 KiB Raw Blame History